60分钟带你跑通Spring Boot第一个项目

写在前面：我当初从培训班出来，第一次接触 Spring Boot 的时候，被那些配置折腾了整整两天。Maven 依赖冲突、端口被占用、注解看不懂……踩过的坑比写过的代码还多。后来带学生，发现大家踩的坑跟我当年一模一样。所以今天这篇文章，我把所有新手会遇到的问题都提前帮你避开了，跟着走，60 分钟之内你一定能跑通第一个项目。

---

一、Spring Boot 到底是什么？

用一句话讲：Spring Boot 就是帮你省掉一堆配置，让你专注写业务代码的工具。

你肯定听说过 Spring 框架，那是 Java 后端开发的"老大哥"。但传统的 Spring 项目，光配置文件就能写到你怀疑人生——web.xml、applicationContext.xml、dispatcher-servlet.xml……每个文件都有几十上百行，新手根本搞不清楚哪个是干嘛的。

Spring Boot 的出现就是为了解决这个问题。它的核心理念叫 "约定优于配置"（Convention Over Configuration），意思是：大部分配置它都帮你默认设好了，你只需要关注那些需要自定义的部分。

打个比方：传统 Spring 就像毛坯房，你得自己装修每一步；Spring Boot 就像精装房，拎包入住，想改哪里再微调。

对比项	传统 Spring	Spring Boot
配置文件	大量 XML	几乎不需要 XML
依赖管理	手动管理版本	提供 starter 依赖包
项目启动	需要部署到 Tomcat	内嵌 Tomcat，直接运行 main 方法
上手难度	高，需要理解大量概念	低，快速启动

---

二、环境准备：工欲善其事

我当初学的时候，环境搭建就卡了大半天。下面我把步骤拆得特别细，你跟着做就行。

2.1 安装 JDK

Spring Boot 3.x 要求 JDK 17 及以上版本。

步骤：

1. 去 Oracle 官网或 Adoptium 下载 JDK 17
2. 安装完成后，打开终端/命令行，输入：

java -version

看到类似 openjdk version "17.0.x" 的输出就说明安装成功了。

3. 配置环境变量：
   • JAVA_HOME 指向 JDK 安装目录
   • 把 %JAVA_HOME%\bin 加入 PATH

2.2 安装 IDE

推荐用 IntelliJ IDEA（社区版免费）。我当初用的 Eclipse，后来换了 IDEA 就再也没回去过，代码提示和调试功能确实强很多。

2.3 安装 Maven

Maven 是 Java 的依赖管理工具，类似于前端的 npm。Spring Boot 项目基本都用 Maven 来管理依赖。

mvn -version

能输出版本号就说明安装成功了。

小提示： IDEA 社区版自带 Maven，如果你用 IDEA 开发，这一步可以跳过。

---

三、创建第一个 Spring Boot 项目

3.1 使用 Spring Initializr

这是官方提供的项目生成工具，地址：https://start.spring.io

你也可以直接在 IDEA 里操作：File → New → Project → Spring Initializr

填写项目信息：

配置项	建议值
Project	Maven
Language	Java
Spring Boot	3.2.x（选最新稳定版）
Group	com.example（你的域名反写）
Artifact	demo（项目名）
Packaging	Jar
Java	17

Dependencies（依赖）选择：

• Spring Web（提供 Web 开发能力）
• Lombok（减少样板代码，可选）

点击 Create，IDEA 会自动下载依赖并创建项目。第一次创建会比较慢，因为要下载一堆 jar 包，耐心等一下。

3.2 项目结构认识

创建完成后，你会看到这样的目录结构：

demo/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           └── demo/
│   │   │               └── DemoApplication.java    ← 启动类
│   │   └── resources/
│   │       ├── static/          ← 静态资源（CSS、JS、图片）
│   │       ├── templates/       ← 模板文件（Thymeleaf等）
│   │       └── application.yml  ← 配置文件
│   └── test/                    ← 测试代码
├── pom.xml                      ← Maven 配置文件
└── .gitignore

