如何判断一个 API 是否优秀？

到目前为止，我们已经负责API近两年了。在过去的两年里，我们发现现有的API存在越来越多的问题，但许多API一旦发布就无法修改，需要立即升级和维护。一旦API发生变化，可能会给相关调用器带来巨大的成本。用户需要调查所有调用代码和所有相关部件，这对他们来说是额外的。如果你在努力完成这些工作后发现了相关的bug，对用户的打击会更大。如果API经常发生变化，用户将对提供商失去信心，从而影响当前业务。但是为什么要修改API呢？为API看起来更漂亮？为了提供更多的功能？为提供更好的性能？还是觉得是时候改变了？对于用户来说，他们更喜欢使用稳定但不那么时尚的API，这并不意味着我们不再改进API。当糟糕的API带来越来越多的维护成本时，我认为是时候重构它了。如果我能回头再做一遍，那么我心目中优秀的API应该是什么呢？判断一个API是否优秀，不仅仅是根据第一个版本来判断，而是看API是否还能随着时间的推移而存在，是否还能保持良好。槽糕有各种各样的API接口，但对于用户来说，好的API接口必须满足以下几点：易于学习：有完善的文档，提供尽可能多的示例和可复制－与其他设计工作一样，paste的代码应该应用最小惊喜原则。易于使用：没有复杂的程序，复杂的细节，易于学习；灵活的API允许按字段排序、自定义页面、排序和筛选。一个完整的API意味着包含所有预期的功能。难误用：对于详细的错误提示，一些有经验的用户可以直接使用API而无需阅读文档。对于开发人员来说，要求是不同的：易于阅读：编写代码只需要一次，但在调试或修改时需要阅读代码。易于开发：最小接口是使用尽可能少的类和尽可能少的类成员。这使得更容易理解、记忆、调试和改变API。如何做到以上几点，以下是一些总结:1、 如果一个API被广泛使用，就不可能了解所有使用API的用户。如果设计师想要设计广泛使用的API，他们必须从用户的角度来理解如何设计API库，以及如何设计这样的API库。2、 在设计过程中采用良好的设计理念，如果能以下方式设计，将使API生命更长，收集用户建议，模拟用户，确保API设计易于使用，合理确保后续需求可以扩展完成第一版尽可能少的内容，因为新需求可以扩展，因此，尽量少做事是抑制API设计错误的有效方案，提供清晰的API和文档规范，避免用户错误使用API，特别是用户知道和误用API（见第一节），以下还列出了一些具体的设计方法：方法优于属性工厂方法优于结构函数，避免过度继承，避免API面向接口编程扩展参数的优化或重用代码，应方便组件的合理定位，确定有多少接口提供扩展点3、 在设计API时，一定要避免极端意见，特别是以下几点：必须是美丽的（API不一定是美丽的）API必须正确使用（用户很难理解如何正确使用API，API设计师应该充分考虑API的误用：如果API可能被误用，那么它将被误用）必须是简单的（我们总是面临复杂的需求，两者兼顾的API是更好的API)必须具有绝对兼容性(性能可以通过其他方式优化，不应影响API的设计)(虽然本文一直提到如何保证兼容性，但我们仍然需要意识到，在某些情况下，不兼容性是可以容忍的)4、 API设计完成后，需要对API进行有效的评审，评审的重点如下：用例驱动，评审前必须提供完善的用例，以保证用例的合理性和完整性。系统中其他模块的接口风格是否一致，对称接口的设计是否一致。一致性，是否与系统中其他模块的接口风格和对称接口的设计一致。简单明了，API要简单易懂，容易学习和使用的API不容易被误用，给我们带来更多的麻烦。API应该尽可能少。如果API可以暴露或不暴露，不要暴露他。当用户真正需要它时，成为一个开放接口还不算晚。支持持续改进，API能否通过扩展方式轻松增加功能和优化。5、 提高API的可测试API需要进行测试，测试不应依赖于实现。充分测试的API，特别是经过严格的“兼容性集成测试”的API，可以确保在升级过程中没有兼容性问题。兼容性整合测试是指从用户的角度使用API的一组测试用例集。API升级后，检测这组测试用例是否能完全满足预期，并尽可能发现兼容性问题。6、 对于每个API设计师来说，确保API的向后兼容性都渴望实现“向后兼容性”，因为当前的API用户和潜在的API用户都只相信那些可兼容的API。但向后兼容有多层次的意义，不同层次的向后兼容也意味着不同的重要性和复杂性。7、 为了逐步改进过去，我们总是希望完全推翻现有的“不合理”设计，然后根据当前的“美丽”想法重新设计API，但一段时间后，我们会遇到同样的情况，需要再次推翻。如果没有有效的逐步改进方法，依靠推翻现有设计，重新设计API只能让我们回到起点，重现之前的过程。在API兼容的同时，要有一套有效的持续改进方法，改进API，使之更好。8、 把握API的生命周期。每个API都有一个生命周期。我们需要延长API的生命周期，并在API的生命周期结束时平稳地消亡。告诉用户我们是如何设计的，避免误用，并提供指导。错误的使用通常是缩短API使用寿命的主要杀手提供试用期。API一开始不可能是稳定的。只有经过试验，API才能有更强的生命力来对API进行分类：内部使用；二次开发和使用；在开发或试验过程中；稳定性；放弃API。在避免滥用API的同时，我们可以通过调整API水平来扩大其影响力，更优雅地结束API的生命周期。API开发的过程其实是一个沟通的过程。双方的沟通是API用户和API设计师。9、 当API不可避免地消亡或改变时，我们应该接受并面对这一事实。以下是在保证兼容性的前提下调整API的几种方法：将API标记为弃用，重建新的API。如果API不可避免地消亡，这是唯一的办法。添加额外的参数或参数选项来实现功能添加，将现有的API分成两部分，并提供一个简化的核心API，通过包装核心API实现过去的API。这通常用于解决用户需要精简代码的版本。在现有API的基础上包装，提供功能更丰富的包或类别