skill/fullstack-task/references/api-design.md

@@ -0,0 +1,55 @@
+# API 设计规范
+
+## 风格
+
+- 默认 REST
+- 复杂查询可用 RPC 风格
+- 内部服务可用 tRPC
+
+## 路径
+
+- 资源用复数：`/api/posts`
+- 嵌套不超过两层：`/api/posts/:id/comments`
+- 动作用子资源或 POST：`/api/posts/:id/publish`
+
+## 方法
+
+- GET 查询
+- POST 创建
+- PATCH 局部更新
+- PUT 全量替换
+- DELETE 删除
+
+## 请求
+
+- Body 用 JSON
+- 分页：`?page=1&pageSize=20` 或 cursor
+- 排序：`?sort=-createdAt`
+- 过滤：`?status=published&tag=nextjs`
+
+## 响应
+
+成功：
+
+```json
+{ "data": { ... }, "meta": { ... } }
+```
+
+## 状态码
+
+- 200 -> 成功
+- 201 -> 创建成功
+- 204 -> 删除成功
+- 400 -> 参数错误
+- 401 -> 未登录
+- 403 -> 无权限
+- 404 -> 不存在
+- 409 -> 冲突
+- 422 -> 业务校验失败
+- 500 -> 服务器错误
+
+## 校验
+
+- 所有输入用 Zod 校验
+
+- 错误信息可读，不暴露内部细节