工程正确性 - category - 沐木

工程正确性（二）：Java、TypeScript 与 Native 的密码互操作

mumu — Sat, 11 Jul 2026 00:00:00 +0000

系列导航：11 | 12 | 13 | 14

Java、TypeScript 和 Native 各自完成“加密后能解密”，不能证明它们能互相解密。真正的差异经常出现在模式、填充、IV、Tag、Base64、ASN.1、签名输入和错误处理。GMKit 的跨语言验证把 vectors/interop.json 作为共享输入，再用双向矩阵检查每个实现的字节结果。

向量文件是协议边界

每条向量至少写明算法套件、密钥字节、明文字节、AAD、IV 或 nonce、密文、Tag、签名和编码方式。算法名不能只写 AES，要写模式和参数，例如 GCM 的 Tag 长度、CBC 的填充规则或椭圆曲线名称。JSON 的 UTF-8、字段顺序和 Base64 变体也属于协议。

flowchart TD V[vectors/interop.json] --> Java[Java 实现] V --> TS[TypeScript 实现] V --> Native[Native 实现] Java --> Matrix[跨端矩阵] TS --> Matrix Native --> Matrix Matrix --> Negative[篡改与格式负例] Negative --> Gate[Parity 与发布门禁]

项目生成的向量只能证明实现之间采用了同一套错误或正确的规则，不能自动证明符合外部标准。标准向量、独立库结果和固定边界样本要在来源字段中区分。

双向矩阵怎么列

以信封加密为例，至少覆盖：Java 生成，TypeScript 解封；TypeScript 生成，Java 解封；Native 生成，Java 解封；Java 生成，Native 解封。签名也做同样的方向矩阵。固定向量使用固定 nonce 便于复现，生产接口通过安全随机数生成器提供 nonce，测试入口和生产入口分离。

矩阵中记录运行时、密码库版本和提供者。依赖升级、Native 编译选项变化或浏览器基线变化都会触发完整矩阵。失败报告保存向量 ID、字段摘要和错误枚举，不保存生产密钥、完整明文或私密内容。

工程正确性（三）：迁移登记、Checksum 与回滚边界

mumu — Sat, 11 Jul 2026 00:00:00 +0000

系列导航：11 | 12 | 13 | 14

迁移成功不等于数据库已经可用。空库安装验证的是完整历史，线上升级还要考虑旧应用并存、DDL 锁、回填速度和权限。一次服务发布曾在代码和容器准备完成后，生产账号执行迁移却因缺少 ALTER 和 INDEX 权限失败。这个问题不在 SQL 内容，属于迁移前置条件没有进入发布检查。

登记表是事实来源

迁移记录至少包含版本、文件名、checksum、执行序号、状态、执行人、耗时和错误摘要。已执行文件禁止原地修改，修正使用新版本。启动时发现文件 checksum 与登记值不一致，应停止自动迁移并报警，不能为了让部署继续而覆盖登记表。

flowchart TD subgraph Register[登记] direction LR M[迁移文件] --> Hash[计算 checksum] --> Registry[迁移登记表] end subgraph Migrate[兼容迁移] direction LR Expand[Expand 兼容结构] --> Backfill[游标回填] --> Reconcile[全量对账] end subgraph Shrink[切换与收缩] direction LR Switch[读写切换] --> Contract[Contract 删除旧结构] end Registry --> Expand Reconcile --> Switch Reconcile -->|超限| Pause[暂停与补偿]

登记表自身也要受保护。应用账号只读，迁移执行器拥有写入权限。手工 SQL 如果改变了生产结构，要补成正式迁移或登记为已应用版本，不能让测试环境和线上环境依靠“历史操作”维持一致。

Expand、Backfill、Contract

Expand 先添加可空字段、兼容索引或快照表，旧应用继续可用。应用升级后双写旧字段和新字段，后台使用稳定主键游标分批回填历史数据。对账完成后切换读路径，观察窗口结束，所有旧实例和离线任务退出，才进入 Contract。

回填条件带上新字段为空、源版本未变化等保护，防止覆盖在线写入。每批记录起止主键、扫描数、更新数、跳过数、失败数和校验摘要。暂停后从已提交游标继续，批次重试具备幂等条件，不能依赖 offset 扫描变化中的数据。

对账不只比较行数。字段拆分检查空值、范围、唯一性和重组结果，表迁移检查关联完整性，编码转换检查不可映射值。允许差异和处理结果写进发布记录，抽样人工核对只作为补充。

回滚按阶段定义

增加字段通常可以通过应用开关回退，读切换也可以切回旧路径。已经删除列或完成不可逆数据修正时，回滚依赖备份、归档表或补偿迁移，不能承诺“一键恢复”。发布单在执行前写清每个阶段的恢复动作、数据保留时间和负责人。

工程正确性（四）：构建成功不等于交付物可用

