IMS系统RESTful API设计完全指南

/* RESTful API 设计示例 */

/* 资源命名：使用复数名词，URL 要小写 */
# 用户资源
GET    /api/users              # 获取用户列表
GET    /api/users/:id          # 获取单个用户
POST   /api/users              # 创建用户
PUT    /api/users/:id          # 完全更新用户
PATCH  /api/users/:id          # 部分更新用户
DELETE /api/users/:id          # 删除用户

/* 嵌套资源 */
GET    /api/users/:id/orders   # 获取用户的所有订单
GET    /api/orders/:id/items   # 获取订单的所有项目

/* 统一的响应格式 */
/* 成功响应 */
{
    "code": 200,
    "message": "success",
    "data": {
        "id": 1,
        "name": "张三",
        "email": "zhangsan@example.com"
    }
}

/* 分页响应 */
{
    "code": 200,
    "message": "success",
    "data": [
        { "id": 1, "name": "用户1" },
        { "id": 2, "name": "用户2" }
    ],
    "pagination": {
        "page": 1,
        "pageSize": 20,
        "total": 100,
        "totalPages": 5
    }
}

/* 错误响应格式 */
{
    "code": 400,
    "message": "请求参数错误",
    "errors": [
        {
            "field": "email",
            "message": "邮箱格式不正确"
        },
        {
            "field": "password",
            "message": "密码长度不能少于6位"
        }
    ]
}

/* HTTP 状态码规范 */
200 OK                      # 请求成功
201 Created                 # 资源创建成功
204 No Content             # 删除成功，无返回内容
400 Bad Request            # 请求参数错误
401 Unauthorized           # 未认证
403 Forbidden              # 无权限
404 Not Found              # 资源不存在
500 Internal Server Error  # 服务器内部错误

/* 版本控制方式：URL 路径 */
GET /api/v1/users
GET /api/v2/users

/* 版本控制方式：Header */
GET /api/users
Accept: application/vnd.myapp.v2+json

/* 推荐使用 URL 路径方式，版本区分清晰 */

/* 版本演进策略 */
/* 1. 向后兼容：新增字段，不删除或修改现有字段 */
/* 2. 渐进废弃：使用 Warning Header 提示旧版本即将废弃 */
Warning: 299 - "This API version will be deprecated on 2026-12-31"
/* 3. 提供迁移指南：文档中详细说明不同版本的差异 */

/* 使用 JWT 进行认证 */
/* 请求头中携带 Token */
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

/* JWT Payload 示例 */
{
    "sub": "user_id",
    "name": "张三",
    "role": "admin",
    "exp": 1767225600,
    "iat": 1767146400
}

/* 权限检查示例 */
function checkPermission(user, resource, action) {
    if (user.role === 'admin') return true;
    const permission = user.permissions.find(
        p => p.resource === resource && p.actions.includes(action)
    );
    return !!permission;
}

/* 分页参数 */
GET /api/users?page=1&pageSize=20&sort=name&order=asc

/* 参数说明 */
page:      1               # 页码，从 1 开始
pageSize:  20              # 每页数量，建议最大值 100
sort:      "name"         # 排序字段
order:     "asc"          # 排序方向：asc / desc

/* SQL 分页查询 */
SELECT * FROM users
ORDER BY name ASC
LIMIT 20 OFFSET 0;