从零上手Spring Boot：60分钟打造一个完整小项目

起因：为什么突然要写这个教程？

去年在公司接手了一个新项目，是给一家物流公司做的内部调度系统。时间紧任务重，要求一个月内上线一套可以稳定运行的基础模块，包括订单管理、司机调度和路线规划等几个核心功能。

当时我们团队的前端人手紧缺，后端这边也需要快速搭建出一套可以上线的服务。这个时候，Spring Boot 的优势就显现出来了 —— 它的自动配置机制和开箱即用的设计，让我们能迅速搭建起服务框架，把更多精力集中在业务逻辑开发上。

这篇笔记，就是我从接到需求到部署上线这60分钟内踩过的坑、用到的技术和一些经验总结。希望对你理解 Spring Boot 的基本用法，有所帮助。

---

我们遇到了什么问题？

这个项目一开始，我们的痛点很明确：

• 开发效率太慢，传统 Spring XML 配置麻烦
• 每次启动应用都要手动配置 Tomcat、数据库连接池等等
• 接口设计不统一，不同开发者风格不一
• 微服务架构逐渐成为主流，但老的结构难以升级

更严重的是，我们要在两周内交付第一个可测试版本（MVP），这意味着我们必须尽可能减少“基础设施”建设的时间，专注于实现业务。

这时候团队里有同事建议：“不如直接用 Spring Boot 吧，它内置了各种 starter，连接口文档都能自动生成。”

这句话让我眼前一亮，于是决定尝试 Spring Boot。

---

我们的方案：Spring Boot + MyBatis Plus + Swagger2

整个项目的后端技术栈如下：

Java 17
Spring Boot 2.7.x
MyBatis Plus 3.5.x
Swagger2 (现在也可以用 OpenAPI 3.0)
MySQL 8.0
Redis 6.x
Lombok
Gradle 构建

为什么选择 Spring Boot？

主要基于以下几个考虑点：

1. 自动化配置：不用再写一堆 XML 配置。
2. Starter 包丰富：比如 spring-boot-starter-data-jpa、spring-boot-starter-web 这类 starter 极大地节省了依赖管理成本。
3. 内置服务器：Tomcat 已经打包好了，只需要写代码就能跑起来。
4. 监控和健康检查：actuator 组件自带了 /health、/info 等实用接口。
5. 集成方便：配合 Swagger、Redis、RabbitMQ 都特别简单。

---

实践一下：动手搭建一个小项目

下面我们就来模拟一次实际开发流程，用 Spring Boot 快速搭一个简单的订单管理系统。

第一步：创建 Spring Boot 项目（5分钟）

可以用 start.spring.io 来初始化，或者用 IntelliJ IDEA 直接生成。

需要引入的核心依赖：

implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
implementation 'mysql:mysql-connector-java'
implementation 'com.baomidou:mybatis-plus-boot-starter:3.5.3.1'
implementation 'io.swagger:swagger2:3.0.0'
runtimeOnly 'org.postgresql:postgresql'
developmentOnly 'org.springframework.boot:spring-boot-devtools'
annotationProcessor 'org.projectlombok:lombok'

第二步：配置数据库连接（application.yml）

server:
  port: 8080
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/logistics?useSSL=false&serverTimezone=UTC&characterEncoding=utf8
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver
  jpa:
    hibernate:
      use-new-id-generator-mappings: false
    show-sql: true
mybatis-plus:
  configuration:
    mapUnderscoreToCamelCase: true

这里有几个注意点：

• 如果你用的是 MySQL 8.0，记得添加 serverTimezone=UTC。
• mapUnderscoreToCamelCase: true 是为了自动将下划线字段映射成驼峰命名。
• JPA 的配置主要是为了兼容性，如果你用的是 MyBatis Plus，可以去掉。

第三步：创建实体类 Order.java

@Entity
@Data
@Accessors(chain = true)
public class Order {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    private String orderId;
    
    private String startAddress;
    
    private String endAddress;
    
    private BigDecimal amount;
    
    private Integer status;
}

使用 Lombok 的 @Data 自动生成 getter/setter/toString 等方法，非常方便。

第四步：编写 Mapper 和 Service

用 MyBatis Plus 写一个简单的接口：

public interface OrderMapper extends BaseMapper<Order> {}

Service 层：

@Service
public class OrderService {

    @Autowired
    private OrderMapper orderMapper;

    public List<Order> getAllOrders() {
        return orderMapper.selectList(null);
    }

    public Order getOrderById(Long id) {
        return orderMapper.selectById(id);
    }

    public boolean createOrder(Order order) {
        return orderMapper.insert(order) > 0;
    }
}

是不是很干净？比原来的手动写 SQL 要少一半代码。

第五步：编写 Controller 控制器（加 Swagger）

@RestController
@RequestMapping("/api/orders")
@Api(tags = "订单管理接口")
public class OrderController {

    @Autowired
    private OrderService orderService;

