API 设计与实现：现代技术架构指南

资源（Resource）→ 标识符（URI）→ 表征（Representation）→ 状态转移（State Transfer）

# 资源命名使用名词复数形式
GET    /api/v1/users              # 用户集合
GET    /api/v1/users/{userId}     # 单个用户
POST   /api/v1/users              # 创建用户
PUT    /api/v1/users/{userId}     # 替换用户
PATCH  /api/v1/users/{userId}     # 部分更新
DELETE /api/v1/users/{userId}     # 删除用户
 
# 子资源关系表达
GET    /api/v1/users/{userId}/orders           # 用户订单集合
GET    /api/v1/users/{userId}/orders/{orderId} # 特定订单
 
# 过滤、排序、分页通过查询参数实现
GET    /api/v1/users?status=active&sort=-createdAt&page=1&limit=20

syntax = "proto3";
 
package order.v1;
 
option go_package = "github.com/example/gen/order/v1;orderv1";
 
import "google/protobuf/timestamp.proto";
import "google/protobuf/field_mask.proto";
 
service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order);
  rpc ListOrders(ListOrdersRequest) returns (stream Order);
  rpc CreateOrder(stream CreateOrderRequest) returns (CreateOrderResponse);
  rpc ProcessOrders(stream OrderRequest) returns (stream OrderResponse);
}
 
message Order {
  string order_id = 1;
  string user_id = 2;
  repeated OrderItem items = 3;
  OrderStatus status = 4;
  google.protobuf.Timestamp created_at = 5;
  google.protobuf.Timestamp updated_at = 6;
}
 
message GetOrderRequest {
  string order_id = 1;
  google.protobuf.FieldMask read_mask = 2;
}

{
  "method": "POST",
  "url": "/api/v1/orders",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer <token>",
    "X-Request-ID": "uuid-v4",
    "X-Correlation-ID": "trace-across-services",
    "Idempotency-Key": "client-generated-key"
  },
  "body": {
    "data": {
      "type": "order",
      "attributes": {
        "items": [...],
        "shipping_address": {...}
      },
      "relationships": {
        "user": {"data": {"type": "user", "id": "123"}}
      }
    }
  }
}

{
  "jsonapi": {"version": "1.1"},
  "data": {
    "type": "order",
    "id": "order-123",
    "attributes": {
      "status": "pending",
      "total": 299.99,
      "created_at": "2025-06-07T10:30:00Z"
    },
    "relationships": {
      "user": {
        "data": {"type": "user", "id": "user-456"},
        "links": {"related": "/api/v1/orders/order-123/user"}
      }
    },
    "links": {"self": "/api/v1/orders/order-123"}
  },
  "meta": {
    "request_id": "req-uuid",
    "timestamp": "2025-06-07T10:30:01Z"
  }
}

{
  "type": "https://api.example.com/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 400,
  "detail": "Account balance $50.00 is insufficient for order total $299.99",
  "instance": "/api/v1/orders/order-123",
  "traceId": "trace-uuid-123",
  "errors": [
    {
      "code": "INSUFFICIENT_BALANCE",
      "field": "payment.amount",
      "message": "Required amount exceeds available balance"
    }
  ]
}

openapi: 3.1.0
info:
  title: Order Management API
  version: 1.2.0
  description: |
    Enterprise order management system API.
    Supports order lifecycle from creation to fulfillment.
  contact:
    name: API Support
    email: api@example.com
    url: https://developer.example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
 
servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://api.staging.example.com/v1
    description: Staging
 
tags:
  - name: Orders
    description: Order management operations
  - name: Users
    description: User account operations
 
paths:
  /orders:
    get:
      tags: [Orders]
      operationId: listOrders
      summary: List orders with filtering and pagination
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, processing, shipped, delivered, cancelled]
        - name: created_after
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'
              example:
                data:
                  - id: order-123
                    status: delivered
                    total: 299.99
                meta:
                  total: 150
                  page: 1
                  limit: 20
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    
    post:
      tags: [Orders]
      operationId: createOrder
      summary: Create a new order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created
          headers:
            Location:
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/BadRequest'
        '422':
          $ref: '#/components/responses/ValidationError'
 
  /orders/{orderId}:
    parameters:
      - $ref: '#/components/parameters/OrderIdParam'
    
    get:
      tags: [Orders]
      operationId: getOrder
      summary: Get order by ID
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          $ref: '#/components/responses/NotFound'
 
