Back to Details

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

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
Rule:
  • Do not keep legacy API paths alive 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
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
Keeping both old and new APIs creates dual-path complexity, slows cleanup, and makes the codebase feel append-only.
当我们确定新API设计更合理时，应在同一重构迭代中迁移调用方并移除旧API，而非保留兼容层。
规则：
  • 不要仅因存在内部调用方便保留旧API路径
  • 清点所有调用方，完成迁移后立即删除旧API
  • 将临时适配器视为特殊且有时间限制的方案，而非默认架构
  • 更新测试以验证新契约，并删除仅用于保护重构前实现细节的测试
适用场景：
  • 无外部用户依赖向后兼容性
  • 项目可接受协调式的破坏性变更
  • 新API属于简化或重构计划的一部分
同时保留新旧API会带来双路径复杂度，拖慢清理进度，还会让代码库呈现出“只增不减”的状态。