principle-migrate-callers-then-delete-legacy-apis

先迁调用方，再删旧 API

When we decide a new API is the right design, migrate callers and remove the old API in the same refactor wave instead of preserving compatibility layers.

一旦认定新 API 是对的设计，在同一波重构里迁移调用方并删掉旧 API，别留兼容层。

Rule:

规则：

• Do not keep legacy API paths only because internal callers still exist

• Inventory callers, migrate them, and delete the old API immediately

• Treat temporary adapters as exceptional and time-boxed, not default architecture

• Update tests to assert the new contract, and delete tests that only protect pre-refactor implementation details

• 别只因内部调用方还在就保留遗留 API 路径

• 盘点调用方，迁移它们，立刻删旧 API

• 临时适配器当例外并限时，不当默认架构

• 更新测试断言新契约；只保护重构前实现细节的测试删掉

When this applies:

适用：

• No external users depend on backward compatibility

• The project can absorb coordinated breaking changes

• The new API is part of a simplification or refactor initiative

• 没有外部用户依赖向后兼容

• 项目能吸收协同破坏性改动

• 新 API 属于简化或重构倡议

Keeping both old and new APIs creates dual-path complexity, slows cleanup, and makes the codebase feel append-only.

新旧 API 并存制造双路径复杂度，拖慢清理，让代码库像只能追加。