API 契约版本管理：兼容比整洁更重要

// ❌ 坏做法：直接改字段名
// v1 原始返回
{
  "user_id": 12345,
  "display_name": "张三",
  "avatar_url": "https://cdn.example.com/avatar.jpg",
  "created_at": "2025-01-15T08:30:00Z"
}

// ✅ 好做法：新增字段，保留旧字段，标记弃用
interface UserProfileResponse {
  // 旧字段——保留，标记弃用
  /** @deprecated Use userId instead. Will be removed after 2026-12-31. */
  user_id: number
  /** @deprecated Use displayName instead. Will be removed after 2026-12-31. */
  display_name: string
  /** @deprecated Use avatarUrl instead. Will be removed after 2026-12-31. */
  avatar_url: string
 
  // 新字段——驼峰风格
  userId: number
  displayName: string
  avatarUrl: string
  createdAt: string
}
 
// 服务端实现：同时填充新旧字段
function buildUserProfileResponse(user: User): UserProfileResponse {
  return {
    // 旧字段：保持与历史一致
    user_id: user.id,
    display_name: user.name,
    avatar_url: user.avatar,
    // 新字段：同样的数据
    userId: user.id,
    displayName: user.name,
    avatarUrl: user.avatar,
    createdAt: user.createdAt.toISOString(),
  }
}

// ❌ 坏做法：新增枚举值后，旧客户端的 default 分支产生误导
// 客户端代码（旧版本）
function renderOrderStatus(status: string): string {
  switch (status) {
    case 'pending': return '待支付'
    case 'paid': return '已支付'
    case 'shipped': return '已发货'
    case 'completed': return '已完成'
    default: return '未知状态'  // refunding 走到这里，用户困惑
  }
}

// ✅ 好做法：枚举值用能力协商 + 客户端降级策略
// 客户端代码（改进后）
function renderOrderStatus(status: string): string {
  const knownStatus: Record<string, string> = {
    pending: '待支付',
    paid: '已支付',
    shipped: '已发货',
    completed: '已完成',
  }
  // 未知枚举值：显示通用但准确的文案，而不是「未知」
  return knownStatus[status] ?? '处理中'
}
 
// 服务端同时提供结构化状态信息
interface OrderStatusInfo {
  code: string        // 'refunding'
  label: string       // '退款中'——服务端提供人类可读标签
  isFinal: boolean    // false
  allowActions: string[]  // ['view_refund_progress', 'contact_support']
}

// ✅ 服务端返回结构化状态，而不是纯枚举字符串
{
  "orderId": "ORD-2026062601",
  "status": {
    "code": "refunding",
    "label": "退款中",
    "isFinal": false,
    "allowedActions": ["view_refund_progress", "contact_support"]
  }
}

// ❌ 坏做法：复用已有错误码
enum PaymentErrorCode {
  INSUFFICIENT_BALANCE = 10001,
  WRONG_PASSWORD = 10002,
  // 原本是 ACCOUNT_FROZEN，被改成了 CHANNEL_TIMEOUT
  CHANNEL_TIMEOUT = 10003,  // ❌ 复用了账户冻结的码
  ACCOUNT_FROZEN = 10008,   // ❌ 迁移到了新码，但旧调用方还在监听 10003
}

// ✅ 好做法：错误码只增不改不删
enum PaymentErrorCode {
  INSUFFICIENT_BALANCE = 10001,
  WRONG_PASSWORD = 10002,
  ACCOUNT_FROZEN = 10003,        // 保持原义不变
  // 新增错误码使用新编号
  CHANNEL_TIMEOUT = 10004,       // ✅ 新增，不复用已有码
  CHANNEL_UNAVAILABLE = 10005,   // ✅ 继续递增
}
 
// 错误响应结构保持完整
interface PaymentError {
  code: PaymentErrorCode
  message: string           // 人类可读描述
  details?: {               // 可选的结构化上下文
    channelCode?: string    // 渠道原始错误码
    retryAfter?: number     // 建议重试间隔（秒）
  }
}

## 支付模块错误码注册表（节选）
 
| 编码  | 含义         | 状态   | 引入版本 | 备注                    |
|-------|-------------|--------|---------|------------------------|
| 10001 | 余额不足     | 活跃   | v1.0    |                        |
| 10002 | 密码错误     | 活跃   | v1.0    |                        |
| 10003 | 账户冻结     | 活跃   | v1.0    | 不可复用给其他含义      |
| 10004 | 渠道超时     | 活跃   | v1.2    | 原计划复用 10003，已纠正 |
| 10005 | 渠道不可用   | 活跃   | v1.2    |                        |

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.example.com/migration/v2>; rel="successor-version"
Warning: 299 - "This API version will be retired on 2026-12-31. See migration guide."
 
{
  "data": { ... },
  "_deprecation": {
    "message": "This endpoint is deprecated. Please migrate to /api/v2/orders.",
    "sunsetDate": "2026-12-31T23:59:59Z",
    "migrationGuide": "https://docs.example.com/migration/v2"
  }
}

// ✅ 好做法：在网关层采集版本级和字段级使用指标
function trackApiUsage(req: Request, res: Response) {
  const apiVersion = req.headers['api-version'] ?? 'unknown'
  const endpoint = req.path
 
  // 版本级指标
  metrics.increment(`api.calls.${endpoint}.${apiVersion}`)
 
  // 字段级指标（通过响应拦截器统计）
  const deprecatedFields = ['user_id', 'display_name', 'avatar_url']
  for (const field of deprecatedFields) {
    if (res.body && field in res.body) {
      metrics.increment(`api.deprecated_field.${field}.read`)
    }
  }
}