重点记住这几个位置：

• DemoApplication.java：项目入口，点它的 main 方法就能启动
• application.yml：配置文件，改端口、数据库连接都在这
• pom.xml：管理依赖，需要引入新的第三方库就改这里

---

四、核心概念：这几个注解你必须懂

我当初学的时候，最头疼的就是各种注解。其实 Spring Boot 常用的注解就那么几个，理解透了就够用了。

4.1 @SpringBootApplication

打开启动类，你会看到这个注解：

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

这个注解是个"三合一"注解，它等于：

• @Configuration：标记这是一个配置类
• @EnableAutoConfiguration：开启自动配置（Spring Boot 的核心魔法）
• @ComponentScan：自动扫描当前包及子包下的组件

通俗理解： 它告诉 Spring Boot——"我是入口，你帮我把该加载的都加载了。"

4.2 @RestController 和 @RequestMapping

这两个注解用来写接口，是最常用的：

@RestController
@RequestMapping("/api")
public class HelloController {

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

    @GetMapping("/hello/{name}")
    public String helloName(@PathVariable String name) {
        return "Hello, " + name + "!";
    }

    @GetMapping("/search")
    public String search(@RequestParam String keyword) {
        return "搜索关键词：" + keyword;
    }
}

逐个解释：

• @RestController：标记这是一个控制器，并且返回值直接作为 HTTP 响应体（相当于 @Controller + @ResponseBody）
• @RequestMapping("/api")：类级别的 URL 前缀，所有接口都以 /api 开头
• @GetMapping：处理 GET 请求
• @PathVariable：获取 URL 路径中的参数，比如 /hello/Tom 中的 Tom
• @RequestParam：获取查询参数，比如 /search?keyword=Java 中的 Java

4.3 常用注解速查表

注解	作用	使用场景
@RestController	标记 REST 控制器	写接口
@RequestMapping	映射 URL	类或方法级别
@GetMapping	映射 GET 请求	查询数据
@PostMapping	映射 POST 请求	新增数据
@PutMapping	映射 PUT 请求	修改数据
@DeleteMapping	映射 DELETE 请求	删除数据
@PathVariable	获取路径参数	/users/{id}
@RequestParam	获取查询参数	?name=xxx
@RequestBody	获取请求体 JSON	POST 提交 JSON
@Autowired	自动注入依赖	注入 Service、Repository

---

五、实战：写一个待办事项 API

光看概念太抽象了，我们直接上手写一个完整的待办事项（Todo）增删改查接口。

5.1 创建实体类

package com.example.demo.entity;

public class Todo {
    private Long id;
    private String title;
    private boolean completed;

    // 构造方法
    public Todo(Long id, String title, boolean completed) {
        this.id = id;
        this.title = title;
        this.completed = completed;
    }

    // Getter 和 Setter
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }

    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }

    public boolean isCompleted() { return completed; }
    public void setCompleted(boolean completed) { this.completed = completed; }
}

如果你引入了 Lombok，可以用 @Data 注解替代所有 getter/setter/构造方法，代码会简洁很多。

5.2 创建 Service 层

Service 层负责处理业务逻辑。为了简单，我们用内存存储（实际项目会用数据库）：

package com.example.demo.service;

import com.example.demo.entity.Todo;
import org.springframework.stereotype.Service;
import java.util.*;
import java.util.concurrent.atomic.AtomicLong;

@Service
public class TodoService {

    private final Map<Long, Todo> todoStore = new HashMap<>();
    private final AtomicLong idGenerator = new AtomicLong(1);

    // 获取所有待办
    public List<Todo> getAll() {
        return new ArrayList<>(todoStore.values());
    }

    // 根据 ID 获取
    public Todo getById(Long id) {
        return todoStore.get(id);
    }

    // 新增
    public Todo create(Todo todo) {
        Long id = idGenerator.getAndIncrement();
        todo.setId(id);
        todoStore.put(id, todo);
        return todo;
    }

