bridge-boundary-error-protocol-simulation

1. 实验目标

用纯 Java CLI 仿真「桥接边界与错误协议」（对应 docs/05-bridge-hybrid/12）：

• 大整数精度：snowflake id（> 2⁵³）必须用字符串传，避免 JS number 丢精度
• 返回栈协商：goBack 先问 H5，H5 有历史就消费一条、无历史/超时才交还原生关页
• 错误信封：桥错误用 {__isBridgeError:true} 包裹，让 H5 区分「原生报错」与「正常返回」

2. 工程要点

• 跨 JS 边界的数字默认走 number（双精度，仅 53 位尾数），大整数必须字符串化
• 返回栈属于「UI 语义」，不能原生一句话关页，要先让 H5 协商
• 错误信封让 H5 渲染层不会把异常当业务数据

3. 关键实现速览

// 大整数双重 encode：让 JS 当 string 解析，不当 number 丢精度
long snowflakeId = 1872039485720394857L; // > 2^53
String safe = "\"" + snowflakeId + "\"";  // 等价于 JSON.encode(JSON.encode(id))

// 错误信封：区分原生异常与正常返回
static String errorReturn(String code) {
    return "{__isBridgeError:true, code:\"" + code + "\"}";
}

为什么看这段：三个坑都不在「能不能通」，而在「边界数据怎么不丢、UI 语义怎么协商、异常怎么不被误当数据」。这正是桥接工程化最容易翻车的地方。

4. 运行方式

cd labs/java/bridge-hybrid/bridge-boundary-error-protocol-simulation
javac -d out src/BridgeBoundaryErrorProtocolSimulation.java
java -cp out BridgeBoundaryErrorProtocolSimulation

5. 预期控制台输出

=== 1. 大整数精度：snowflake id > 2^53 ===
  原始 long      = 1872039485720394857
  直接当 number  = 丢失精度（Double 只有 53 位尾数）
  双重 encode     = "1872039485720394857" → JS 当 string 解析，精度保全 ✅
=== 2. 返回栈协商：goBack 先问 H5 ===
  H5 消费一条历史（Vue Router back），页面不关 ✅
=== 3. 错误信封：区分『原生报错』与『正常返回』===
  正常返回: {data:{success:true}}
  原生报错: {__isBridgeError:true, code:"PERMISSION_DENIED"}
  H5 靠 __isBridgeError 区分，不会把异常当业务数据渲染 ✅
=== 结论 ===
  · 大 ID 用字符串传，避免 JS number 精度丢失
  · goBack 协商 + 超时兜底，避免误关页或卡在死栈
  · 错误信封让 H5 分清『原生异常』与『正常数据』

6. 常见误区

误区	实际情况
ID 直接 JSON 传就行	snowflake/雪花 id 超过 2⁵³，JS number 解析即丢精度，必须用字符串
原生 goBack 直接关页	H5 内部还有路由栈时会误关 App；应先让 H5 协商
桥返回里塞个 error 字段区分	不够彻底；用独立错误信封，渲染层一眼识别，不会误渲染

7. 对应知识库文档

• 理论主文档：桥接边界与错误协议

8. 完整源码

• BridgeBoundaryErrorProtocolSimulation.java