API 设计原则：

1. 一致性：相同的操作使用相同的模式
2. 简单性：减少认知负担
3. 可发现性：通过 API 本身能理解用法
4. 安全性：默认安全，防止常见错误
5. 可扩展性：允许未来添加功能

向后兼容规则：

1. 永远不要删除已有的字段
2. 永远不要改变已有字段的类型
3. 永远不要改变已有字段的行为
4. 新增字段必须是可选的（或有默认值）
5. 新增方法不能影响已有方法

不兼容变更的处理：
- 废弃旧版本，提供迁移期
- 使用版本号区分
- 提供迁移工具

版本管理策略：

1. URL 版本：/api/v1/users
   - 优点：直观，易于路由
   - 缺点：URL 不统一

2. Header 版本：Accept: application/vnd.api.v1+json
   - 优点：URL 干净
   - 缺点：不够直观

3. 无版本：通过向后兼容避免版本
   - 优点：最简单
   - 缺点：需要严格遵守兼容规则

推荐：优先向后兼容，必要时使用 URL 版本

资源命名：
- 使用复数名词：/users, /orders
- 使用 kebab-case：/order-items
- 避免动词：/users（GET）而不是 /getUsers

字段命名：
- 使用 camelCase：firstName, orderDate
- 保持一致：不要混用 camelCase 和 snake_case
- 使用有意义的名称：userEmail 而不是 email（在嵌套时）

资源设计：
GET    /api/v1/users          # 列表
POST   /api/v1/users          # 创建
GET    /api/v1/users/{id}     # 获取
PATCH  /api/v1/users/{id}     # 部分更新
DELETE /api/v1/users/{id}     # 删除

请求/响应示例：

POST /api/v1/users
{
  "name": "Alice",
  "email": "alice@example.com"
}

Response 201:
{
  "id": "usr_123",
  "name": "Alice",
  "email": "alice@example.com",
  "createdAt": "2024-01-01T00:00:00Z"
}