api - 如何定义 API 的好坏？

Question

就目前情况而言，这个问题不太适合我们的问答形式。我们希望答案得到事实、引用资料或专业知识的支持，但这个问题可能会引发辩论、争论、民意调查或扩展讨论。如果您觉得这个问题可以改进并可能重新开放， visit the help center以获得指导。

已关闭 11 年前。

背景:

我正在大学上一门名为“软件约束”的类(class)。在第一个类中，我们学习了如何构建良好的 API。

我们得到的一个非常糟糕的 API 函数的好例子是套接字 public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds);在 C# 中。该函数接收 3 个套接字列表，并销毁它们，使得用户必须克隆所有套接字，然后才能将它们输入 Select() 。它还具有一个整数超时(以微秒为单位)，用于设置服务器可以等待套接字的最长时间。其限制是 +/-35 分钟(因为它是一个 int)。

<小时/>

问题:

1. 如何将 API 定义为“坏”？
2. 你如何定义API“好”吗？

<小时/>

需要考虑的要点:

• 函数名称很难记住。
• 难以理解的函数参数。
• 糟糕的文档。
• 一切都如此相互关联，如果您需要更改 1 行代码，您实际上需要更改其他地方的数百行代码。
• 破坏其参数的函数。
• 由于“隐藏”的复杂性，可扩展性较差。
• 用户/开发人员需要围绕 API 构建包装器，以便可以使用它。

Answer 1

在 API 设计中，我一直发现这个主题演讲非常有帮助:
How to Design a Good API and Why it Matters - by Joshua Bloch

这是摘录，我建议阅读全文/观看视频。

II. General Principles

• API Should Do One Thing and Do it Well
  
• API Should Be As Small As Possible But No Smaller
  
• Implementation Should Not Impact API
  
• Minimize Accessibility of Everything
  
• Names Matter–API is a Little Language
  
• Documentation Matters
  
• Document Religiously
  
• Consider Performance Consequences of API Design Decisions
  
• Effects of API Design Decisions on Performance are Real and Permanent
  
• API Must Coexist Peacefully with Platform

III. Class Design

• Minimize Mutability
  
• Subclass Only Where it Makes Sense
  
• Design and Document for Inheritance or Else Prohibit it

IV. Method Design

• Don't Make the Client Do Anything the Module Could Do
  
• Don't Violate the Principle of Least Astonishment
  
• Fail Fast - Report Errors as Soon as Possible After They Occur
  
• Provide Programmatic Access to All Data Available in String Form
  
• Overload With Care
  
• Use Appropriate Parameter and Return Types
  
• Use Consistent Parameter Ordering Across Methods
  
• Avoid Long Parameter Lists
  
• Avoid Return Values that Demand Exceptional Processing