RESTful API设计规范：打造优雅的接口

RESTful API是目前最主流的接口设计风格，前后端分离项目中几乎都在使用。一套设计良好的API能大幅提升开发效率和协作体验。本文总结RESTful API的核心设计规范和最佳实践。

一、URL设计规范

正确示范 vs 错误示范

# ✅ 正确的URL（使用名词复数，表示资源）
GET    /api/users              # 获取用户列表
GET    /api/users/123          # 获取指定用户
POST   /api/users              # 创建用户
PUT    /api/users/123          # 更新用户（全量）
PATCH  /api/users/123          # 更新用户（部分）
DELETE /api/users/123          # 删除用户

# ❌ 错误的URL（不要使用动词，HTTP方法已表达操作语义）
GET    /api/getUser            # 错误
POST   /api/createUser         # 错误
GET    /api/delete_user/123    # 严重错误

# ✅ 嵌套资源
GET    /api/users/123/articles     # 获取用户的文章列表
GET    /api/users/123/orders       # 获取用户的订单
POST   /api/articles/456/comments  # 给文章添加评论

二、HTTP方法语义

GET：查询资源（安全、幂等）
POST：创建资源（非幂等）
PUT：全量更新资源（幂等）
PATCH：部分更新资源
DELETE：删除资源（幂等）

三、统一响应格式

// ✅ 成功响应
{
    "code": 200,
    "message": "success",
    "data": {
        "id": 123,
        "username": "zhangsan",
        "email": "zhangsan@example.com"
    }
}

// ✅ 列表响应（带分页）
{
    "code": 200,
    "message": "success",
    "data": {
        "list": [...],
        "pagination": {
            "page": 1,
            "pageSize": 10,
            "total": 156,
            "totalPages": 16
        }
    }
}

// ✅ 错误响应
{
    "code": 422,
    "message": "参数验证失败",
    "errors": [
        { "field": "email", "message": "邮箱格式不正确" },
        { "field": "password", "message": "密码长度不能少于8位" }
    ]
}

四、HTTP状态码使用

// 常用状态码
OK              - 请求成功
Created         - 创建成功（POST后返回）
No Content      - 删除成功，无返回体
Moved Permanently - 永久重定向
Not Modified    - 缓存有效
Bad Request     - 请求参数错误
Unauthorized    - 未认证（需要登录）
Forbidden       - 无权限（已登录但权限不足）
Not Found       - 资源不存在
Unprocessable   - 参数验证失败
Internal Error  - 服务器内部错误

五、认证与授权

JWT Token认证

// 登录获取Token
POST /api/auth/login
{
    "username": "zhangsan",
    "password": "password123"
}

// 响应
{
    "code": 200,
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "expires_in": 7200,
        "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g..."
    }
}

// 后续请求携带Token
GET /api/users/profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

六、分页、过滤与排序

# 分页
GET /api/articles?page=2&page_size=20

# 过滤（查询条件）
GET /api/articles?status=published&category=tech
GET /api/users?age_min=18&age_max=30

# 排序
GET /api/articles?sort=-created_at,+view_count
# - 表示降序，+ 表示升序

# 搜索
GET /api/articles?keyword=Python&fields=title,content

# 字段筛选（只返回需要的字段）
GET /api/users/123?fields=id,username,email

七、版本控制

# URL版本（最常用）
GET /api/v1/users
GET /api/v2/users

# Header版本
GET /api/users
Accept: application/vnd.myapp.v1+json

注意：API一旦发布，不要随意修改已有接口的字段名和结构。如果有破坏性变更，必须使用新版本（v1 → v2）。旧版本应保持至少6个月的兼容期。

八、错误处理最佳实践

// 全局异常处理（以PHP为例）
class ApiExceptionHandler {
    public function handle(Throwable $e): array {
        $code = match(get_class($e)) {
            ValidationException::class => 422,
            AuthenticationException::class => 401,
            AuthorizationException::class => 403,
            ModelNotFoundException::class => 404,
            default => 500
        };
        
        http_response_code($code);
        
        return [
            'code' => $code,
            'message' => $code === 500 ? '服务器内部错误' : $e->getMessage(),
            'errors' => method_exists($e, 'errors') ? $e->errors() : null
        ];
    }
}

九、安全建议

HTTPS必须：生产环境所有API必须使用HTTPS
频率限制：防止暴力请求和DDoS攻击
输入验证：永远不信任客户端数据，后端必须验证
CORS配置：只允许已知的前端域名跨域访问
敏感数据脱敏：密码、手机号等不要明文返回

十、API文档工具

好的API必须有清晰的文档。推荐用 Swagger/OpenAPI 自动生成：

// Swagger注解示例（Spring Boot）
@ApiOperation("获取用户列表")
@ApiParam(value = "页码", defaultValue = "1")
@GetMapping("/users")
public Result getUsers(@RequestParam(defaultValue = "1") int page) {
    // ...
}

其他文档方案：

Postman：开发调试 + 自动生成文档
Apifox：国产工具，集成文档、调试、Mock
Markdown文档：最简单，适合小型项目

十一、性能优化

缓存：用Redis缓存频繁查询的数据，减少数据库压力
分页：大数据量时必须分页，不要一次返回所有数据
限流：对每个用户/IP设置请求频率限制，防止恶意请求
压缩：开启 Gzip 压缩，减少响应体积
索引：对查询频繁的字段建立数据库索引

总结：RESTful API设计的核心是“一致性”——URL命名、响应格式、错误处理都要统一。好的API让前端用起来舒服，也让后期维护更轻松。