不能直接在main分支重构核心模块，因为变更粒度失控会导致ci失败、下游功能中断、测试覆盖率骤降及业务叫停；必须通过feature toggle分三层控制、git worktree隔离环境、三类集成测试验证，并完成开关关闭与旧代码清理才算真正收尾。
为什么不能直接在 main 上重构核心模块
直接在 main 分支上重写订单服务或支付网关这类核心模块，几乎必然导致：CI 构建失败、依赖它的下游功能临时不可用、测试覆盖率断崖下跌、业务方紧急叫停。根本原因不是代码写得不好，而是变更粒度失控——一次提交里混着接口调整、数据库迁移、第三方 SDK 升级和日志格式变更，没人能准确评估影响范围。
更隐蔽的问题是：旧逻辑和新逻辑共存时，if-else 嵌套、临时开关变量、未清理的 mock 行为会悄悄污染主干，后续排查问题的成本远高于前期隔离成本。
- 所有跨模块调用必须走明确定义的契约（如 OpenAPI spec 或 protobuf 接口），而不是直接 import 旧包
- 新模块初始版本只提供空实现或返回兜底数据，确保编译通过、测试可跑
- 禁止在
main上 merge 任何未通过特性开关控制的新逻辑
如何用 Feature Toggle 控制新旧模块切换
特性开关不是简单加个 if (featureFlag)，而是要分三层落地：配置层（YAML/Consul）、运行时层（Spring Boot 的 @ConditionalOnProperty 或 Go 的 feature.IsEnabled("payment-v2")）、路由层（API 网关按 header 或 query 参数分流）。关键点在于开关本身必须可热更新，且默认关闭。
示例中常见错误是把开关写死在代码里：if (env == "prod" && version == 2) —— 这等于没开关，发布即锁定，失去灰度能力。
- 开关命名需带业务上下文，比如
order-service.payment-engine.v2.enabled，避免泛用feature.toggle - 每个开关必须配套监控指标：新路径成功率、旧路径调用量衰减曲线、开关状态变更日志
- 上线后 48 小时内未触发的开关应自动告警，防止遗忘清理
git worktree + Docker 构建隔离真实环境
重构期间需要同时维护旧版部署、新版验证、灰度流量测试三个环境，但共用一个本地工作区极易误操作。用 git worktree add ../payment-v2 release/v2.1 创建独立目录后，再用 docker-compose.yml 显式挂载该目录到容器：volumes: - ../payment-v2:/app/src。这样每次构建都基于精确 commit，不会受当前 main 分支未提交修改干扰。
注意：不要在 worktree 目录里执行 git pull，它默认关联原仓库远程，容易意外拉取其他分支。安全做法是先 cd ../payment-v2，再 git fetch origin && git reset --hard origin/release/v2.1。
- 每个
worktree应绑定唯一 CI job，避免多个流水线并发写同一目录 - Dockerfile 中禁止使用
COPY .，必须指定子路径如COPY ./src ./src，防止误拷其他模块文件 -
git worktree remove前务必确认该目录下无未提交修改，否则会被永久删除
重构完成前必须验证的三类测试
光有单元测试覆盖不够。真正卡住重构落地的是三类集成验证：1）老接口输入 → 新模块输出 vs 旧模块输出一致性比对；2）数据库 schema 变更后，旧写新读 / 新写旧读双路并行校验；3）压测时新模块 P99 延迟不劣于旧模块 10%。
最容易被跳过的其实是第一类——用生产流量录制生成回归测试集，而非人工构造 case。工具如 goose（Go）或 traffic-mirror（Java）可自动捕获 HTTP 请求/响应对，再注入新模块验证行为一致性。
- 一致性比对脚本必须包含浮点数容差（如金额字段允许 ±0.01）、时间戳忽略、UUID 替换逻辑
- 数据库双写校验需开启事务回滚开关，避免污染线上数据
- 压测环境必须复现真实链路，包括消息队列延迟、下游服务 mock 响应时间
重构不是替换完代码就结束，而是直到开关关闭、旧模块代码删除、监控告警规则更新完毕才算真正收尾。中间任何一个环节漏掉，都会让技术债以更隐蔽的方式沉淀下来。
