Safe Change 是一个用于安全变更的技能:当其他代码依赖某项内容时,不要直接原地修改。它给出的原则是:在旁边新增内容,把调用方迁移过去,再移除旧内容。每个阶段都是独立的 PR 和部署,且每个阶段都能单独安全回滚。
启动前准备
第 0 步:了解调用方。开始前需要拿到完整的调用方清单;若尚未做影响分析(impact-analysis),应先执行。若被修改的代码测试覆盖不足,先运行特性测试(characterization-tests),以便在行为变化时能够察觉。
第 1 步:选择变更模式
- 重命名模型字段(例如 status → state):扩展阶段新增 state(可空或带默认值),保存时双写,并执行迁移与回填(django-migrations);随后迁移读方,把所有读取(代码、序列化器、过滤器、admin、原生 SQL、其他仓库)切换到 state;停止写入 status,如原本非空则改为可空;收缩阶段用 SeparateDatabaseAndState 仅移除模型状态中的字段,部署后再在后续迁移中删除列。
- 重命名或移除被其他仓库消费的 API 响应字段:扩展阶段同时返回 status 和 state,并将 state 加入契约测试;消费方切换读取 state(各自的 PR 与部署,见 cross-repo-change);确认无人再读 status(搜索消费方仓库、如有 API 日志则检查日志);收缩阶段移除 status、更新契约测试,并在发布说明中提及。
- 修改请求负载或校验:同时接受新旧两种输入形态,在序列化器里统一归一化为新形态;对仍使用旧形态的请求做日志或计数;当计数在一个完整发布周期内为零时移除旧形态。
- 修改函数或服务签名:新增带默认值的参数,或新增函数并让旧函数作为调用新函数的薄包装;迁移调用方,用 grep 找出所有调用点,包括 Celery 任务调用(.delay( / .apply_async()):部署期间消息队列中可能仍有以旧参数序列化的任务,因此任务需在一个发布周期内同时接受两种参数;最后删除包装或旧参数。
- 修改 URL:新增路由,旧路由仍指向同一视图;迁移内部链接与消费方;浏览器 URL 的旧路由返回重定向,API 的旧路由保留至消费方完成后再移除。
- 在同一接口后修改行为:使用功能开关(按项目现有方式,如 django-waffle、settings 标志、数据库标志),默认关闭,按环境开启,之后移除开关和旧分支。
第 2 步:写下计划
编码前,在工单或 PR 描述中以清单形式写出各阶段,例如:阶段 1(本 PR)新增 state、双写、回填,部署后端;阶段 2 在后端和 web-app 切换读取,先部署后端再部署 web-app;阶段 3 停止写入 status、从模型状态中移除,部署后端;阶段 4 删除列,在下一个版本部署后端。并注明每个阶段的回滚方式(回滚 PR;由于阶段 3 之前仍写旧字段,不会丢数据)。请开发者确认后,只实现当前阶段。
第 3 步:实现当前阶段
新旧路径并存期间,为两者都写测试;每个阶段都必须让主分支可部署、所有消费方可正常工作;用注释明确标记临时代码,例如 # expand/contract: remove after ABC-123 phase 3;为剩余阶段创建后续工单(jira-tickets),避免收缩步骤被遗忘。
规则
每个 PR 只做一个阶段;同时新增新字段并移除旧字段的 PR 不算安全变更。另一仓库仍在读取的内容,必须等该仓库在不依赖它的情况下完成部署后才能移除。不得在活动表上通过单次迁移重命名模型字段或数据库列。
适用场景与限制
该技能针对 Django 及跨仓库 API 的兼容性变更给出通用流程,涉及迁移、特性开关、Celery 队列与服务签名等具体做法。资料未说明其自身安装方式、运行命令、许可方式或支持的平台范围,这些信息暂未提供。