REST 资源设计

这一课你将能做到

1. 设计出符合 REST 规范的 URI，避免动词、层级过深等常见错误
2. 实现 API 版本控制，掌握 URI 版本、Header 版本、参数版本三种方案
3. 设计分页、排序、过滤的查询接口，并保证幂等性

为什么要学

URI 是 API 的门面。/api/getLesson?id=1 和 /api/lessons/1 哪个更专业？答案显而易见。版本策略决定你的 API 能不能平滑升级，分页设计影响性能和用户体验。面试必问：怎么设计幂等接口？API 版本怎么管理？

先建立图像

资源层级设计：
┌────────────────────────────────────────┐
│  /api/tracks/java-web                  │  ← 学习路径（集合）
│  /api/tracks/java-web/lessons          │  ← 路径下的课程（子集合）
│  /api/lessons/123                      │  ← 具体课程（单个资源）
│  /api/lessons/123/submissions          │  ← 课程的提交记录（子集合）
│  /api/submissions/456                  │  ← 具体提交（单个资源）
└────────────────────────────────────────┘

分页响应结构：
{
  "code": 200,
  "data": {
    "content": [...],           ← 当前页数据
    "page": 0,                  ← 当前页码（0-based）
    "size": 20,                 ← 每页大小
    "totalElements": 156,       ← 总条数
    "totalPages": 8             ← 总页数
  }
}

跟着做

步骤 1：URI 设计规范

好的 URI：

GET    /api/lessons              # 课程列表
GET    /api/lessons/123          # 单个课程
POST   /api/lessons              # 创建课程
PUT    /api/lessons/123          # 全量更新
PATCH  /api/lessons/123          # 部分更新
DELETE /api/lessons/123          # 删除

GET    /api/lessons/123/submissions    # 某课程的提交列表
POST   /api/lessons/123/submissions    # 提交作业

坏的 URI：

GET  /api/getLesson?id=123       # 动词 get
POST /api/createLesson           # 动词 create
GET  /api/lesson/list            # 单数 + 动词
GET  /api/lessons/123/submissions/456/comments/789/likes   # 层级太深

原则：URI 里只有名词，用 HTTP 方法表达动作；层级不超过 3 层。

步骤 2：版本控制

三种主流方案：

方案 A：URI 版本（最直观）

GET /api/v1/lessons
GET /api/v2/lessons

@RestController
@RequestMapping("/api/v1/lessons")
public class LessonV1Controller { ... }

@RestController
@RequestMapping("/api/v2/lessons")
public class LessonV2Controller { ... }

优点：简单、可缓存、浏览器直接访问。缺点：URI 污染。

方案 B：Header 版本（最优雅）

GET /api/lessons
Accept: application/vnd.codeforge.v1+json

@GetMapping(produces = "application/vnd.codeforge.v1+json")
public ApiResponse<List<LessonV1>> listV1() { ... }

@GetMapping(produces = "application/vnd.codeforge.v2+json")
public ApiResponse<List<LessonV2>> listV2() { ... }