contract-consistency-simulation

1. 实验目标

用纯 Java CLI 仿真多端契约一致性（对应 docs/05-bridge-hybrid/03 与 docs/05-bridge-hybrid/09）：

• 单一事实源：契约只在 Schema 定义一处，多端按契约解析
• 三个场景：加可选字段（向后兼容）/ 字段类型变更（破坏性）/ 缺必填字段（脏数据）
• 场景 6：契约漂移 CI 强校验——注册通道集合与契约表不一致、或同名通道版本不一致时阻断构建

2. 工程要点

• parseV1 模拟老客户端：只取已知字段，忽略未知字段（向后兼容的关键）
• 类型变更场景：(String) data.get("name") 对 String[] 强转 → ClassCastException
• 缺字段场景：服务端异常返回缺 userId 的 200 → 老端 null 后业务崩溃

3. 运行方式

cd labs/java/bridge-hybrid/contract-consistency-simulation
javac -d out src/ContractConsistencySimulation.java
java -cp out ContractConsistencySimulation

4. 预期现象

场景	输出
加可选字段	老端正常解析，未知字段被忽略 ✅
类型变更	ClassCastException ❌
缺必填字段	userId=null → 业务崩溃 ❌
契约漂移（注册≠契约表/版本不一致）	CI 失败，阻断构建 ❌

5. 常见误区

误区	实际情况
加字段就是向后兼容	只有"可选字段"才兼容；必填化 / 类型变更 / 删字段都是破坏性变更
契约一致 = 字段名一致	还包括类型、枚举值、语义（错误码）一致性
多端各自补字段就行	会双写漂移；必须走"Schema 变更 → 全端代码生成"的单一事实源流程

6. 对应知识库文档

• 理论主文档：跨端一致性设计：多端架构分层与设计系统（契约升级兼容/破坏）
• 理论主文档：桥接契约版本治理：把 JSBridge 当作版本化 API 表面（契约版本治理 + CI 强校验）

7. 完整源码

• ContractConsistencySimulation.java