01 · REST API 设计

从需求描述到 API 设计

在写代码之前，先让 Claude 帮你设计 API：

我在做一个在线课程平台，核心功能：用户购买课程、观看视频、记录进度。

帮我设计 RESTful API：
- 列出所有需要的接口（方法 + URL + 简要说明）
- 设计请求/响应的 JSON 结构
- 指出哪些接口需要认证
- 标注哪些是高频接口（需要缓存或优化）

暂时不要写代码，先出 API 设计文档。

用 Hono 实现 API

API 设计确认后，让 Claude 实现：

用 Hono（TypeScript）实现课程 API：

路由：
- GET /api/courses — 课程列表（支持分页和分类过滤）
- GET /api/courses/:id — 课程详情
- POST /api/courses/:id/enroll — 报名课程（需要登录）
- GET /api/courses/:id/lessons — 课时列表
- POST /api/lessons/:id/progress — 更新学习进度

每个路由加输入验证（用 Zod），错误统一用 { error: string, code: string } 格式返回。

生成 OpenAPI 文档

读 /src/routes/ 下所有路由文件，
生成对应的 OpenAPI 3.0 YAML 文档，输出到 /docs/openapi.yaml。

包含：
- 所有接口的请求参数和响应结构
- 认证要求（JWT Bearer）
- 正确的 HTTP 状态码语义

写中间件

用 Hono 写以下中间件：

1. authMiddleware：验证 JWT token，把 userId 挂到 ctx 上
2. rateLimitMiddleware：基于 IP，每分钟最多 60 次请求
3. loggerMiddleware：记录请求方法、URL、状态码、耗时

放在 /src/middleware/ 目录。

API 测试

为 /src/routes/courses.ts 里的 GET /api/courses 接口写测试（Vitest）：

测试用例：
- 默认分页返回 20 条
- page 和 limit 参数正确工作
- category 过滤正确
- 无效参数返回 400

用 Hono 的 app.request() 测试，不需要真实启动服务器。