数据库字段迁移经常被误认为是一件很简单的事。

订单表里原本有一个字段：

customer_name VARCHAR(128)

团队后来决定把它拆成：

customer_first_name VARCHAR(64)
customer_last_name VARCHAR(64)

开发者把表结构和实体片段交给 AI 后，很容易得到类似建议：

ALTER TABLE orders
ADD COLUMN customer_first_name VARCHAR(64),
ADD COLUMN customer_last_name VARCHAR(64);

ALTER TABLE orders
DROP COLUMN customer_name;

代码里也顺手改成：

public record CustomerName(
    String firstName,
    String lastName
) {
}

本地开发环境中，这种修改通常顺利通过：数据库结构最新、本地应用最新、测试数据可重新生成、没有旧实例继续运行、没有异步任务在处理旧格式，也没有老版本接口继续读旧字段。

但真实发布环境通常不是“旧版本瞬间消失、新版本瞬间全部上线”。更常见的状态是：旧实例仍在处理请求；新实例开始灰度上线；数据库结构已经变化；异步任务还在消费旧格式消息；定时任务仍按旧字段读写；管理后台可能还没更新；补偿任务和数据修复脚本仍依赖旧结构。

此时直接删除旧字段，可能出现：新实例写新字段、旧实例查询旧字段失败；老代码仍执行 INSERT customer_name；新代码只读新字段、历史数据却尚未回填；回滚到旧版本后旧代码无法读取新格式数据；消息消费者收到旧事件时字段解析失败；导出任务因字段缺失中断；部分节点刷新而部分节点仍旧，错误只在少数实例出现。

根源通常不是 SQL 语法写错，而是把数据库 Schema 迁移当成一次“结构修改”，忽略了它本质上是一场跨版本协作。

一、最常见的错误：把数据库结构当成只服务当前代码版本

开发环境中的流程常常是：改实体、改 SQL、改表结构、本地启动、测试通过。但生产环境中，数据库可能同时服务灰度中的旧实例、已发布的新实例、延迟执行的异步任务、消息消费者、定时任务、导出与统计任务、审计程序、运维脚本、异常补偿逻辑以及需要紧急回退的旧版本。

假设当前有两个应用版本：

版本 V1：读 customer_name，写 customer_name
版本 V2：读 customer_first_name + customer_last_name，写 customer_first_name + customer_last_name

如果数据库先删掉 customer_name，V1 立刻失去运行能力。但如果数据库只新增新字段，V2 也可能无法正确读取历史数据，因为历史记录里旧字段有值而新字段为空。

所以 Schema 迁移最先需要回答的不是“最终字段长什么样”，而是：在新旧版本并存期间，谁读什么、谁写什么、历史数据在哪里、回滚后还能不能运行。

二、不要直接“替换字段”，先把变更拆成扩展和收缩

更稳定的 Schema 演进通常遵循：

Expand
↓
Migrate
↓
Contract

也就是：先扩展、再兼容、后迁移、最后收缩。

第一阶段：扩展结构

先只新增字段：

ALTER TABLE orders
ADD COLUMN customer_first_name VARCHAR(64) NULL,
ADD COLUMN customer_last_name VARCHAR(64) NULL;

不删除旧字段。新旧版本都还能运行：V1 继续读写 customer_name；V2 至少仍能读 customer_name；数据库同时存在旧字段和新字段。

第二阶段：让新代码具备兼容能力

新版本读取时使用兼容策略：

public CustomerName resolveCustomerName(Order order) {
    if (order.getCustomerFirstName() != null
        || order.getCustomerLastName() != null) {
        return new CustomerName(
            order.getCustomerFirstName(),
            order.getCustomerLastName()
        );
    }

    return splitLegacyName(order.getCustomerName());
}

这意味着新代码既能处理新数据，也能读取历史旧数据。

第三阶段：双写或转换写入

新版本写入时，在兼容窗口内同时写两套字段：

public void applyCustomerName(
    Order order,
    CustomerName customerName
) {
    order.setCustomerFirstName(customerName.firstName());
    order.setCustomerLastName(customerName.lastName());
    order.setCustomerName(joinLegacyName(customerName));
}

这样即使系统中还有 V1 实例，旧实例仍能读取 customer_name。

第四阶段：回填历史数据

新增字段后，历史记录并不会自动拥有新值。需要明确回填策略：

UPDATE orders
SET
    customer_first_name = ...,
    customer_last_name = ...
WHERE customer_name IS NOT NULL
  AND customer_first_name IS NULL
  AND customer_last_name IS NULL;

