如何使用私有Java类进行有效的API设计

Question

我正在编写我的第一个“API jar”，它将是开源库并由（可能）其他开发人员使用。 我已经阅读了Joshua Block关于有效API设计的论文 ，他谈到的一件事 - 我从来没有想到过 - 是他最小化访问和最大化信息隐藏的概念。 基本上，您只希望您的API开发人员能够访问他们将使用的Java对象，并且您不希望您的API开发人员能够访问您库中的任何“内脏”。

在我作为Java开发人员的几年中，我从来没有必要创建除了public之外的任何类。 此外，我从未使用过嵌套类。 所以我坐在这里想知道如何在我的Java API中实现这种“信息隐藏”最佳实践？ 我认为私有的，可能是嵌套的类是答案。 但从哪里开始？

• 每个.java源文件都需要至少一个public类来编译。 因此，对于我来说private （和非嵌套）类，我需要“将它与public类捆绑在一起。对我来说，这只有在public / private类密切相关时才有意义。但是，如果我有一个部分我的API只包含与任何其他public类比无关的private类（用于可访问性最小化目的）？
• 你什么时候嵌套private类，什么时候让它嵌套？ 或者只是一个偏好问题？

Answer 1

包私有的类（即没有任何可见性修饰符）只能由同一个包的类可见。 这是一种让API的其他几个类可见的方法，而不是外部世界。

嵌套的私有类对于创建非公共类也很有用，它们的范围甚至更窄：它们只能由封闭类可见。

我建议看一下Guava的优秀API设计源代码 。 你会看到各种技术来隐藏内部的内部。

Answer 2

就个人而言，我不相信private 。 在可行的情况下，我使用protected以允许OO设计的一些主要好处。

基本上，“信息隐藏”原则并不是一个指南。 但是，在实践中，不应该在所有情况下盲目地遵循它。 - 对于纯粹的原则，正如其他人所建议的那样，你需要将一组接口定义为公共接口，并使用包私有类，工厂方法等隐藏所有其余的lib。 鉴于Java的包 - 私有可见性存在一些问题，在许多情况下（在您的lib中的类将希望跨包合作 - ）这有点无用，这反过来似乎阻止了这种方法。

此外，API总是至少有两种类型的用户：基本用户，谁将使用您提供的对象和方法，以及具有复杂需求的用户，他们希望通过继承来修改API的行为（至少） ，很多'隐藏'的东西会成功阻止。

不要害羞地把这些东西public ，这些东西可能是有意义的， protected那些并非真正需要public东西，并且只有那些可能造成伤害的private东西如果直接被除了直接相关的代码之外的任何东西访问。

另一个注意事项：隐藏原则的主要目的是简化其他人对代码的使用，并暗示和鼓励正确使用代码。 但请记住， 文档是实现这一目标的另一个重要手段; 无论如何，图书馆都需要文档。 - 如果您有100个公共方法，并且您的文档说明用例需要10个这样的用户，那么您的lib的用户可能会与他一样好，如果他只能看到那10个那么。

Answer 3

我确实相信私人。 我一直在研究框架类，Joshua正确地告诉你，你应该尽可能地隐藏它。 其背后的原因是您将暴露的所有内容都将被使用。 一旦使用它，您无法在不破坏客户端代码的情况下进行更改。 所有非私人的东西都可以从客户那里获得！ 基本上你应该使用包私有类，只允许在有用的情况下继承，并且只使那些公开的类是绝对必要的，以使你的lib有用。 在扩展功能时，“ 界面隔离原则 ”是您的朋友。