AI 构建应用的契约迁移门槛

你让 AI 编码代理把 plan 重命名为 subscription_tier。它改好了数据库模型、API 返回值，也替换了代码库里能搜到的所有引用。测试通过，预览正常，创始人于是批准上线。

第二天早上，尚未升级的移动端仍在发送 plan；支付服务的 Webhook 继续写入旧字段；夜间导出任务还在查询旧列；一个延迟任务又重放了部署前产生的事件。生成的语法并没有错。真正的问题是：这个字段并非单个代码库里的名字，而是多个版本共同依赖的契约。

本文面向已经有真实用户、持久数据、外部集成、后台任务，或无法同步升级全部客户端的 AI 构建应用。核心判断只有一句：只有当新旧生产者、消费者和历史记录能够在一段经过测量的兼容窗口内共存，契约变更才算可上线。 代码差异、迁移文件、成功构建或成功部署都不能单独证明这一点。

你将得到一份消费者清单、一个“扩展—迁移—收缩”流程、一张跨版本测试矩阵、一份机器可读的迁移凭证，以及明确的放行与停止条件。这套方法适用于常见 SaaS 字段、REST/GraphQL 响应、Webhook、队列消息、分析事件、功能配置和文件导出。它不能替代受监管记录、资金账本、安全关键系统、超大数据库，或无法从旧含义可靠推导新含义时所需的专业审查。遇到这些场景，可以沿用本文的证据结构，但必须让有经验的数据库、安全、合规或领域负责人参与。

“扩展—收缩”本身是一种成熟的迁移模式。本文的新贡献，是在它外围加上一道可验收门槛：任何破坏性清理得到授权之前，团队必须把具名消费者清单、由真实滞后推导的兼容窗口、跨版本结果测试、生产不变量和分阶段凭证连成一条证据链。

把字段当成契约，而不是一个词

成熟平台早已在处理同一类问题。GitHub 在官方破坏性变更政策中，把删除或重命名响应字段、增加必填参数、改变类型、删除枚举值都列为破坏性 API 变更；新 REST API 版本发布后，旧版本至少继续支持 24 个月。早期应用未必需要承诺 24 个月，但应采用同一种纪律：给契约命名、给变更分版本，并明确旧消费者可以继续工作的期限。

先回答代码无法替你决定的授权问题

代理可以搜索调用点，却无法仅凭源码推断所有运营和商业承诺。让它动手前，先写一句授权声明：

我们要把账户分类字段 plan 替换为 subscription_tier；字段含义不变；旧读写方必须在经过测量的兼容窗口内继续工作；定价、权益、历史报表和合作伙伴载荷均不得改变。

这句话把一个含糊提示词可能混在一起的四种变更拆开：

如果含义或执行方式也要改变，即使同一个提交实现了它，也应作为独立产品决策来审批。否则，一个看似无害的改名可能顺带改变哪些用户能使用付费功能。

不要在这句话里拍脑袋填写窗口长度。先通过消费者清单找出最长真实滞后，再把时长及推导依据一起写进迁移凭证。

还要写出非目标：“本次发布不删除旧字段；不增加新的必填输入；不改变用户权益；不重写历史账单。” 非目标能让 AI 产出更容易审查，也让测试知道什么情况必须判失败。

最后，指定哪份文件才是权威契约。它可能是 OpenAPI 文档、Prisma 模式、SQL 迁移文件、Protobuf 文件、事件模式或类型接口。OpenAPI 规范没有让团队用代码注释暗示“以后会删”，而是为操作、参数和模式提供明确的 deprecated 标记；其规范文本说明，被标记为弃用的参数应逐步停止使用。但只有运行中的产品与迁移计划真的遵守，标记才有意义。

动生产前，先做消费者清单

代码搜索找到的是显式引用；消费者清单找到的是产品义务。沿着所有可能写入、存储、复制、排队、缓存、导出或解释这份数据的路径排查。

“代码里没搜到引用”不等于“没有消费者”。仪表盘里保存的 SQL、Zapier 步骤、无代码自动化、表格导入规则、旧应用二进制包以及客户自己的 Webhook 解析器，都可能在代码库外。应询问计费、客服、市场运营、数据和合作伙伴负责人；如果隐私政策与留存规则允许，也可以从日志验证字段是否仍被使用。

清单也能避免无限保守。如果某条路径确实没有活跃消费者，就记录证据并把它移出迁移范围。目标是得到一个有边界的兼容判断，而不是把所有想象中的系统都列成仪式。

把每个消费者标记为：已确认兼容、必须升级、未知或有证据表明已退役。高后果路径上的“未知”必须阻断收缩；只要扩展阶段完全保留旧行为，它未必需要阻断第一步的加法变更。