    @GetMapping("/")
    @ApiOperation("获取所有订单")
    public List<Order> getAll() {
        return orderService.getAllOrders();
    }

    @GetMapping("/{id}")
    @ApiOperation("根据ID查询订单")
    public Order getById(@PathVariable Long id) {
        return orderService.getOrderById(id);
    }

    @PostMapping("/")
    @ApiOperation("创建新订单")
    public Boolean create(@RequestBody Order order) {
        return orderService.createOrder(order);
    }
}

加上 Swagger 注解之后，访问 /swagger-ui.html 就能直接看到接口文档。

第六步：启动并测试

运行主类：

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

启动后访问 http://localhost:8080/api/orders/，应该能看到接口正常返回数据（如果数据库里有测试数据的话）。

---

踩坑实录：我在开发中遇到的真实问题

别以为一切顺利，其实过程并不轻松。这里分享几个实战中的典型坑，都是血泪教训。

坑一：Swagger 文档不显示

一开始写了 Swagger 注解，但在浏览器里却看不到任何 API。查了一下发现没有启用 Swagger 配置。

解决方案：增加一个 SwaggerConfig.java：

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("物流系统API文档")
                .description("基于Spring Boot和Swagger2"))
                .externalDocs(new ExternalDocumentation()
                .description("GitHub地址")
                .url("https://github.com/your/project"));
    }
}

坑二：MyBatis Plus 的 insert 方法返回 false

插入数据时 insert() 返回 false，后来发现是因为某些字段用了 null，而字段设置为 not null 导致失败。

解决方式：

• 数据校验前置
• 使用 @TableField(fill = FieldFill.INSERT) 自动填充默认值

坑三：Spring Boot 的自动扫描失效

有时候写完类但是 Spring 报找不到 bean，原因是组件扫描路径不对。

解决方式：确保启动类上加了 @ComponentScan 或者目录结构合理，如：

com.example.logistics.LogisticsApplication  // 主类
com.example.logistics.controller            // controller 放这里
com.example.logistics.service               // service 放这里

---

效果回顾：项目上线后的表现

这套系统我们只用了两周多时间完成初版，部署上线之后：

• 接口响应时间平均在 100ms 内（MySQL 查询 + Redis 缓存）
• 单机 QPS 在 500+ 左右（还没做性能调优）
• 开发效率大大提高，接口文档也省去了手写的过程
• 日志输出统一，异常处理标准化，后续维护更轻松

而且我们还加入了定时任务、消息队列等扩展功能，整个架构也比较清晰。

---

从实践中得出的经验总结

1. 明确选型理由，不要为用而用

Spring Boot 虽然好用，但也不是银弹。比如小型工具脚本、静态资源托管、或者对性能极致要求的场景，可能更适合 Go 或 Rust。但如果你是要快速构建微服务、企业级后台，Spring Boot 的生态优势非常明显。

2. 分清职责：Controller、Service、Dao 各司其职

虽然代码简洁了，但也不能全塞在一个类里面。良好的分层结构会让你的项目更容易维护，尤其是在多人协作时尤为重要。

3. 多利用 IDE 提升编码效率

比如 IntelliJ IDEA 提供了 Spring Initializr 插件可以直接生成项目骨架，Lombok 插件可以解析注解，还有代码热加载等功能大大提升了开发效率。

4. 不要忽视配置文件管理

推荐使用 YAML 而不是 properties 文件，层次更清晰。还可以通过 @PropertySource 动态读取外部配置。

5. 关注线上监控和日志分析

哪怕是一个刚上线的小系统，也建议至少接入 Prometheus + Grafana 做基础监控。生产环境中日志收集也很重要，ELK 可以帮助你快速定位问题。

---

给新人的一些建议

如果你是个刚入门的后端开发者，想快速掌握 Spring Boot，我的建议是：

• 先了解 Java 核心语法，尤其是 IO/NIO、集合、泛型这些
• 学习 Spring 框架的基本原理（控制反转、AOP）
• 掌握 Restful API 设计规范，这是现代后端接口的标准
• 熟悉 Maven / Gradle 依赖管理工具
• 最好会一点前后端分离的知识，比如对接 Vue.js 或 React
• 多看看 GitHub 上开源项目是如何组织代码结构的

最后，一定要边学边敲代码。看再多不如亲手写一遍。

---

结语：60分钟不只是快速起步，而是通往未来的起点

这篇文章虽然叫“60分钟快速上手”，但实际上远远不止这60分钟。这只是你迈入 Spring Boot 世界的开始。

作为开发者，我们面对的每一个项目都不是孤立的，背后都有复杂的业务逻辑、技术选型甚至团队协作。真正能解决问题的，从来不是某个框架本身，而是你对它的理解与灵活运用。

Spring Boot 让我们更快地把想法落地，也让更多精力投入到创新和优化上。希望你在学习过程中也能找到属于自己的节奏，让开发变得更高效、更有温度。

祝你好运。