前后端接口版本兼容如何设计？前端如何应对接口变更？

简化版

接口版本兼容是为了避免后端字段、语义或路径变化导致旧前端崩溃。常见策略包括新增字段优先、避免破坏性删除、字段保持向后兼容、使用版本号路径或 header、灰度发布、契约测试和前端容错解析。前端要避免强依赖非必要字段，对缺失字段提供默认值，对枚举未知值兜底，并通过监控发现接口异常。

详细版

前后端发布节奏不同，接口变更必须兼容一段时间。

变更类型	风险	推荐
新增字段	低	通常兼容
删除字段	高	先废弃再删除
字段改名	高	新旧字段并存过渡
枚举新增	中	前端要有 unknown 兜底
语义变化	高	新版本接口

const username = data.username ?? data.name ?? '未知用户'

接口兼容的核心不是版本号好看，而是不同版本前端和后端在灰度期能同时工作。

完整版教学

一、为什么接口兼容很重要

Web 页面可能被用户缓存，App 内 WebView 可能长时间不更新，灰度发布时也会同时存在新旧前端和新旧后端。

如果后端直接删除字段或改变语义，旧前端可能白屏或展示错误。

二、向后兼容原则

最安全的变更是新增字段，因为旧前端会忽略它。危险变更包括删除字段、改字段类型、改枚举语义、改变分页规则。

后端变更应遵守“先加后删、双写双读、观察后清理”的节奏。

三、版本号放在哪里

接口版本可以放路径、header 或 query。

方式	示例	特点
路径	`/api/v2/users`	清晰直观
Header	`Accept-Version: 2`	路径稳定
Query	`?version=2`	简单但容易混乱

版本号不是越多越好，频繁开新版本会增加维护成本。

四、前端容错解析

前端不能假设所有字段都一定存在。展示层要有默认值，关键逻辑要判断类型。

function normalizeUser(raw: any) {
  return {
    id: String(raw.id),
    name: raw.name ?? raw.nickname ?? '未命名',
    role: ['admin', 'user'].includes(raw.role) ? raw.role : 'user'
  }
}

可以用 adapter 层把接口数据转成页面模型。

五、枚举新增的坑

后端新增状态 pending_review，旧前端如果 switch 没有 default，可能显示空白。

switch (status) {
  case 'success': return '成功'
  case 'failed': return '失败'
  default: return '处理中'
}

未知枚举必须有兜底展示。

六、契约测试和监控

契约测试可以检查接口响应是否满足前端依赖。OpenAPI、TypeScript 类型生成、Mock 服务都能帮助提前发现破坏性变更。

线上要监控接口错误率、字段缺失、JSON 解析失败和页面白屏。

七、常见误区与追问

误区：接口加版本号就一定兼容。 版本号只是手段，灰度期新旧版本能否共存才关键。
误区：前端可以完全相信接口字段。 网络异常、灰度和旧缓存都可能让字段缺失或格式不同。
误区：枚举值不会新增。 业务状态经常扩展，前端必须有 unknown 兜底。
追问：字段改名怎么平滑迁移？ 后端新旧字段并存，前端兼容读取，监控稳定后再删除旧字段。
追问：前端 adapter 层有什么价值？ 隔离接口模型和页面模型，减少接口变化扩散。
追问：如何发现破坏性变更？ 契约测试、类型生成、Mock 校验和线上异常监控一起用。

八、加强记忆

接口兼容记成“新旧前后端能同台演出”。新增优先，删除谨慎，枚举兜底，adapter 隔离，契约测试和监控负责提前报警。

简化版

详细版