远端配置最危险的地方，不是请求失败，而是请求成功、JSON 也能解析，里面某两个字段却悄悄改变了类型。应用没有崩，只是在特定用户那里把支付按钮隐藏了。

一、一次“成功响应”带来的灰度事故

Demo 叫 ConfigShield Lab，配置发布 ID 为 cfg_20261001_13，版本 42。服务端返回 48 个字段，其中 7 个是本次新增；灰度比例为 10%，缓存有效期 30 分钟。事故来自两个字段：payEntry.enabled 从布尔值变成字符串，feed.pageSize 被配置成 0。

JSON.parse 没报错，HTTP 状态也是 200。旧代码用可选链和默认值读取，支付入口拿到字符串后在某些判断中被当成真值，分页大小为 0 又让请求循环停不下来。最难排查的是，两个问题只影响命中灰度的用户，重启后缓存还会继续生效。

最终方案使用 Zod 做运行时 Schema 校验，但没有采取“一个字段错、整份配置全部丢弃”的粗粒度策略。48 个字段中，7 个新增字段进入灰度，2 个错误字段被拒绝并回退到上一版，其余 46 个字段照常生效；解析耗时 4.8 ms，状态 CONFIG_SAFE。

复盘日志时还有一个细节很关键：旧实现只打印“配置加载成功”，所以接口层完全看不出问题。新实现把“获取成功”和“晋升成功”拆成两个事件。前者说明网络与反序列化完成，后者才说明字段校验、灰度、回退、缓存写入全部结束。监控面板也分别统计请求成功率、字段拒绝率和快照晋升率。这样即便 HTTP 仍是百分之百成功，拒绝率突然上升也会单独告警。

核心判断是：远端配置不是一个不可分割的 JSON 文件，而是一组风险不同的字段。安全开关、支付入口等关键字段失败时应关闭或回退；颜色、文案等非关键字段可以使用本地默认；实验字段则必须同时满足 Schema、灰度和过期条件。

二、Schema 先表达业务约束，而不只检查类型

只写 z.number() 还不够。pageSize=0 类型正确，却违反业务边界；实验比例 150 也能被 number 接受。我们把范围、枚举和嵌套结构都放进 Schema，并给关键字段单独命名，方便错误定位。

下面这段代码解决“请求成功但值不可用”。它保留 48 个已知字段的结构，新字段通过明确扩展进入，而不是让任意未知键静默穿透。

import { z } from 'zod'

const PayEntrySchema = z.object({
  enabled: z.boolean(),
  minVersion: z.number().int().nonnegative()
}).strict()

const FeedSchema = z.object({
  pageSize: z.number().int().min(10).max(100),
  layout: z.enum(['LIST', 'GRID'])
}).strict()

export const RemoteConfigSchema = z.object({
  version: z.number().int().positive(),
  expiresInSec: z.number().int().min(60).max(3600),
  canaryPercent: z.number().min(0).max(100),
  payEntry: PayEntrySchema,
  feed: FeedSchema,
  searchHint: z.string().max(40)
}).strict()

export type RemoteConfig = z.infer<typeof RemoteConfigSchema>

strict() 是刻意选择。未知字段如果直接通过，客户端可能误以为已经支持服务端的新能力。正式项目可以使用版本化 Schema：版本 42 只接受已知结构，版本 43 新增字段后再升级客户端，不把“可解析”误认为“可消费”。

Schema 属于进程级常量，不需要页面反复创建。Zod 校验失败会返回路径、期望类型和实际值，但日志不能原样打印整个配置，尤其是 URL、实验标识或可能包含业务秘密的字段。我们只记录路径、规则和配置版本。

三、整份 safeParse 不够，还要字段级隔离

如果直接对整份对象调用 RemoteConfigSchema.safeParse()，一个错误会让 46 个正确字段也回退。对发布者来说，这很安全；对正在灰度的新首页来说，却会把无关模块一起关掉。我们给每个配置域定义独立策略：FAIL_CLOSED、LAST_KNOWN_GOOD、LOCAL_DEFAULT。

这段代码解决“两个错误字段不拖垮整份配置”。每个域分别校验，失败时按策略选择值，并记录是否来自网络、旧值或本地默认。

type Source = 'REMOTE' | 'LAST_KNOWN_GOOD' | 'LOCAL_DEFAULT'