真实回填不一定适合一次性全表执行。还要考虑数据量、锁等待、批次大小、回填进度、异常中断、是否可重复执行、数据解析规则是否存在歧义，以及回填后是否需要人工抽样验证。

第五阶段：停止旧字段写入

只有当旧实例全部下线、旧消费者全部完成兼容、回填验证完成后，才能停止写旧字段。

第六阶段：收缩结构

最后才考虑：

ALTER TABLE orders
DROP COLUMN customer_name;

这不是一次普通删除，而是团队确认系统中已经没有任何仍然依赖旧字段的运行路径。

三、最难的问题不是新增字段，而是新旧版本如何同时写

字段迁移里常见兼容策略：

策略	写入方式	优点	风险
旧写新读	继续写旧字段，新代码兼容读取	改动小	新字段长期为空
双写	同时写旧字段和新字段	新旧实例兼容性强	两套字段可能不一致
写新读旧兜底	新字段优先，旧字段作为回退	逐步完成迁移	历史数据需要回填
只写新字段	新版本完全切换	最终结构干净	旧实例和回滚风险高

最容易出问题的是双写。它看似解决了兼容性，但也可能导致新字段写成功、旧字段写失败；旧字段格式可以表达而新字段不能完整表达；新旧代码采用不同拼接规则，读取结果不一致。

因此双写必须明确：哪个字段是最终事实来源；两边不一致时谁优先；旧字段是否只是兼容副本；双写失败时是否整体回滚；是否需要定期校验；双写持续多久；什么条件满足后可以停止旧写。

例如可以定义：新字段是权威数据；旧字段是兼容字段；不一致时以新字段为准并记录异常；旧字段写失败时按业务决定是否阻断。

四、错误但常见的做法：数据库先改完，再让代码慢慢追上

有些团队的顺序是：先执行 ALTER TABLE，直接删除旧字段，再发布新代码。这在停机发布、没有异步链路、没有多实例、可以瞬间切换的环境里或许成立，但对大多数在线系统风险很高。

因为数据库变更一旦先发生，旧代码可能立即失败：V1 仍在运行，查询 customer_name，字段被删除，SQL 异常，请求失败。

更麻烦的是回滚：V2 发布后发现问题，想回滚到 V1，但旧字段已删除，V1 仍依赖旧字段，回滚版本也无法运行。所谓回滚不可用。

判断 Schema 迁移是否安全，不能只看新版本能不能运行，还要看旧版本能不能继续运行、旧版本能不能作为回滚版本运行、历史数据能不能被新版本读取、新数据能不能被旧版本兼容处理。这就是双向兼容。

五、让 AI 先整理新旧版本读写矩阵，而不是直接输出 DROP COLUMN

如果只问 AI：“我想把 customer_name 拆成 first_name 和 last_name，帮我改数据库”，它可能直接给出 ADD COLUMN 和 DROP COLUMN。这些 SQL 在最终阶段不一定错误，但如果没有上下文，AI 无法判断系统是否灰度发布、是否还有旧实例、是否有消息消费者依赖旧字段、是否有延迟任务处理历史消息、是否支持快速回滚、历史数据能否无损拆分、是否需要双写、哪个字段是权威来源，旧字段是否存在导出、审计或脚本依赖。

更有效的提示方式：

你是 Java 数据库 Schema 迁移与灰度发布评审助手。

场景：订单表中的 customer_name 需要拆分为 customer_first_name 和 customer_last_name。系统有多个应用实例，采用灰度发布；存在异步任务、消息消费者、导出任务和定时任务；上线后必须保留可回滚能力。

请不要直接输出 DROP COLUMN。
请输出：
1. 新旧版本的读写矩阵；
2. 扩展、兼容、回填、停旧写、收缩各阶段的顺序；
3. 双写时哪个字段应作为权威来源；
4. 历史数据回填如何分批、重试和核验；
5. 新旧实例并存时的错误场景；
6. 回滚到旧版本需要保留哪些结构和数据；
7. 至少 10 个兼容性、回填和发布测试场景；
8. 哪些命名、解析和业务规则必须由产品或运营确认。

当团队把 ChatGPT Plus 用于迁移方案审查、SQL 评估、发布清单整理和故障复盘时，工具接入准备不只是能否快速生成脚本，还包括是否能完整描述变更范围、明确新旧版本关系、保留异常证据，并让回滚在真正需要时仍然可用。

团队把 AI 工具纳入日常流程时，除了权限与脱敏规范，也应提前确认使用规则、周期和异常处理路径；需要集中核对时可参考gpt0424com

六、回填任务必须可重复、可暂停、可核验

历史数据回填通常是 Schema 迁移里最耗时、最容易被低估的一段。

