下面是 RESTful API 团队开发规范（Markdown 版），可直接复制到你的团队文档库（GitHub、Gitea、GitLab、Wiki、Notion 等）。

---

目录

• 目录
• 设计原则
• URL 规范（Endpoints）
  • ✔ 使用名词（资源名），不要使用动词
  • ✔ 资源名使用复数
  • ✔ 层级结构表示包含关系
  • ✔ 不超过三级
  • ✔ 统一使用 kebab-case 或 camelCase（建议 kebab-case）
• HTTP 方法规范
• 请求与响应规范
  • ✔ 请求与响应使用 JSON（application/json）
  • ✔ 返回结构不能为数组（便于扩展）
• 状态码规范
• 错误返回格式
• 资源关联规则
  • 多层资源示例：
  • 不要使用动词形式的子资源：
• 分页、排序、过滤
  • ✔ 分页
  • ✔ 排序
  • ✔ 过滤
• 版本管理
  • URL 版本（推荐方式）
• 安全规范
  • ✔ 必须使用 HTTPS
  • ✔ 授权方式
  • ✔ 不允许把敏感信息放在 URL 中
  • ✔ 所有接口必须返回 traceId（用于日志追踪）
  • ✔ 防止暴露内部信息
• 性能优化与可扩展性
  • ✔ ETag + 缓存
  • ✔ 批量接口（推荐）
  • ✔ 分布式限流（建议）
  • ✔ 异步任务用 202 Accepted
• 命名规范
  • ✔ 前端/后端统一 camelCase
  • ✔ 内部数据库可使用 snake_case，但不得映射到 API 原样输出
• API 文档规范
• 常见反模式与避免方式
• 最佳实践清单
• 其它相关内容

---

设计原则

• 资源导向（Resource-Oriented）
• 面向接口（Interface-Oriented）
• 统一格式（统一错误码、统一响应格式）
• 保持兼容性
• 幂等性优先
• 避免暴露内部实现（DB 字段、服务名等）

---

URL 规范（Endpoints）

✔ 使用名词（资源名），不要使用动词

错误示例：

POST /createUser
GET /getOrderList

正确示例：

POST /users
GET /orders

✔ 资源名使用复数

/users
/products

✔ 层级结构表示包含关系

GET /users/{id}/orders
GET /shops/{shopId}/products

✔ 不超过三级

不推荐：

/a/b/c/d/e

✔ 统一使用 kebab-case 或 camelCase（建议 kebab-case）

/user-groups
/shop-items

---

HTTP 方法规范

Method	意义	示例	幂等性
GET	获取资源	GET /users	✔
POST	创建资源	POST /users	❌
PUT	全量更新	PUT /users/123	✔
PATCH	局部更新	PATCH /users/123	❌（可视实现而定）
DELETE	删除资源	DELETE /users/123	✔

示例：

POST /orders
GET /orders/100
PUT /orders/100
DELETE /orders/100

---

请求与响应规范

✔ 请求与响应使用 JSON（application/json）

不允许使用 XML。

✔ 返回结构不能为数组（便于扩展）

错误：

[ ... ]

正确：

{
  "items": [ ... ],
  "total": 100
}

---

状态码规范

状态码	含义
200 OK	成功（GET/PUT/PATCH/DELETE）
201 Created	成功创建
204 No Content	成功但无返回内容
400 Bad Request	请求参数错误
401 Unauthorized	未认证
403 Forbidden	无权限
404 Not Found	资源不存在
409 Conflict	业务冲突，如重复创建
422 Unprocessable Entity	参数校验失败
500 Internal Server Error	压力之下最后的盾牌

---

错误返回格式

为了便于前端统一处理，错误结构必须统一：

{
  "code": "USER_NOT_FOUND",
  "message": "用户不存在",
  "details": {
    "userId": "123"
  },
  "traceId": "c12dffab239a45de"
}

字段说明：

• code：业务错误码（字符串，必须可读）
• message：给前端和用户看的提示
• details：字段错误信息、上下文信息
• traceId：链路追踪 ID，用于日志系统定位问题

---

资源关联规则

多层资源示例：

GET /shops/{id}/products
GET /shops/{id}/employees

不要使用动词形式的子资源：

错误：

GET /users/123/getOrders

---

分页、排序、过滤

✔ 分页

统一使用：

?page=1&pageSize=20

返回格式：

{
  "items": [ ... ],
  "total": 200,
  "page": 1,
  "pageSize": 20
}

✔ 排序

?sort=createdAt
?sort=-price

✔ 过滤

?status=active
?type=premium

---

版本管理

URL 版本（推荐方式）

/api/v1/users
/api/v2/users

不推荐：

• headers 版本
• query 版本

版本升级原则：

• 非兼容性变更 → 升级版本
• 兼容性新增字段 → 不升级版本

---

安全规范

✔ 必须使用 HTTPS

所有环境（包括开发环境）禁止 HTTP。

✔ 授权方式

• JWT（推荐）
• OAuth2
• API Key（内部服务用）

✔ 不允许把敏感信息放在 URL 中

GET /login?password=123456   # ❌

✔ 所有接口必须返回 traceId（用于日志追踪）

✔ 防止暴露内部信息

500 错误不能泄漏：

• SQL 语句
• 堆栈
• 内部服务名

---

性能优化与可扩展性

✔ ETag + 缓存

ETag: "abc123"

✔ 批量接口（推荐）

POST /users/batch
POST /orders/batch-cancel

✔ 分布式限流（建议）

• Gateway 层实现
• 避免业务层滥用限流

✔ 异步任务用 202 Accepted

POST /reports
→ 202 + taskId
GET /tasks/{taskId}

---

命名规范

✔ 前端/后端统一 camelCase

{
  "userId": 123,
  "createdAt": "2025-11-01T10:00:00Z"
}

✔ 内部数据库可使用 snake_case，但不得映射到 API 原样输出

---

API 文档规范

• 使用 OpenAPI（Swagger） 自动生成文档

• 为每个接口提供：

  • 描述
  • 参数说明
  • body 示例
  • 响应示例（成功/失败）
  • 状态码
  • 错误码含义

• 业务错误码需集中管理

---

常见反模式与避免方式

反模式	原因	正确方式
POST 代替 GET	不可缓存	用 GET
GET 修改数据	不幂等、不安全	用 POST/PUT/PATCH
URL 太长	难维护	控制在 3 层内
返回数组	缺少可扩展性	使用对象包装
返回 200 + 错误信息	前端难处理	使用正确状态码
暴露 DB 字段	泄漏内部设计	用 DTO

---

最佳实践清单

• ✔ API 结构清晰
• ✔ URL 与 Method 一致
• ✔ 状态码语义正确
• ✔ 错误格式统一
• ✔ 输出字段稳定、向下兼容
• ✔ 对外不暴露内部数据库结构
• ✔ 分页、排序、缓存
• ✔ 必须 HTTPS
• ✔ 打日志、加 traceId
• ✔ 有 API 文档（OpenAPI/Swagger）

其它相关内容

• 包含 .NET 8 Web API 架构示例的项目模板
• 错误码设计规范（推荐）
• RESTful 规范检查清单（Checklist）