interface FieldResult<T> {
  value: T
  source: Source
  error?: string
}

export function resolveField<T>(path: string, schema: z.ZodType<T>, raw: unknown,
  lastGood: T | undefined, localDefault: T,
  policy: 'FAIL_CLOSED' | 'LAST_KNOWN_GOOD' | 'LOCAL_DEFAULT'): FieldResult<T> {
  const parsed = schema.safeParse(raw)
  if (parsed.success) return { value: parsed.data, source: 'REMOTE' }

  if (policy === 'FAIL_CLOSED') {
    return { value: localDefault, source: 'LOCAL_DEFAULT', error: `${path}:closed` }
  }
  if (policy === 'LAST_KNOWN_GOOD' && lastGood !== undefined) {
    return { value: lastGood, source: 'LAST_KNOWN_GOOD', error: `${path}:fallback` }
  }
  return { value: localDefault, source: 'LOCAL_DEFAULT', error: `${path}:default` }
}

支付入口使用 FAIL_CLOSED，错误时明确关闭；分页大小使用 LAST_KNOWN_GOOD，恢复版本 41 的 24；搜索提示文案使用 LOCAL_DEFAULT。本轮因此出现 2 个拒绝、2 个回退，其他域不受影响。

字段级隔离不等于可以随意混搭版本。存在跨字段约束时，必须把相关字段放在同一个域内共同校验。例如 minVersion 和 enabled 属于支付入口，不能一个来自新配置、一个来自旧配置。域是最小原子单位，而不是每个叶子字段都独立。

四、灰度命中也需要稳定身份与代际

配置版本 42 设置 10% 灰度。如果每次启动都用随机数判断，用户今天看到新布局，明天又回旧布局，问题难以复现。我们用匿名安装桶计算稳定命中，但不把账号或设备标识发送到配置服务。

同时，请求可能乱序返回：版本 42 的慢请求晚于版本 43，若直接覆盖内存，新配置会被旧响应倒退。下面的仓库用 generation 和版本号共同守门，只允许更新的已校验配置晋升为当前值。

export class ConfigRepository {
  private generation = 0
  private currentVersion = 41
  private current?: ResolvedConfig

  async refresh(): Promise<void> {
    const requestGeneration = ++this.generation
    const response = await fetchRemoteConfig()
    if (requestGeneration !== this.generation) return
    if (response.version <= this.currentVersion) return

    const resolved = resolveDomains(response, this.current)
    await atomicWrite(`config-${response.version}.json`, JSON.stringify(resolved))
    if (requestGeneration !== this.generation) return

    this.current = resolved
    this.currentVersion = response.version
    publishState('CONFIG_SAFE', resolved)
  }

  dispose(): void {
    this.generation += 1
    this.current = undefined
  }
}

数据变化顺序是：请求返回、Schema 校验、字段域回退、原子写缓存、再次检查代际、最后发布 UI 状态。页面在 publishState 之前看不到半成品。重复刷新会让旧 generation 自动失效，不需要让每个页面都维护取消标志。

dispose() 只用于业务容器真正销毁，普通页面隐藏不应该清空全局配置。网络请求最好配合 Network Kit 的超时与取消能力，但即使底层请求无法立即停止，代际检查也能阻止旧结果写入。缓存文件通过临时文件重命名晋升，避免进程退出留下损坏 JSON。

仓库外面还有一层订阅适配器。旧实现每解析一个字段就发一次通知，48 个字段会让 ArkUI 页面在很短时间内反复重建；更糟的是，前几个通知到达时，支付域已经更新，分页域仍是旧值，页面短暂处在一个从未发布过的混合版本。现在 ResolvedConfig 在内存中完整组装，通过不可变快照一次替换。订阅者收到的是 version + values + sources + errors 四部分一致的数据，渲染层不再自己拼来源。

为了验证没有重复发布，我给仓库加了内容摘要。版本相同且摘要相同的响应只刷新拉取时间，不触发 UI；版本相同但内容不同则视为服务端违规发布，记录告警并保持当前快照。远端配置系统最忌讳在同一版本下偷偷改内容，因为客户端缓存、问题追踪和回滚都会失去锚点。发布侧应强制版本不可变，客户端的摘要检查则是最后一道保险。

五、TTL 到期以后，旧值还能不能用

