RESTful API 设计原则与最佳实践

一、REST架构概述

REST(Representational State Transfer)是一种软件架构风格，通过统一接口、无状态通信等原则实现系统间的交互。

二、资源命名规范

资源命名应使用名词而非动词，采用小写字母和连字符分隔。

// 推荐的资源命名
GET /api/products          // 获取产品列表
GET /api/products/1        // 获取单个产品
POST /api/products         // 创建产品
PUT /api/products/1        // 更新产品
DELETE /api/products/1     // 删除产品

// 嵌套资源
GET /api/products/1/reviews    // 获取产品的评论
GET /api/users/1/orders        // 获取用户的订单

三、HTTP方法使用规范

正确使用HTTP方法表达操作意图。

四、状态码设计

使用合适的HTTP状态码传达请求结果。

// 成功响应
200 OK              // 请求成功
201 Created         // 资源创建成功
204 No Content      // 请求成功但无内容返回

// 客户端错误
400 Bad Request     // 请求参数错误
401 Unauthorized    // 未认证
403 Forbidden       // 无权限
404 Not Found       // 资源不存在
409 Conflict        // 资源冲突

// 服务器错误
500 Internal Server Error  // 服务器内部错误
503 Service Unavailable    // 服务不可用

五、API版本控制

API版本控制确保向后兼容性。

// 方法一：URL版本控制（推荐）
GET /api/v1/products
GET /api/v2/products

// 方法二：HTTP头部版本控制
Accept: application/vnd.example.v1+json

// 方法三：查询参数版本控制
GET /api/products?version=1

六、请求参数设计

合理设计查询参数、路径参数和请求体。

// 查询参数示例
GET /api/products?category=electronics&minPrice=100&page=1&size=10

// 过滤、排序、分页
GET /api/products?filter[name]=iPhone&sort=price&order=desc&page=2&limit=20

七、错误处理与响应格式

统一的错误响应格式便于客户端处理。

{
    "error": {
        "code": "INVALID_ARGUMENT",
        "message": "参数验证失败",
        "details": [
            { "field": "email", "message": "邮箱格式不正确" },
            { "field": "password", "message": "密码长度至少6位" }
        ]
    }
}

八、认证与授权

使用JWT、OAuth2等标准协议进行认证授权。

九、API文档

使用Swagger/OpenAPI提供完整的API文档。

十、安全性考虑

包括HTTPS、输入验证、限流、CORS配置等方面。