一、JSON 能解析页面照样能被它拖垮FlagHarbor 的首页灰度配置已经跑了几个月事故却来自一次“合法 JSON”。任务FLAG-1534在 15:34 收到cfg_home_v12的第 73 代配置网络请求 184 ms正文 12,864 字节ETag 是W/9f2c-73。JSON.parse没报错ArkUI 的 Grid 随后拿到columns0预取调度又拿到prefetch-3。前者让布局计算失去意义后者把一段保护不足的循环推向异常。更麻烦的是用户快速切换网络后还有两条请求并行较新的第 73 代先返回并失败稍旧的请求随后抵达旧代码却把它当成最新结果提交。于是我们看到的不是稳定回退而是页面在默认值、旧值和坏值之间闪烁。最后我没有继续给每个 ArkUI 属性补Math.max而是把远程配置当成不可信输入先用 Zod 4 做运行时收窄再用请求代次阻止过期结果提交最后只从“已验证的最近好快照”回滚。Demo 的最终状态刻意保留为FALLBACK_ACTIVE。第 73 代发现 2 个问题columns0、prefetch-3最近好快照仍是第 72 代灰度比例 25%过期响应丢弃 1 次。页面稳定使用home-feed-v4的第 72 代参数不把解析成功误写成业务有效。二、Schema 是 UI 边界不是接口注释服务端 TypeScript 类型不会穿过网络。即使客户端和服务端共用接口声明线上响应也只是字节串as HomeFeedConfig只会让编译器闭嘴不会让columns0自动变成 2。FlagHarbor 用 Zod 4 定义唯一运行时入口并把类型从 Schema 推导出来避免一份接口类型和一份校验规则渐渐分叉。这一段解决的是字段存在但取值越界的问题。columns只能为 1 到 4 的整数prefetch只能为 0 到 12rollout是 0 到 100 的整数版本标识必须是字面量home-feed-v4。.strict()让未知字段显式失败避免服务端拼错字段名时客户端默默使用默认值掩盖发布错误。import{z}fromzod;exportconstHomeFeedSchemaz.object({schema:z.literal(home-feed-v4),configId:z.string().min(1),generation:z.number().int().nonnegative(),rollout:z.number().int().min(0).max(100),layout:z.object({columns:z.number().int().min(1).max(4),cardGapVp:z.number().min(4).max(32)}).strict(),loading:z.object({prefetch:z.number().int().min(0).max(12),timeoutMs:z.number().int().min(300).max(5000)}).strict()}).strict();exporttypeHomeFeedConfigz.infertypeofHomeFeedSchema;exportfunctionvalidateConfig(raw:unknown):HomeFeedConfig{constparsedHomeFeedSchema.safeParse(raw);if(!parsed.success){constcompactparsed.error.issues.map(issue${issue.path.join(.)}${issue.message});thrownewError(CONFIG_INVALID:${compact.join(|)});}returnparsed.data;}选择safeParse()而不是直接parse()是因为调用方需要把问题转成可展示、可统计的结构而不是只接一个异常。Demo 的诊断层进一步把两个 issue 映射为layout.columns0和loading.prefetch-3但不会把整份远程 JSON 写进日志以免配置中未来加入敏感或高体量字段。Schema 也不负责一切。业务上的“第 73 代必须大于第 72 代”属于提交规则不该塞进字段校验灰度命中依赖稳定设备桶也不等于单字段范围。把所有约束都写进一个巨大 refine会让错误路径难以测试也让缓存恢复依赖网络上下文。我的边界是Schema 只回答“这份对象能否安全进入应用层”Store 再回答“它此刻是否应该生效”。三、异步请求靠代次提交不靠返回顺序原实现用一个loading布尔值阻止重复请求但网络切换、手动刷新和前台恢复仍可能同时发起。取消请求不是完整答案底层回调可能已经排队或者取消失败。FlagHarbor 每次刷新递增requestEpoch提交前同时检查 epoch 和配置 generation。旧请求即使成功也只能被计入staleDropped不能修改 UI。下面的RemoteConfigLoader串起下载、解析、校验和回退。fetchJson返回的元数据固定包括耗时、字节数和 ETag便于把第 73 代问题与实际请求对应。失败时先从SnapshotStore读取最近好快照再次通过同一 Schema 校验避免“缓存天然可信”的错觉。interfaceFetchResult{raw:unknown;latencyMs:number;bytes:number;etag:string;}exportclassRemoteConfigLoader{privaterequestEpoch:number0;staleDropped:number0;constructor(privatesnapshots:SnapshotStore){}asyncrefresh(fetchJson:()PromiseFetchResult):PromiseLoadResult{constepochthis.requestEpoch;constresponseawaitfetchJson();if(epoch!this.requestEpoch){this.staleDropped;return{state:STALE_DROPPED};}constparsedHomeFeedSchema.safeParse(response.raw);if(parsed.success){constlastawaitthis.snapshots.read();if(lastparsed.data.generationlast.generation){this.staleDropped;return{state:STALE_DROPPED};}awaitthis.snapshots.write(parsed.data,response.etag);return{state:REMOTE_APPLIED,config:parsed.data};}constfallbackawaitthis.snapshots.readValidated();return{state:FALLBACK_ACTIVE,config:fallback,issues:parsed.error.issues,metrics:response};}}提交检查必须位于所有异步步骤之后。如果只在请求返回时检查 epoch随后读取缓存或写盘期间又发起了新请求旧链仍可能在末尾覆盖状态。生产版本在 Store 的commit()前再做一次令牌校验本文为了让核心路径可读保留了单写者约束所有 refresh 都通过同一个 loaderSnapshotStore 不直接更新页面。generation 的比较也不能简单写成“不相等就拒绝”。同一代配置可能因 CDN 重试重复送达这是幂等命中低于最近好代次才是回退响应高于它才有资格进入校验和持久化。若服务端发生正式回滚应发布更高 generation、内容回到旧参数而不是把 generation 数字倒退。四、最近好快照必须经过同一扇门很多“回退”代码只是把上一份 JSON 原样落盘再用类型断言读回来。应用升级后 Schema 已经从home-feed-v3变成home-feed-v4旧缓存可能不再满足当前页面要求。FlagHarbor 的 SnapshotStore 保存config、etag和savedAt读取时仍运行HomeFeedSchema.safeParse()无效缓存会被清除并返回内置安全默认值而不是继续传播。这一段解决持久化边界和并发覆盖。只有已经验证、且代次不小于当前快照的对象能写入。写入后flush()完成Store 才能向 UI 发出REMOTE_APPLIED。如果进程在 flush 前终止下一次启动最多回到第 72 代不会出现 UI 显示第 73 代而磁盘仍是第 71 代的伪成功。import{preferences}fromkit.ArkData;import{common}fromkit.AbilityKit;exportclassSnapshotStore{privatedb?:preferences.Preferences;constructor(privatecontext:common.UIAbilityContext){}privateasyncopen():Promisepreferences.Preferences{if(!this.db){this.dbawaitpreferences.getPreferences(this.context,{name:flag_harbor_snapshot});}returnthis.db;}asyncreadValidated():PromiseHomeFeedConfig{constdbawaitthis.open();consttextawaitdb.get(config,)asstring;if(!text)returnSAFE_HOME_FEED;try{constresultHomeFeedSchema.safeParse(JSON.parse(text));if(result.success)returnresult.data;}catch(_){}awaitdb.delete(config);awaitdb.flush();returnSAFE_HOME_FEED;}asyncread():PromiseHomeFeedConfig|undefined{constcfgawaitthis.readValidated();returncfg.configIdbuiltin-safe?undefined:cfg;}asyncwrite(config:HomeFeedConfig,etag:string):Promisevoid{constdbawaitthis.open();constcurrentawaitthis.read();if(currentconfig.generationcurrent.generation)return;awaitdb.put(config,JSON.stringify(config));awaitdb.put(etag,etag);awaitdb.put(savedAt,Date.now());awaitdb.flush();}}内置SAFE_HOME_FEED同样在单元测试里通过 Schema而不是靠开发者目测。Preferences 适合这份十几 KB 的轻量快照若配置增长到多份历史、图片二进制或频繁写入应改用文件或关系型存储。另一个生命周期要求是不能在每次组件重建时创建 StoreExperimentGuardPage 只持有观察状态loader 与 store 由页面级 ViewModel 或 Ability 容器提供页面退出时取消订阅网络请求仍可完成但不会再投递到已销毁视图。五、ArkUI 只消费验证后的不可变快照ExperimentGuardPage 的 Grid 不再直接绑定原始 JSON而是绑定ExperimentSnapshotstate、config、issues、staleDropped和请求指标一次性提交。这样columns与prefetch不会分两次更新避免一帧里出现新列数配旧预取值。真正影响布局的值在提交时复制成新对象旧快照仍可供日志和回退比较页面不在原对象上就地修改。工程目录也按边界拆开schema/HomeFeedSchema.ets负责运行时收窄network/RemoteConfigLoader.ets管理请求代次data/SnapshotStore.ets持久化最近好配置pages/ExperimentGuardPage.ets渲染诊断页。HiLog 的关键行是FLAG-1534 recv gen73 bytes12864 latency184ms etagW/9f2c-73随后是validate failed issues2 columns0 prefetch-3再到fallback gen72 rollout25 stateFALLBACK_ACTIVE和staleDropped1。我把调试按钮设计成“模拟坏配置”和“重新拉取”而不是只放一个成功按钮。连续点三次重新拉取前两条慢请求必须被 epoch 拦下把快照中的 schema 手工改成 v3启动时必须清除缓存并使用内置安全值把第 73 代修正为 columns2、prefetch6 后状态才允许从FALLBACK_ACTIVE进入REMOTE_APPLIED。这些用例覆盖的是边界顺序不只是 Schema 的字段规则。六、故障页面比 Toast 更有用本次运行最终保留故障而不自动伪造成功。手机页面显示FALLBACK_ACTIVE当前应用 generation 72、rollout 25%、schemahome-feed-v4被拒绝的是 generation 73错误数量 2字段值明确为columns0和prefetch-3。请求数据保持 184 ms、12,864 B、ETagW/9f2c-73staleDropped 为 1。这种诊断页不应在正式用户界面泄露全部配置但开发构建、灰度内测和远程日志需要保留同一组结构化字段。普通用户只看到“已使用稳定配置”开发人员则能用 configId、generation 和 ETag 定位服务端版本。两套文案共享同一个状态对象避免用户页面说已恢复日志却仍显示坏配置已生效。还有几个边界值得写在交付单上。Zod 校验运行在主线程时超大对象仍可能造成卡顿当前 12,864 字节可接受超过约定阈值应前移到任务池或减少载荷。safeParse的成功也不代表资源 URL 可访问、实验桶稳定或业务组合合理这些要进入后续阶段。最后ArkTS 工程接入三方 npm 包时应锁定兼容版本并验证构建产物不要因文章写了 Zod 4 就无条件漂移到未来大版本。FlagHarbor 的最终收益不是少了一次崩溃而是把远程配置从“服务端说什么就渲染什么”改成四个明确关口字节能否解码、对象能否收窄、响应是否仍是当前代次、失败时是否有可验证快照。只要这四个问题有一个答案是否定的ArkUI 就不会看到那份对象。七、参考资料Zod 官方Basic usage 与 safeParseZod 官方Defining schemasZod 4 官方发布说明HarmonyOS 用户首选项持久化指南
一、JSON 能解析页面照样能被它拖垮FlagHarbor 的首页灰度配置已经跑了几个月事故却来自一次“合法 JSON”。任务FLAG-1534在 15:34 收到cfg_home_v12的第 73 代配置网络请求 184 ms正文 12,864 字节ETag 是W/9f2c-73。JSON.parse没报错ArkUI 的 Grid 随后拿到columns0预取调度又拿到prefetch-3。前者让布局计算失去意义后者把一段保护不足的循环推向异常。更麻烦的是用户快速切换网络后还有两条请求并行较新的第 73 代先返回并失败稍旧的请求随后抵达旧代码却把它当成最新结果提交。于是我们看到的不是稳定回退而是页面在默认值、旧值和坏值之间闪烁。最后我没有继续给每个 ArkUI 属性补Math.max而是把远程配置当成不可信输入先用 Zod 4 做运行时收窄再用请求代次阻止过期结果提交最后只从“已验证的最近好快照”回滚。Demo 的最终状态刻意保留为FALLBACK_ACTIVE。第 73 代发现 2 个问题columns0、prefetch-3最近好快照仍是第 72 代灰度比例 25%过期响应丢弃 1 次。页面稳定使用home-feed-v4的第 72 代参数不把解析成功误写成业务有效。二、Schema 是 UI 边界不是接口注释服务端 TypeScript 类型不会穿过网络。即使客户端和服务端共用接口声明线上响应也只是字节串as HomeFeedConfig只会让编译器闭嘴不会让columns0自动变成 2。FlagHarbor 用 Zod 4 定义唯一运行时入口并把类型从 Schema 推导出来避免一份接口类型和一份校验规则渐渐分叉。这一段解决的是字段存在但取值越界的问题。columns只能为 1 到 4 的整数prefetch只能为 0 到 12rollout是 0 到 100 的整数版本标识必须是字面量home-feed-v4。.strict()让未知字段显式失败避免服务端拼错字段名时客户端默默使用默认值掩盖发布错误。import{z}fromzod;exportconstHomeFeedSchemaz.object({schema:z.literal(home-feed-v4),configId:z.string().min(1),generation:z.number().int().nonnegative(),rollout:z.number().int().min(0).max(100),layout:z.object({columns:z.number().int().min(1).max(4),cardGapVp:z.number().min(4).max(32)}).strict(),loading:z.object({prefetch:z.number().int().min(0).max(12),timeoutMs:z.number().int().min(300).max(5000)}).strict()}).strict();exporttypeHomeFeedConfigz.infertypeofHomeFeedSchema;exportfunctionvalidateConfig(raw:unknown):HomeFeedConfig{constparsedHomeFeedSchema.safeParse(raw);if(!parsed.success){constcompactparsed.error.issues.map(issue${issue.path.join(.)}${issue.message});thrownewError(CONFIG_INVALID:${compact.join(|)});}returnparsed.data;}选择safeParse()而不是直接parse()是因为调用方需要把问题转成可展示、可统计的结构而不是只接一个异常。Demo 的诊断层进一步把两个 issue 映射为layout.columns0和loading.prefetch-3但不会把整份远程 JSON 写进日志以免配置中未来加入敏感或高体量字段。Schema 也不负责一切。业务上的“第 73 代必须大于第 72 代”属于提交规则不该塞进字段校验灰度命中依赖稳定设备桶也不等于单字段范围。把所有约束都写进一个巨大 refine会让错误路径难以测试也让缓存恢复依赖网络上下文。我的边界是Schema 只回答“这份对象能否安全进入应用层”Store 再回答“它此刻是否应该生效”。三、异步请求靠代次提交不靠返回顺序原实现用一个loading布尔值阻止重复请求但网络切换、手动刷新和前台恢复仍可能同时发起。取消请求不是完整答案底层回调可能已经排队或者取消失败。FlagHarbor 每次刷新递增requestEpoch提交前同时检查 epoch 和配置 generation。旧请求即使成功也只能被计入staleDropped不能修改 UI。下面的RemoteConfigLoader串起下载、解析、校验和回退。fetchJson返回的元数据固定包括耗时、字节数和 ETag便于把第 73 代问题与实际请求对应。失败时先从SnapshotStore读取最近好快照再次通过同一 Schema 校验避免“缓存天然可信”的错觉。interfaceFetchResult{raw:unknown;latencyMs:number;bytes:number;etag:string;}exportclassRemoteConfigLoader{privaterequestEpoch:number0;staleDropped:number0;constructor(privatesnapshots:SnapshotStore){}asyncrefresh(fetchJson:()PromiseFetchResult):PromiseLoadResult{constepochthis.requestEpoch;constresponseawaitfetchJson();if(epoch!this.requestEpoch){this.staleDropped;return{state:STALE_DROPPED};}constparsedHomeFeedSchema.safeParse(response.raw);if(parsed.success){constlastawaitthis.snapshots.read();if(lastparsed.data.generationlast.generation){this.staleDropped;return{state:STALE_DROPPED};}awaitthis.snapshots.write(parsed.data,response.etag);return{state:REMOTE_APPLIED,config:parsed.data};}constfallbackawaitthis.snapshots.readValidated();return{state:FALLBACK_ACTIVE,config:fallback,issues:parsed.error.issues,metrics:response};}}提交检查必须位于所有异步步骤之后。如果只在请求返回时检查 epoch随后读取缓存或写盘期间又发起了新请求旧链仍可能在末尾覆盖状态。生产版本在 Store 的commit()前再做一次令牌校验本文为了让核心路径可读保留了单写者约束所有 refresh 都通过同一个 loaderSnapshotStore 不直接更新页面。generation 的比较也不能简单写成“不相等就拒绝”。同一代配置可能因 CDN 重试重复送达这是幂等命中低于最近好代次才是回退响应高于它才有资格进入校验和持久化。若服务端发生正式回滚应发布更高 generation、内容回到旧参数而不是把 generation 数字倒退。四、最近好快照必须经过同一扇门很多“回退”代码只是把上一份 JSON 原样落盘再用类型断言读回来。应用升级后 Schema 已经从home-feed-v3变成home-feed-v4旧缓存可能不再满足当前页面要求。FlagHarbor 的 SnapshotStore 保存config、etag和savedAt读取时仍运行HomeFeedSchema.safeParse()无效缓存会被清除并返回内置安全默认值而不是继续传播。这一段解决持久化边界和并发覆盖。只有已经验证、且代次不小于当前快照的对象能写入。写入后flush()完成Store 才能向 UI 发出REMOTE_APPLIED。如果进程在 flush 前终止下一次启动最多回到第 72 代不会出现 UI 显示第 73 代而磁盘仍是第 71 代的伪成功。import{preferences}fromkit.ArkData;import{common}fromkit.AbilityKit;exportclassSnapshotStore{privatedb?:preferences.Preferences;constructor(privatecontext:common.UIAbilityContext){}privateasyncopen():Promisepreferences.Preferences{if(!this.db){this.dbawaitpreferences.getPreferences(this.context,{name:flag_harbor_snapshot});}returnthis.db;}asyncreadValidated():PromiseHomeFeedConfig{constdbawaitthis.open();consttextawaitdb.get(config,)asstring;if(!text)returnSAFE_HOME_FEED;try{constresultHomeFeedSchema.safeParse(JSON.parse(text));if(result.success)returnresult.data;}catch(_){}awaitdb.delete(config);awaitdb.flush();returnSAFE_HOME_FEED;}asyncread():PromiseHomeFeedConfig|undefined{constcfgawaitthis.readValidated();returncfg.configIdbuiltin-safe?undefined:cfg;}asyncwrite(config:HomeFeedConfig,etag:string):Promisevoid{constdbawaitthis.open();constcurrentawaitthis.read();if(currentconfig.generationcurrent.generation)return;awaitdb.put(config,JSON.stringify(config));awaitdb.put(etag,etag);awaitdb.put(savedAt,Date.now());awaitdb.flush();}}内置SAFE_HOME_FEED同样在单元测试里通过 Schema而不是靠开发者目测。Preferences 适合这份十几 KB 的轻量快照若配置增长到多份历史、图片二进制或频繁写入应改用文件或关系型存储。另一个生命周期要求是不能在每次组件重建时创建 StoreExperimentGuardPage 只持有观察状态loader 与 store 由页面级 ViewModel 或 Ability 容器提供页面退出时取消订阅网络请求仍可完成但不会再投递到已销毁视图。五、ArkUI 只消费验证后的不可变快照ExperimentGuardPage 的 Grid 不再直接绑定原始 JSON而是绑定ExperimentSnapshotstate、config、issues、staleDropped和请求指标一次性提交。这样columns与prefetch不会分两次更新避免一帧里出现新列数配旧预取值。真正影响布局的值在提交时复制成新对象旧快照仍可供日志和回退比较页面不在原对象上就地修改。工程目录也按边界拆开schema/HomeFeedSchema.ets负责运行时收窄network/RemoteConfigLoader.ets管理请求代次data/SnapshotStore.ets持久化最近好配置pages/ExperimentGuardPage.ets渲染诊断页。HiLog 的关键行是FLAG-1534 recv gen73 bytes12864 latency184ms etagW/9f2c-73随后是validate failed issues2 columns0 prefetch-3再到fallback gen72 rollout25 stateFALLBACK_ACTIVE和staleDropped1。我把调试按钮设计成“模拟坏配置”和“重新拉取”而不是只放一个成功按钮。连续点三次重新拉取前两条慢请求必须被 epoch 拦下把快照中的 schema 手工改成 v3启动时必须清除缓存并使用内置安全值把第 73 代修正为 columns2、prefetch6 后状态才允许从FALLBACK_ACTIVE进入REMOTE_APPLIED。这些用例覆盖的是边界顺序不只是 Schema 的字段规则。六、故障页面比 Toast 更有用本次运行最终保留故障而不自动伪造成功。手机页面显示FALLBACK_ACTIVE当前应用 generation 72、rollout 25%、schemahome-feed-v4被拒绝的是 generation 73错误数量 2字段值明确为columns0和prefetch-3。请求数据保持 184 ms、12,864 B、ETagW/9f2c-73staleDropped 为 1。这种诊断页不应在正式用户界面泄露全部配置但开发构建、灰度内测和远程日志需要保留同一组结构化字段。普通用户只看到“已使用稳定配置”开发人员则能用 configId、generation 和 ETag 定位服务端版本。两套文案共享同一个状态对象避免用户页面说已恢复日志却仍显示坏配置已生效。还有几个边界值得写在交付单上。Zod 校验运行在主线程时超大对象仍可能造成卡顿当前 12,864 字节可接受超过约定阈值应前移到任务池或减少载荷。safeParse的成功也不代表资源 URL 可访问、实验桶稳定或业务组合合理这些要进入后续阶段。最后ArkTS 工程接入三方 npm 包时应锁定兼容版本并验证构建产物不要因文章写了 Zod 4 就无条件漂移到未来大版本。FlagHarbor 的最终收益不是少了一次崩溃而是把远程配置从“服务端说什么就渲染什么”改成四个明确关口字节能否解码、对象能否收窄、响应是否仍是当前代次、失败时是否有可验证快照。只要这四个问题有一个答案是否定的ArkUI 就不会看到那份对象。七、参考资料Zod 官方Basic usage 与 safeParseZod 官方Defining schemasZod 4 官方发布说明HarmonyOS 用户首选项持久化指南