缓存有效期是 30 分钟。到期后如果网络不可用，完全丢掉配置会让页面突变；无限使用旧值，又可能让已撤回的实验长期存在。我们按风险区分：支付与安全域过期后回到本地安全默认，普通布局域允许最多宽限 6 小时，实验域到期立即退出灰度。

手机页面展示版本 42、48 个字段、新增 7、拒绝 2、回退 2、灰度 10%、TTL 30 分钟和解析 4.8 ms。每个域还能展开查看来源：支付入口 LOCAL_DEFAULT，分页大小 LAST_KNOWN_GOOD(v41)，其余为 REMOTE(v42)。状态栏时间 13:46，最终状态 CONFIG_SAFE。

TTL 的起点也经过一次修正。起初我们用设备收到响应的时间作为起点，用户手动调整系统时间后，缓存可能突然过期或被延长。现在响应包含服务端签发时间，客户端同时记录单调时钟的接收点；本次进程内用单调时间判断，重启后再结合签发时间与可信时间偏差计算。若时间明显回拨，安全域直接采用本地默认，普通域也不会超过 6 小时宽限。这个策略宁可少开一个实验，也不让撤回后的功能长期残留。

离线启动时，页面不会先渲染远端旧值再闪回默认。仓库先读取缓存元数据，按域完成过期判决，生成一份可用快照后才发布首屏。网络恢复后拿到版本 42，只替换满足规则的域。于是 payEntry.enabled 类型错误时，支付入口从首帧开始就是关闭状态；feed.pageSize 则稳定使用版本 41 的 24，不会经历 0、24、0 的抖动。对用户来说这是视觉稳定，对工程来说则减少了一批难以复现的竞态。

六、测试和发布边界

我们准备了四类配置：完全正确、类型错误、范围错误、跨域版本倒退。自动化不仅检查最终值，还检查来源标记和错误路径。两个错误字段必须分别产生 payEntry.enabled:closed 与 feed.pageSize:fallback，不能只得到一句“解析失败”。

灰度测试固定匿名桶，覆盖命中与未命中两组；时间测试用可注入时钟推进 30 分钟和 6 小时，避免真的等待。配置服务返回 42、43、42 的乱序序列时，最终版本必须保持 43。应用前后台切换不会重复应用同一版本，订阅者只收到一次晋升事件。

我们还专门测试了安装桶变化。匿名桶不能从账号昵称、广告标识或可被用户频繁清理的临时值生成，否则同一设备会在灰度内外来回跳。Demo 使用应用安装范围内的随机种子，首次启动生成后只保存在本地，再对 experimentKey + seed 做稳定哈希。退出账号不会改变桶，卸载重装会重新分桶，这是产品能够解释的边界。若业务要求同一账号跨设备一致，应改用服务端分桶，但要同步处理隐私、登录前状态和账号切换。

错误可观测性也按层拆开。网络失败记录请求阶段与错误码；Schema 失败记录字段路径和规则；回退记录来源版本；灰度未命中只计数，不当作错误。这样看到 rejected=2 时可以继续定位到两个字段，而不会和超时混在一个“配置加载失败”指标里。HiLog 的发布摘要只包含 release=cfg_20261001_13 version=42 fields=48 等非敏感统计，完整错误详情进入受控诊断数据。

发布流程最后加了一道样本门禁：服务端准备发布版本 42 时，先用客户端同版本 Schema 跑一组真实脱敏样本，再进行 1%、10%、50% 的递增灰度。每一阶段观察拒绝率、回退率和版本晋升率，而不是只看接口成功率。本次 10% 阶段出现两个字段拒绝，系统仍保持 CONFIG_SAFE，但发布平台应暂停继续扩量，直到配置被修正。客户端兜底保证用户安全，不等于服务端可以忽略错误。

第三方校验库也要纳入依赖治理。锁定 Zod 版本、记录许可证和包摘要，升级前跑配置样本集。不要在运行时从远端加载 Schema 代码；远端只能提供数据，校验规则随客户端发布，这样审核和回滚才有稳定依据。

这次事故最后没有通过更多 if 修补，而是建立了配置进入应用的明确路径：Network Kit 获取数据，Zod 验证结构和业务边界，字段域策略决定失败后取值，代际与 TTL 决定何时晋升和退出。CONFIG_SAFE 不是“网络成功”，而是每个正在生效的值都有可解释来源。