分清四种不同的兼容

团队若不说明“谁读取什么”，“向后兼容”四个字几乎没有操作价值。

消息系统很好地展示了读写方向的差异。Confluent 在官方模式演进文档中，把向后兼容定义为“新模式可以读取旧数据”，向前兼容定义为“旧模式可以读取新数据”，完全兼容则同时满足两者；传递性模式还会与不止最近一个版本比较。即使你的应用只是用 JSON 加一条简单队列，也应回答：

• 新代码能否读取仍可能出现的每一种旧事件？
• 旧代码能否忽略或安全处理新字段？
• 字段缺失时，默认行为是否明确？
• 新旧字段冲突时，以谁为准？
• 重新序列化后，未知数据会不会丢失？

把“扩展—迁移—收缩”拆成三次发布

字段改名最常见的安全做法不是原地重命名，而是分成三个可观察阶段。

扩展：只加，不删

新增可选字段 subscription_tier，同时保留 plan。让新读方同时接受两者，并写清冲突规则：新字段存在时是否优先；只有旧字段时如何转换；两个字段不一致时，是报警、隔离，还是阻断，而不是静默猜测。

新写方可以同时写两个字段，也可以只写新字段，再由兼容适配层维护旧字段。但双写并不天然安全：其中一次写入失败，就可能产生分歧。能放进同一数据库事务时就放进去；不能时，适配器必须可幂等重试，并持续对账。

Prisma 的官方扩展—收缩迁移指南演示了先引入新结构、迁移数据与应用代码，最后才删除旧结构。值得借鉴的不是某条命令，而是时间上的拆分：兼容性引入、数据转换、读方切换和破坏性清理，不应塞进一个黑盒部署。

迁移：回填数据，逐个移动消费者

用有边界、可重启的小批次回填历史记录。记录游标、速率、错误数和对账结果。不要因为“任务退出码为 0”就宣布完成。应比较：符合条件的记录数、成功转换数、无需改动数、冲突数、失败数，以及回填期间新产生的记录数。

把读方切到新字段，同时在兼容窗口内保留读取旧字段的降级路径。随后逐一迁移清单上的写方。给弃用字段的读取行为加上可观察性，才能知道旧消费者是否真的消失。没有使用证据的弃用警告，只会让收缩日期变成猜测。

收缩：证据齐了才删除

先停止写入旧字段，再观察完整兼容窗口。之后才在一次独立、明确的变更里删除适配器、API 字段、事件变体和数据库列。代码层面应保留可验证的回退版本；数据层面则要有经过演练的恢复或向前修复路径。

PostgreSQL 当前的 ALTER TABLE 文档说明，不同操作所需锁级别不同；除非另有说明，默认会取得 ACCESS EXCLUSIVE 锁；某些类型变更或默认值还会重写整张表及其索引。文档也介绍了在特定约束场景中先使用 NOT VALID、随后再验证，以降低对并发更新的影响。详见官方命令参考。因此，“SQL 语法正确”不能证明线上操作安全。你必须针对实际数据库版本，测量表规模、锁行为、存储余量、执行时间和恢复方式。

留下一份创始人也能看懂的迁移凭证

一次放行需要一个紧凑的证据载体，把预期契约与实际观察连起来。下面是一份可复用的起点：

contract_migration:
  id: "account-plan-to-subscription-tier-2026-08"
  owner: "具名负责人"
  authority:
    old_field: "account.plan"
    new_field: "account.subscription_tier"
    semantic_change: false
    entitlement_change: false
  versions:
    old: "account-contract-v3"
    expanded: "account-contract-v4"
    contracted: "account-contract-v5"
  compatibility_window:
    starts_at: "ISO-8601"
    minimum_days: 30
    basis:
      mobile_active_version_p99_days: 21
      webhook_retry_days: 3
      queue_max_age_days: 7
      restore_test_horizon_days: 30
  consumers:
    total: 8
    compatible: 8
    unknown: 0
    register_hash: "sha256"
  data:
    eligible_rows: 12840
    converted_rows: 12840
    conflicts: 0
    read_after_write_sample: "证据链接"
  production_signals:
    old_field_reads_last_7d: 0
    old_field_writes_last_7d: 0
    divergence_rows: 0
    parse_errors: 0
  gates:
    expand: "approved | held"
    migrate: "approved | held"
    contract: "approved | held"
  recovery:
    code_revert_test: "证据链接"
    data_forward_repair_test: "证据链接"
    owner: "具名负责人"

这些数字只是字段示例，不是 YBuild 客户数据，也不是通用阈值。请用真实观察替换。消费者清单应附哈希或稳定链接，否则清单从八项变成九项之后，凭证仍可能悄悄声称“八项全部兼容”。

