用最小可运行的项目结构理解控制器、依赖注入与自动配置，跑通第一个返回 JSON 的接口。
本文要点
- 项目分层：controller / service / repository 各司其职
- 用 @RestController 与 @GetMapping 暴露接口
- 通过配置文件区分开发与生产环境
- 用统一返回结构规范接口输出
很多初学者在学 SpringBoot 时，会被大量注解和配置劝退。其实一个可运行的接口服务，只需要很少的代码。这篇文章的目标是让你在半小时内跑通第一个返回 JSON 的接口，并理解每一行代码为什么存在。
先理解分层，再写代码
一个可维护的后端项目，通常把「接收请求」「处理业务」「访问数据」分开。控制器只负责接收参数与返回结果，业务逻辑放在服务层，数据访问交给仓储层。这样拆分之后，任何一层的变化都不会牵连其他层。
- controller：解析请求参数、调用服务、组装响应
- service：编排业务流程，不关心 HTTP 细节
- repository：封装数据访问，屏蔽数据库差异
写出第一个接口
下面是一段最小控制器示例。启动应用后访问 /api/health，就能看到服务返回的 JSON。注意注解只做声明，真正的对象创建由容器完成，这就是依赖注入的价值。
java
1import org.springframework.web.bind.annotation.*;23@RestController4@RequestMapping("/api")5public class HealthController {67 private final HealthService healthService;89 public HealthController(HealthService healthService) {10 this.healthService = healthService;11 }1213 @GetMapping("/health")14 public ApiResponse health() {15 return ApiResponse.ok(healthService.status());16 }17}统一返回结构
接口返回格式统一之后，前端处理错误会简单很多。建议固定 code、message、data 三个字段，成功与失败都走同一套结构，避免每个接口各写各的。
- 成功时 code 为 0，data 携带业务数据
- 失败时 code 非 0，message 给出可读提示
- 不要把异常堆栈直接返回给前端
下一步做什么
跑通接口之后，建议接着补上参数校验、全局异常处理和接口文档，这三件事能让你的服务从「能跑」走向「好用」。完成后可以回到学习路线的进阶阶段，继续了解数据访问与事务。