components:
  schemas:
    Order:
      type: object
      required: [id, status, items, total, created_at]
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        status:
          $ref: '#/components/schemas/OrderStatus'
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
          minItems: 1
        total:
          type: number
          format: decimal
          minimum: 0
          exclusiveMinimum: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
 
    OrderStatus:
      type: string
      enum: [pending, processing, shipped, delivered, cancelled]
      default: pending
 
    OrderItem:
      type: object
      required: [product_id, quantity, unit_price]
      properties:
        product_id:
          type: string
          format: uuid
        quantity:
          type: integer
          minimum: 1
          maximum: 100
        unit_price:
          type: number
          format: decimal
 
    CreateOrderRequest:
      type: object
      required: [items, shipping_address]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        shipping_address:
          $ref: '#/components/schemas/Address'
        payment_method_id:
          type: string
          format: uuid
 
    OrderList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
 
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
        has_more:
          type: boolean
 
  parameters:
    OrderIdParam:
      name: orderId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
 
  responses:
    BadRequest:
      description: Bad request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    Unauthorized:
      description: Authentication required
    NotFound:
      description: Resource not found
    ValidationError:
      description: Validation failed
    InternalError:
      description: Internal server error
 
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/oauth/authorize
          tokenUrl: https://auth.example.com/oauth/token
          scopes:
            read:orders: Read order information
            write:orders: Create and modify orders
            admin: Full administrative access
 
security:
  - BearerAuth: []
  - OAuth2: [read:orders]

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Link: </api/v2/orders>; rel="successor-version"
Link: </docs/migration/v1-to-v2>; rel="deprecation-help"
Warning: 299 - "API v1 is deprecated, migrate to v2 by 2025-12-31"

import crypto from 'crypto';
 
function generatePKCE() {
  const verifier = crypto.randomBytes(32).toString('base64url');
  const challenge = crypto
    .createHash('sha256')
    .update(verifier)
    .digest('base64url');
  
  return {
    code_verifier: verifier,
    code_challenge: challenge,
    code_challenge_method: 'S256'
  };
}

jwt_security:
  algorithm:
    allowed: [RS256, RS384, RS512, ES256, ES384, ES512]
    forbidden: [HS256, none]  # 禁止对称算法和无签名
  
  claims:
    required: [iss, sub, aud, exp, iat]
    issuer_validation: true
    audience_validation: true
  
  token:
    access_token_ttl: 900      # 15 分钟
    refresh_token_ttl: 604800  # 7 天
    id_token_ttl: 3600         # 1 小时
  
  key_management:
    rotation_enabled: true
    jwks_cache_ttl: 3600
    key_id_required: true
  
  transmission:
    secure_cookie: true
    cookie_same_site: strict
    cookie_http_only: true
    authorization_header_only: true

rate_limiting:
  global:
    requests_per_second: 10000
    concurrent_connections: 5000
  
  per_endpoint:
    /api/v1/orders:
      get:
        requests_per_minute: 1000
        burst: 100
      post:
        requests_per_minute: 100
        burst: 20
    
    /api/v1/search:
      requests_per_minute: 500
      cost_weight: 2  # 搜索消耗更多配额
  
  per_client:
    tier_free:
      requests_per_day: 1000
      requests_per_minute: 10
    tier_pro:
      requests_per_day: 100000
      requests_per_minute: 100
    tier_enterprise:
      requests_per_day: unlimited
      requests_per_minute: 1000
  
  headers:
    limit: X-RateLimit-Limit
    remaining: X-RateLimit-Remaining
    reset: X-RateLimit-Reset
    retry_after: Retry-After

