第一次在 Java 中创建 API答案

【问题标题】：Creating an API in Java for the first time第一次在 Java 中创建 API
【发布时间】：2018-10-12 19:53:10
【问题描述】：

我的任务是设计一个 API 列表，供我必须开发的 GUI 使用，以便与外部应用程序通信。考虑到应用程序刚刚设计好并且我有它的初始类图，我应该：

1- 仅列出此应用程序类图中 GUI 与应用程序通信所需的字段和方法

或

2- 创建 GUI 所需的全新字段和方法列表，以便与应用程序开发人员应创建的应用程序进行通信

提前致谢！！！

【问题讨论】：

标签： java api

【解决方案1】：

我读过的最好的 API 设计指南之一是“The Little Manual of API Design”(PDF)，其中有一些很棒的平台中立指南，说明如何为应用程序或服务。它提供的一些最重要的指导是：

第一个提示是最好的，恕我直言；当您的所有用例所需的只是世界的一小部分时，它会阻止您编写提供世界的 API。它还迫使您思考如何使用它，并根据这些用途而不是抽象地做出设计决策。

【讨论】：

【解决方案2】：

“只需列出此应用程序类图中的字段和方法，GUI 与应用程序通信所需的字段和方法”

这真的很好用。

完成此操作后，尝试编写文档——带有详细示例。如果您的文档难以编写、令人困惑或蹩脚，那么您需要修复 API 以添加功能。

然后展示给其他人。

如果人们感到困惑或抱怨，那么您可能需要向 API 添加其他功能。

在人们真正感到困惑或真正抱怨之前，不要做任何超过最低限度的事情。

【讨论】：

我认为我不同意做最少的事情，除非你想成为在工厂工作的机器人。我的建议是首先尝试了解用例和功能需求（如果已经制定）。接下来考虑这些，并尝试找出任何可能的错误或缺失的需求，并询问相关的利益相关者。然后查看现有的类图并应用相同的评估过程。检查项目的分阶段可能也是一个好主意：您现在需要构建什么，以及接下来的里程碑中会出现什么？
@Adriaan Koster：如果您有编写 API 的经验，那是一个好方法。对于您的第一个 API，这是过度设计和创建极其复杂的东西的秘诀。通常，初始的方法和属性集包括一些尴尬的特性。修复这些就足以开始了。

【解决方案3】：

我会指定一个接口。这将 GUI 和应用程序解耦。

GUI 将只使用接口（除了对返回具体对象的工厂方法的一次调用），API 将实现接口。就像 GUI 不知道应用程序的类名一样。这导致了最适合未来发展的稳定设计。

此外，该接口还可以作为完整 API 的一个很好的文档。

【讨论】：

【解决方案4】：

我会让 API（半）独立于 GUI 的实现，因为稍后您可能想要为同一个应用程序创建不同的界面，或者只是更改 GUI，然后您就会遇到任何问题你为你的第一个 GUI 的第一遍创建。

另外，我强烈建议您查看Josh Bloch's talk about API design。 Bloch 是设计 Java Collections API 的人。

【讨论】：