    // 修改
    public Todo update(Long id, Todo todo) {
        if (!todoStore.containsKey(id)) {
            return null;
        }
        todo.setId(id);
        todoStore.put(id, todo);
        return todo;
    }

    // 删除
    public boolean delete(Long id) {
        return todoStore.remove(id) != null;
    }
}

5.3 创建 Controller 层

package com.example.demo.controller;

import com.example.demo.entity.Todo;
import com.example.demo.service.TodoService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.List;

@RestController
@RequestMapping("/api/todos")
public class TodoController {

    @Autowired
    private TodoService todoService;

    // 查询所有
    @GetMapping
    public List<Todo> getAll() {
        return todoService.getAll();
    }

    // 根据 ID 查询
    @GetMapping("/{id}")
    public ResponseEntity<Todo> getById(@PathVariable Long id) {
        Todo todo = todoService.getById(id);
        if (todo == null) {
            return ResponseEntity.notFound().build();
        }
        return ResponseEntity.ok(todo);
    }

    // 新增
    @PostMapping
    public Todo create(@RequestBody Todo todo) {
        return todoService.create(todo);
    }

    // 修改
    @PutMapping("/{id}")
    public ResponseEntity<Todo> update(@PathVariable Long id, @RequestBody Todo todo) {
        Todo updated = todoService.update(id, todo);
        if (updated == null) {
            return ResponseEntity.notFound().build();
        }
        return ResponseEntity.ok(updated);
    }

    // 删除
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> delete(@PathVariable Long id) {
        if (todoService.delete(id)) {
            return ResponseEntity.noContent().build();
        }
        return ResponseEntity.notFound().build();
    }
}

5.4 启动并测试

点击 DemoApplication 的 main 方法运行，看到类似下面的日志就说明启动成功了：

Tomcat started on port(s): 8080 (http)
Started DemoApplication in 2.3 seconds

测试接口（用浏览器、Postman 或 curl）：

# 新增一个待办
curl -X POST http://localhost:8080/api/todos \
  -H "Content-Type: application/json" \
  -d '{"title":"学习Spring Boot","completed":false}'

# 查询所有
curl http://localhost:8080/api/todos

# 根据 ID 查询
curl http://localhost:8080/api/todos/1

# 修改
curl -X PUT http://localhost:8080/api/todos/1 \
  -H "Content-Type: application/json" \
  -d '{"title":"学习Spring Boot（已完成）","completed":true}'

# 删除
curl -X DELETE http://localhost:8080/api/todos/1

恭喜你！到这里你已经完成了一个完整的 RESTful API。

---

六、配置文件详解

打开 src/main/resources/application.yml（或 application.properties），这是 Spring Boot 的全局配置文件。

server:
  port: 8080                    # 服务端口，默认8080
  servlet:
    context-path: /app          # 应用前缀，加了之后所有接口变成 /app/api/todos

spring:
  application:
    name: demo                  # 应用名称
  jackson:
    date-format: yyyy-MM-dd HH:mm:ss  # JSON 日期格式
    time-zone: GMT+8

我当初踩过的坑：

• 端口 8080 被占用：改成别的端口，比如 8081
• yml 格式对缩进很敏感，一定要用空格，不能用 Tab
• 配置文件修改后需要重启项目才生效

---

七、关于 AI 辅助开发的思考

写到这里，我想聊一个跟技术本身无关但很重要的话题。

现在 AI 编程工具发展很快，比如 Augment Code 这样的 AI 编码助手，可以在你写代码的时候提供智能补全、代码生成、Bug 修复建议。对于新手来说，这类工具确实能加速学习过程——你卡在一个问题上，AI 能快速给你思路和代码片段。

还有像 Runway 这样的创意 AI 平台，虽然主要面向视频和多媒体生成，但它代表的趋势是：AI 正在渗透到开发的各个环节。作为开发者，我们需要学会跟 AI 协作，而不是抗拒它。

但我要特别强调一点： AI 工具是加速器，不是替代品。