务必保留“未知”状态。没有遥测不能写成零使用。如果旧字段读取无法观测，凭证应填写 not_measured；收缩门槛必须改用其他证据，例如活跃客户端版本、合成重放、合作伙伴确认，或更长的兼容窗口。

测试版本矩阵，而不是单条理想路径

当前客户端连接当前服务端，只证明了一个格子。测试必须覆盖发布过程中真实会出现的共存状态。

使用接近生产形态、但已移除秘密与个人数据的记录，或合成数据。覆盖空值、字段缺失、畸形值、最大记录、Unicode、旧枚举值，以及各阶段边界上产生的记录。

Protocol Buffers 说明了为什么测试必须跟着格式走。Proto3 指南明确要求：字段编号一旦投入使用就不应改变；删除后的编号应保留，避免日后复用；二进制格式里的旧程序可以忽略新字段，但 ProtoJSON 的安全变更规则不同。生成代码的类型检查可能完全通过，JSON 客户端、枚举分支或重新序列化路径仍可能丢失信息。

解析通过之后，还要检查业务结果。旧的 pro 记录是否仍得到同样的项目额度？退款账户是否仍保持退款状态？一次重试会不会发出两封邮件？如果契约测试只断言“成功反序列化”，它停得太早了。

在线上测量迁移不变量

对于本文示例，可以使用：

• 每一条 plan = pro 的账户记录，在对应回填批次结束后都有 subscription_tier = pro。
• 两个字段同时存在时，规范化后的业务含义一致。
• 新字段的读方在具备已测试的旧字段降级路径之前，不得参与权益决策。
• 同一 Webhook 事件在重试和重放中最多生效一次。
• 弃用字段的读取量应按具名消费者下降，而不只看全局汇总。
• 回填错误集合必须有边界、可留存并可重试。
• 仅因表示方式改变，用户访问权限、价格和账单历史都不得改变。

应用行为可以使用金丝雀发布，但金丝雀不能替代兼容性证明。AWS API Gateway 的官方金丝雀发布文档介绍了如何让少量流量访问新 API 部署，并用独立日志和指标决定是否扩大。随机抽样仍可能错过每周才运行一次的导出任务或合作伙伴 Webhook。因此，除了普通流量抽样，还要让具名的合成消费者和已知高风险路径访问候选版本。

上线前写清停止、回退和向前修复规则

真正的门槛必须导向决策，而不是放着一块无人有权操作的仪表盘。

出现以下情况应停止扩展：新增字段意外改变响应；原本可选的输入被强制为必填；数据库锁等待超过测试预算；或出现未知的高后果消费者。

出现以下情况应停止迁移：字段分歧持续增加；回填重试不具备幂等性；实时写入可能被覆盖；用户结果发生变化；或无法复现符合条件记录的分母。

出现以下情况应停止收缩：仍有无法解释的旧字段读写；任一受支持客户端版本仍依赖旧契约；恢复演练还需要旧字段；合作伙伴尚未确认；或兼容窗口尚未结束。

代码回退与数据回退不是一回事。回退应用代码可以恢复旧读方，却不能让被删除的列复活，不能撤回已经发给外部的 Webhook，也不能找回被覆盖的业务含义。在加法阶段，旧字段还在，代码回退通常较容易。回填之后，更安全的恢复方式可能是根据不可变映射或备份进行向前修复。破坏性收缩之后，恢复可能需要停机，还可能丢失备份之后写入的数据。

Stripe 的 API 升级文档提供了一个值得借鉴的运营范式：账户 API 版本会决定响应和 Webhook 行为；大版本包含不兼容变更；月度版本只包含向后兼容变更；账户升级后有文档明确说明的 72 小时回退期。具体机制属于 Stripe，但可迁移的原则是：按版本和时间约束回退能力，并测试会接收到该版本响应的消费者。

同时写清谁有权停止每个阶段，以及如何恢复。“团队会监控”远弱于“任何权益不一致出现时，由当班创始人停止回填；迁移负责人调查；重新启动必须签发新凭证”。

走一遍真实感足够的小应用迁移

假设 CourseDock 是一个售卖训练营课程的小型 AI 构建应用。数据库存有 plan，网页 API 返回它，Stripe Webhook 更新它，每日邮件任务根据它选择模板，每周还会给讲师导出 CSV。创始人准备增加年付方案，于是让代理先把字段改名为 subscription_tier。

代理找到 TypeScript 引用并生成原地改名的数据库迁移，构建顺利通过。消费者清单却发现四项遗漏：部分用户仍在使用带缓存的旧版移动端外壳应用；另一项目里有一个无服务器邮件函数；Stripe Webhook 端点仍固定在旧 API 行为；讲师的表格公式还在寻找名为 plan 的表头。

