我正在开发一个基于 Java 的 RESTful Web 应用程序，旨在成为其各种客户端应用程序的核心。这些客户端应用程序可以对主系统中的相同资产进行操作（例如，客户端应用程序 A 在主系统中创建资产，客户端应用程序 B 从系统中获取它们）。我们推出了/v1/ API 版本并在/v2/中开发了新功能。要求是发布 v2，同时在一段时间内仍支持 v1 的向后兼容性，直到所有客户端应用程序都移植到 v2。这一要求背后的想法是，可能针对不同 API 版本编写的客户端应用程序仍然应该能够在相同的资产上进行协作。
目前，我们在一个系统实例中涵盖了这两个 API 版本。虽然对于 HTTP API 的一些小改动，通常提供一个新的控制器就足够了（比如桥模式），对于稍微大一点的改动，最好编写一个新的控制器和服务层（希望两个版本都能在在某种程度上，重用一组通用功能）。
然而，还有更广泛的变化即将到来。更重要的是，主系统不仅仅是一个愚蠢的 CRUD，而是一个复杂的多组件网络，集成了一些外部服务，涉及一些异步作业的处理等。当然它只是一个保持向后兼容性的方便地方行为方面。
是否有任何最佳实践来保持 API 和行为的向后兼容性，同时又不会将代码变成一团糟？
我们确实关心代码的质量，并且讨厌使用复制粘贴调整类和维护重复/并行功能实现来污染它。是的，我们已经为 v1 和 v2 划分了 java 包。
另外，我们希望避免旧版本的代码束缚我们的手，使我们无法重新设计新版本的架构，只是为了保持这种向后兼容性的简单性。