我正在将一个开源 Java 库转换为 C#，其中有许多方法和类标记为已弃用。这个项目是一个从头开始的机会，所以我计划完全删除它们。然而，对于大型项目的工作来说，我很担心这种情况会再次出现。由于大部分敏捷开发都围绕着让某些东西现在工作并在需要时进行重构，所以 API 的弃用似乎是一个普遍的问题。即使我不完全确定项目的未来方向，我是否可以采取预防措施来避免/最大限度地减少 API 弃用？
【问题讨论】：
标签： api agile deprecated
我不确定你能做多少。需求发生了变化，如果您绝对必须确保 API 的客户端不会被较新的 API 版本破坏，那么您将不得不依赖简单的弃用代码，直到您认为没有人使用弃用的代码。
在代码上放置 [Obsolete] 属性会导致编译器在存在对过时方法的任何引用时创建警告。这样 API 的客户，如果他们努力修复编译器警告，就可以逐渐转向新方法，而不会因新版本而中断。
如果你使用 ObsoleteAttribute 的覆盖字符串，它会很有用：
[Obsolete("Foo is deprecated. Use Bar instead for munging widgets.")]
也许你可以创建一个 TimeBombAttribute：
[TimeBomb(new DateTime(2010,1,1), "Foo will blow up! Better use Bar, or else."]
在您的代码中，反映具有 timebomb 属性的方法，如果在指定日期之后调用它们，则抛出 KaboomException。这将确保在 2010 年 1 月 1 日之后没有人使用过时的方法，并且您可以很好地清理您的 API。 :)
轻浮>
【讨论】：
正如马特所说，Obsolete 属性是您的朋友……但无论何时应用它，请提供有关如何更改调用代码的详细信息。这样你就有更好的机会让人们真正改变。您可能还需要考虑指定您预计在哪个版本中删除该方法（可能是下一个主要版本）。
当然，您应该努力确保您不要调用过时的代码——尤其是在示例代码中。
【讨论】：
由于大部分敏捷开发都围绕着让某些东西现在工作并在以后需要时重构
这不是敏捷。这是伪装在敏捷标签下的牛仔编码。
理想的情况是，无论你完成什么，都是完成，根据你对完成的任何定义。通常，DoD 会按照“功能实施、测试和相关代码重构”的方式陈述一些内容。当然，如果您正在制作一次性原型，您可以拥有更轻松的 DoD。
API 修改是一件困难的事情。如果它们只是您正在修改的项目内部 API，那么最好的方法是尽早重构。如果您需要更改内部 API，只需同时更改所有 API 客户端即可。这样，重构债务不会变得非常大，并且您不必使用弃用。
对于已发布的 API，您可能需要维护一些源代码和二进制兼容性保证，至少要等到下一个主要版本发布。在保持兼容性的同时，将旧 API 标记为已弃用。与内部 API 一样，您应该尽快修复内部代码，以免使用已弃用的 API。
【讨论】：
马特的回答是中肯的建议。我只是想提一下，最初您可能想要使用以下内容：
[Obsolete("Please use ... instead ", false)]
移植代码后，将 false 更改为 true，然后编译器会将对该方法的所有调用视为错误。
【讨论】：
观看 Josh Bloch 的“How to Design a Good API and Why It Matters”
对于弃用而言，最重要的是知道“当有疑问时，将其排除在外”。观看视频以进行澄清，但这与必须永远支持您提供的内容有关。如果您确实期望该 API 被重用，那么您实际上是在确定自己的决定。
我认为 API 设计在敏捷方式中是一件更棘手的事情，因为您希望它可能以多种不同的方式被重用。您必须担心会破坏依赖您的其他人，因此虽然可以做到，但如果没有其他团队的快速转变，很难出现正确的设计。当然，弃用在这里会有所帮助，但我认为 YAGNI 在 API 方面是更好的设计启发式。
【讨论】：
我认为弃用代码是敏捷过程（如持续重构和增量开发）不可避免的副产品。因此，如果您在处理项目时最终使用了已弃用的代码，那不一定是坏事——只是生活中的事实。当然，您可能会发现，您最终保留了大量代码，但将其重构为不同的方法、类等，而不是弃用代码。
所以，底线是：我不会担心在敏捷开发期间弃用代码。如果它在一段时间内发挥了作用，那么您就做对了。
【讨论】：
API 设计的经验法则是关注它的作用，而不是它的作用方式。一旦你知道了最终目标，找出你需要的绝对最小输入并使用它。避免将您自己的对象作为参数传递，只传递数据。
将配置与执行分开。例如，也许你有一个图像编码器/解码器。
而不是像这样拨打电话：
Encoder.Encode( bytes, width, height, compression_type, compression_ratio, palette, etc etc);
做起来
Encoder.setCompressionType(compression_type);
Encoder.setCompressionType(compression_ratio);
etc,etc
Encoder.Encode(bytes, width, height);
这样添加或删除设置不太可能破坏现有的实现。
【讨论】：
对于弃用，基本上有 3 种类型的 API：内部、外部和公共。
内部是指只有您的团队在编写代码。弃用这些 API 没什么大不了的。你的团队是唯一使用它的人，所以他们的存在时间不长，有改变它们的压力，人们不害怕改变它们，而且人们知道如何改变它们。
外部是指相同的代码库，但不同的团队正在使用它。这可能是大公司的一些常用库，也可能是流行的开源库。关键是，人们可以选择他们编译的代码版本。弃用 API 的难易程度取决于组织的规模以及它们的沟通情况。 IMO，弃用者的工作是更新旧代码，而不是将其标记为弃用并让警告在整个代码库中传播。为什么是弃用者而不是弃用者？因为贬低者是知情的；他们知道发生了什么变化以及为什么发生变化。
这两种情况很简单。只要有向后兼容性，您通常可以做任何您想做的事情，自己更新客户端，或说服维护者这样做。
然后是公共 api。这些基本上是客户端无法控制的外部 API，例如 Web API。这些很难更新或弃用。大多数人不会注意到它坏了，不会有人来修理它，不会收到它改变的通知，并且只有一旦它坏了就会修复它（在他们对 你为了打破它，当然）。
我不得不多次执行上述操作，这真是一件苦差事。我认为您能做的最好的事情就是在及早故意破坏它，稍等片刻，然后再恢复它。当然，您首先发出通常的警告和弃用，但是 - 相信我 - 除非出现问题，否则什么都不会发生。
我还没有尝试过的一个想法是让人们注册运行小型测试的简单应用程序。当您想要进行 API 更新时，您需要运行外部测试并联系受影响的人。
【讨论】：
另一种流行的方法是让客户依赖（网络）服务。有一些结构允许您对服务进行版本控制并允许客户端执行查找。这会在方程式中增加更多的移动部分和复杂性，但如果您正在考虑转换大量版本并且必须在生产中支持多个版本，这可能会有所帮助。
This article 很好地解释了问题和方法。
【讨论】：