mumu — Sat, 11 Jul 2026 00:00:00 +0000

系列导航：11 | 12 | 13 | 14

编译器显示成功，只能证明源码在当前环境生成了产物。用户安装的是 JAR、npm 包或容器，真正的验收对象是这些文件能否被目标运行时加载，Native 资源是否随包分发，文档示例是否使用了正确入口。发布链路如果只跑单元测试，问题会在上传后才出现。

GMKit 的发布整理说明了这条边界：Java 的 gmkit-sm9 需要把多平台 Native 运行时装入同一个 JAR，TypeScript 包还要检查 tarball 内容和生产依赖。源码测试通过并不能证明打出来的包包含这些资源。

flowchart TD subgraph Build[源码验证与构建] direction LR Source[源码与向量] --> Verify[测试与 parity] --> Package[构建制品] end subgraph Audit[制品审计] direction LR Inspect[包内容与 checksum] --> Install[干净环境安装] --> Smoke[运行时 smoke] end subgraph Release[发布] direction LR Publish[发布仓库] end Package --> Inspect Smoke --> Publish Inspect -->|缺资源或多余文件| Reject[阻断发布]

先确定交付清单

Java 发布清单写明 group、artifact、版本、依赖、服务文件和 Native 路径。gmkit-sm9 的 JAR 中应有 META-INF/gmkit/sm9-native.properties、各平台运行时和摘要文件，加载逻辑按当前平台选择资源并校验 checksum。Native 库缺失时启动要给出明确错误，不能回退到一个“未实现但返回成功”的空实现。

工程正确性（一）：测试全绿仍可能违反规格

mumu — Sat, 11 Jul 2026 00:00:00 +0000

系列导航：11 | 12 | 13 | 14

有一次工具链模块的 Maven 测试达到 110 个通过，构建也显示成功。随后按规格逐项检查，仍发现三个问题：启动 Java 进程时参数被拼成一个字符串，删除镜像请求带了过大的 bearer scope，注册表探测把 401 当成服务可用。测试覆盖了代码路径，却没有覆盖协议的精确定义。

这类问题很难靠继续堆单元测试解决。测试断言、实现和假服务都来自同一份理解时，三者会稳定地一起通过。正确性需要把规格、实现、独立参考和运行行为放在同一张检查表中。

flowchart TD Spec[规格与协议] --> Contract[契约清单] Contract --> Unit[单元测试] Contract --> Integration[真实服务契约测试] Contract --> Review[人工边界审查] Unit --> Evidence[差异与证据包] Integration --> Evidence Review --> Evidence Evidence --> Gate[发布门禁]

绿灯的含义要写清

单元测试通过表示输入和断言范围内的函数行为符合预期。它不自动证明参数序列化符合命令行语义，不证明权限范围足够窄，也不证明第三方服务对状态码的解释正确。构建成功只说明编译、打包和被启用的测试任务完成，项目默认跳过测试时尤其要显式检查 -DskipTests=false。

每个关键规则写成可观察的证据：命令行参数保存为参数数组，删除操作的 scope 断言为 pull,push 以外的权限被拒绝，注册表探测把 401 分类为“服务响应但需要认证”，而非健康。断言越接近协议字段，错误越容易被定位。

从规格拆检查项

先把规格拆成输入、输出、状态码、权限、超时和副作用。实现审查逐项标记证据来源：标准测试向量、第三方服务响应、独立实现、日志或运行截图。没有证据的项保持未验证，不用“已有测试”代替。

接口测试使用真实 HTTP 或接近真实的契约服务器，fake 只模拟网络异常和固定响应。fake 必须拒绝真实服务会拒绝的输入，接受范围过宽会掩盖参数错误。对 CLI、JNI、浏览器和数据库边界，至少准备一组字节或命令行级别的断言，不能只测高层对象。

性质和变形测试

算法或数据处理难以枚举期望值时，加入性质测试：排序保留元素多重集合，金额拆分总和守恒，状态转换不跳过必需阶段，签名篡改后验签失败。变形测试对输入做允许的变换，再检查输出关系，能覆盖示例测试没有触及的组合。

随机测试保存固定反例和生成器版本。只保存随机种子会因生成器改变而无法重现。失败样本缩减后进入回归集，回归集再由人工确认业务含义。

代码通过后的协议复核

复核要跳出实现本身，逐项对照规格检查四个问题：

参数是否按对方解析方式传递，尤其是字符串、数组和空值。
权限是否只申请当前操作必需的范围，错误码是否被正确分类。
成功响应是否真的产生了预期副作用，失败是否留下部分状态。
文档、测试、运行配置和打包产物是否描述同一行为。

这一步发现的差异不应直接归类为“测试不稳定”。如果规格修正了预期，保留差异报告、旧行为、变更原因和迁移影响。零差异不是目标，未解释的差异才是发布阻断项。