Bug 藏在接缝处：从 HivePlane 实战看持久化边界的六类缺陷

单元测试全绿，内存存储完美往返，逻辑本身毫无问题——但换成真实 PostgreSQL 后，系统在一个又一个边界上崩溃。这是 HivePlane v0.2.0 现场测试的核心发现：Bug 不在逻辑里，而在数据穿越持久化边界的接缝处。

六类接缝缺陷：一张分类表

HivePlane 团队在实战中记录了一份缺陷台账（D-1 至 D-11），其中五个典型缺陷恰好覆盖了六种接缝类型：

缺陷	穿越接缝的值	断裂位置
D-5	密文以 bytes 存储	Postgres JSON 列拒绝二进制
D-7	以 id 为主键的 desired_specs 行	第二数据源触发主键冲突
D-8	kill-switch 记录存在	GET /tools/disabled 返回了已启用工具
D-9	含运行记录的工作负载被删除	原始外键违规返回 500 而非 409
#573	备份清单锁定 alembic_head=0034	实际 schema head 为 0035，恢复错版本

这张表本身就是分类法：每一个缺陷的根因都不是算法或业务逻辑，而是值在边界处形态发生了变化。

当 bytes 撞上 JSON 列

D-5 是最干净的案例。加密密钥保管库将密文以 bytes 类型存储。在内存存储中，它完美往返；单元测试全数通过。但 Postgres 的对应列是 JSON 类型，而 bytes 无法被 JSON 序列化。密钥保管库在持久化边界——内存测试从未触及的那个位置——直接崩溃。

修复方案不在模型层，而在边界处：写入 Postgres 时对密文做 base64 编码，读回时解码。模型保持 bytes 不变，由接缝学会翻译。那个使用内存存储的单元测试依然通过——也依然无法证明接缝处的任何事。

实践提示： 内存存储与 Postgres 共享的是接口，不是序列化协议。一个能在内存中往返的值，完全可能死在 JSON 列上。追踪值穿越边界的过程，而那个边界恰恰是内存测试不会跨越的。

背景补充：为什么 JSON 列容不下 bytes？

JSON 是一种文本格式，其规范（RFC 8259）只定义了六种数据类型：字符串、数字、布尔、null、数组和对象。二进制数据不在其中，因此 bytes 无法直接序列化为 JSON。PostgreSQL 的 json 和 jsonb 列同样遵循这一约束——它们接收的是合法的 JSON 文本，插入 bytes 会直接触发类型错误。要在 JSON 列中存放二进制数据，通用做法是先用 base64 把字节编码成 ASCII 字符串，读回时再解码。这就是 D-5 的修复逻辑：bytes 本身没问题，问题在于它必须穿过一个只接受文本契约的边界。

值得一提的替代方案是 PostgreSQL 的 bytea 类型，它专为二进制设计，可以原样存放 bytes。但文章场景选择保留 JSON 列而对密文做 base64，说明 schema 选型已定，改动列类型牵涉面更大——这也正是"接缝处翻译"比"改模型"更务实的原因。

第二数据源击穿第一数据源

D-7 是 id 与唯一性约束的混淆。reconcile 加载器以 id 为主键构建 desired_specs。单数据源场景一切正常；但当第二个数据源应用相同的期望状态时，主键冲突爆发——因为行已存在，而该主键假设了只有一个数据源。唯一性约束和主键是同一个字段，却承载着不同语义。

修复方式是复合键与幂等 upsert：(source_id, workload_id)。第二个数据源产生第二行，而非碰撞。这个 bug 只在双数据源场景下才出现，这也解释了为什么单源现场测试永远抓不到它。

背景补充：主键、唯一性约束与幂等 upsert

主键和唯一性约束在 SQL 中都能防止重复，但语义不同：主键唯一标识一行，唯一性约束约束的是某一组业务字段的组合。D-7 的症结在于 desired_specs 把 id 既当作行的标识、又当作"一个工作负载只应有一份期望状态"的业务保证，两种语义被压进同一个字段，于是第二个数据源带来的合法重复立刻变成主键冲突。

复合键 (source_id, workload_id) 把两个语义拆开：行的唯一性由两列共同保证，每个数据源各自持有自己的期望状态行。配合幂等 upsert（PostgreSQL 的 INSERT ... ON CONFLICT ... DO UPDATE），重复应用同一期望状态只会更新而非插入，从而同时满足正确性与可重放性。这一模式在事件驱动的 reconcile 循环里几乎是标配。

接口报告的是记录，不是状态

