第一次用 Java 创建 API
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/1975104/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Creating an API in Java for the first time
提问by Anto
I have been given the task to design a list of APIs to be used by a GUI that I have to develop, in order to communicate with an external application. Considering that the application has just been designed and I have its initial class diagram, should I:
我的任务是设计一个 API 列表，供我开发的 GUI 使用，以便与外部应用程序进行通信。考虑到刚刚设计了应用程序并且我有它的初始类图，我应该：
1- Just list the fields and methods from this application class diagram that will be needed by the GUI to communicate with the application
1- 只需从该应用程序类图中列出 GUI 与应用程序通信所需的字段和方法
or
或者
2- Create a list of completely new fields and methods needed by the GUI to communicate with the application which the application developer should create
2- 创建 GUI 与应用程序开发人员应创建的应用程序进行通信所需的全新字段和方法的列表
Thanks in advance!!!
提前致谢！！！
采纳答案by S.Lott
"Just list the fields and methods from this application class diagram that will be needed by the GUI to communicate with the application"
“只需从这个应用程序类图中列出 GUI 与应用程序通信所需的字段和方法”
This works really well.
这真的很好用。
After doing this, try to write documentation -- with detailed examples. If your documentation is hard to write, confusing or lame, then you need to fix the API's to add features.
完成此操作后，尝试编写文档 - 包含详细示例。如果您的文档难以编写、混乱或蹩脚，那么您需要修复 API 以添加功能。
Then show it to other people.
然后把它展示给其他人。
If people are confused or complain, then you may need to add additional features to the API.
如果人们感到困惑或抱怨，那么您可能需要向 API 添加其他功能。
Until people are actually confused or actually complain, don't do anything more than the minimum.
在人们真正感到困惑或真正抱怨之前，不要做任何超过最低限度的事情。
回答by jqno
I'd make the API (semi-)independent from the implementation of the GUI, because later you might want to create a different interface to the same application, or simply change the GUI, and then you're stuck with whatever you created for the first pass of your first GUI.
我会让 API（半）独立于 GUI 的实现，因为稍后您可能想要为同一个应用程序创建不同的界面，或者只是更改 GUI，然后您会被困在为您创建的任何内容中第一个 GUI 的第一遍。
Also, I highly recommend taking a look at Josh Bloch's talk about API design. Bloch is the guy who designed the Java Collections API.
此外，我强烈建议您阅读Josh Bloch 关于 API 设计的演讲。Bloch 是设计 Java Collections API 的人。
回答by akuhn
I would specify an interface. This decouples GUI and applications.
我会指定一个接口。这将 GUI 和应用程序解耦。
The GUI will only use the interface (except for one call to a factory method that return a concrete object) and the API will implement the interface. Like that none of the class names of the application is known to the GUI. This leads to a stable design that is the most fit for future evolution.
GUI 将仅使用该接口（除了对返回具体对象的工厂方法的一次调用），API 将实现该接口。像这样，GUI 不知道应用程序的任何类名。这导致了最适合未来发展的稳定设计。
Also, the interface serves as a nice documentation of the complete API.
此外，该界面还可以作为完整 API 的一个很好的文档。
回答by delfuego
One of the best guides to API design I've read is "The Little Manual of API Design" (PDF), which has some great, platform-neutral guidance as to how to create an API for an application or service. Some of the most important guidance it gives is:
我读过的最好的 API 设计指南之一是“ API 设计小手册”（PDF），它提供了一些关于如何为应用程序或服务创建 API 的出色的、平台中立的指南。它提供的一些最重要的指导是：
- create use cases before you start coding the API itself;
- get peer review of the API design before you code it;
- write examples against the API to test its robustness.
- 在开始编写 API 本身之前创建用例；
- 在编写 API 设计之前获得同行评审；
- 针对 API 编写示例以测试其健壮性。
The first tip is the best, IMHO; it prevents you from coding an API that provides the world when all your use cases require is a small portion of that world. It also forces you to think out how it'll be used, and make design decisions based on those uses rather than in the abstract.
第一个提示是最好的，恕我直言；当您的所有用例需要的只是世界的一小部分时，它会阻止您编写提供世界的 API。它还迫使您考虑如何使用它，并根据这些用途而不是抽象地做出设计决策。