CourseDock 先冻结语义：年付将在未来作为独立变更上线，本次改名不得改变权益。数据库与 API 先新增可选的 subscription_tier，读方同时支持两者，对仍受支持的旧客户端同时返回两个字段。Webhook 适配层把各种输入规范化为一个内部契约版本。CSV 暂时保留 plan，新增 subscription_tier，并向讲师给出迁移日期。

团队以可重启批次回填，并检查三个不变量：规范化值一致、权益不变、邮件任务不重复。日志带上客户端版本和契约版本。旧移动端活跃量降为零、邮件函数完成部署、讲师验收新 CSV，并且最长重试/恢复窗口结束之后，CourseDock 才停止写 plan。再经过一个观察期，才用独立迁移把它删除。

这显然比一次改名花更久时间，而这正是它的价值：多出来的时间暴露了代码库无法呈现的承诺。AI 仍然很有用，可以起草适配器、搜集代码引用、生成样例、比较模式、准备对账查询；但含义、外部义务、阈值和破坏性授权必须留在人类门槛内。

避免九种看似高效的失败方式

做一次有边界的 48 小时影子演练

不要把真实的 30 天兼容窗口硬压缩成两天。48 小时的用途，是准备门槛并在影子环境里验证，而不是提前做破坏性收缩。

即使结论是暂停，这次演练也可能成功。生产前发现一个无人负责的合作方导出，是结果，不是需要掩盖的拖延。

什么时候这套框架还不够

对于普通早期 SaaS 变更，如果团队能列清消费者、设计加法兼容、观察使用并修复数据，可以直接使用这套门槛。

以下情况必须升级审查：记录具有法定不可变要求；字段会影响资金流转、税务、医疗、安全、身份、访问控制或监管报告；表规模或可用性目标让锁行为需要专业设计；合作合同固定了载荷；或新旧概念并不等价。比如把 gender 改名为 sex_at_birth 并不是表示方式迁移，而是含义变化，不能靠假设自动回填。

也有些系统不适合承受双写复杂度。如果团队能控制所有消费者，并在维护窗口内统一停机，协调式迁移可能反而更简单、更安全。这时应记录停机边界、备份、验证与重启顺序。Confluent 的兼容模式也明确说明，部署顺序与团队能否控制生产者/消费者，会决定哪些演进方式安全；不存在适合所有系统的唯一模式。

对尚无用户、没有外部消费者、也没有保存义务的原型数据，则不必增加整套迁移机械。导出真正重要的内容，干净重建，并记录旧契约本来就是可丢弃的。恢复纪律应减少未知风险，而不是给没有连续性承诺的数据增加仪式。

用创始人发布清单做最后判断

批准扩展之前：

• [ ] 授权声明已经拆开表示、含义、数据和执行。
• [ ] 非目标明确禁止意外改变权益、定价、隐私或政策。
• [ ] 消费者清单覆盖代码、客户端、任务、队列、Webhook、导出、分析、客服和合作伙伴。
• [ ] 新旧契约版本及冲突裁决方明确。
• [ ] 加法数据库操作已测试锁、重写、空间和执行时间。
• [ ] 旧对新、新对旧样例在用户结果层面通过。
• [ ] 停止授权人和恢复路径已经具名。

• [ ] 回填有边界、可幂等、可重启，并按符合条件的分母完成对账。
• [ ] 实时写竞争和双写分歧已经测试。
• [ ] 可以按消费者与版本观察弃用字段的读写。
• [ ] 恢复、重放、重试和延迟任务路径均通过。
• [ ] 没有未知的高后果消费者。

• [ ] 每个受支持消费者都已升级、有证据表明已退役，或被明确迁移到其他版本。
• [ ] 有依据的最长兼容窗口已经结束。
• [ ] 旧字段读写为零，或每一次都能单独解释。
• [ ] 恢复和向前修复流程不再依赖旧表示。
• [ ] 破坏性 SQL 及其运营影响已单独审批。
• [ ] 最终凭证链接真实证据，并诚实记录未知项。

参考资料

1. GitHub Docs：REST API 的破坏性变更
2. Stripe Docs：API 升级
3. Prisma Docs：扩展—收缩数据迁移
4. PostgreSQL 18 文档：ALTER TABLE
5. Protocol Buffers 文档：Proto3 语言指南与消息更新
6. Confluent 文档：Schema 演进与兼容性
7. Kubernetes 文档：API 弃用政策
8. OpenAPI Initiative：OpenAPI Specification 3.0.4
9. AWS 文档：API Gateway 金丝雀发布