{
  "specversion": "1.0.2",
  "type": "com.example.order.created",
  "source": "/services/order-service",
  "id": "A234-1234-1234",
  "time": "2025-06-07T10:30:00Z",
  "datacontenttype": "application/json",
  "dataschema": "https://schemas.example.com/order/v1",
  "subject": "order-12345",
  "data": {
    "orderId": "order-12345",
    "userId": "user-67890",
    "items": [...],
    "total": 299.99
  },
  "extension_traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

# 生成 TypeScript Axios 客端
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./sdk/typescript \
  --additional-properties=npmName=@example/api-client,npmVersion=1.0.0
 
# 生成 Go 客户端
openapi-generator-cli generate \
  -i openapi.yaml \
  -g go \
  -o ./sdk/go \
  --additional-properties=packageName=apiclient,isGoSubmodule=true
 
# 生成 Python 客户端
openapi-generator-cli generate \
  -i openapi.yaml \
  -g python \
  -o ./sdk/python \
  --additional-properties=packageName=example_api_client,packageVersion=1.0.0

// 消费者测试
const { Verifier } = require('@pact-foundation/pact');
const path = require('path');
 
describe('Order API Consumer Tests', () => {
  it('should match the order creation contract', async () => {
    const result = await new Verifier({
      providerBaseUrl: 'http://localhost:8080',
      pactUrls: [
        path.resolve(__dirname, './pacts/order-consumer-order-provider.json')
      ],
      providerVersion: '1.2.0',
      providerVersionTags: ['main'],
      publishVerificationResult: true,
      stateHandlers: {
        'user exists': () => userRepository.insert(testUser),
        'order is empty': () => orderRepository.clear()
      }
    }).verifyProvider();
    
    expect(result.matched).toBe(true);
  });
});

# prism-config.yaml
routes:
  - path: /api/*
    strategy: mock
    mock:
      dynamic: true
      code: 200
      delay:
        min: 100
        max: 500
      examples:
        - name: success
          code: 200
          mediaType: application/json
          body:
            id: "mock-order-123"
            status: "pending"
        - name: error
          code: 400
          mediaType: application/problem+json
          body:
            type: "https://example.com/errors/validation"
            title: "Validation Error"
 
logging:
  level: info
  format: json
 
cors:
  allowedOrigins: ["*"]
  allowedMethods: ["GET", "POST", "PUT", "DELETE"]

api_performance:
  request:
    - 启用 HTTP/2 或 HTTP/3
    - 启用 Gzip/Brotli 压缩
    - 使用 Keep-Alive 连接复用
    - 批量请求支持
  
  response:
    - 分页限制响应大小
    - 字段选择减少传输
    - ETag 支持 304 Not Modified
    - Cache-Control 头设置
  
  infrastructure:
    - CDN 缓存静态资源
    - API Gateway 响应缓存
    - 数据库查询优化
    - 连接池配置
  
  monitoring:
    - P50/P95/P99 延迟监控
    - 错误率告警
    - 流量异常检测
    - 容量规划预警

// 问题：REST 返回过多字段
GET /api/v1/users/123
Response: { id, name, email, address, phone, preferences, ... }  // 100+ 字段
 
// 解决方案 1：字段选择
GET /api/v1/users/123?fields=id,name,email
 
// 解决方案 2：GraphQL 精确查询
query { user(id: "123") { id name email } }

// 问题：循环调用 API
for (const order of orders) {
  const user = await fetchUser(order.userId);  // N 次请求
}
 
// 解决方案：批量查询或包含参数
GET /api/v1/orders?include=user
// 或
GET /api/v1/users?ids=user1,user2,user3

// 问题：重复提交创建多个订单
POST /api/v1/orders
{ "items": [...] }
 
// 解决方案：幂等键
POST /api/v1/orders
Headers: { "Idempotency-Key": "client-uuid-123" }
Body: { "items": [...] }
 
// 服务端存储幂等键，重复请求返回原结果

// 问题：时区混乱
{ "created_at": "2025-06-07 10:30:00" }  // 什么时区？
 
// 解决方案：统一 UTC + ISO 8601
{ "created_at": "2025-06-07T10:30:00Z" }
// 或带时区偏移
{ "created_at": "2025-06-07T18:30:00+08:00" }

ai_native_api:
  design_principles:
    - 语义清晰的端点命名
    - 完整的 OpenAPI 描述
    - 丰富的示例和错误说明
    - 结构化的错误响应
  
  llm_integration:
    - Function Calling 接口
    - 语义搜索 API
    - 向量数据库接口
    - 流式响应支持
  
  tools:
    - LangChain API 集成
    - OpenAI Function 定义
    - Semantic Kernel 插件

{
  "type": "function",
  "function": {
    "name": "create_order",
    "description": "创建新订单，包含商品列表和配送地址",
    "parameters": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "product_id": {"type": "string", "description": "商品ID"},
              "quantity": {"type": "integer", "minimum": 1}
            }
          }
        },
        "shipping_address": {
          "type": "object",
          "description": "配送地址"
        }
      },
      "required": ["items", "shipping_address"]
    }
  }
}

subscription OnOrderStatusChanged($orderId: ID!) {
  orderStatusChanged(orderId: $orderId) {
    id
    status
    updatedAt
    tracking {
      carrier
      trackingNumber
      location
    }
  }
}