D-8 是一类至今回想起来仍觉荒谬的状态与记录混淆。GET /tools/disabled 返回的列表中竟包含已启用的工具。kill-switch 记录确实存在于表中，但工具实际上并未被禁用。端点报告的是记录本身，而非当前状态。一份包含已启用工具的"禁用列表"比没有列表更糟糕——它会训练运维人员直接忽略它。

修复方式：端点报告状态，由记录与工具当前状态共同推导，而非只读记录。一条后来被撤销的禁用记录属于历史，不是当前事实。

外键违规返回了 500

D-9 是数据库在给 API 设计上课。删除一个含有运行记录的工作负载时，接口返回了 500——一个原始外键违规被当作内部错误抛出。调用方收到服务器错误，运维人员拿不到任何原因。

修复方案是返回 409，附带"工作负载有 N 条运行记录；请先删除运行记录或级联删除"。约束违规是面向用户的条件，不是服务器故障。数据库与 API 之间的接缝，正是 500 变成 409 的地方。

背景补充：HTTP 状态码里的"谁的错"

HTTP 4xx 表示客户端的请求有问题，5xx 表示服务端出了故障。外键约束违规在数据库层是一个完整性错误，但从 API 视角看，它是"你试图删除一个仍被引用的实体"——这是调用方可理解、可纠正的条件，属于 4xx 范畴。具体到本场景，409 Conflict 表明请求与当前资源状态冲突，比 400 Bad Request 更贴切，因为它暗示的是资源之间存在依赖关系而非请求格式有误。

把原始数据库异常直接冒泡成 500 是常见的接缝事故：数据库说的"违规"和 API 说的"故障"是两套语汇，中间缺少一层翻译。成熟做法是在持久层捕获具体异常类型（如 psycopg 的 ForeignKeyViolation），映射为领域错误，再由 API 层渲染成合适的状态码与可读消息。

清单谎报 schema head

#573 是潜在的灾难性缺陷。一份备份清单将 alembic_head 锁定为 0034，而线上 schema head 已是 0035。恢复操作会成功——因为清单声称 schema 匹配——但恢复目标是一个领先了整整一个迁移版本的数据库。恢复过程验证的是清单的声明，而非世界的真相。

修复方式：恢复时校验实际 schema head 与清单是否一致，不匹配则拒绝执行。一份对自身 head 撒谎的清单，就是一份会把你恢复到系统错误版本的备份。

背景补充：Alembic 与 schema head

Alembic 是 SQLAlchemy 生态的数据库迁移工具，每份迁移脚本有独立的版本标识，形成一条有向的迁移链，链的末端称为 head。alembic_head 记录的就是"当前数据库已应用到的最后一份迁移"。恢复一份备份时，数据库的实际 head 与备份清单里写的 head 必须一致，否则数据与代码假设的 schema 可能对不上——例如某个后来加入的列在旧备份里根本不存在。

#573 的危险之处在于清单只验证了自己的声明，没有去读数据库里的 alembic_version 表。一旦声明与事实分离，恢复会"成功"地把系统带回错误的迁移版本，后续所有依赖新 schema 的代码路径都会在运行时以难以诊断的方式失败。正确做法是恢复前查询实际 head 并与清单比对，不一致就拒绝，让错误在最早、最可控的时点暴露。

从接缝处学到的工程经验

HivePlane 团队总结了六种需要逐一追踪的接缝类型：

• 二进制 vs JSON：bytes 能过内存，过不了 JSON 列
• 全局键 vs 租户作用域：单租户测试掩盖多租户冲突
• id vs 唯一性：同一个字段承载两种语义时，多数据源场景必然碰撞
• 状态 vs 记录：记录是历史，状态是当前事实
• 外键 vs 409：约束违规是用户条件，不是服务器故障
• 清单 head vs schema head：备份要验证实际状态，而非自身声明

核心结论：停在接缝之前的单元测试会通过，Bug 活在再往前一个边界。真正能抓住这些问题的是受 Postgres 门控的测试——CI 中真正连数据库跑的那些测试。v0.2.0 现场测试对真实技术栈（含真实 PostgreSQL）执行零跳过策略，取得 36/36 场景、67/67 容器测试的成绩，而缺陷台账 D-1 至 D-11 本身就是证据：接缝，而非逻辑，才是真正的工作量所在。

要验证这一点，方法很简单：在你的系统中挑一个值，从模型追踪到 Postgres 列再到 API 响应。它在哪里改变了形态？那里就是你下一个 Bug 的藏身处——也正是你单元测试停下脚步的地方。