API Design
在这一简短但重要的部分中，您将学到一些简单的准则，这些准则将使您的 API 与遵循这些准则的所有其他 API 无缝地互操作。本质上，这些规则定义了在收藏界要成为一个好的“公民”所需要的条件。
Parameters
如果您的 API 包含需要 Importing 集合的方法，那么将相关参数类型声明为集合interface类型之一至关重要。 **绝对不要使用implementation类型，因为它违反了基于interface的 Collections Framework 的 Object，该 Object 是允许在不考虑实现细节的情况下操作 collection。
此外，您应始终使用有意义的最少特定类型。例如，如果Collection会不需要List或Set。这并不是说您永远不需要 ImportingList或Set。如果方法取决于这些interface之一的属性，则这样做是正确的。例如，Java 平台提供的许多算法在 Importing 上都需要List，因为它们取决于列表是有序的。通常，Importing 上使用的最佳类型是最通用的：Collection和Map。
Caution:
切勿定义自己的临时collection类，并在 Importing 时要求此类的对象。这样，您将丢失所有Java Collections Framework 提供的好处。
Return Values
与使用 Importing 参数相比，使用返回值可以提供更大的灵 Active。可以返回实现或扩展集合interface之一的任何类型的对象。它可以是interface之一，也可以是扩展或实现这些interface之一的专用类型。
例如，可以想象一个名为ImageList的图像处理程序包，该程序包返回实现List的新类的对象。除了List操作之外，ImageList还可以支持似乎需要的任何特定于应用程序的操作。例如，它可能提供indexImage操作，该操作返回的图像包含ImageList中每个图形的缩略图。重要的是要注意，即使 API 在输出中提供ImageList实例，它也应在 Importing 中接受任意的Collection(或List)实例。
从某种意义上说，返回值应该具有与 Importing 参数相反的行为：最好返回最具体的适用集合interface，而不是最通用的interface。例如，如果您确定将始终返回SortedMap，则应为相关方法提供SortedMap而不是Map的返回类型。 SortedMap实例的构建比普通Map实例更耗时，并且功能也更强大。鉴于您的模块已经投入时间来构建SortedMap，因此使用户能够使用其增强的功能非常有意义。此外，用户将能够将返回的对象传递给需要SortedMap的方法以及接受任何Map的方法。
Legacy APIs
当前，有许多 API 定义了它们自己的临时集合类型。尽管这很不幸，但这确实是事实，因为 Java 平台的前两个主要版本中没有 Collections Framework。假设您拥有这些 API 之一；这是您可以做的。
如果可能，请对旧式收集类型进行改造以实现标准收集interface之一。这样，您返回的所有集合将可以与其他基于集合的 API 顺利地互操作。如果这是不可能的(例如，由于一个或多个预先存在的类型签名与标准集合interface冲突)，请定义一个* adapter 类*，该类包装您的一个旧集合对象，使其能够用作标准集合。 (Adapter类是custom implementation的示例。)
如果可能，请使用遵循 Importing 准则的新调用对 API 进行改进，以接受标准集合interface的对象。这样的调用可以与采用旧式收集类型的调用共存。如果这不可能，请为您的遗留类型提供一个构造函数或静态工厂，该构造函数或静态工厂将使用标准interface之一的对象并返回包含相同元素(或 Map)的遗留集合。这两种方法均允许用户将任意集合传递到您的 API 中。