我当初学 Spring Boot 的时候，没有 AI 工具，每个报错都要自己查文档、看日志、翻 Stack Overflow。过程很痛苦，但正是那些痛苦让我真正理解了框架的原理。如果你一上来就完全依赖 AI 生成代码，你会变成一个"代码搬运工"，遇到 AI 解决不了的问题就抓瞎。

正确的使用姿势：

1. 先自己思考和尝试，实在搞不定再问 AI
2. AI 给你的代码，一定要理解每一行在做什么
3. 用 AI 来验证你的思路，而不是让它替你思考
4. 把 AI 当成一个随时在线的高级同事，而不是代写作业的枪手

---

八、新手常见问题 FAQ

Q1：启动报错 "Port 8080 already in use"

原因： 8080 端口被其他程序占用了。

解决：

# Windows 查找占用端口的进程
netstat -ano | findstr :8080
# 然后用 taskkill 杀掉对应进程

# Mac/Linux
lsof -i :8080
kill -9 <PID>

或者直接在 application.yml 里改端口：

server:
  port: 8081

Q2：启动报错 "BeanCreationException"

原因： 通常是依赖注入失败，比如 @Autowired 的类没有被 Spring 管理。

解决： 检查目标类是否加了 @Service、@Component 等注解。

Q3：接口返回 404

排查步骤：

1. 检查 URL 路径是否正确（注意 context-path）
2. 检查 Controller 是否被扫描到（要在启动类的包或子包下）
3. 检查 HTTP 方法是否匹配（GET 接口用 POST 请求会 405）

Q4：返回的 JSON 字段名跟实体类不一致

解决： 用 @JsonProperty 注解指定：

@JsonProperty("todo_title")
private String title;

Q5：依赖下载特别慢

解决： 配置 Maven 国内镜像源，在 ~/.m2/settings.xml 中添加阿里云镜像：

<mirrors>
  <mirror>
    <id>aliyun</id>
    <mirrorOf>central</mirrorOf>
    <url>https://maven.aliyun.com/repository/central</url>
  </mirror>
</mirrors>

---

九、下一步学什么？

跑通第一个项目只是起点，后面还有很多东西要学。我根据重要性给你排个优先级：

第一阶段（1-2 周）：打牢基础

• Spring Boot 整合数据库：学习 Spring Data JPA 或 MyBatis，把内存存储换成真正的数据库
• 统一响应格式：封装一个 Result<T> 类，让所有接口返回统一的结构
• 全局异常处理：用 @ControllerAdvice 统一处理异常

第二阶段（2-4 周）：进阶能力

• Spring Security：学习认证和授权，给接口加上登录验证
• 参数校验：用 @Valid + @NotBlank 等注解做入参校验
• Swagger/Knife4j：自动生成 API 文档
• 日志管理：用 SLF4J + Logback 规范日志输出

第三阶段（1-2 月）：工程化实践

• Docker 部署：把项目打包成 Docker 镜像
• Redis 缓存：学习缓存的使用场景
• 消息队列：了解 RabbitMQ 或 Kafka
• 微服务入门：学习 Spring Cloud 基础组件

---

十、最后说几句掏心窝的话

我当初从培训班出来的时候，简历上写的是"精通 Spring Boot"，面试官问我自动配置原理，我直接懵了。后来花了很长时间才把基础补上来。

所以我想告诉你：入门只是开始，别被"60 分钟快速上手"这种标题骗了。 真正的功夫在后面的持续学习和项目实践中。

几个建议：

1. 不要只看不写：教程看十遍不如自己敲一遍
2. 学会看报错日志：Spring Boot 的报错信息其实很详细，耐心读，答案就在里面
3. 多造轮子：试着不看教程自己写一个小项目，写不出来再查
4. 加入社区：遇到问题去 SegmentFault、掘金、Stack Overflow 搜，大部分问题别人都遇到过

Spring Boot 是 Java 后端开发的基石，学好了它，后面学微服务、学云原生都会顺畅很多。加油，你可以的！