java - 我应该在 Java 中向我的库 API 添加帮助器/实用程序方法吗？

Question

我正在用 Java 开发一个小型库，它可以从压缩图像数据源(例如 PNG 文件)读取图像并对其进行解码，返回一个 Image 对象。 Image 类具有各种名为 Image.createImage(...) 的函数，可以根据指定的参数创建图像。

我已经在库 API 中添加了几个公共(public) Image.createImage(...) 方法，每个数据源类型一个:Image.createImage(Path) , Image.createImage(InputStream), Image.createImage(String), Image.createImage(byte[]), ..., 到让用户无需键入大量代码即可轻松地从各种数据源获取Image。

然而，这意味着每个方法的 Javadoc 都是重复的，并且 API 变得更大，因此更难学习，即使辅助方法本身非常简单(例如 Image.createImage(byte[]) 只是 return Image.createImage(new ByteArrayInputStream(array));)，所以我决定重新设计我的库 API 设计。

我想到了三种不同的方法来重新设计我的 Image API:

• 仅提供采用输入流的单一图像解码方法，例如Image.createImage(InputStream)，并让用户自己从他的数据源创建一个输入流(并且可能在 Javadoc 中包含一些示例代码，例如“要解码存储在文件中的图像，您可以使用 Files.newInputStream(Paths.get(...)) ...")
• 为每种数据源类型提供一个(辅助)方法，例如Image.createImage(ByteBuffer), Image.createImage(Path), ...每个方法都有Javadoc essentially duplicated (这实际上是当前的情况)
• 设计一个 DataSource 类，它可以从一种数据源类型(例如 new DataSource(Path), ...)构建，并有一个图像采用 DataSource 对象的解码方法，例如Image.createImage(数据源)

我想知道哪种设计最好。

• 我认为第一个很好，因为它使库非常小/轻，但缺点是用户必须自己编写“胶水代码”(或从 Javadoc 示例中复制)，因此必须知道如何从路径或资源字符串中获取 InputStream。我很想选择这种设计。
• 我认为第二个不太好，因为 Javadoc 变得非常“冗长”/庞大，可能不值得向 API 添加单行方法。
• 我认为第三个可能是最糟糕的一个，因为如果用户必须阅读两个 Image 的 Javadoc，那么获取 Image 就变得太复杂了> 和 DataSource，然后找到如何创建 DataSource，我个人也觉得它非常“重量级”(让我想起拥有大量类和包，而我喜欢让我的项目小而简洁)。

如果您要使用这个库，您更喜欢哪种设计？第一个设计是最好的吗？

Answer 1

根据约书亚·布洛赫 (Joshua Bloch) 的说法，

API Should Be As Small As Possible But No Smaller

• When in doubt leave it out ─ Functionality, classes, methods, parameters, etc. ─ You can always add, but you can never remove

通过此链接查看第 14 页

http://www.cs.bc.edu/~muller/teaching/cs102/s06/lib/pdf/api-design