一、环境准备（超详细版）

搭建前必须确保环境配置正确，这是避免后续踩坑的关键：

1. 安装并验证 JDK

• 下载 JDK

  ：

  • JDK 8（兼容 Spring Boot 2.x）：Oracle 官网 或 OpenJDK
  • JDK 17（兼容 Spring Boot 3.x）：Oracle 官网 或 OpenJDK

• 安装步骤

  ：

  • 双击安装包，一路下一步（建议安装路径不要有中文 / 空格，如 D:\jdk17）。

• 配置环境变量

  （Windows 为例）：

  1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」。

  2. 系统变量

     → 新建：

     • 变量名：JAVA_HOME
     • 变量值：JDK 安装路径（如 D:\jdk17）

  3. 编辑系统变量中的

     1

     Path

     → 新建：

     • %JAVA_HOME%\bin

  4. 验证：Win+R 输入

     1

     cmd

     ，执行

     1	java -version

     ，输出如下则成功：

     1 2 3

     java version "17.0.8" 2023-07-18 LTS Java(TM) SE Runtime Environment (build 17.0.8+9-LTS-211) Java HotSpot(TM) 64-Bit Server VM (build 17.0.8+9-LTS-211, mixed mode, sharing)

2. 安装开发工具（IDEA 详细配置）

• 下载 IDEA：IntelliJ IDEA 官网，选择「Community 社区版」（免费）。

• 安装 IDEA

  ：

  • 双击安装包，勾选「64-bit launcher」「.java/.groovy/.kt 等文件关联」，安装路径建议非中文（如 D:\IDEA）。

• 配置 IDEA 中的 JDK

  ：

  1. 打开 IDEA，点击「File」→「Project Structure」（快捷键 Ctrl+Alt+Shift+S）。
  2. 左侧「Platform Settings」→「SDKs」→ 右上角「+」→「Add SDK」→「JDK」。
  3. 选择本地 JDK 安装路径（如 D:\jdk17），点击「OK」。
  4. 左侧「Project Settings」→「Project」，将「SDK」选为刚配置的 JDK，「Language level」选对应版本（如 JDK 17 选 17）。

3. 验证 Maven（IDEA 内置，无需额外安装）

IDEA 内置了 Maven，只需配置镜像（解决依赖下载慢）：

1. 打开 IDEA →「File」→「Settings」（Ctrl+Alt+S）→ 搜索「Maven」。

2. 确认「Maven home directory」为 IDEA 内置路径（如 D:\IDEA\plugins\maven\lib\maven3）。

3. 勾选「Override」，修改「User settings file」为自定义 settings.xml（若无则新建），内容如下（配置阿里云镜像）：

   1 2 3 4 5 6 7 8 9 10 11 12 13

   <?xml version="1.0" encoding="UTF-8"?> <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> <mirrors> <!-- 阿里云 Maven 镜像 --> <mirror> <id>aliyunmaven</id> <mirrorOf>central</mirrorOf> <url>https://maven.aliyun.com/repository/public</url> </mirror> </mirrors> </settings>

4. 点击「Apply」→「OK」完成配置。

二、IDEA 中搭建 Spring Boot 项目（分步实操）

以 Spring Boot 3.2.x + JDK 17 为例，每一步都标注注意事项：

步骤 1：新建项目

1. 打开 IDEA，点击「New Project」（若已有项目，点击「File」→「New」→「Project」）。

2. 左侧选择「Spring Initializr」：

   • 右侧「SDK」：选择已配置的 JDK 17（必须和后续项目配置一致）。
   • 「Initializr Service URL」：默认 https://start.spring.io/（无需修改）。
   • 点击「Next」。

步骤 2：配置项目元数据（关键）

配置完成后点击「Next」。

步骤 3：选择依赖（新手必选）

在「Dependencies」搜索框中输入并勾选以下依赖（后续可在 pom.xml 中添加）：

• Spring Web：核心依赖，提供 Web 开发能力（MVC、Tomcat、RESTful 等）。
• Lombok：简化代码，自动生成 getter/setter/toString 等方法。
• Spring Boot DevTools（可选）：热部署，修改代码后无需重启项目（开发效率提升）。

勾选后点击「Next」。

步骤 4：确认项目路径并创建

1. 「Project name」：自动填充为 Artifact 名称（springboot-demo）。
2. 「Project location」：选择非中文 / 无空格的路径（如 D:\code\springboot-demo）。
3. 点击「Finish」，IDEA 会自动下载 Maven 依赖（首次下载可能需要 1-3 分钟，耐心等待）。

三、项目结构深度解析（新手必懂）

创建完成后，项目结构如下（标注每个文件的作用）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

springboot-demo/
├── .idea/                # IDEA 配置文件（无需关注）
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/demo/  # 基础包
│   │   │       ├── DemoApplication.java  # 启动类（核心！不可删/改名/移包）
│   │   │       ├── controller/           # 控制器（接口层，存放接口代码）
│   │   │       ├── service/             # 服务层（业务逻辑）
│   │   │       ├── mapper/              # 数据访问层（操作数据库）
│   │   │       └── entity/              # 实体类（对应数据库表/返回数据）
│   │   └── resources/                   # 资源目录
│   │       ├── application.properties   # 全局配置文件（端口、数据库等）
│   │       ├── static/                  # 静态资源（CSS/JS/图片）
│   │       └── templates/               # 模板文件（Thymeleaf/Freemarker）
│   └── test/                            # 测试目录（单元测试）
├── target/                              # 编译后的文件（自动生成）
├── pom.xml                              # Maven 依赖配置（核心！管理依赖版本）
└── HELP.md                              # 帮助文档（可删）

