56 lines
877 B
Markdown
56 lines
877 B
Markdown
# 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 校验
|
||
|
||
- 错误信息可读，不暴露内部细节
|