后端悄悄换了 API 字段结构，前端在发布窗口期集体崩溃——规范化层救场

后端把一个字段从 string[] 改成了 {type, priority, text}[]，同时把另一个字段从中文枚举换成了英文 enum，还把一个大字段拆成了三个小字段——改动合理，前后端沟通也到位，上线当天似乎一切正常。

然后噩梦开始了：部分用户的页面区块一片空白，有用户开始上报 Cannot read property 'priority' of string。排查日志才发现：小程序 OTA 存在延迟，大约 10-30% 的活跃用户手里还是老版前端，但后端已经切流推出了 v2 响应——v1 前端代码遇到 v2 JSON，直接爆。

现象

后端先切流：前端 v1 代码碰到 v2 结构 → stage 是英文 enum 识别不了，徽章变灰；actions[0].text 直接报 TypeError，因为 actions 现在是对象数组而原来是字符串数组
前端先发布：新版前端读到 v1 响应 → 新 UI 区块全空白，dailyTip / winbackTip 字段不存在，显示为 undefined
即便前后端「同日上线」，服务端灰度切流期间仍有请求返回 v1，前端偶发崩溃难以复现

根因

前端把 API 的原始 res.data 直接 setData 或 setState，组件绑定的字段结构 = 后端的 JSON 契约。契约一变，渲染层直接爆炸，中间没有任何缓冲。

坑：raw JSON 直接进 setData，API 换结构就是零日崩溃

只要后端 API 发生 breaking change——字段类型变了、嵌套层级变了、枚举值换语言——前端哪怕提前一分钟上线，发布窗口期内也必然有用户崩溃。小程序没有强制升级机制，OTA 延迟可达数天，这个窗口期可能很长。

正解

在数据进入 setData / setState 之前插入一层 _normalizeV2(raw) 函数，让它同时识别 v1 和 v2 结构，统一输出 v2 shape。组件只认规范化后的数据，完全不感知后端处于哪个版本。

// 微信小程序示例
const STAGE_V1_TO_V2 = {
  '成熟期': 'mature', '成长期': 'growing', '新客引入期': 'introducing',
  '衰退期': 'declining', '流失期': 'lost',
}
const STAGE_COLOR_MAP = {
  mature: '#10b981', growing: '#3b82f6', introducing: '#06b6d4',
  declining: '#f97316', lost: '#ef4444',
}
 
_normalizeV2(raw) {
  if (!raw) return null
 
  // stage：v1 中文枚举 → v2 英文 enum（有则直通，无则映射）
  const stage = STAGE_V1_TO_V2[raw.stage] || raw.stage || 'mature'
 
  // actions：v1 string[] → v2 object[]（typeof 判断做升级）
  let actions = raw.actions || []
  if (actions.length && typeof actions[0] === 'string') {
    actions = actions.map(text => ({ type: 'care', priority: 'mid', text }))
  }
 
  // 拆分字段：v1 speechTip 回退成 v2 dailyTip
  return {
    stage,
    stageLabel: raw.stageLabel || raw.stage || '',
    stageColor: STAGE_COLOR_MAP[stage] || '#94a3b8', // 颜色前端自己 map，不依赖后端
    actions,
    dailyTip: raw.dailyTip || raw.speechTip || '',  // v1 兼容回退
    winbackTip: raw.winbackTip || '',
    festivalTip: raw.festivalTip || '',
    tags: raw.tags || [],
    summary: raw.summary || '',
  }
}
 
// 调用处：只改这一行
fetchData() {
  api.getData().then(res => {
    this.setData({ detail: this._normalizeV2(res.data) })
  })
}

正解：规范化层隔离后端契约，v1/v2 双态同时支持

在数据入口插 _normalizeV2(raw)，让它吞 v1 吐 v2。用 typeof actions[0] === 'string' 判断数组元素类型做升级，用 raw.dailyTip || raw.speechTip || '' 做字段回退，枚举值的颜色前端自己 map 不依赖后端。过渡窗口期 v1/v2 都能正常渲染，零崩溃。

几条关键规则

规范化层必须覆盖的四个场景：

字段类型变了（string → object）：用 typeof 或 Array.isArray 做运行时判断，分支处理
枚举值换语言（中文 → 英文）：维护一张映射表，MAP[raw.val] || raw.val 双重回退
字段被拆分（一 → 多）：新字段 || 旧字段作为默认值
展示样式与 API 解耦：颜色、图标、文案由前端 enum→style map 决定，不从后端拿 hex

生命周期管理：规范化层是临时代码。等后端稳定 v2 超过两周、客户端触达率 > 99% 之后，主动删除 v1 兼容分支，否则就是技术债无限堆积。

验收两态缺一不可

规范化层写完，必须分别喂 v1 mock 和 v2 mock 各跑一遍：v1 不崩且新区块空态折叠，v2 完整渲染新区块——两态都通过才算验收。

一句话外卖

前端的稳定性边界不应该是 API 契约，而应该是规范化层——只要在数据入口做好 v1/v2 双态识别，后端随时切流、前端随时发版，过渡窗口期就不会崩溃。