# 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 校验

- 错误信息可读，不暴露内部细节