REST API 开发规范

1. URL 设计规范

1.1 基本原则

使用名词，避免动词
使用复数形式
使用小写字母和连字符
保持层级简洁，避免过深嵌套

正确示例：
GET /api/users
GET /api/users/123
GET /api/users/123/orders
POST /api/users
PUT /api/users/123
DELETE /api/users/123

错误示例：
GET /api/getUsers
GET /api/user
GET /api/users/123/orders/456/items/789/details
POST /api/createUser

1.2 RESTful 路径设计

# 用户资源
GET    /api/users          # 获取用户列表
POST   /api/users          # 创建用户
GET    /api/users/123      # 获取特定用户
PUT    /api/users/123      # 更新用户（理论全量替换，但实际开发中很多 API 为了便利性只要求提供需要更新的字段。）
PATCH  /api/users/123      # 更新用户（部分）
DELETE /api/users/123      # 删除用户

# 嵌套资源
GET    /api/users/123/orders     # 获取用户的订单列表
POST   /api/users/123/orders     # 为用户创建订单
GET    /api/orders/456           # 获取特定订单

1.3 查询参数规范

# 分页
GET /api/users?page=1&limit=20&offset=0

# 排序
GET /api/users?sort=created_at&order=desc
GET /api/users?sort=-created_at  # 降序的简写方式

# 过滤
GET /api/users?status=active&role=admin
GET /api/users?created_after=2024-01-01

# 字段选择
GET /api/users?fields=id,name,email

# 搜索
GET /api/users?search=john&search_fields=name,email

2. HTTP 状态码规范

2.1 成功状态码

OK              # 请求成功（GET、PUT、PATCH）
Created         # 资源创建成功（POST）
Accepted        # 请求已接受，异步处理中
No Content      # 请求成功，无返回内容（DELETE）

2.2 客户端错误状态码

Bad Request          # 请求参数错误
Unauthorized         # 未认证
Forbidden           # 无权限
Not Found           # 资源不存在
Method Not Allowed  # HTTP 方法不支持
Conflict            # 资源冲突
Unprocessable Entity # 请求格式正确但语义错误
Too Many Requests   # 请求过于频繁

2.3 服务器错误状态码

Internal Server Error   # 服务器内部错误
Not Implemented        # 功能未实现
Bad Gateway            # 网关错误
Service Unavailable    # 服务不可用

3. 请求和响应格式

3.1 请求格式

// POST /api/users
{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "user"
}

// PUT /api/users/123
{
  "name": "John Smith",
  "email": "john.smith@example.com",
  "role": "admin"
}

// PATCH /api/users/123
{
  "name": "John Smith"
}

3.2 响应格式规范

3.2.1 成功响应格式

// 单个资源响应
{
  "success": true,
  "data": {
    "id": "123",
    "name": "John Doe",
    "email": "john@example.com",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "message": "User retrieved successfully"
}

// 列表响应
{
  "success": true,
  "data": [
    {
      "id": "123",
      "name": "John Doe",
      "email": "john@example.com"
    },
    {
      "id": "124",
      "name": "Jane Smith",
      "email": "jane@example.com"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  },
  "message": "Users retrieved successfully"
}

3.2.2 错误响应格式

// 客户端错误
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Email is required"
      },
      {
        "field": "name",
        "message": "Name must be at least 2 characters"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/api/users"
}

// 服务器错误
{
  "success": false,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "request_id": "req_123456789"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/api/users"
}

4. 错误处理规范

4.1 错误代码定义

enum ErrorCode {
  // 认证相关
  AUTHENTICATION_REQUIRED = "AUTHENTICATION_REQUIRED",
  INVALID_CREDENTIALS = "INVALID_CREDENTIALS",
  TOKEN_EXPIRED = "TOKEN_EXPIRED",

  // 权限相关
  INSUFFICIENT_PERMISSIONS = "INSUFFICIENT_PERMISSIONS",
  RESOURCE_ACCESS_DENIED = "RESOURCE_ACCESS_DENIED",

  // 验证相关
  VALIDATION_ERROR = "VALIDATION_ERROR",
  INVALID_INPUT_FORMAT = "INVALID_INPUT_FORMAT",
  MISSING_REQUIRED_FIELD = "MISSING_REQUIRED_FIELD",

  // 资源相关
  RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND",
  RESOURCE_ALREADY_EXISTS = "RESOURCE_ALREADY_EXISTS",
  RESOURCE_CONFLICT = "RESOURCE_CONFLICT",

  // 业务逻辑相关
  BUSINESS_RULE_VIOLATION = "BUSINESS_RULE_VIOLATION",
  OPERATION_NOT_ALLOWED = "OPERATION_NOT_ALLOWED",

  // 系统相关
  INTERNAL_SERVER_ERROR = "INTERNAL_SERVER_ERROR",
  SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
  RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED",
}

4.2 错误处理最佳实践

// 详细的验证错误
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Email format is invalid",
        "value": "invalid-email"
      },
      {
        "field": "age",
        "code": "OUT_OF_RANGE",
        "message": "Age must be between 18 and 120",
        "value": 15,
        "constraints": {
          "min": 18,
          "max": 120
        }
      }
    ]
  }
}

5. 认证和授权

5.1 JWT Token 规范

# 请求头格式
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# 登录响应
{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_expires_in": 2592000,
    "user": {
      "id": "123",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "user"
    }
  }
}

5.2 权限控制

