Spring Boot 3 环境准备与项目初始化

本文将带你从零搭建 Spring Boot 3.x 开发环境，使用官方工具快速创建项目，并理解 Maven/Gradle 构建配置与标准项目目录结构。完成后，你将运行起第一个 Spring Boot 应用。

环境准备

必要工具

开发 Spring Boot 3.x 至少需要以下环境：

工具	最低版本	推荐版本
JDK	17	21 LTS
Maven	3.8+	3.9+
IDE	—	IntelliJ IDEA Ultimate / VS Code (Spring Tools)

Spring Boot 3.x 基于 Spring Framework 6，要求最低 JDK 17，并全面拥抱 Java 17+ 新特性（如 records、sealed classes）。如果使用 Windows，推荐使用 SDKMAN 或 jabba 管理多版本 JDK。

验证环境

bash

# 检查 Java 版本
java -version
# openjdk version "21.0.2" 2026-01-15

# 检查 Maven 版本
mvn -version
# Apache Maven 3.9.9

使用 Spring Initializr 创建项目

网页方式

访问 start.spring.io，填写以下信息：

Project：Maven / Gradle（推荐 Maven）
Language：Java
Spring Boot：3.4.x（最新稳定版）
Group：com.example
Artifact：demo
Dependencies：添加 Spring Web、Spring Data JPA、H2 Database

点击 GENERATE 下载压缩包，解压后用 IDE 打开。

命令行方式（更推荐）

bash

# 使用 curl 调用 Spring Initializr API
curl https://start.spring.io/starter.tgz \
  -d type=maven-project \
  -d language=java \
  -d bootVersion=3.4.0 \
  -d baseDir=demo \
  -d groupId=com.example \
  -d artifactId=demo \
  -d name=demo \
  -d packageName=com.example.demo \
  -d javaVersion=21 \
  -d dependencies=web,data-jpa,h2 \
  | tar -xzvf -

# 进入项目目录
cd demo

Maven 构建配置

pom.xml 核心结构

xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- 父 POM：定义依赖版本 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.4.0</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>demo</name>
    <description>Spring Boot Demo Application</description>

    <properties>
        <java.version>21</java.version>
    </properties>

    <dependencies>
        <!-- Web 开发起步依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Spring Boot 测试起步依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- Spring Boot Maven 插件：打 fat jar -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

spring-boot-starter-parent 是 Spring Boot 的版本仲裁中心，它统一管理所有 Starter 依赖的版本号，你无需关心版本兼容性问题。

Gradle（可选）

groovy

// build.gradle
plugins {
    id 'java'
    id 'org.springframework.boot' version '3.4.0'
    id 'io.spring.dependency-management' version '1.1.7'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    sourceCompatibility = '21'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

项目目录结构

Spring Boot 采用约定优于配置的哲学，标准目录结构如下：

plaintext

demo/
├── src/
│   ├── main/
│   │   ├── java/com/example/demo/
│   │   │   ├── DemoApplication.java    ← 启动类（含 main 方法）
│   │   │   ├── controller/              ← 控制器层
│   │   │   ├── service/                 ← 业务逻辑层
│   │   │   ├── repository/             ← 数据访问层
│   │   │   └── config/                 ← 配置类
│   │   └── resources/
│   │       ├── application.yml         ← 应用配置
│   │       ├── static/                 ← 静态资源（CSS/JS/图片）
│   │       └── templates/              ← 模板文件（Thymeleaf/Freemarker）
│   └── test/
│       └── java/com/example/demo/
│           └── DemoApplicationTests.java
├── pom.xml
└── mvnw / mvnw.cmd                     ← Maven Wrapper 脚本

关键约定：

启动类必须放在根包下（com.example.demo），且包含 @SpringBootApplication 注解
resources/application.yml 是默认配置文件
src/main/java 下的类会被自动扫描注册为 Bean

第一个可运行应用

启动类

java

// DemoApplication.java
package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        // 启动 Spring Boot 应用
        SpringApplication.run(DemoApplication.class, args);
    }
}

@SpringBootApplication 是 Spring Boot 最核心的注解，它组合了三个注解：

@SpringBootConfiguration：标注当前类为配置类（等同于 @Configuration）
@EnableAutoConfiguration：启用自动配置
@ComponentScan：默认扫描启动类所在包及其子包中的组件

第一个控制器

java

// controller/HelloController.java
package com.example.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello, Spring Boot 3!";
    }
}

运行应用

bash

# Maven 方式
./mvnw spring-boot:run

# 或先打包再运行
./mvnw package
java -jar target/demo-0.0.1-SNAPSHOT.jar

启动后访问 http://localhost:8080/hello，页面将显示 Hello, Spring Boot 3!。

Spring Boot 启动时会打印一个 ASCII 艺术 banner。你可以通过在 src/main/resources/ 下添加 banner.txt 自定义：

txt

${AnsiColor.BRIGHT_RED}
   ____      _ _
  / ___|__ _| | |_
 | |   / _` | | __|
 | |__| (_| | | |_
  \____\__,_|_|\__|
${AnsiColor.DEFAULT}
Spring Boot ${spring-boot.version}

常见问题

端口被占用

yaml

# application.yml
server:
  port: 8080  # 默认端口，可自定义

连接仓库慢

将 Maven 仓库切换为阿里云镜像：

xml

<!-- ~/.m2/settings.xml -->
<mirrors>
  <mirror>
    <id>aliyun</id>
    <mirrorOf>central</mirrorOf>
    <url>https://maven.aliyun.com/repository/central</url>
  </mirror>
</mirrors>

小结

本文完成了以下内容：

安装并验证 JDK 17+ 和 Maven 3.8+ 环境
使用 Spring Initializr 创建标准 Spring Boot 项目
理解 pom.xml 的核心配置与 spring-boot-starter-parent 的版本仲裁机制
熟悉 Spring Boot 标准项目目录结构
运行了第一个包含 REST 控制器的 Spring Boot 应用

下一篇文章我们将深入 Spring Boot 自动配置原理，理解 @SpringBootApplication 背后的工作机制。

Spring Boot 3 环境准备与项目初始化

Spring Boot 3 环境准备与项目初始化

环境准备

必要工具

验证环境

使用 Spring Initializr 创建项目

网页方式

命令行方式（更推荐）

Maven 构建配置

pom.xml 核心结构

Gradle（可选）

项目目录结构

第一个可运行应用

启动类

第一个控制器

运行应用

自动 banner

常见问题

端口被占用

连接仓库慢

小结

评论

Related Articles

Spring Boot 3 环境准备与项目初始化

Spring Boot 3 监控、可观测性与性能调优

Spring Security 安全认证