API 语义审查

这一课你将能做到

1. 拿到一个 Spring Boot Controller 的 PR，能在 5 分钟内识别出 REST 语义错误（动词用错、状态码乱返、资源命名不规范）
2. 判断接口契约变更是否破坏向后兼容，并给出迁移方案
3. 审查 DTO、校验注解、错误响应结构是否一致且可演进

为什么要学

API 是后端和前端、和其他系统之间的「合同」。合同一旦签出去，改一个字都可能让调用方线上炸掉。Code Review 时审 API 语义，就是在签合同前帮双方把条款看清楚：路径是不是名词、方法是不是幂等、错误码前端能不能直接用、这次改动老版本 App 还能不能调通。

人话：实现写错了，改一行代码就行；API 语义设计错了，会跟着你三年，因为总有客户端在用旧版本。

先建立图像

一个语义清晰的接口长这样：

资源: /api/v1/courses                ← 名词复数，无动词
├─ GET    /api/v1/courses           200 列表查询（幂等）
├─ POST   /api/v1/courses           201 创建（返回 Location）
├─ GET    /api/v1/courses/{id}      200 / 404
├─ PUT    /api/v1/courses/{id}      200 全量更新（幂等）
├─ PATCH  /api/v1/courses/{id}      200 部分更新
└─ DELETE /api/v1/courses/{id}      204 删除（幂等）

错误响应统一结构:
{ "code": "COURSE_NOT_FOUND", "message": "...", "traceId": "..." }

审查时就拿这张图去对照：路径里出现 getCourse、deleteCourseById 这种动词的，一律打回。

跟着做

步骤 1：审路径和方法语义

❌ 反例（本站早期风格的坏味道）：

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

    @PostMapping("/getCourseList")          // 用 POST 做查询
    public List<CourseVO> list() { ... }

    @GetMapping("/deleteCourse")            // GET 做删除，浏览器预加载都会误删
    public void delete(@RequestParam Long id) { ... }

    @PostMapping("/updateCourseInfo")
    public Result update(@RequestBody Course course) { ... }
}

✅ 正例：

@RestController
@RequestMapping("/api/v1/courses")
public class CourseController {

    @GetMapping
    public PageResult<CourseVO> list(CourseQuery query) { ... }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> delete(@PathVariable Long id) {
        courseService.delete(id);
        return ResponseEntity.noContent().build();   // 204
    }

    @PutMapping("/{id}")
    public CourseVO update(@PathVariable Long id,
                           @Valid @RequestBody CourseUpdateReq req) { ... }
}

审查动作：逐条接口问三个问题——路径是纯名词吗？HTTP 方法幂等性匹配吗（GET 只读、PUT/DELETE 幂等）？状态码准确吗（创建返 201 而不是 200）？

步骤 2：审向后兼容

❌ 反例：直接改字段名、删字段、改类型

// 上一版
public class CourseVO {
    private String courseName;   // v1 已上线
}

// 这次 PR 直接改名
public class CourseVO {
    private String title;        // 老前端读 courseName 全是 null
}