// 用户权限结构
{
  "user": {
    "id": "123",
    "role": "admin",
    "permissions": [
      "users:read",
      "users:write",
      "users:delete",
      "orders:read",
      "orders:write"
    ]
  }
}

// 资源访问控制
{
  "resource": "users",
  "actions": ["read", "write"],
  "conditions": {
    "owner_only": true,
    "department": ["engineering", "product"]
  }
}

6. 版本控制

6.1 URL 版本控制

# 推荐方式：在 URL 中包含版本
GET /api/v1/users
GET /api/v2/users

# 备选方式：请求头版本控制
GET /api/users
Accept: application/vnd.api+json;version=1

6.2 版本兼容性

// API 版本信息响应
{
  "api_version": "v2",
  "supported_versions": ["v1", "v2"],
  "deprecated_versions": ["v1"],
  "retirement_schedule": {
    "v1": "2024-12-31"
  }
}

7. 缓存策略

7.1 HTTP 缓存头

# 响应头
Cache-Control: public, max-age=3600
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Last-Modified: Wed, 21 Oct 2024 07:28:00 GMT

# 条件请求
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
If-Modified-Since: Wed, 21 Oct 2024 07:28:00 GMT

7.2 不同接口缓存策略

// 缓存控制配置
{
  "endpoints": {
    "/api/users": {
      "cache_duration": 300,
      "cache_key_pattern": "users:list:{query_hash}"
    },
    "/api/users/:id": {
      "cache_duration": 600,
      "cache_key_pattern": "users:detail:{id}"
    }
  }
}

8. 限流和监控

8.1 限流响应

# 限流响应头
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

# 限流超出响应
HTTP/1.1 429 Too Many Requests
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "retry_after": 60
  }
}

8.2 API 监控指标

// 监控响应头
{
  "headers": {
    "X-Request-ID": "req_123456789",
    "X-Response-Time": "23ms",
    "X-API-Version": "v2",
    "X-Server-Instance": "api-server-01"
  }
}

9. 文档规范

9.1 OpenAPI/Swagger 规范

# api.yaml
openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users

paths:
  /users:
    get:
      summary: Get users list
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Users retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsersResponse"

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email

9.2 API 文档最佳实践

提供完整的请求/响应示例
包含错误响应示例
说明认证和权限要求
提供 SDK 和代码示例
维护变更日志

文档示例

POST /api/users - 创建新用户

认证要求： Bearer Token 认证

权限要求： users:write 权限

请求体：

{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "user"
}

成功响应：

{
  "success": true,
  "data": {
    "id": "123",
    "name": "John Doe",
    "email": "john@example.com",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

错误响应：

{
  "success": false,
  "error": {
    "code": "EMAIL_ALREADY_EXISTS",
    "message": "Email address is already in use"
  }
}

9.3 AI 文档生成工具推荐

现代开发中，AI 工具可以大幅提升 API 文档的编写效率和质量。

ApiPost

国产工具，中文支持优秀
AI 智能生成接口文档
支持团队协作和版本管理
集成测试、Mock、监控功能
适合：中小团队快速上手

Postman + AI Assistant

全球最流行的 API 工具
GPT 集成，智能生成文档
强大的测试和自动化功能
丰富的插件生态系统
适合：大型团队专业开发

Apifox

国产一体化 API 协作平台
AI 智能生成和优化文档
支持自动化测试和 Mock
性价比高，免费版实用
适合：追求效率的开发团队

1. URL 设计规范​

1.1 基本原则​

1.2 RESTful 路径设计​

1.3 查询参数规范​

2. HTTP 状态码规范​

2.1 成功状态码​

2.2 客户端错误状态码​

2.3 服务器错误状态码​

3. 请求和响应格式​

3.1 请求格式​

3.2 响应格式规范​

3.2.1 成功响应格式​

3.2.2 错误响应格式​

4. 错误处理规范​

4.1 错误代码定义​

4.2 错误处理最佳实践​

5. 认证和授权​

5.1 JWT Token 规范​

5.2 权限控制​

6. 版本控制​

6.1 URL 版本控制​

6.2 版本兼容性​

7. 缓存策略​

7.1 HTTP 缓存头​

7.2 不同接口缓存策略​

8. 限流和监控​

8.1 限流响应​

8.2 API 监控指标​

9. 文档规范​

9.1 OpenAPI/Swagger 规范​

9.2 API 文档最佳实践​

文档示例​

9.3 AI 文档生成工具推荐​

1. URL 设计规范

1.1 基本原则

1.2 RESTful 路径设计

1.3 查询参数规范

2. HTTP 状态码规范

2.1 成功状态码

2.2 客户端错误状态码

2.3 服务器错误状态码

3. 请求和响应格式

3.1 请求格式

3.2 响应格式规范

3.2.1 成功响应格式

3.2.2 错误响应格式

4. 错误处理规范

4.1 错误代码定义

4.2 错误处理最佳实践

5. 认证和授权

5.1 JWT Token 规范

5.2 权限控制

6. 版本控制

6.1 URL 版本控制

6.2 版本兼容性

7. 缓存策略

7.1 HTTP 缓存头

7.2 不同接口缓存策略

8. 限流和监控

8.1 限流响应

8.2 API 监控指标

9. 文档规范

9.1 OpenAPI/Swagger 规范

9.2 API 文档最佳实践

文档示例

9.3 AI 文档生成工具推荐