RESTful API 设计与调试（零基础详细版）

学习目标与前置

建议用时：60 分钟准备：已有 Spring Boot + 数据访问

设计资源路径与方法，理解幂等性。
统一响应模型与业务错误码。
使用 OpenAPI/Swagger/Knife4j 输出文档并在线调试。

Step 1：统一响应模型

flowchart LR
  A[设计统一响应 ApiResp] --> B[Controller 返回 ApiResp]
  B --> C[客户端/前端]
  A --> D[错误码约定]
  D --> C

record ApiResp<T>(int code, String msg, T data) {
  static <T> ApiResp<T> ok(T data) { return new ApiResp<>(0, "ok", data); }
  static ApiResp<Void> err(int code, String msg) { return new ApiResp<>(code, msg, null); }
}

约定：HTTP 状态码反映通道是否畅通；业务码 code 反映业务结果（0 成功）。

Step 2：RESTful 路径与幂等性（Todo 示例）

@RestController
@RequestMapping("/api/todos")
public class TodoRestController {
  private final TodoService service;
  public TodoRestController(TodoService service) { this.service = service; }

  @PostMapping
  public ApiResp<Todo> create(@RequestBody @Valid Todo req) {
    return ApiResp.ok(service.create(req));
  }

  @GetMapping("/{id}")
  public ApiResp<Todo> get(@PathVariable long id) {
    return service.find(id)
      .map(ApiResp::ok)
      .orElseGet(() -> ApiResp.err(404, "not found"));
  }

  @GetMapping
  public ApiResp<List<Todo>> list(@RequestParam(defaultValue = "0") int page,
                                   @RequestParam(defaultValue = "10") int size) {
    return ApiResp.ok(service.page(page, size));
  }
}

说明：GET/PUT/DELETE 设计为幂等；POST 非幂等。

Step 3：状态码与业务码建议

HTTP：200 成功；400 参数错误；401 未授权；404 资源不存在；500 服务器异常。
业务：0 成功；4001 参数校验失败；4004 数据不存在；5000 未知错误。
约定响应体：{ code, msg, data }。

Step 4：配置 Swagger/Knife4j

flowchart LR
  A[Controller 注解] --> B[OpenAPI/Swagger 文档]
  B --> C[Swagger UI/Knife4j]
  C --> D[在线调试接口]

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.5.0</version>
</dependency>
<!-- 如需 Knife4j，在上方基础上再加 knife4j-openapi3-ui -->

@Configuration
@OpenAPIDefinition(info = @Info(title = "Todo API", version = "1.0"))
public class SwaggerConfig {}

启动后访问 /swagger-ui/index.html（或 Knife4j UI）在线调试。

Step 5：操作与验证

在 Swagger UI 执行 POST /api/todos，查看响应结构。
执行 GET /api/todos?page=1&size=2，观察分页。
请求不存在的 id，返回业务码 404，说明 HTTP 200 + 业务码 404 的区别。
用 Postman 重复上述请求，保存为集合。

常见问题与排查

Swagger 页面 404：确认依赖引入、访问路径、是否 WebMVC 项目。
返回中文乱码：默认 Spring Boot JSON 为 UTF-8，一般无需额外配置。
分页错误：确认 page/size 校验，offset 计算是否正确。

课堂练习

在统一响应中加入 traceId（UUID），每次请求生成并返回。
为 POST/PUT 编写 400/409/500 的错误返回示例，并在 Swagger 文档中声明响应。

课后巩固

为 Todo 增加搜索参数（title 关键字），在 Swagger 中声明。
导出接口文档（Swagger JSON 或 HTML），随作业提交。