API 设计之禅

API 设计之禅

译者按：本文翻译自 How to design a good API and why it matters。根据笔者经历，很多大厂程序员所写的代码和大厂内部封装的各种中间件、类库，毫不客气地说，90%都是没有经过仔细考虑的，常常有各种各样的性能、拓展、可读性、一致性等题目。本文总结深刻，建议反复阅读学习。文章首发公众号，欢迎关注。

在传统的 API 设计方法中，我尝试将讲座的英华提炼成一系列格言，以资助开辟者更好地明白和设计高质量的 API：

• 所有程序员都是 API 设计师。好的程序是模块化的，模块之间的边界定义了 API。好的模块可以被重用。
  
• API 可以是你最名贵的资产，也大概是负担。好的 API 可以创造长期的客户，而差的 API 会造成长期的维护噩梦。
  
• 公共 API，像钻石一样，永恒存在。你只有一次时机来设计它，所以要尽尽力做到最好。
  
• API 应该易于使用且难以滥用。做简朴的事情应该容易，做复杂的事情应该大概，做错误的事情应该尽大概困难或不大概。
  
• API 应该是自文档化的：对于一个好的 API，代码应该很少须要额外的文档说明。事实上，编写好的 API 代码时，通常也不须要太多文档说明。
  
• 在设计 API 时，起首要收集需求，且保持一定的怀疑态度。人们通常会提供办理方案，但你的任务是发现潜在的题目并寻找最佳的办理方案。
  
• 以用例的情势构建需求：用例是你衡量 API 的标准。
  
• API 的早期草稿应该简短，通常是一页纸，列出类和方法的签名以及一行形貌。这能方便你在首次设计不完全正确时进行重构。
  
• 在实现 API 之前，甚至在它完全规范之前，先编写用例代码。这样可以避免实现或设计出根本不合适的 API。
  
• 随着 API 的演化，维护用例代码。这不仅能避免突然的意外，而且天生的代码将成为 API 的示例、教程和测试的基础。
  
• 示例代码应该是典范。如果一个 API 被广泛使用，它的示例将成为成千上万程序的原型。任何错误都会以千倍的速度反弹回来。
  
• 你无法取悦所有人，所以应该只管让每个人都不满。大多数 API 都会受到过多的束缚。
  
• 预期由于想象力的局限导致的 API 设计错误。你不大概合理地想象出每个人会如何使用一个 API，或者它将如何与系统的其他部门交互。
  
• API 设计不是孤立的活动。把你的设计展示给尽大概多的人，并认真听取他们的反馈。那些你没能想到的大概对别人来说是显而易见的。
  
• 避免固定输入大小的限定。它们会限定 API 的实用性，并加速它的过时。
  
• 如果难以找到合适的名称，就重新开始设计。不要害怕拆分或合并 API，或将其嵌入更通用的设置中。如果名称开始变得合适，你就走在了正确的轨道上。
  
• 命名非常重要。追求可读性、一致性和对称性。每个 API 都是一个小语言，人们必须学习如何阅读和书写它。如果你设计得当，代码会像散文一样流畅。
  
• 当不确定时，去除不须要的部门。如果有 API 设计的基本定理，那就是这一条。这适用于功能、类、方法和参数。API 的每个方面都应该尽大概简洁，但不能少于须要的部门。你可以随时添加，但不能删除。
  
• 最小化概念上的重量比类或方法的数量更重要。
  
• 保持 API 远离实现细节。它们会让用户狐疑，而且限定了演化的机动性。什么是实现细节并不总是显而易见的：小心过度规范。
  
• 最小化可变性。不可变对象简朴、线程安全而且可以自由共享。
  
• 文档很重要。无论 API 多么优秀，没有良好的文档，它都不会被广泛使用。文档应该覆盖每个导出的 API 元素：每个类、方法、字段和参数。
  
• 考虑 API 设计决议的性能后果，但不要为了性能而扭曲 API。幸运的是，好的 API 通常也能够带来高效的实现。
  
• API 必须与平台调和共处，所以要遵循常规。险些总是错误的做法是将一个平台的 API 直接“翻译”到另一个平台。
  
• 最小化访问权限；不确定时将其设为私有。这简化了 API，并淘汰了耦合。
  
• 只有当你能断言子类的每个实例都是真正的父类实例时，才应该使用子类化。暴露的类不应仅仅为了重用实今世码而子类化。
  
• 设计并文档化继承，或者禁止继承。这个文档情势是自用模式：类中的方法如何相互使用。如果没有这种文档，安全的子类化是不大概的。
  
• 不要让客户端做任何库本可以做的事。违反这一规则会导致客户端中大量重复的代码，增加了堕落的时机和难度。
  
• 遵循最小惊讶原则。每个方法应该做出它最不让人惊讶的事情，给定它的名称。如果一个方法没有做用户期望的事情，就会引发 bug。
  
• 快速失败。陈诉错误的时机越早，造成的陵犯越小。编译时失败是最佳的。如果必须在运行时失败，只管早做失败处理。
  
• 为所有字符串情势的数据提供编程访问。否则，程序员就不得不手动解析字符串，这很痛苦。而且，字符串情势终极会变成事实上的 API。
  
• 谨慎使用方法重载。如果两个方法的举动有差异，最好给它们差别的名称。
  
• 为任务选择合适的数据类型。比方，不要使用字符串，如果有更合适的类型。
  
• 在方法中保持一致的参数顺序。否则，程序员大概会搞错顺序。
  
• 避免长参数列表，尤其是那些有多个一连相同类型参数的列表。
  
• 避免返回值要求特殊处理。客户端会忘记编写特殊处理代码，导致 bug。比方，返回零长度的数组或集合，而不是 null。
  
• 只有在出现异常情况时才抛出异常。否则，客户端会强迫用异常来处理正常的流程，导致程序难以阅读、易堕落或性能较差。
  
• 抛出未查抄的异常，除非客户端能合理地从失败中恢复。
  
• API 设计是一门艺术，而不是科学。追求美感，并相信你的直觉。不要死板地遵循上述启示，但偶尔合理地违反它们。
  

通过这些设计原则，你将能够更好地明白和设计高质量、易用、可维护的 API，为久远的开辟打下坚实的基础。

本文由博客一文多发平台 OpenWrite 发布！

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。