877 B
877 B
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
响应
成功：
{ "data": { ... }, "meta": { ... } }
状态码
- 200 -> 成功
- 201 -> 创建成功
- 204 -> 删除成功
- 400 -> 参数错误
- 401 -> 未登录
- 403 -> 无权限
- 404 -> 不存在
- 409 -> 冲突
- 422 -> 业务校验失败
- 500 -> 服务器错误
校验
-
所有输入用 Zod 校验
-
错误信息可读，不暴露内部细节