核心文件说明：

1. DemoApplication.java（启动类）：

   1 2 3 4 5 6 7 8 9 10 11 12 13 14

   package com.example.demo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; // 核心注解：标识 Spring Boot 应用，自动配置/组件扫描/启用自动配置 @SpringBootApplication public class DemoApplication { // 程序入口：启动 Spring Boot 项目 public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }

   • 注意：启动类必须放在最外层包（如 com.example.demo），否则无法扫描子包（controller/service 等）。

2. pom.xml（依赖配置）：

   核心依赖片段（自动生成）：

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

   <!-- Spring Boot 父工程：统一管理依赖版本，无需手动指定版本号 --> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.1</version> <relativePath/> </parent> <!-- Web 核心依赖 --> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- Lombok 依赖 --> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> <!-- 测试依赖 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies>

四、编写并测试接口（完整流程）

步骤 1：创建控制器类

在 com.example.demo 下新建 controller 包，创建 HelloController.java：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

package com.example.demo.controller;

import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

// 1. 标识为 REST 控制器：返回 JSON 数据（而非页面）
// 2. 替代 @Controller + @ResponseBody
@RestController
// Lombok 注解：自动生成日志对象（无需手动 new Logger）
@Slf4j
public class HelloController {

    // 定义 GET 请求接口，路径：/hello
    @GetMapping("/hello")
    public String hello() {
        // 打印日志（测试用）
        log.info("接收到 /hello 请求");
        return "Hello Spring Boot! 搭建成功！";
    }

    // 进阶：带参数的接口（路径参数）
    @GetMapping("/hello/{name}")
    public String helloWithName(@PathVariable String name) {
        log.info("接收到 /hello/{} 请求", name);
        return "Hello, " + name + "! 这是带参数的 Spring Boot 接口";
    }
}

步骤 2：启动项目

1. 找到 DemoApplication.java，右键点击「Run DemoApplication」。

2. 查看控制台日志，出现以下内容说明启动成功：

   1 2	2026-01-10 10:00:00.000 INFO 12345 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8080 (http) with context path '' 2026-01-10 10:00:00.001 INFO 12345 --- [ main] com.example.demo.DemoApplication : Started DemoApplication in 2.5 seconds (process running for 3.0)

   • 常见启动失败原因：端口 8080 被占用（解决方案见下文）。

步骤 3：访问接口验证

1. 打开浏览器 / Postman，访问：

   • 无参数接口：

     1	http://localhost:8080/hello

     输出：

     1	Hello Spring Boot! 搭建成功！

   • 带参数接口：

     1	http://localhost:8080/hello/张三

     输出：

     1	Hello, 张三! 这是带参数的 Spring Boot 接口

2. 查看 IDEA 控制台，会打印日志：

   1 2	2026-01-10 10:01:00.000 INFO 12345 --- [nio-8080-exec-1] c.e.d.controller.HelloController : 接收到 /hello 请求 2026-01-10 10:02:00.000 INFO 12345 --- [nio-8080-exec-2] c.e.d.controller.HelloController : 接收到 /hello/张三 请求

五、常见问题及解决方案（避坑指南）

问题 1：端口 8080 被占用

• 解决方案：修改

  1	application.properties

  配置文件，添加：

  1 2	# 自定义端口为 8081 server.port=8081

  重启项目后，访问地址变为

  1	http://localhost:8081/hello

  。

问题 2：Maven 依赖下载慢 / 失败

• 解决方案：

  1. 确认已配置阿里云镜像（见上文 IDEA Maven 配置）。
  2. IDEA 中点击「File」→「Invalidate Caches / Restart」→「Invalidate and Restart」，清空缓存重启。
  3. 手动删除 ~/.m2/repository（Maven 本地仓库）中的报错依赖，重新下载。

问题 3：启动类扫描不到控制器

• 原因：启动类所在包层级低于控制器（如启动类在 com.example，控制器在 com.example.demo.controller）。

• 解决方案：

  1. 将启动类移到最外层包（如 com.example.demo）。

  2. 或在启动类上添加

     1	@ComponentScan

     指定扫描包：

     1 2 3

     @SpringBootApplication @ComponentScan("com.example") // 扫描 com.example 下所有包 public class DemoApplication { ... }

总结

1. 环境核心：JDK 版本与 Spring Boot 版本匹配（3.x→JDK17+，2.x→JDK8+），配置阿里云 Maven 镜像解决依赖下载问题。
2. 搭建关键：启动类是项目入口（不可移包 / 改名），@SpringBootApplication 注解是核心，依赖按需选择（新手先加 Spring Web + Lombok）。
3. 测试验证：编写简单接口，通过浏览器 / Postman 访问，控制台日志是排查问题的重要依据。