REST 与资源设计

这一课你将能做到

1. 用「名词路径 + HTTP 方法 + 状态码」三件套设计一组 tracks/lessons API，而不是 /getTrackList 式动词路径
2. 分清路径参数（标识资源身份）与查询参数（过滤/分页/瘦身），并说明公开读 /api/** 与管理写 /admin/** 的职责分离
3. 用 curl 拉列表、详情、lite 变体，亲手写出一张「方法 + 路径 + 成功码 + 失败码」的迷你 API 合同

为什么要学

API 是前后端的合同。路径乱七八糟、动词塞 URL、错误一律 200，客户端、网关、监控全都痛苦：缓存不知道能不能存、前端拦截器没法统一分支、新人接手要靠口口相传。

REST（Representational State Transfer）在工程实践里落地为一套可抄的骨架：资源用 URL 命名，动作用 HTTP 方法表达，结果用状态码表达。面试里「如何设计一个 XX 的 API」考的就是这套骨架运用。本课用课表 API 当样板，不空谈学位论文式 REST 纯度。

先建立图像

资源：tracks 集合、单个 track、其下 lessons
操作：GET 读 / POST 建 / PUT 换 / DELETE 删
结果：200/201/204/404/401…

一张可直接抄进接口文档的设计表：

意图	方法	路径	成功码	失败码
课表列表	GET	/api/tracks	200	—
课表详情	GET	/api/tracks/{slug}	200	404
某课的课节列表	GET	/api/tracks/{slug}/lessons	200	404
创建课表（管理）	POST	/admin/tracks	201	400/401/403
全量更新	PUT	/admin/tracks/{id}	200	400/404
局部更新	PATCH	/admin/tracks/{id}	200	400/404
删除	DELETE	/admin/tracks/{id}	204	401/403/404

页面（给人看）：  /tracks/http-protocol-essentials      → HTML（前端服务）
API（给程序）：   /api/tracks/http-protocol-essentials  → JSON（Spring）

结构相似、职责不同：页面可缓存可跳转，API 契约稳定可演进。

跟着做

步骤 1：写一个「资源感」正确的 Controller

@RestController
public class TrackController {

    // 集合：GET /api/tracks
    // 查询参数做过滤，不改资源身份
    @GetMapping("/api/tracks")
    public List<Map<String, Object>> list(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size,
            @RequestParam(required = false) String q) {
        // page/size/q 是「这次查询的条件」，不是「哪个资源」
        return List.of(Map.of("slug", "http-protocol-essentials", "title", "HTTP 必修"));
    }

    // 成员：路径变量标识单个资源
    @GetMapping("/api/tracks/{slug}")
    public ResponseEntity<Map<String, Object>> detail(@PathVariable String slug) {
        if (!"http-protocol-essentials".equals(slug)) {
            return ResponseEntity.notFound().build();   // 找不到 → 404
        }
        return ResponseEntity.ok(Map.of(
            "slug", slug,
            "title", "HTTP 必修",
            "lessonCount", 12));
    }

    // 子资源：资源归属用路径层级表达
    @GetMapping("/api/tracks/{slug}/lessons")
    public List<Map<String, Object>> lessons(@PathVariable String slug) { return List.of(); }
}