20.2 RESTful API 设计

20.2 RESTful API 设计

RESTful API 是现代前后端分离架构的核心通信桥梁，优秀的设计能显著提升系统可维护性和开发效率。本节将深入讲解电商平台中的RESTful API设计规范与最佳实践。

核心设计原则

1. Richardson成熟度模型

2. 统一接口约束

// 优秀设计示例
GET    /products          // 获取商品列表
POST   /products          // 创建新商品
GET    /products/{id}     // 获取特定商品
PUT    /products/{id}     // 全量更新商品
PATCH  /products/{id}     // 部分更新商品
DELETE /products/{id}     // 删除商品

资源命名规范

3. 电商资源模型设计

classDiagram
    class Product {
        +id: string
        +name: string
        +price: number
        +sku: string
        +categories: Category[]
    }
    
    class Category {
        +id: string
        +name: string
        +products: Product[]
    }
    
    class Order {
        +id: string
        +user: User
        +items: OrderItem[]
        +status: string
    }
    
    class User {
        +id: string
        +email: string
        +orders: Order[]
    }
    
    Product "1" -- "0..*" Category
    Order "1" -- "1..*" Product
    User "1" -- "0..*" Order

4. 端点设计示例

请求与响应设计

5. 请求头规范

GET /api/v1/products HTTP/1.1
Accept: application/json
Accept-Language: zh-CN
Authorization: Bearer xxxxxx
X-Request-ID: 3a7b3f4d-2c5e-4a1b-9f8e-c6d5a2b3e1f7
If-None-Match: "a3f4e5"

6. 响应结构设计

{
  "data": {
    "id": "prod_123",
    "type": "products",
    "attributes": {
      "name": "智能手机",
      "price": 2999.00,
      "stock": 100
    },
    "relationships": {
      "category": {
        "data": { "id": "cat_1", "type": "categories" }
      }
    },
    "links": {
      "self": "/products/prod_123"
    }
  },
  "included": [
    {
      "id": "cat_1",
      "type": "categories",
      "attributes": {
        "name": "电子产品"
      }
    }
  ],
  "meta": {
    "total": 1,
    "page": 1
  },
  "links": {
    "self": "/products?page=1",
    "next": "/products?page=2"
  }
}

高级设计模式

7. 过滤、排序与分页

GET /api/v1/products?
  filter[price][gte]=1000&
  filter[price][lte]=5000&
  filter[category]=electronics&
  sort=-price,name&
  page[number]=1&
  page[size]=20&
  fields[products]=name,price&
  include=category

参数说明：

• filter: 多条件过滤
• sort: 多字段排序(-表示降序)
• page: 分页控制
• fields: 稀疏字段集
• include: 关联资源

8. 批量操作设计

POST /api/v1/batch HTTP/1.1
Content-Type: application/json

{
  "operations": [
    {
      "method": "POST",
      "path": "/products",
      "body": {
        "name": "新品1",
        "price": 999
      }
    },
    {
      "method": "PATCH",
      "path": "/products/123",
      "body": {
        "stock": 50
      }
    }
  ]
}

错误处理规范

9. 标准错误响应

{
  "error": {
    "code": "invalid_parameter",
    "message": "价格必须大于0",
    "target": "price",
    "details": [
      {
        "code": "range_error",
        "message": "值不能小于0",
        "target": "price"
      }
    ],
    "innererror": {
      "traceId": "a1b2c3d4",
      "timestamp": "2023-08-20T12:34:56Z"
    }
  }
}

10. HTTP状态码使用指南

版本控制策略

11. 多版本共存方案

# URL路径版本
GET /api/v1/products

# 请求头版本
GET /api/products HTTP/1.1
Accept: application/vnd.myapi.v1+json

# 自定义头版本
GET /api/products HTTP/1.1
X-API-Version: 1

12. 版本迁移路线图

timeline
    title API版本演进计划
    section 2023
        Q3 : v1.0 基础商品/订单API
        Q4 : v1.1 新增评价系统
    section 2024
        Q1 : v2.0 不兼容变更(移除旧字段)
        Q2 : v1.x 仅安全更新

性能优化设计

13. 缓存控制策略

GET /api/v1/products/123 HTTP/1.1
If-None-Match: "a1b2c3d4"

HTTP/1.1 304 Not Modified
ETag: "a1b2c3d4"
Cache-Control: public, max-age=3600
Last-Modified: Wed, 21 Oct 2023 07:28:00 GMT

14. 部分响应(Partial Response)

GET /api/v1/products/123?fields=name,price HTTP/1.1
Range: bytes=0-1023

HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1023/2048

安全设计实践

15. 认证与授权

// JWT认证流程
POST /auth/token
→ 返回access_token和refresh_token

// 访问受保护资源
GET /api/orders
Authorization: Bearer <access_token>

// 刷新token
POST /auth/refresh-token
{ "refresh_token": "xxxx" }

16. 敏感操作审计

{
  "action": "order.create",
  "user_id": "user_123",
  "ip": "192.168.1.100",
  "user_agent": "Mozilla/5.0",
  "timestamp": "2023-08-20T12:34:56Z",
  "metadata": {
    "order_id": "order_456",
    "total_amount": 2999.00
  }
}

文档化规范

17. OpenAPI 3.0示例

openapi: 3.0.0
info:
  title: 电商平台API
  version: 1.0.0

paths:
  /products:
    get:
      summary: 获取商品列表
      parameters:
        - $ref: '#/components/parameters/pageNumber'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: 成功获取商品列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'

components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        price:
          type: number
          format: float
  parameters:
    pageNumber:
      name: page[number]
      in: query
      schema:
        type: integer
        default: 1

电商平台特有API设计

18. 购物车API设计

# 获取当前用户购物车
GET /api/v1/cart

# 添加商品到购物车
POST /api/v1/cart/items
{
  "product_id": "prod_123",
  "quantity": 2
}

# 更新购物车项
PATCH /api/v1/cart/items/item_123
{
  "quantity": 3
}

# 结算购物车
POST /api/v1/cart/checkout
{
  "shipping_address": "xxx",
  "payment_method": "credit_card"
}

19. 订单状态机设计

stateDiagram-v2
    [*] --> PENDING
    PENDING --> PAID: 支付成功
    PENDING --> CANCELLED: 用户取消
    PAID --> PROCESSING: 商家接单
    PROCESSING --> SHIPPED: 发货
    SHIPPED --> DELIVERED: 确认收货
    SHIPPED --> RETURNING: 发起退货
    RETURNING --> RETURNED: 退货完成
    DELIVERED --> COMPLETED: 订单完成

对应API端点：

POST /api/v1/orders/{id}/pay     # 支付订单
POST /api/v1/orders/{id}/cancel  # 取消订单
POST /api/v1/orders/{id}/ship    # 发货操作

实时API设计

20. WebSocket API设计

// 建立连接
wss://api.example.com/notifications

// 订阅消息
{
  "action": "subscribe",
  "channel": "order_updates",
  "token": "xxxxxx"
}

// 接收消息
{
  "event": "order.updated",
  "data": {
    "order_id": "order_123",
    "new_status": "shipped"
  },
  "timestamp": "2023-08-20T12:34:56Z"
}

通过以上设计规范，你可以构建出符合RESTful原则、高性能且易于维护的电商平台API。接下来我们将学习数据库集成方案。