API 什么时候会被过度设计？
我鄙视使用过度设计的 API，因为它们不会让简单的事情变得简单。 尽管如此，我正在为一个开源库设计一个 API，我开始觉得我陷入了过度设计的陷阱。 我真的不能确定，因为当然，我写了这个该死的东西，所以它的工作原理对我来说比其他任何人都更明显。 从开发人员的角度来看，您的 API 可能被过度设计的警告信号有哪些？
I despise working with overengineered APIs that don't make simple things simple. Nonetheless, I'm working on designing an API for an open-source library and I'm starting to feel that I'm falling into the overengineering trap. I really can't tell for sure because, of course, I wrote the darn thing, so how it works is more obvious to me than anyone else. What are some warning signs from a developer's perspective that your API might be overengineered?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（11）
当常见 api 调用的堆栈跟踪需要您滚动屏幕才能查看整个内容时。
when the stack trace for a common api call requires you to scroll the screen to see the entire thing.
在查看文档和示例时，讨论 API 本身的用语百分比与讨论其在可信用例中的应用的用语百分比相比较。
When reviewing the documentation and examples, the percentage of verbiage discussing the API in relation to itself cmpared to the percentage of verbiage discussing its application to credible use cases.
正如 S.Lott 所说，用例。 他们将确定您的 API 到底应该用于做什么。 如果您设计 API 是为了完成一个非常明确、具体的目标 - 功能一致 -您很可能最终会得到一个既易于使用又易于理解的 API 或 API 中的组件。
设计 API 应该像设计用户界面一样。 大多数 UI 概念都可以被 API 包含，例如 KISS 原则甚至 Kaizen。
我会链接到这些 UI 概念，但我是新用户，所以他们不允许我发布超过 1 个超链接。 很好的例子：StackOverflow，在发布之前请告诉我们;)。
As S.Lott said, use-cases. They will determine what exactly your API should be directed towards doing. If you design your API to complete a very clear, specific goal - functionally coherent - you are most likely going to end up with an API or component in your API that is both easy to use and understand.
Designing an API should be like designing a user interface. Most all concepts of UI can be embraced by an API, for example, the KISS principle or even Kaizen.
I'd link to those UI concepts, but I'm a new user so they won't let me post more than 1 hyperlink. Good example there: StackOverflow, let us know before we post ;).
立即想到两个（相关的）问题要问自己：
更难回答，这本身并不是过度设计的迹象，但绝对是 API 还没有那么简单的迹象：
Two (related) questions to ask yourself come to mind immediately:
More difficult to answer, and not a sign of overengineering in itself, but definitely a sign the API isn't as simple as it could be yet:
当它如此聪明以至于没有人能够理解它时。
When it's so clever that nobody else can understand it.
当您拥有一个包含大量函数的大型 API 时，请开始担心，经过仔细检查，这些函数实际上是由更简单的操作组成的。 组合机制与原语比例较高的 API 通常是一个好的设计。
（API 设计与语言设计非常相似，在这里我本质上拥护Scheme 哲学——不要将更多例程堆积到 API 中，而是对其进行简化并包含组合机制，从而不需要额外的例程。）
Start to worry when you have a large API with a lot of functions which, on closer inspection, turn out to be compositions of simpler operations. An API with a high ratio of composition mechanisms to primitives is usually a good design.
(API design is very similar to language design, and here I am essentially espousing the Scheme philosophy—instead of piling more routines into the API, simplify it and include composition mechanisms that render the additional routines unnecessary.)
我发现一个非常有用并且在过去对我有帮助的技巧是在编码之前、期间和之后编写文档。
在设计供其他人使用的 API 时，我通常会在编写代码之前记录设计。 如果我过度设计设计，设计规范通常会充满冲突和废话。
在编码过程中，我通常会删除类定义和函数体，并开始为它们编写 doxygen 注释。 在评论中，我将提供用例、示例代码和接口的假设。 在这个阶段，在编写太多实际代码之前，类接口通常会经过多次重新设计。 当示例代码很难编写并且我很难解释界面时，我知道我已经过度工程化了。 当您尝试向人们解释如何使用您的 API 时，许多糟糕的设计思想就会暴露出来并被消除。
编码后，我将注释中的示例代码替换为从单元测试中复制的真实编译和测试代码，并进一步记录界面的行为。 过度工程的另一个迹象是，我的单元测试无法跟上界面的变化，因为有太多的移动部件和太多的方法来做同样的事情，并且单元测试以指数比例增长。
One trick I found very useful and it has helped me in the past is write doc before, during, and after you code.
When designing an API to be used by other people I usually document the design before writing code. If I was over engineering the design, the design spec usually full of conflicts and nonsense.
During coding, I usually stub out the class definition and function body and start writing doxygen comments for them. In the comments I'll have use case, sample code, and assumptions of the interfaces. During this phase, before too much real code is written, the class interface usually gone through redesign multiple times. I know I was over engineering when the sample code is hard to write and I have a hard time explaining the interface. A lot of the bad design ideas are exposed and eliminated when you try to explain to people how to use your API.
After coding, I replace the sample code in the comments with real compiled and tested code copied from my unit tests and further document the behavior of the interface. Another sign of over engineering is when my unit tests cannot keep up with the interface change because there are too many moving parts and too many ways to do the same thing and unit tests growth at an exponential proportion.
“从开发人员的角度来看，您的 API 可能被过度设计了，有哪些警告信号？”
没有用例。
如果您无法运行简单的“执行此操作”场景，那么您就没有在考虑特定用例的情况下设计有用的 API。
您的文档应该是那些用例。
不直接解决用例的功能可能是过度设计的。
"What are some warning signs from a developer's perspective that your API might be overengineered?"
No use cases.
If you can't run through simple "to do this" scenarios, you're not designing a useful API with specific use cases in mind.
Your documentation should be those use cases.
Features that don't directly address the use cases are probably over-engineering.
您应该查看 Google 技术讲座 如何设计良好的 API 及其重要性约书亚·布洛赫（Joshua Bloch）……他涵盖了很多此类内容。
You should check out the Google Tech Talk How To Design A Good API and Why it Matters by Joshua Bloch ... he covers a lot of this stuff.
使用API时是：
(1) 比仅使用底层技术更迟钝、更复杂、效率更低且更不可预测，并且
(2) 在安全性、可扩展性或跨平台自由度方面没有提供显着的优势。
When using the API is:
(1) more obtuse, more complex, less efficient, and less predictable than just using the underlying technology, AND
(2) does not offer a significant advantage for safety, scalability, or cross-platform freedom.
根据我的经验，您可以看出整个项目何时会拖延数月，等待 API 完成。
In my experience you can tell when the whole project is held up for months, waiting on the API to be finished.