用途:安全地变更持久化层,管理表/列/索引等模式变更、迁移、读写路径更新,以及兼容性与发布策略,核心目标是防止数据丢失和破坏性变更。
主要能力:识别现有迁移机制与约定;选择安全变更策略(优先增量变更,必要时双写或回填,破坏性变更需明确迁移计划);实现具备确定性 up/down 行为的迁移;更新数据访问代码以适配新模式;谨慎添加或调整索引以避免性能回退;补充或调整测试。
输入:期望的模式变更(新增/修改/删除)、向后兼容需求(能否一步部署或需多步发布)、涉及的数据访问层(ORM/查询构建器/原生 SQL),以及可选的仓库配置 <repo>/REPO_PROFILE.json。
输出:迁移或模式变更产物、更新后的数据访问代码、更新或新增的测试,以及多步发布时的说明(按仓库规范写入注释或文档)。
工作流:先识别迁移机制与约定,再选择安全策略并实现迁移,随后更新读写路径(发布期间读可容忍两种状态,写保持一致),谨慎处理索引,补充迁移可应用及读写可用的测试,最后运行配置要求的校验。
检查项:迁移在全新环境可干净应用;无明确计划不得做破坏性变更;测试通过且至少覆盖一条新访问路径;如配置了类型检查/lint 需通过;考虑索引、N+1、全表扫描等性能风险。
失败模式:缺少迁移框架时停止并建议先建立;请求破坏性变更时要求分阶段计划与回滚说明;生产约束未知时建议先采用保守的增量迁移。
非目标:与模式无关的业务逻辑变更、端点接线(除非编译需要)、整体重写持久化层。
遥测记录:skill: backend/persistence-layer-change、migration_type(additive/staged/destructive)、artifacts_written、files_touched、outcome(success/partial/blocked)。