订单表有数千万条记录时，一次性 UPDATE 可能带来大量行锁或事务压力、主从复制延迟扩大、业务写入等待、磁盘和日志增长、长事务难以回滚、执行中断后无法判断处理到哪里，以及在线请求受影响。

更稳妥的方式通常是按主键范围或时间范围分批处理：

第 1 批：id 1 - 10000
第 2 批：id 10001 - 20000
第 3 批：id 20001 - 30000

每批都应记录批次编号、处理范围、开始时间、结束时间、成功数量、失败数量、重试次数、错误摘要和校验结果。

回填逻辑最好满足“已经回填完成的数据再次执行时不会产生副作用”。例如：

UPDATE orders
SET
    customer_first_name = :firstName,
    customer_last_name = :lastName
WHERE id = :id
  AND customer_first_name IS NULL
  AND customer_last_name IS NULL;

回填完成后，不应只看任务跑完了，还要核对旧字段有值但新字段为空的记录数、新旧字段解析后不一致的记录数、无法自动拆分的异常记录数，以及新字段为空但业务仍依赖的数据量。

七、至少覆盖这些兼容与回滚测试

测试场景	预期结果
V1 写旧字段	V2 能正确读取
V2 写双字段	V1 仍能正常读取旧字段
V2 读取历史数据	能通过旧字段兼容展示
历史回填中断	可从断点继续，不重复破坏数据
双写某一侧失败	按规则阻断、告警或进入修复队列
灰度实例混合运行	新旧接口均可用
老消息延迟到达	新消费者能兼容旧字段
新消息被旧消费者处理	旧消费者不会因字段缺失崩溃
新版本回滚到 V1	V1 仍可运行
停止旧写后	旧字段不再被依赖
收缩前扫描	没有任何代码、任务和脚本依赖旧字段
字段删除后验证	数据、导出、统计和审计均不受影响

示例：

@Test
void shouldReadLegacyNameWhenNewFieldsAreEmpty() {
    Order order = new Order();
    order.setCustomerName("张三");
    order.setCustomerFirstName(null);
    order.setCustomerLastName(null);

    CustomerName result = customerNameResolver.resolve(order);

    assertEquals("张", result.firstName());
    assertEquals("三", result.lastName());
}

@Test
void shouldKeepLegacyFieldDuringCompatibilityWindow() {
    CustomerName name = new CustomerName("张", "三");
    Order order = new Order();

    orderWriter.applyCustomerName(order, name);

    assertEquals("张三", order.getCustomerName());
    assertEquals("张", order.getCustomerFirstName());
    assertEquals("三", order.getCustomerLastName());
}

八、上线后要观察什么

建议至少记录：

legacy_field_read_total
legacy_field_write_total
new_field_read_total
new_field_write_total
dual_write_mismatch_total
backfill_processed_total
backfill_failed_total
backfill_unparseable_total
schema_compatibility_error_total
old_version_query_error_total

重点观察旧字段是否仍被读取或写入、双写是否出现不一致、回填进度是否停滞、是否有无法解析的历史数据、是否有旧实例因字段缺失报错、异步任务是否仍依赖旧格式、是否存在新旧字段同时为空或冲突，以及是否已经满足删除旧字段的前置条件。

真正执行收缩前，最好能明确回答：旧字段最近一次被读取和写入是什么时候？是否还有活跃实例运行旧版本？是否有延迟消息或补偿任务可能使用旧字段？是否存在未经检查的脚本和导出任务？回滚版本是否仍需要旧字段？如果这些问题没有答案，删除旧字段通常还太早。

九、结语

数据库字段迁移的风险，不在于 ALTER TABLE 写错。真正困难的是让新旧版本、历史数据、异步任务和回滚路径在同一段时间里仍能彼此兼容。

可靠的 Schema 演进，需要先扩展后收缩；明确新旧字段在兼容窗口内如何读写；明确双写时谁是最终事实来源；明确历史数据如何回填和核验；确认新旧实例并存时是否仍可运行；确认回滚是否真可执行；扫描旧字段是否仍被脚本、任务、消费者或导出逻辑使用；明确哪些异常必须阻断发布，哪些边界需要人工确认。

AI 可以帮助整理读写矩阵、生成迁移脚本、补齐测试场景和梳理发布清单。但真正需要团队决定的是：这次字段演进是否允许旧版本继续存在、旧版本要兼容多久，以及什么时候才能证明旧字段已经真正没有任何运行依赖。

可靠的 Schema 迁移，不是最快删掉旧字段，而是在新旧版本同时存在、异常发生、需要回滚时，系统依然能够稳定运行。