每当我需要用 Java 设计 API 时，我通常会从打开 IDE 并创建包、类和接口开始。方法实现都是虚拟的，但 javadocs 很详细。
这是处理事情的最佳方式吗？我开始觉得应该首先编写 API 文档——甚至在编写第一个 .java 文件之前。这有几个优点：
有没有其他人同意这个观点？如果是这样，您将如何开始 API 设计？
此外，是否有任何工具可以提供帮助？甚至可能是某种基于注释的工具，它生成文档，然后生成骨架源（有点像模型到代码生成器）？我遇到了Eclipse PDE API 工具——但这是特定于 Eclipse 插件项目的。我没有找到更通用的东西。
对于 API（以及 IMO 的许多类型的问题），自上而下的问题划分和分析方法是可行的方法。
然而（这只是我的 2c 基于我自己的个人经验，所以要持保留态度），专注于它的 Javadoc 部分是一件好事，但这仍然不够，而且不能可靠地做到起点。事实上，这是非常面向实现的。那么在此之前应该进行的设计、建模和推理（无论多么简短）发生了什么？
您必须进行某种建模来识别构成 API 的实体（名词、角色和动词）。而且无论一个人想要多么“敏捷”，如果没有清晰的问题陈述图（即使它只是一个 10K 英尺的视图），这些东西就无法原型化。
最好的起点是指定您尝试实现的内容，或者更准确地说，指定您的 API 尝试解决的问题类型。BDD 可能会有所帮助（更多内容如下）。也就是说，您的 API 将提供什么（数据元素），以及向谁执行什么操作（动词）以及在什么条件下（上下文）。这导致确定哪些实体提供这些东西以及在哪些角色下提供这些东西（接口，特别是与单个、明确的角色或功能的接口，而不是包罗万象的方法）。这导致分析它们是如何编排在一起的（继承、组合、委托等）
一旦你有了这些，你就可以开始做一些初步的Javadoc。然后，您可以开始着手实现这些接口、这些角色。接下来是更多 Javadoc（除了可能不属于 Javadoc 的其他文档，即教程、操作方法等）
您从用例和可验证的需求以及每件事应该单独或协作完成的行为描述开始您的实施。BDD 在这里会非常有帮助。
随着你的工作，你不断地重构，希望通过一些指标（圈复杂度和LCOM 的一些变体）。这两个告诉你应该在哪里重构。
API 的开发不应与应用程序的开发有本质上的不同。毕竟，API 是用户（碰巧有开发角色）的实用应用程序。
因此，您不应将 API 工程与一般软件密集型应用程序工程区别对待。使用相同的做法，根据你的需要调整它们（每个使用软件的人都应该这样做），你会做得很好。
很长一段时间以来，谷歌一直在 youtube 上上传其“Google Tech Talk”视频讲座系列。其中之一是长达一小时的讲座，题为“如何设计一个好的 API 及其重要性”。您可能还想检查一下。
一些可能对您有所帮助的链接：
Google Tech Talk 的“超越测试驱动开发：行为驱动开发”：http ://www.youtube.com/watch?v=XOkHh8zF33o
行为驱动开发：http ://behaviour-driven.org/
“实用 API 设计”一书的网站伴侣：http ://wiki.apidesign.org/wiki/Main_Page
回到基础——结构化设计#内聚和耦合：http ://en.wikipedia.org/wiki/Structured_Design#Structured_Design
首先定义接口是声明前置条件、后置条件和不变量的契约式编程风格。我发现它与测试驱动开发 (TDD) 结合得很好，因为您首先编写的不变量和后置条件是您的测试可以检查的行为。
顺便说一句，似乎 TDD 的行为驱动开发细化似乎是因为程序员没有习惯性地首先考虑接口。
至于我自己，我总是更喜欢从编写接口及其文档开始，然后才从实现开始。
过去我采用了另一种方法，从 UML 开始，然后使用自动代码生成。我遇到的最好的工具是Rational Rose，它不是免费的，但我确信有很多免费的插件和实用程序。Rational Rose 与我遇到的其他设计师相比的优势在于，您可以将设计“附加”到您的代码中，然后对代码或设计进行修改，而另一个会更新。
我直接使用原型进行编码。任何需要的接口很快就会出现在你面前，你可以将你的原型塑造成最终产品。如果可以的话，从任何将要使用您的 API 的人那里获得反馈。
没有接近 API 设计的“最佳方式”，做任何适合你的事情。领域知识也有很大的作用
我非常喜欢对界面进行编程。它在代码的实现者和用户之间形成了契约。我通常从系统的基本模型（UML 图等，具体取决于复杂性）开始，而不是直接研究代码。这不仅可以作为很好的文档，还可以直观地阐明系统结构。有了这个，编码部分就更容易完成了。这种设计文档还可以让您在 6 个月后重新使用系统或尝试修复错误时更容易理解系统：) 原型设计也有其优点，但要准备好扔掉它并重新开始。