api 安全_安全弃用API

api 安全

Deprecation is a position in the software development lifecycle where a certain feature needs to be removed or avoided because it’s out of date. Deprecated features are not done away with immediately; rather they are retained but raise warning messages that recommend using alternative practices. This gives users time to update their code before the unwanted code is finally removed.

弃用是软件开发生命周期中的一种位置，由于某些功能过时，因此需要删除或避免使用某些功能。 弃用的功能不会立即消失； 而是保留了它们，但提出了警告消息，建议您使用替代方法。 这使用户有时间在最终删除不需要的代码之前更新其代码。

Deprecation can happen for various reasons – perhaps an API is no longer useful and has reached its end-of-life, or the refactoring of code to improve its reusability and testability obsoletes particular methods.

弃用可能由于各种原因而发生-也许某个API不再有用且已达到其使用寿命，或者重构代码以提高其可重用性和可测试性使某些方法过时了。

In this article I’ll share with you some key points that you should follow when deprecating APIs so you can continue to grow your code and provide fair warning to those who depend on it.

在本文中，我将与您分享一些弃用API时应遵循的关键点，以便您可以继续增加代码并向依赖它的人提供合理的警告。

准备重构 (Prepare for Refactoring)

Even though it is tedious, make sure you first document your code. This will assist you in better understanding what code is responsible for what functionality and how it functions as a whole. Use a standardized document format so it can be used by your IDE and easily compiled into readable documentation.

即使很繁琐，也请确保先记录代码。 这将帮助您更好地理解哪些代码负责什么功能以及其整体功能。 使用标准化的文档格式，以便IDE可以使用它并轻松地将其编译为可读的文档。

Then, to ensure your service or library continues to work after you deprecate parts of its API, test the original code with your unit tests. If the tests fail, you must fix the problems so you can distinguish between failures that were brought by deprecating the API and failures that were already there.

然后，要确保您的服务或库在弃用其API的某些部分后仍能继续工作，请使用单元测试对原始代码进行测试。 如果测试失败，则必须解决问题，以便区分不赞成使用API​​带来的失败和已经存在的失败。

实行单一责任原则 (Employ the Single Responsibility Principle)

Logically organize your code based on the purpose and function of various components, and employ the Single Responsibility Principle (SRP). The principle ensures the methods and classes that perform more than one job are refactored so each has a single task. This increases the reusability and testability of your code. Don’t worry if there are many classes and methods in your API as a result of applying the SRP; reusable and testable code allows deprecating changes to be targeted to a minimal amount of code.

根据各种组件的用途和功能合理地组织代码，并采用单一职责原则(SRP)。 该原理确保重构执行多个任务的方法和类，以便每个方法和类具有一个任务。 这样可以提高代码的可重用性和可测试性。 应用SRP可以确保您的API中没有很多类和方法，请不要担心。 可重用和可测试的代码允许将不赞成使用的更改定向到最少的代码。

与您的用户交流 (Communicate with your Users)

Depending on the size of your user base, establishing good communication can be difficult. A good solution is to establish a mailing list to which they can subscribe. The period of time that you can allow users to continue using old methods once you’ve announced the intended changes on the list depends on factors like the importance and why the change is being made. Depending on your API and the resources available to your project, it might also be beneficial to host a project wiki where developers can share alternative strategies and workarounds to avoid deprecated methods calls.

根据用户群的大小，建立良好的沟通可能很困难。 一个好的解决方案是建立一个他们可以订阅的邮件列表。 一旦您在列表中宣布了预期的更改，您可以允许用户继续使用旧方法的时间取决于诸如重要性以及进行更改的原因等因素。 根据您的API和项目可用的资源，托管一个项目Wiki，使开发人员可以共享替代策略和变通办法以避免不赞成使用的方法调用，这也可能是有益的。

For libraries, the methods and classes that provide your API should be updated to issue descriptive warning messages that can be logged when they’re used. If you’re providing a web service, define headers that do not affect the current implementation but which allow you to include metadata with the service call. These headers can allow you communicate with your users about service changes.

对于库，应该更新提供API的方法和类，以发出描述性警告消息，使用它们时可以记录这些警告消息。 如果要提供Web服务，请定义不影响当前实现的标头，但允许您在服务调用中包含元数据。 这些标头可以使您与用户就服务更改进行交流。

删除旧代码 (Remove the Old Code)

After making the necessary changes, be sure to read through your code carefully to make sure the unneeded, unused, or old code, is safe to remove. Code analysis tools can be helpful as well.

进行必要的更改后，请确保仔细通读代码，以确保可以安全删除不需要的，未使用的或旧的代码。 代码分析工具也可能会有所帮助。

When a suitable deprecation period has passed, you can go ahead and prune the old code. After removing code that is no longer necessary, it is important you perform tests to make sure the system is still functioning properly so as to avoid failures.

经过适当的弃用期限后，您可以继续修剪旧代码。 删除不再需要的代码后，执行测试以确保系统仍然正常运行很重要，这样可以避免故障。

摘要 (Summary)

Deprecation can improve the internal consistency of a web service or library in the software code, its structure or the user interface. This makes it easier for users to understand how the system works reducing the cost of coming up with a new system. Refactoring helps to improve the user experience of your API and makes future changes to your code easier to implement. Code becomes more reusable and testable. But the process of refactoring also means some code because unnecessary and should be removed to keep the project clean.

弃用可以提高软件代码，其结构或用户界面中Web服务或库的内部一致性。 这使用户更容易理解系统的工作方式，从而降低了开发新系统的成本。 重构有助于改善API的用户体验，并使将来对代码的更改更易于实现。 代码变得更加可重用和可测试。 但是重构的过程也意味着一些代码，因为不必要的代码应被删除，以保持项目的清洁。

Deprecating features before they are done away or transformed gives users who depend on your code time to update their own code. By following the advice in this article, you will find it easier to keep your code fresh and your users won’t have any unhappy surprises.

在功能消除或转换之前不推荐使用的功能，给依赖于您代码的用户时间来更新自己的代码。 通过遵循本文中的建议，您将发现更容易保持代码新鲜，并且用户不会感到不满意。

Image via Fotolia

图片来自Fotolia

翻译自: https://www.sitepoint.com/safely-deprecating-apis/

api 安全