39. 注解优于命名模式

发表于 2022-10-29 更新于 2024-06-07

39. 注解优于命名模式

过去，通常使用命名模式（naming patterns）来指示某些程序元素需要通过工具或框架进行特殊处理。例如，在第 4 版之前，JUnit 测试框架要求其用户通过以 test[Beck04] 开始名称来指定测试方法。这种技术是有效的，但它有几个很大的缺点。首先，拼写错误导致失败，但不会提示。例如，假设意外地命名了测试方法 tsetSafetyOverride 而不是 testSafetyOverride。 JUnit 3 不会报错，但它也不会执行测试，导致错误的安全感。

命名模式的第二个缺点是无法确保它们仅用于适当的程序元素。例如，假设调用了 TestSafetyMechanisms 类，希望 JUnit 3 能够自动测试其所有方法，而不管它们的名称如何。同样，JUnit 3 也不会出错，但它也不会执行测试。

命名模式的第三个缺点是它们没有提供将参数值与程序元素相关联的好的方法。例如，假设想支持只有在抛出特定异常时才能成功的测试类别。异常类型基本上是测试的一个参数。你可以使用一些精心设计的命名模式将异常类型名称编码到测试方法名称中，但这会变得丑陋和脆弱（详见第 62 条）。编译器无法知道要检查应该命名为异常的字符串是否确实存在。如果命名的类不存在或者不是异常，那么直到尝试运行测试时才会发现。

注解[JLS，9.7] 很好地解决了所有这些问题，JUnit 从第 4 版开始采用它们。在这个项目中，我们将编写我们自己的测试框架来显示注解的工作方式。假设你想定义一个注解类型来指定自动运行的简单测试，并且如果它们抛出一个异常就会失败。以下是名为 Test 的这种注解类型的定义：

// Marker annotation type declaration
import java.lang.annotation.*;

/**
 * Indicates that the annotated method is a test method.
 * Use only on parameterless static methods.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Test {

}

Test 注解类型的声明本身使用 Retention 和 Target 注解进行标记。注解类型声明上的这种注解称为元注解。 @Retention（RetentionPolicy.RUNTIME）元注解指示 Test 注解应该在运行时保留。没有它，测试工具就不会看到 Test 注解。@Target.get（ElementType.METHOD）元注解表明 Test 注解只对方法声明合法：它不能应用于类声明，属性声明或其他程序元素。

在 Test 注解声明之前的注释说：“仅在无参静态方法中使用”。如果编译器可以强制执行此操作是最好的，但它不能，除非编写注解处理器来执行此操作。有关此主题的更多信息，请参阅 javax.annotation.processing 文档。在缺少这种注解处理器的情况下，如果将 Test 注解放在实例方法声明或带有一个或多个参数的方法上，那么测试程序仍然会编译，并将其留给测试工具在运行时来处理这个问题。

以下是 Test 注解在实践中的应用。它被称为标记注解，因为它没有参数，只是“标记”注解元素。如果程序员错拼 Test 或将 Test 注解应用于程序元素而不是方法声明，则该程序将无法编译。

// Program containing marker annotations
public class Sample {

    @Test
    public static void m1() { }  // Test should pass

    public static void m2() { }

    @Test
    public static void m3() {     // Test should fail
        throw new RuntimeException("Boom");
    }

    public static void m4() { }

    @Test
    public void m5() { } // INVALID USE: nonstatic method

    public static void m6() { }

    @Test
    public static void m7() {    // Test should fail
        throw new RuntimeException("Crash");
    }

    public static void m8() { }
}

Sample 类有七个静态方法，其中四个被标注为 Test。其中两个，m3 和 m7 引发异常，两个 m1 和 m5 不引发异常。但是没有引发异常的注解方法之一是实例方法，因此它不是注释的有效用法。总之，Sample 包含四个测试：一个会通过，两个会失败，一个是无效的。未使用 Test 注解标注的四种方法将被测试工具忽略。

Test 注解对 Sample 类的语义没有直接影响。他们只提供信息供相关程序使用。更一般地说，注解不会改变注解代码的语义，但可以通过诸如这个简单的测试运行器等工具对其进行特殊处理：

// Program to process marker annotations
import java.lang.reflect.*;

public class RunTests {
    public static void main(String[] args) throws Exception {
        int tests = 0;
        int passed = 0;
        Class<?> testClass = Class.forName(args[0]);
        for (Method m : testClass.getDeclaredMethods()) {
            if (m.isAnnotationPresent(Test.class)) {
                tests++;
                try {
                    m.invoke(null);
                    passed++;
                } catch (InvocationTargetException wrappedExc) {
                    Throwable exc = wrappedExc.getCause();
                    System.out.println(m + " failed: " + exc);
                } catch (Exception exc) {
                    System.out.println("Invalid @Test: " + m);
                }
            }
        }
        System.out.printf("Passed: %d, Failed: %d%n",
                          passed, tests - passed);
    }
}

测试运行器工具在命令行上接受完全限定的类名，并通过调用 Method.invoke 来反射地运行所有类标记有 Test 注解的方法。 isAnnotationPresent 方法告诉工具要运行哪些方法。如果测试方法引发异常，则反射机制将其封装在 InvocationTargetException 中。该工具捕获此异常并打印包含由 test 方法抛出的原始异常的故障报告，该方法是使用 getCause 方法从 InvocationTargetException 中提取的。

如果尝试通过反射调用测试方法会抛出除 InvocationTargetException 之外的任何异常，则表示编译时未捕获到没有使用的 Test 注解。这些用法包括注解实例方法，具有一个或多个参数的方法或不可访问的方法。测试运行器中的第二个 catch 块会捕获这些 Test 使用错误并显示相应的错误消息。这是在 RunTests 在 Sample 上运行时打印的输出：

public static void Sample.m3() failed: RuntimeException: Boom
Invalid @Test: public void Sample.m5()
public static void Sample.m7() failed: RuntimeException: Crash
Passed: 1, Failed: 3

现在，让我们添加对仅在抛出特定异常时才成功的测试的支持。我们需要为此添加一个新的注解类型：

// Annotation type with a parameter
import java.lang.annotation.*;

/**
 * Indicates that the annotated method is a test method that
 * must throw the designated exception to succeed.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
    Class<? extends Throwable> value();
}

此注解的参数类型是 Class<? extends Throwable>。毫无疑问，这种通配符是拗口的。在英文中，它表示“扩展 Throwable 的某个类的 Class 对象”，它允许注解的用户指定任何异常（或错误）类型。这个用法是一个限定类型标记的例子（详见第 33 条）。以下是注解在实践中的例子。请注意，类名字被用作注解参数值：

// Program containing annotations with a parameter
public class Sample2 {

    @ExceptionTest(ArithmeticException.class)
    public static void m1() {  // Test should pass
        int i = 0;
        i = i / i;
    }

    @ExceptionTest(ArithmeticException.class)
    public static void m2() {  // Should fail (wrong exception)
        int[] a = new int[0];
        int i = a[1];
    }

    @ExceptionTest(ArithmeticException.class)
    public static void m3() { }  // Should fail (no exception)
}

现在让我们修改测试运行器工具来处理新的注解。这样将包括将以下代码添加到 main 方法中：

if (m.isAnnotationPresent(ExceptionTest.class)) {
    tests++;
    try {
        m.invoke(null);
        System.out.printf("Test %s failed: no exception%n", m);
    } catch (InvocationTargetException wrappedEx) {
        Throwable exc = wrappedEx.getCause();
        Class<? extends Throwable> excType =
            m.getAnnotation(ExceptionTest.class).value();
        if (excType.isInstance(exc)) {
            passed++;
        } else {
            System.out.printf(
                "Test %s failed: expected %s, got %s%n",
                m, excType.getName(), exc);
        }
    } catch (Exception exc) {
        System.out.println("Invalid @Test: " + m);
    }
}

此代码与我们用于处理 Test 注解的代码类似，只有一个例外：此代码提取注解参数的值并使用它来检查测试引发的异常是否属于正确的类型。没有明确的转换，因此没有 ClassCastException 的危险。测试程序编译的事实保证其注解参数代表有效的异常类型，但有一点需要注意：如果注解参数在编译时有效，但代表指定异常类型的类文件在运行时不再存在，则测试运行器将抛出 TypeNotPresentException 异常。

将我们的异常测试示例进一步推进，可以设想一个测试，如果它抛出几个指定的异常中的任何一个，就会通过测试。注解机制有一个便于支持这种用法的工具。假设我们将 ExceptionTest 注解的参数类型更改为 Class 对象数组：

// Annotation type with an array parameter
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
    Class<? extends Exception>[] value();
}

注解中数组参数的语法很灵活。它针对单元素数组进行了优化。所有以前的 ExceptionTest 注解仍然适用于 ExceptionTest 的新数组参数版本，并且会生成单元素数组。要指定一个多元素数组，请使用花括号将这些元素括起来，并用逗号分隔它们：

// Code containing an annotation with an array parameter
@ExceptionTest({ IndexOutOfBoundsException.class,
                 NullPointerException.class })
public static void doublyBad() {
    List<String> list = new ArrayList<>();
    // The spec permits this method to throw either
    // IndexOutOfBoundsException or NullPointerException
    list.addAll(5, null);
}

修改测试运行器工具以处理新版本的 ExceptionTest 是相当简单的。此代码替换原始版本：

if (m.isAnnotationPresent(ExceptionTest.class)) {
    tests++;
    try {
        m.invoke(null);
        System.out.printf("Test %s failed: no exception%n", m);
    } catch (Throwable wrappedExc) {
        Throwable exc = wrappedExc.getCause();
        int oldPassed = passed;
        Class<? extends Exception>[] excTypes =
            m.getAnnotation(ExceptionTest.class).value();
        for (Class<? extends Exception> excType : excTypes) {
            if (excType.isInstance(exc)) {
                passed++;
                break;
            }
        }
        if (passed == oldPassed)
            System.out.printf("Test %s failed: %s %n", m, exc);
    }
}

从 Java 8 开始，还有另一种方法来执行多值注解。可以使用 @Repeatable 元注解来标示注解的声明，而不用使用数组参数声明注解类型，以指示注解可以重复应用于单个元素。该元注解采用单个参数，该参数是包含注解类型的类对象，其唯一参数是注解类型[JLS，9.6.3] 的数组。如果我们使用 ExceptionTest 注解采用这种方法，下面是注解的声明。请注意，包含注解类型必须使用适当的保留策略和目标进行注解，否则声明将无法编译：

// Repeatable annotation type
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Repeatable(ExceptionTestContainer.class)
public @interface ExceptionTest {
    Class<? extends Exception> value();
}

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTestContainer {
    ExceptionTest[] value();
}

下面是我们的 doublyBad 测试用一个重复的注解代替基于数组值注解的方式:

// Code containing a repeated annotation
@ExceptionTest(IndexOutOfBoundsException.class)
@ExceptionTest(NullPointerException.class)
public static void doublyBad() { ... }

处理可重复的注解需要注意。重复注解会生成包含注解类型的合成注解。 getAnnotationsByType 方法掩盖了这一事实，可用于访问可重复注解类型和非重复注解。但 isAnnotationPresent 明确指出重复注解不是注解类型，而是包含注解类型。如果某个元素具有某种类型的重复注解，并且使用 isAnnotationPresent 方法检查元素是否具有该类型的注释，则会发现它没有。使用此方法检查注解类型的存在会因此导致程序默默忽略重复的注解。同样，使用此方法检查包含的注解类型将导致程序默默忽略不重复的注释。要使用 isAnnotationPresent 检测重复和非重复的注解，需要检查注解类型及其包含的注解类型。以下是 RunTests 程序的相关部分在修改为使用 ExceptionTest 注解的可重复版本时的例子：

// Processing repeatable annotations
if (m.isAnnotationPresent(ExceptionTest.class)
    || m.isAnnotationPresent(ExceptionTestContainer.class)) {
    tests++;
    try {
        m.invoke(null);
        System.out.printf("Test %s failed: no exception%n", m);
    } catch (Throwable wrappedExc) {
        Throwable exc = wrappedExc.getCause();
        int oldPassed = passed;
        ExceptionTest[] excTests =
                m.getAnnotationsByType(ExceptionTest.class);
        for (ExceptionTest excTest : excTests) {
            if (excTest.value().isInstance(exc)) {
                passed++;
                break;
            }
        }
        if (passed == oldPassed)
            System.out.printf("Test %s failed: %s %n", m, exc);
    }
}

添加了可重复的注解以提高源代码的可读性，从逻辑上将相同注解类型的多个实例应用于给定程序元素。如果觉得它们增强了源代码的可读性，请使用它们，但请记住，在声明和处理可重复注解时存在更多的样板，并且处理可重复的注解很容易出错。

这个项目中的测试框架只是一个演示，但它清楚地表明了注解相对于命名模式的优越性，而且它仅仅描绘了你可以用它们做什么的外观。如果编写的工具要求程序员将信息添加到源代码中，请定义适当的注解类型。 当可以使用注解代替时，没有理由使用命名模式。

这就是说，除了特定的开发者（toolsmith）之外，大多数程序员都不需要定义注解类型。 但所有程序员都应该使用 Java 提供的预定义注解类型（详见第 27 和 40 条）。另外，请考虑使用 IDE 或静态分析工具提供的注解。这些注解可以提高这些工具提供的诊断信息的质量。但请注意，这些注解尚未标准化，因此如果切换工具或标准出现，可能额外需要做一些工作。

87. 考虑使用自定义的序列化形式

发表于 2022-10-29 更新于 2024-06-07

87. 考虑使用自定义的序列化形式

当你在时间紧迫的情况下编写类时，通常应该将精力集中在设计最佳的 API 上。有时，这意味着发布一个「一次性」实现，你也知道在将来的版本中会替换它。通常这不是一个问题，但是如果类实现 Serializable 接口并使用默认的序列化形式，你将永远无法完全摆脱这个「一次性」的实现。它将永远影响序列化的形式。这不仅仅是一个理论问题。这种情况发生在 Java 库中的几个类上，包括 BigInteger。

在没有考虑默认序列化形式是否合适之前，不要接受它。 接受默认的序列化形式应该是一个三思而后行的决定，即从灵活性、性能和正确性的角度综合来看，这种编码是合理的。一般来说，设计自定义序列化形式时，只有与默认序列化形式所选择的编码在很大程度上相同时，才应该接受默认的序列化形式。

对象的默认序列化形式，相对于它的物理表示法而言是一种比较有效的编码形式。换句话说，它描述了对象中包含的数据以及从该对象可以访问的每个对象的数据。它还描述了所有这些对象相互关联的拓扑结构。理想的对象序列化形式只包含对象所表示的逻辑数据。它独立于物理表征。

如果对象的物理表示与其逻辑内容相同，则默认的序列化形式可能是合适的。 例如，默认的序列化形式对于下面的类来说是合理的，它简单地表示一个人的名字：

// Good candidate for default serialized form
public class Name implements Serializable {
    /**
     * Last name. Must be non-null.
     * @serial
     */
    private final String lastName;

    /**
     * First name. Must be non-null.
     * @serial
     */
    private final String firstName;

    /**
     * Middle name, or null if there is none.
     * @serial
     */
    private final String middleName;
    ... // Remainder omitted
}

从逻辑上讲，名字由三个字符串组成，分别表示姓、名和中间名。Name 的实例字段精确地反映了这个逻辑内容。

即使你认为默认的序列化形式是合适的，你通常也必须提供 readObject 方法来确保不变性和安全性。 对于 Name 类而言, readObject 方法必须确保字段 lastName 和 firstName 是非空的。第 88 条和第 90 条详细讨论了这个问题。

注意，虽然 lastName、firstName 和 middleName 字段是私有的，但是它们都有文档注释。这是因为这些私有字段定义了一个公共 API，它是类的序列化形式，并且必须对这个公共 API 进行文档化。@serial 标记的存在告诉 Javadoc 将此文档放在一个特殊的页面上，该页面记录序列化的形式。

与 Name 类不同，考虑下面的类，它是另一个极端。它表示一个字符串列表（使用标准 List 实现可能更好，但此时暂不这么做）：

// Awful candidate for default serialized form
public final class StringList implements Serializable {
    private int size = 0;
    private Entry head = null;
    private static class Entry implements Serializable {
        String data;
        Entry next;
        Entry previous;
    }
    ... // Remainder omitted
}

从逻辑上讲，这个类表示字符串序列。在物理上，它将序列表示为双向链表。如果接受默认的序列化形式，该序列化形式将不遗余力地镜像出链表中的所有项，以及这些项之间的所有双向链接。

当对象的物理表示与其逻辑数据内容有很大差异时，使用默认的序列化形式有四个缺点：

它将导出的 API 永久地绑定到当前的内部实现。 在上面的例子中，私有 StringList.Entry 类成为公共 API 的一部分。如果在将来的版本中更改了实现，StringList 类仍然需要接受链表形式的输出，并产生链表形式的输出。这个类永远也摆脱不掉处理链表项所需要的所有代码，即使不再使用链表作为内部数据结构。
它会占用过多的空间。 在上面的示例中，序列化的形式不必要地表示链表中的每个条目和所有链接关系。这些链表项以及链接只不过是实现细节，不值得记录在序列化形式中。因为这样的序列化形式过于庞大，将其写入磁盘或通过网络发送将非常慢。
它会消耗过多的时间。 序列化逻辑不知道对象图的拓扑结构，因此必须遍历开销很大的图。在上面的例子中，只要遵循 next 的引用就足够了。
它可能导致堆栈溢出。 默认的序列化过程执行对象图的递归遍历，即使对于中等规模的对象图，这也可能导致堆栈溢出。用 1000-1800 个元素序列化 StringList 实例会在我的机器上生成一个 StackOverflowError。令人惊讶的是，序列化导致堆栈溢出的最小列表大小因运行而异（在我的机器上）。显示此问题的最小列表大小可能取决于平台实现和命令行标志；有些实现可能根本没有这个问题。

StringList 的合理序列化形式就是列表中的字符串数量，然后是字符串本身。这构成了由 StringList 表示的逻辑数据，去掉了其物理表示的细节。下面是修改后的 StringList 版本，带有实现此序列化形式的 writeObject 和 readObject 方法。提醒一下，transient 修饰符表示要从类的默认序列化表单中省略该实例字段：

// StringList with a reasonable custom serialized form
public final class StringList implements Serializable {
    private transient int size = 0;
    private transient Entry head = null;
    // No longer Serializable!

    private static class Entry {
        String data;
        Entry next;
        Entry previous;
    }
    // Appends the specified string to the list
    public final void add(String s) { ... }

    /**
     * Serialize this {@code StringList} instance.
     *
     * @serialData The size of the list (the number of strings
     * it contains) is emitted ({@code int}), followed by all of
     * its elements (each a {@code String}), in the proper
     * sequence.
     */
    private void writeObject(ObjectOutputStream s) throws IOException {
        s.defaultWriteObject();
        s.writeInt(size);
        // Write out all elements in the proper order.
        for (Entry e = head; e != null; e = e.next)
            s.writeObject(e.data);
    }

    private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException {
        s.defaultReadObject();
        int numElements = s.readInt();
        // Read in all elements and insert them in list
        for (int i = 0; i < numElements; i++)
            add((String) s.readObject());
    }

    ... // Remainder omitted
}

writeObject 做的第一件事是调用 defaultWriteObject, readObject 做的第一件事是调用 defaultReadObject，即使 StringList 的所有字段都是 transient 的。你可能听说过，如果一个类的所有实例字段都是 transient 的，那么你可以不调用 defaultWriteObject 和 defaultReadObject，但是序列化规范要求你无论如何都要调用它们。这些调用的存在使得在以后的版本中添加非瞬态实例字段成为可能，同时保留了向后和向前兼容性。如果实例在较晚的版本中序列化，在较早的版本中反序列化，则会忽略添加的字段。如果早期版本的 readObject 方法调用 defaultReadObject 失败，反序列化将失败，并出现 StreamCorruptedException。

注意，writeObject 方法有一个文档注释，即使它是私有的。这类似于 Name 类中私有字段的文档注释。这个私有方法定义了一个公共 API，它是序列化的形式，并且应该对该公共 API 进行文档化。与字段的 @serial 标记一样，方法的 @serialData标记告诉 Javadoc 实用工具将此文档放在序列化形式页面上。

为了给前面的性能讨论提供一定的伸缩性，如果平均字符串长度是 10 个字符，那么经过修改的 StringList 的序列化形式占用的空间大约是原始字符串序列化形式的一半。在我的机器上，序列化修订后的 StringList 的速度是序列化原始版本的两倍多，列表长度为 10。最后，在修改后的形式中没有堆栈溢出问题，因此对于可序列化的 StringList 的大小没有实际的上限。

虽然默认的序列化形式对 StringList 不好，但是对于某些类来说，情况会更糟。对于 StringList，默认的序列化形式是不灵活的，并且执行得很糟糕，但是它是正确的，因为序列化和反序列化 StringList 实例会生成原始对象的无差错副本，而所有不变量都是完整的。对于任何不变量绑定到特定于实现的细节的对象，情况并非如此。

例如，考虑哈希表的情况。物理表示是包含「键-值」项的哈希桶序列。一个项所在的桶是其键的散列代码的函数，通常情况下，不能保证从一个实现到另一个实现是相同的。事实上，它甚至不能保证每次运行都是相同的。因此，接受哈希表的默认序列化形式将构成严重的 bug。对哈希表进行序列化和反序列化可能会产生一个不变量严重损坏的对象。

无论你是否接受默认的序列化形式，当调用 defaultWriteObject 方法时，没有标记为 transient 的每个实例字段都会被序列化。因此，可以声明为 transient 的每个实例字段都应该做这个声明。这包括派生字段，其值可以从主数据字段（如缓存的哈希值）计算。它还包括一些字段，这些字段的值与 JVM 的一个特定运行相关联，比如表示指向本机数据结构指针的 long 字段。在决定使字段非 **transient 之前，请确信它的值是对象逻辑状态的一部分。** 如果使用自定义序列化表单，大多数或所有实例字段都应该标记为 transient，如上面的 StringList 示例所示。

如果使用默认的序列化形式，并且标记了一个或多个字段为 transient，请记住，当反序列化实例时，这些字段将初始化为默认值：对象引用字段为 null，数字基本类型字段为 0，布尔字段为 false [JLS, 4.12.5]。如果这些值对于任何 transient 字段都是不可接受的，则必须提供一个 readObject 方法，该方法调用 defaultReadObject 方法，然后将 transient 字段恢复为可接受的值（详见第 88 条）。或者，可以采用延迟初始化（详见第 83 条），在第一次使用这些字段时初始化它们。

无论你是否使用默认的序列化形式，必须对对象序列化强制执行任何同步操作，就像对读取对象的整个状态的任何其他方法强制执行的那样。 例如，如果你有一个线程安全的对象（详见第 82 条），它通过同步每个方法来实现线程安全，并且你选择使用默认的序列化形式，那么使用以下 write-Object 方法：

// writeObject for synchronized class with default serialized form
private synchronized void writeObject(ObjectOutputStream s) throws IOException {
    s.defaultWriteObject();
}

如果将同步放在 writeObject 方法中，则必须确保它遵守与其他活动相同的锁排序约束，否则将面临资源排序死锁的风险 [Goetz06, 10.1.5]。

无论选择哪种序列化形式，都要在编写的每个可序列化类中声明显式的序列版本 UID。 这消除了序列版本 UID 成为不兼容性的潜在来源（详见第 86 条）。这么做还能获得一个小的性能优势。如果没有提供序列版本 UID，则需要执行高开销的计算在运行时生成一个 UID。

声明序列版本 UID 很简单，只要在你的类中增加这一行：

1	private static final long serialVersionUID = randomLongValue;

如果你编写一个新类，为 randomLongValue 选择什么值并不重要。你可以通过在类上运行 serialver 实用工具来生成该值，但是也可以凭空选择一个数字。串行版本 UID 不需要是唯一的。如果修改缺少串行版本 UID 的现有类，并且希望新版本接受现有的序列化实例，则必须使用为旧版本自动生成的值。你可以通过在类的旧版本上运行 serialver 实用工具（序列化实例存在于旧版本上）来获得这个数字。

如果你希望创建一个新版本的类，它与现有版本不兼容，如果更改序列版本 UID 声明中的值，这将导致反序列化旧版本的序列化实例的操作引发 InvalidClassException。不要更改序列版本 UID，除非你想破坏与现有序列化所有实例的兼容性。

总而言之，如果你已经决定一个类应该是可序列化的（详见第 86 条），那么请仔细考虑一下序列化的形式应该是什么。只有在合理描述对象的逻辑状态时，才使用默认的序列化形式；否则，设计一个适合描述对象的自定义序列化形式。设计类的序列化形式应该和设计导出方法花的时间应该一样多，都应该严谨对待（详见第 51 条）。正如不能从未来版本中删除导出的方法一样，也不能从序列化形式中删除字段；必须永远保存它们，以确保序列化兼容性。选择错误的序列化形式可能会对类的复杂性和性能产生永久性的负面影响。

26. 不要使用原始类型

发表于 2022-10-29 更新于 2024-06-07

26. 不要使用原始类型

自 Java 5 以来，泛型已经成为该语言的一部分。在泛型之前，你必须转换从集合中读取的每个对象。如果有人不小心插入了错误类型的对象，则在运行时可能会失败。使用泛型，你告诉编译器在每个集合中允许哪些类型的对象。编译器会自动插入强制转换，并在编译时告诉你是否尝试插入错误类型的对象。这样做的结果是既安全又清晰的程序，但这些益处，不限于集合，是有代价的。本章告诉你如何最大限度地提高益处，并将并发症降至最低。

26. 不要使用原始类型

首先，有几个术语。一个类或接口，它的声明有一个或多个类型参数（type parameters ），被称之为泛型类或泛型接口[JLS，8.1.2,9.1.2]。例如，List 接口具有单个类型参数 E，表示其元素类型。接口的全名是 List<E>（读作「E」的列表），但是人们经常称它为 List。泛型类和接口统称为泛型类型（generic types）。

每个泛型定义了一组参数化类型（parameterized types），它们由类或接口名称组成，后跟一个与泛型类型的形式类型参数[JLS，4.4,4.5] 相对应的实际类型参数的尖括号「<>」列表。例如，List<String>（读作「字符串列表」）是一个参数化类型，表示其元素类型为 String 的列表。（String 是与形式类型参数 E 相对应的实际类型参数）。

最后，每个泛型定义了一个原始类型（raw type），它是没有任何类型参数的泛型类型的名称[JLS，4.8]。例如，对应于 List<E> 的原始类型是 List。原始类型的行为就像所有的泛型类型信息都从类型声明中被清除一样。它们的存在主要是为了与没有泛型之前的代码相兼容。

在泛型被添加到 Java 之前，这是一个典型的集合声明。从 Java 9 开始，它仍然是合法的，但并不是典型的声明方式了：

// Raw collection type - don't do this!

// My stamp collection. Contains only Stamp instances.
private final Collection stamps = ... ;

如果你今天使用这个声明，然后不小心把 coin 实例放入你的 stamp 集合中，错误的插入编译和运行没有错误（尽管编译器发出一个模糊的警告）：

1 2	// Erroneous insertion of coin into stamp collection stamps.add(new Coin( ... )); // Emits "unchecked call" warning

直到您尝试从 stamp 集合中检索 coin 实例时才会发生错误：

// Raw iterator type - don't do this!
for (Iterator i = stamps.iterator(); i.hasNext(); )
    Stamp stamp = (Stamp) i.next(); // Throws ClassCastException
        stamp.cancel();

正如本书所提到的，在编译完成之后尽快发现错误是值得的，理想情况是在编译时。在这种情况下，直到运行时才发现错误，在错误发生后的很长一段时间，以及可能远离包含错误的代码的代码中。一旦看到 ClassCastException，就必须搜索代码类库，查找将 coin 实例放入 stamp 集合的方法调用。编译器不能帮助你，因为它不能理解那个说「仅包含 stamp 实例」的注释。

对于泛型，类型声明包含的信息，而不是注释：

1 2	// Parameterized collection type - typesafe private final Collection<Stamp> stamps = ... ;

从这个声明中，编译器知道 stamps 集合应该只包含 Stamp 实例，并保证它是 true，假设你的整个代码类库编译时不发出（或者抑制；参见条目 27）任何警告。当使用参数化类型声明声明 stamps 时，错误的插入会生成一个编译时错误消息，告诉你到底发生了什么错误：

Test.java:9: error: incompatible types: Coin cannot be converted
to Stamp
    c.add(new Coin());
              ^

当从集合中检索元素时，编译器会为你插入不可见的强制转换，并保证它们不会失败（再假设你的所有代码都不会生成或禁止任何编译器警告）。虽然意外地将 coin 实例插入 stamp 集合的预期可能看起来很牵强，但这个问题是真实的。例如，很容易想象将 BigInteger 放入一个只包含 BigDecimal 实例的集合中。

如前所述，使用原始类型（没有类型参数的泛型）是合法的，但是你不应该这样做。 如果你使用原始类型，则会丧失泛型的所有安全性和表达上的优势。 鉴于你不应该使用它们，为什么语言设计者首先允许原始类型呢？答案是为了兼容性。泛型被添加时，Java 即将进入第二个十年，并且有大量的代码没有使用泛型。所有这些代码都是合法的，并且与使用泛型的新代码进行交互操作被认为是至关重要的。将参数化类型的实例传递给为原始类型设计的方法必须是合法的，反之亦然。这个需求，被称为迁移兼容性，驱使决策支持原始类型，并使用擦除来实现泛型（详见第 28 条）。

虽然不应使用诸如 List 之类的原始类型，但可以使用参数化类型来允许插入任意对象（如 List<Object>）。原始类型 List 和参数化类型 List<Object> 之间有什么区别？松散地说，前者已经选择了泛型类型系统，而后者明确地告诉编译器，它能够保存任何类型的对象。虽然可以将 List<String> 传递给 List 类型的参数，但不能将其传递给 List<Object> 类型的参数。泛型有子类型的规则，List<String> 是原始类型 List 的子类型，但不是参数化类型 List<Object> 的子类型（条目 28）。因此，如果使用诸如 List 之类的原始类型，则会丢失类型安全性，但是如果使用参数化类型（例如 List<Object>）则不会。

为了具体说明，请考虑以下程序：

// Fails at runtime - unsafeAdd method uses a raw type (List)!
public static void main(String[] args) {
    List<String> strings = new ArrayList<>();
    unsafeAdd(strings, Integer.valueOf(42));
    String s = strings.get(0); // Has compiler-generated cast
}

private static void unsafeAdd(List list, Object o) {
    list.add(o);
}

此程序可以编译，它使用原始类型列表，但会收到警告：

Test.java:10: warning: [unchecked] unchecked call to add(E) as a
member of the raw type List
    list.add(o);
            ^

实际上，如果运行该程序，则当程序尝试调用 strings.get(0) 的结果（一个 Integer）转换为一个 String 时，会得到 ClassCastException 异常。这是一个编译器生成的强制转换，因此通常会保证成功，但在这种情况下，我们忽略了编译器警告并付出了代价。

如果用 unsafeAdd 声明中的参数化类型 List<Object> 替换原始类型 List，并尝试重新编译该程序，则会发现它不再编译，而是发出错误消息：

1
2
3

Test.java:5: error: incompatible types: List<String> cannot be
converted to List<Object>
    unsafeAdd(strings, Integer.valueOf(42));

你可能会试图使用原始类型来处理元素类型未知且无关紧要的集合。例如，假设你想编写一个方法，它需要两个集合并返回它们共同拥有的元素的数量。如果是泛型新手，那么您可以这样写：

// Use of raw type for unknown element type - don't do this!
static int numElementsInCommon(Set s1, Set s2) {
    int result = 0;
    for (Object o1 : s1)
        if (s2.contains(o1))
            result++;
    return result;
}

这种方法可以工作，但它使用原始类型，这是危险的。安全替代方式是使用无限制通配符类型（unbounded wildcard types）。如果要使用泛型类型，但不知道或关心实际类型参数是什么，则可以使用问号来代替。例如，泛型类型 Set<E> 的无限制通配符类型是 Set<?>（读取「某种类型的集合」）。它是最通用的参数化的 Set 类型，能够保持任何集合。下面是 numElementsInCommon 方法使用无限制通配符类型声明的情况：

1 2	// Uses unbounded wildcard type - typesafe and flexible static int numElementsInCommon(Set<?> s1, Set<?> s2) { ... }

无限制通配符 Set<?> 与原始类型 Set 之间有什么区别？问号真的给你放任何东西吗？这不是要点，但通配符类型是安全的，原始类型不是。你可以将任何元素放入具有原始类型的集合中，轻易破坏集合的类型不变性（如第 119 页上的 unsafeAdd 方法所示）; 你不能把任何元素（除 null 之外）放入一个 Collection<?> 中。试图这样做会产生一个像这样的编译时错误消息：

WildCard.java:13: error: incompatible types: String cannot be
converted to CAP#1
    c.add("verboten");
          ^
  where CAP#1 is a fresh type-variable:
    CAP#1 extends Object from capture of ?

不可否认的是，这个错误信息留下了一些需要的东西，但是编译器已经完成了它的工作，不管它的元素类型是什么，都不会破坏集合的类型不变性。你不仅不能将任何元素（除 null 以外）放入一个 Collection<?> 中，并且根本无法猜测你会得到那种类型的对象。如果这些限制是不可接受的，可以使用泛型方法（详见第 30 条）或有限制的通配符类型（详见第 31 条）。

对于不应该使用原始类型的规则，有一些小例外。 你必须在类字面值（class literals）中使用原始类型。 规范中不允许使用参数化类型（尽管它允许数组类型和基本类型）[JLS，15.8.2]。换句话说，List.class，String[].class 和 int.class 都是合法的，但 List<String>.class 和 List<?>.class 都是不合法的。

规则的第二个例外与 instanceof 操作符有关。因为泛型类型信息在运行时被擦除，所以在无限制通配符类型以外的参数化类型上使用 instanceof 运算符是非法的。使用无限制通配符类型代替原始类型，不会对 instanceof 运算符的行为产生任何影响。在这种情况下，尖括号（<>）和问号（?）就显得多余。 以下是使用泛型类型的 **instanceof 运算符的首选方法：**

// Legitimate use of raw type - instanceof operator
if (o instanceof Set) {       // Raw type
    Set<?> s = (Set<?>) o;    // Wildcard type
    ...
}

请注意，一旦确定 o 对象是一个 Set，则必须将其转换为通配符 Set<?>，而不是原始类型 Set。这是一个受检查的（checked）转换，所以不会导致编译器警告。

总之，使用原始类型可能导致运行时异常，所以不要使用它们。原始类型只是为了与引入泛型机制之前的遗留代码进行兼容和互用而提供的。作为一个快速回顾，Set<Object> 是一个参数化类型，表示一个可以包含任何类型对象的集合，Set<?> 是一个通配符类型，表示一个只能包含某些未知类型对象的集合，Set 是一个原始类型，它不在泛型类型系统之列。前两个类型是安全的，最后一个不是。

为了快速参考，下表中总结了本条目（以及本章稍后介绍的一些）中介绍的术语：

术语	中文含义	举例	所在条目
Parameterized type	参数化类型	`List<String>`	条目 26
Actual type parameter	实际类型参数	`String`	条目 26
Generic type	泛型类型	`List<E>`	条目 26 和条目 29
Formal type parameter	形式类型参数	`E`	条目 26
Unbounded wildcard type	无限制通配符类型	`List<?>`	条目 26
Raw type	原始类型	`List`	条目 26
Bounded type parameter	限制类型参数	`<E extends Number>`	条目 29
Recursive type bound	递归类型限制	`<T extends Comparable<T>>`	条目 30
Bounded wildcard type	限制通配符类型	`List<? extends Number>`	条目 31
Generic method	泛型方法	`static <E> List<E> asList(E[] a)`	条目 30
Type token	类型令牌	`String.class`	条目 33

32. 合理地结合泛型和可变参数

发表于 2022-10-29 更新于 2024-06-07

32. 合理地结合泛型和可变参数

在 Java 5 中，可变参数方法（详见第 53 条）和泛型都被添加到平台中，所以你可能希望它们能够正常交互; 可悲的是，他们并没有。可变参数的目的是允许客户端将一个可变数量的参数传递给一个方法，但这是一个脆弱的抽象（leaky abstraction）：当你调用一个可变参数方法时，会创建一个数组来保存可变参数；那个应该是实现细节的数组是可见的。因此，当可变参数具有泛型或参数化类型时，会导致编译器警告混淆。

回顾条目 28，非具体化（non-reifiable）的类型是其运行时表示比其编译时表示具有更少信息的类型，并且几乎所有泛型和参数化类型都是不可具体化的。如果某个方法声明其可变参数为非具体化的类型，则编译器将在该声明上生成警告。如果在推断类型不可确定的可变参数参数上调用该方法，那么编译器也会在调用中生成警告。警告看起来像这样：

1 2	warning: [unchecked] Possible heap pollution from parameterized vararg type List<String>

当参数化类型的变量引用不属于该类型的对象时会发生堆污染（Heap pollution）[JLS，4.12.2]。它会导致编译器的自动生成的强制转换失败，违反了泛型类型系统的基本保证。

例如，请考虑以下方法，该方法是第 127 页上的代码片段的一个不太明显的变体：

// Mixing generics and varargs can violate type safety!
static void dangerous(List<String>... stringLists) {
    List<Integer> intList = List.of(42);
    Object[] objects = stringLists;
    objects[0] = intList;             // Heap pollution
    String s = stringLists[0].get(0); // ClassCastException
}

此方法没有可见的强制转换，但在调用一个或多个参数时抛出 ClassCastException 异常。它的最后一行有一个由编译器生成的隐形转换。这种转换失败，表明类型安全性已经被破坏，并且将值保存在泛型可变参数数组参数中是不安全的。

这个例子引发了一个有趣的问题：为什么声明一个带有泛型可变参数的方法是合法的，当明确创建一个泛型数组是非法的时候呢？换句话说，为什么前面显示的方法只生成一个警告，而 127 页上的代码片段会生成一个错误？答案是，具有泛型或参数化类型的可变参数参数的方法在实践中可能非常有用，因此语言设计人员选择忍受这种不一致。事实上，Java 类库导出了几个这样的方法，包括 Arrays.asList(T... a)，Collections.addAll(Collection<? super T> c, T... elements)，EnumSet.of(E first, E... rest)。与前面显示的危险方法不同，这些类库方法是类型安全的。

在 Java 7 中，@SafeVarargs 注解已添加到平台，以允许具有泛型可变参数的方法的作者自动禁止客户端警告。实质上，@SafeVarargs 注解构成了作者对类型安全的方法的承诺。为了交换这个承诺，编译器同意不要警告用户调用可能不安全的方法。

除非它实际上是安全的，否则注意不要使用 @SafeVarargs 注解标注一个方法。那么需要做些什么来确保这一点呢？回想一下，调用方法时会创建一个泛型数组，以容纳可变参数。如果方法没有在数组中存储任何东西（它会覆盖参数）并且不允许对数组的引用进行转义（这会使不受信任的代码访问数组），那么它是安全的。换句话说，如果可变参数数组仅用于从调用者向方法传递可变数量的参数——毕竟这是可变参数的目的——那么该方法是安全的。

值得注意的是，你可以违反类型安全性，即使不会在可变参数数组中存储任何内容。考虑下面的泛型可变参数方法，它返回一个包含参数的数组。乍一看，它可能看起来像一个方便的小工具：

// UNSAFE - Exposes a reference to its generic parameter array!
static <T> T[] toArray(T... args) {
    return args;
}

这个方法只是返回它的可变参数数组。该方法可能看起来并不危险，但它是！该数组的类型由传递给方法的参数的编译时类型决定，编译器可能没有足够的信息来做出正确的判断。由于此方法返回其可变参数数组，它可以将堆污染传播到调用栈上。

为了具体说明，请考虑下面的泛型方法，它接受三个类型 T 的参数，并返回一个包含两个参数的数组，随机选择：

static <T> T[] pickTwo(T a, T b, T c) {
    switch(ThreadLocalRandom.current().nextInt(3)) {
      case 0: return toArray(a, b);
      case 1: return toArray(a, c);
      case 2: return toArray(b, c);
    }
    throw new AssertionError(); // Can't get here
}

这个方法本身不是危险的，除了调用具有泛型可变参数的 toArray 方法之外，不会产生警告。

编译此方法时，编译器会生成代码以创建一个将两个 T 实例传递给 toArray 的可变参数数组。这段代码分配了一个 Object[] 类型的数组，它是保证保存这些实例的最具体的类型，而不管在调用位置传递给 pickTwo 的对象是什么类型。 toArray 方法只是简单地将这个数组返回给 pickTwo，然后 pickTwo 将它返回给调用者，所以 pickTwo 总是返回一个 Object[] 类型的数组。

1
2
3

public static void main(String[] args) {
    String[] attributes = pickTwo("Good", "Fast", "Cheap");
}

这种方法没有任何问题，因此它编译时不会产生任何警告。但是当运行它时，抛出一个 ClassCastException 异常，尽管不包含可见的转换。你没有看到的是，编译器已经生成了一个隐藏的强制转换为由 pickTwo 返回的值的 String[] 类型，以便它可以存储在属性中。转换失败，因为 Object[] 不是 String[] 的子类型。这种故障相当令人不安，因为它从实际导致堆污染（toArray）的方法中移除了两个级别，并且在实际参数存储在其中之后，可变参数数组未被修改。

这个例子是为了让人们认识到给另一个方法访问一个泛型的可变参数数组是不安全的，除了两个例外：将数组传递给另一个可变参数方法是安全的，这个方法是用 @SafeVarargs 正确标注的，将数组传递给一个非可变参数的方法是安全的，该方法仅计算数组内容的一些方法。

这里是安全使用泛型可变参数的典型示例。此方法将任意数量的列表作为参数，并按顺序返回包含所有输入列表元素的单个列表。由于该方法使用 @SafeVarargs 进行标注，因此在声明或其调用站位置上不会生成任何警告：

// Safe method with a generic varargs parameter
@SafeVarargs
static <T> List<T> flatten(List<? extends T>... lists) {
    List<T> result = new ArrayList<>();
    for (List<? extends T> list : lists)
        result.addAll(list);
    return result;
}

决定何时使用 @SafeVarargs 注解的规则很简单：在每种方法上使用 @SafeVarargs，并使用泛型或参数化类型的可变参数，这样用户就不会因不必要的和令人困惑的编译器警告而担忧。这意味着你不应该写危险或者 toArray 等不安全的可变参数方法。每次编译器警告你可能会受到来自你控制的方法中泛型可变参数的堆污染时，请检查该方法是否安全。提醒一下，在下列情况下，泛型可变参数方法是安全的：

它不会在可变参数数组中存储任何东西
它不会使数组（或克隆）对不可信代码可见。如果违反这些禁令中的任何一项，请修复。

请注意，SafeVarargs 注解只对不能被重写的方法是合法的，因为不可能保证每个可能的重写方法都是安全的。在 Java 8 中，注解仅在静态方法和 final 实例方法上合法; 在 Java 9 中，它在私有实例方法中也变为合法。

使用 SafeVarargs 注解的替代方法是采用条目 28 的建议，并用 List 参数替换可变参数（这是一个变相的数组）。下面是应用于我们的 flatten 方法时，这种方法的样子。请注意，只有参数声明被更改了：

// List as a typesafe alternative to a generic varargs parameter
static <T> List<T> flatten(List<List<? extends T>> lists) {
    List<T> result = new ArrayList<>();
    for (List<? extends T> list : lists)
        result.addAll(list);
    return result;
}

然后可以将此方法与静态工厂方法 List.of 结合使用，以允许可变数量的参数。请注意，这种方法依赖于 List.of 声明使用 @SafeVarargs 注解：

audience = flatten(List.of(friends, romans, countrymen));

这种方法的优点是编译器可以证明这种方法是类型安全的。不必使用 @SafeVarargs 注解来证明其安全性，也不用担心在确定安全性时可能会犯错。主要缺点是客户端代码有点冗长，运行可能会慢一些。

这个技巧也可以用在不可能写一个安全的可变参数方法的情况下，就像第 147 页的 toArray 方法那样。它的列表模拟是 List.of 方法，所以我们甚至不必编写它；Java 类库作者已经为我们完成了这项工作。 pickTwo 方法然后变成这样：

static <T> List<T> pickTwo(T a, T b, T c) {
    switch(rnd.nextInt(3)) {
      case 0: return List.of(a, b);
      case 1: return List.of(a, c);
      case 2: return List.of(b, c);
    }
    throw new AssertionError();
}

main 方变成这样：

1
2
3

public static void main(String[] args) {
    List<String> attributes = pickTwo("Good", "Fast", "Cheap");
}

生成的代码是类型安全的，因为它只使用泛型，不是数组。

总而言之，可变参数和泛型不能很好地交互，因为可变参数机制是在数组上面构建的脆弱的抽象，并且数组具有与泛型不同的类型规则。虽然泛型可变参数不是类型安全的，但它们是合法的。如果选择使用泛型（或参数化）可变参数编写方法，请首先确保该方法是类型安全的，然后使用 @SafeVarargs 注解对其进行标注，以免造成使用不愉快。

01. 考虑使用静态工厂方法替代构造方法

发表于 2022-10-29 更新于 2024-06-07

01. 考虑使用静态工厂方法替代构造方法

1. 考虑使用静态工厂方法替代构造方法

一个类允许客户端获取其实例的传统方式，是提供一个公共构造方法。其实，还有另一种技术应该成为每个程序员工具箱的一部分。一个类可以提供一个简单的、只返回该类实例的公共静态工厂方法。下面是一个 Boolean 简单的例子（基本类型boolean的包装类）。此方法将基本类型boolean转换为 Boolean 对象引用：

1
2
3

public static Boolean valueOf(boolean b) {
    return b ? Boolean.TRUE : Boolean.FALSE;
}

注意，静态工厂方法与设计模式中的工厂方法模式不同[Gamma95]。本条目中描述的静态工厂方法在设计模式中没有直接的等价。

类可以为其客户端提供静态工厂方法，而不是公共构造方法。提供静态工厂方法来代替提供公共构造方法这种方式，有优点也有缺点。

静态工厂方法的一个优点是，与构造方法不同，它们是有名字的。 如果构造方法的参数本身并不描述被返回的对象，则具有精心选择名称的静态工厂更易于使用，并且生成的客户端代码更易于阅读。例如，返回一个可能为素数的 BigInteger 的构造方法 BigInteger(int，int，Random) 可以更好地表示为名为 BigInteger.probablePrime 的静态工厂方法。（这个方法是在 Java 1.4 中添加的。）

一个类只能有一个给定签名的构造方法。程序员知道通过提供两个仅仅在参数类型的顺序不同的构造方法，来解决这个限制。这是一个非常糟糕的主意。对于这样的 API ，用户将永远不会记得哪个构造方法是哪个，最终会错误地调用。阅读使用这些构造方法的代码的人只有在参考类文档的情况下才知道代码的作用。

因为静态工厂方法有名字，所以它们不会受到上述限制。在类中似乎需要具有相同签名的多个构造方法的情况下，用静态工厂方法替换构造方法，并仔细选择名称来突出它们的差异。

静态工厂方法的第二个优点是，与构造方法不同，它们不需要每次调用时都创建一个新对象。 这允许不可变类（详见第 17 条）使用预先构建的实例，或者在构造时缓存实例，并反复分配它们以避免创建不必要的重复对象。Boolean.valueof(boolean) 方法说明了这种方法：它从不创建对象。这种技术类似于 Flyweight 模式[Gamma95]。如果经常请求等价对象，那么它可以极大地提高性能，特别是在创建它们的代价非常昂贵的情况下。

静态工厂方法在重复调用时，返回相同实例这个特点，可以让类在任何时候都能对实例保持严格的控制。这样做的类被称为实例控制类（ instance-controlled）。有很多理由足以让我们去我们编写实例控制类。实例控制可以保证一个类是单例的（详见第 3 条）或不可实例化的（详见第 4 条）。同时,它允许一个不可变的值类（详见第 17 条）保证不存在两个相等但不相同的实例，也就是说当且仅当 a == b 时才有 a.equals(b)。这是Flyweight模式的基础[Gamma95]。Enum 类型（详见第 34 条）可以做到这点。

静态工厂方法的第三个优点是，与构造方法不同，它们可以返回其返回类型的任何子类型的对象。 这为你在选择返回对象的类型时，提供了很大的灵活性。

这种灵活性的一个应用是， API 可以返回对象而不需要公开它的类。以这种方式隐藏实现类，会使 API 非常紧凑。这种技术适用于基于接口的框架（详见第 20 条），其中接口为静态工厂方法提供自然返回类型。

在 Java 8 之前，接口不能有静态方法。根据约定，一个名为 Types 的接口的静态工厂方法被放入一个不可实例化的伙伴类（companion class）（详见第 4 条）Types 类中。例如，Java 集合框架有 45 个接口的实用工具实现，提供不可修改的集合、同步集合等等。几乎所有这些实现都是通过静态工厂方法在一个不可实例化的类 (java.util.collections) 中返回的。返回对象的类都是隐藏的。

Collections 框架 API 的规模要比它之前返回的 45 个单独的公共类要小得多，每个类在集合框架中都有一个便利的实现。不仅精简了API，还减少了程序员为了使用 API而掌握的概念的数量和难度。程序员知道返回的对象恰好有其接口指定的 API，因此不需要为实现类读阅读额外的类文档。此外，使用这种静态工厂方法，需要客户端通过接口替代实现类，来引用返回的对象，这通常是良好的实践（详见第 64 条）。

从 Java 8 开始，接口不能包含静态方法的限制被取消了，所以通常没有理由为接口提供一个不可实例化的伴随类。很多公开的静态成员应该放在这个接口本身。但是，请注意，将这些静态方法的大部分实现代码放在单独的包私有类中仍然是必要的。这是因为 Java 8 要求所有接口的静态成员都是公共的。 Java 9 允许私有静态方法，但静态字段和静态成员类仍然需要公开。

静态工厂的第四个优点是返回对象的类可以根据输入参数的不同而不同。 声明的返回类型的任何子类都是允许的。返回对象的类也可以随每次发布而不同。

EnumSet 类（详见第 36 条）没有公共构造方法，只有静态工厂。在 OpenJDK 实现中，它们根据底层枚举类型的大小返回两个子类中的一个的实例：大多数枚举类型具有 64 个或更少的元素，静态工厂将返回一个 RegularEnumSet 实例，底层是long 类型；如果枚举类型具有六十五个或更多元素，则工厂将返回一个 JumboEnumSet 实例，底层是long 类型的数组。

这两个实现类的存在对于客户端而言是不可见的。如果 RegularEnumSet 对于小的枚举类型不再具有性能优势，则可以在未来版本中将其淘汰，且不会产生任何不良影响。同样，如果可以证明添加 EnumSet 的更多的实现可以提高性能，那么在未来的版本可能就会这样做。客户既不知道也不关心他们从工厂返回的对象的类别; 他们只需要知道它是 EnumSet 的子类。

静态工厂的第五个优点是，在编写包含该方法的类时，返回的对象的类不需要存在。 这种灵活的静态工厂方法构成了服务提供者框架的基础，比如 Java 数据库连接 API（JDBC）。服务提供者框架是提供者实现服务的系统，并且系统使得实现对客户端可用，从而将客户端从实现中分离出来。

服务提供者框架中有三个基本组：服务接口，它表示实现；提供者注册 API，提供者用来注册实现；以及服务访问 API，客户端使用该 API 获取服务的实例。服务访问 API 允许客户指定选择实现的标准。在缺少这样的标准的情况下，API 返回一个默认实现的实例，或者允许客户通过所有可用的实现进行遍历。服务访问 API 是灵活的静态工厂，它构成了服务提供者框架的基础。

服务提供者框架的一个可选的第四个组件是一个服务提供者接口，它描述了一个生成服务接口实例的工厂对象。在没有服务提供者接口的情况下，必须对实现进行反射实例化（详见第 65 条）。在 JDBC 的情况下，Connection 扮演服务接口的一部分，DriverManager.registerDriver 提供程序注册 API、DriverManager.getConnection 是服务访问 API，Driver 是服务提供者接口。

服务提供者框架模式有许多变种。例如，服务访问 API 可以向客户端返回比提供者提供的更丰富的服务接口。这是桥接模式[Gamma95]。依赖注入框架（详见第 5 条）可以被看作是强大的服务提供者。从 Java 6 开始，平台包含一个通用的服务提供者框架 java.util.ServiceLoader，所以你不需要，一般也不应该自己编写（详见第 59 条）。 JDBC 不使用 ServiceLoader，因为前者早于后者。

只提供静态工厂方法的主要限制是，没有公共或受保护构造方法的类不能被子类化。 例如，要想将 Collections 框架中任何遍历的实现类进行子类化，是不可能的。但是这样也会因祸得福，因为它鼓励程序员使用组合（composition）而不是继承（详见第 18 条），并且是不可变类型锁需要的（详见第 17 条）。

静态工厂方法的第二个缺点是，程序员很难找到它们。 它们不像构造方法那样在 API 文档中明确的标注出来。因此，对于提供了静态方法而不是构造器的类来说，想要查明如何实例化一个类是十分困难的。Javadoc 工具可能有一天会注意到静态工厂方法。与此同时，通过关注类或者接口的文档中静态方法，并且遵守标准的命名习惯，也可以弥补这一劣势。下面是一些静态工厂方法的常用名称。以下清单这是列出了其中的一小部分：

from —— 类型转换方法，它接受单个参数并返回此类型的相应实例，例如：Date d = Date.from(instant);
of —— 聚合方法，接受多个参数并返回该类型的实例，并把他们合并在一起，例如：Set<Rank> faceCards = EnumSet.of(JACK, QUEEN, KING);
valueOf —— from 和 to 更为详细的替代方式，例如：BigInteger prime = BigInteger.valueOf(Integer.MAX_VALUE);
instance 或 getinstance —— 返回一个由其参数 (如果有的话) 描述的实例，但不能说它具有相同的值，例如：StackWalker luke = StackWalker.getInstance(options);
create 或 newInstance —— 与 instance 或 getInstance 类似，除此之外该方法保证每次调用返回一个新的实例，例如：Object newArray = Array.newInstance(classObject, arrayLen);
getType —— 与 getInstance 类似，但是在工厂方法处于不同的类中的时候使用。getType 中的 Type 是工厂方法返回的对象类型，例如：FileStore fs = Files.getFileStore(path);
newType —— 与 newInstance 类似，但是在工厂方法处于不同的类中的时候使用。newType中的 Type 是工厂方法返回的对象类型，例如：BufferedReader br = Files.newBufferedReader(path);
type —— getType 和 newType 简洁的替代方式，例如：List<Complaint> litany = Collections.list(legacyLitany);

总之，静态工厂方法和公共构造方法都有它们的用途，并且了解它们的相对优点是值得的。通常，静态工厂更可取，因此避免在没有考虑静态工厂的情况下，直接选择使用或提供公共构造方法。

11. 重写equals方法时同时也要重写hashcode方法

发表于 2022-10-29 更新于 2024-06-07

11. 重写equals方法时同时也要重写hashcode方法

11. 重写 equals 方法时同时也要重写 hashcode 方法

在每个类中，在重写 equals 方法的时侯，一定要重写 hashcode 方法。 如果不这样做，你的类违反了 hashCode 的通用约定，这会阻止它在 HashMap 和 HashSet 这样的集合中正常工作。根据 Object 规范，以下是具体约定。

如果没有修改 equals 方法中用以比较的信息，在应用程序的一次执行过程中对一个对象重复调用 hashCode 方法时，它必须始终返回相同的值。在应用程序的多次执行过程中，每个执行过程在该对象上获取的结果值可以不相同。
如果两个对象根据 equals(Object) 方法比较是相等的，那么在两个对象上调用 hashCode 就必须产生的结果是相同的整数。
如果两个对象根据 equals(Object) 方法比较并不相等，则不要求在每个对象上调用 hashCode 都必须产生不同的结果。但是，程序员应该意识到，为不相等的对象生成不同的结果可能会提高散列表（hash tables）的性能。

当无法重写 hashCode 时，所违反第二个关键条款是：相等的对象必须具有相等的哈希码（ hash codes）。 根据类的 equals 方法，两个不同的实例可能在逻辑上是相同的，但是对于 Object 类的 hashCode 方法，它们只是两个没有什么共同之处的对象。因此， Object 类的 hashCode 方法返回两个看似随机的数字，而不是按约定要求的两个相等的数字。

举例说明，假设你使用条目 10 中的 PhoneNumber 类的实例做为 HashMap 的键（key）：

1 2	Map<PhoneNumber, String> m = new HashMap<>(); m.put(new PhoneNumber(707, 867, 5309), "Jenny");

你可能期望 m.get(new PhoneNumber(707, 867, 5309)) 方法返回 Jenny 字符串，但实际上，返回了 null。注意，这里涉及到两个 PhoneNumber 实例：一个实例插入到 HashMap 中，另一个作为判断相等的实例用来检索。PhoneNumber 类没有重写 hashCode 方法导致两个相等的实例返回了不同的哈希码，违反了 hashCode 约定。put 方法把 PhoneNumber 实例保存在了一个哈希桶（ hash bucket）中，但 get 方法却是从不同的哈希桶中去查找，即使恰好两个实例放在同一个哈希桶中，get 方法几乎肯定也会返回 null。因为 HashMap 做了优化，缓存了与每一项（entry）相关的哈希码，如果哈希码不匹配，则不会检查对象是否相等了。

解决这个问题很简单，只需要为 PhoneNumber 类重写一个合适的 hashCode 方法。hashCode 方法是什么样的？写一个不规范的方法的是很简单的。以下示例，虽然永远是合法的，但绝对不能这样使用：

1 2	// The worst possible legal hashCode implementation - never use! @Override public int hashCode() { return 42; }

这是合法的，因为它确保了相等的对象具有相同的哈希码。这很糟糕，因为它确保了每个对象都有相同的哈希码。因此，每个对象哈希到同一个桶中，哈希表退化为链表。应该在线性时间内运行的程序，运行时间变成了平方级别。对于数据很大的哈希表而言，会影响到能够正常工作。

一个好的 hash 方法趋向于为不相等的实例生成不相等的哈希码。这也正是 hashCode 约定中第三条的表达。理想情况下，hash 方法为集合中不相等的实例均匀地分配 int 范围内的哈希码。实现这种理想情况可能是困难的。幸运的是，要获得一个合理的近似的方式并不难。以下是一个简单的配方：

声明一个 int 类型的变量 result，并将其初始化为对象中第一个重要属性 c 的哈希码，如下面步骤 2.a 中所计算的那样。（回顾条目 10，重要的属性是影响比较相等的领域。）
对于对象中剩余的重要属性 f，请执行以下操作：

a. 比较属性 f 与属性 c 的 int 类型的哈希码：

    – i. 如果这个属性是基本类型的，使用 Type.hashCode(f) 方法计算，其中 Type 类是对应属性 f 基本类型的包装类。

    – ii. 如果该属性是一个对象引用，并且该类的 equals 方法通过递归调用 equals 来比较该属性，并递归地调用 hashCode 方法。如果需要更复杂的比较，则计算此字段的“范式（“canonical representation）”，并在范式上调用 hashCode。如果该字段的值为空，则使用 0（也可以使用其他常数，但通常来使用 0 表示）。

     – iii. 如果属性 f 是一个数组，把它看作每个重要的元素都是一个独立的属性。也就是说，通过递归地应用这些规则计算每个重要元素的哈希码，并且将每个步骤 2.b 的值合并。如果数组没有重要的元素，则使用一个常量，最好不要为 0。如果所有元素都很重要，则使用 Arrays.hashCode 方法。

b. 将步骤 2.a 中属性 c 计算出的哈希码合并为如下结果：result = 31 * result + c;
返回 result 值。

当你写完 hashCode 方法后，问自己是否相等的实例有相同的哈希码。编写单元测试来验证你的直觉（除非你使用 AutoValue 框架来生成你的 equals 和 hashCode 方法，在这种情况下，你可以放心地忽略这些测试）。如果相同的实例有不相等的哈希码，找出原因并解决问题。

可以从哈希码计算中排除派生属性（derived fields）。换句话说，如果一个属性的值可以根据参与计算的其他属性值计算出来，那么可以忽略这样的属性。您必须排除在 equals 比较中没有使用的任何属性，否则可能会违反 hashCode 约定的第二条。

步骤 2.b 中的乘法计算结果取决于属性的顺序，如果类中具有多个相似属性，则产生更好的散列函数。例如，如果乘法计算从一个 String 散列函数中被省略，则所有的字符将具有相同的散列码。之所以选择 31，因为它是一个奇数的素数。如果它是偶数，并且乘法溢出，信息将会丢失，因为乘以 2 相当于移位。使用素数的好处不太明显，但习惯上都是这么做的。 31 的一个很好的特性，是在一些体系结构中乘法可以被替换为移位和减法以获得更好的性能：31 * i ==（i << 5） - i。现代 JVM 可以自动进行这种优化。

让我们把上述办法应用到 PhoneNumber 类中：

// Typical hashCode method
@Override
public int hashCode() {
    int result = Short.hashCode(areaCode);
    result = 31 * result + Short.hashCode(prefix);
    result = 31 * result + Short.hashCode(lineNum);
    return result;
}

因为这个方法返回一个简单的确定性计算的结果，它的唯一的输入是 PhoneNumber 实例中的三个重要的属性，所以显然相等的 PhoneNumber 实例具有相同的哈希码。实际上，这个方法是 PhoneNumber 的一个非常好的 hashCode 实现，与 Java 平台类库中的实现一样。它很简单，速度相当快，并且合理地将不相同的电话号码分散到不同的哈希桶中。

虽然在这个项目的方法产生相当好的哈希函数，但并不是最先进的。它们的质量与 Java 平台类库的值类型中找到的哈希函数相当，对于大多数用途来说都是足够的。如果真的需要哈希函数而不太可能产生碰撞，请参阅 Guava 框架的的[com.google.common.hash.Hashing][1] [Guava] 方法。

Objects 类有一个静态方法，它接受任意数量的对象并为它们返回一个哈希码。这个名为 hash 的方法可以让你编写一行 hashCode 方法，其质量与根据这个项目中的上面编写的方法相当。不幸的是，它们的运行速度更慢，因为它们需要创建数组以传递可变数量的参数，以及如果任何参数是基本类型，则进行装箱和取消装箱。这种哈希函数的风格建议仅在性能不重要的情况下使用。以下是使用这种技术编写的 PhoneNumber 的哈希函数：

// One-line hashCode method - mediocre performance
@Override
public int hashCode() {
   return Objects.hash(lineNum, prefix, areaCode);
}

如果一个类是不可变的，并且计算哈希码的代价很大，那么可以考虑在对象中缓存哈希码，而不是在每次请求时重新计算哈希码。如果你认为这种类型的大多数对象将被用作哈希键，那么应该在创建实例时计算哈希码。否则，可以选择在首次调用 hashCode 时延迟初始化（lazily initialize）哈希码。需要注意确保类在存在延迟初始化属性的情况下保持线程安全（项目 83）。 PhoneNumber 类不适合这种情况，但只是为了展示它是如何完成的。请注意，属性 hashCode 的初始值（在本例中为 0）不应该是通常创建的实例的哈希码：

// hashCode method with lazily initialized cached hash code
private int hashCode; // Automatically initialized to 0

@Override
public int hashCode() {
    int result = hashCode;
    if (result == 0) {
        result = Short.hashCode(areaCode);
        result = 31 * result + Short.hashCode(prefix);
        result = 31 * result + Short.hashCode(lineNum);
        hashCode = result;
    }
    return result;
}

不要试图从哈希码计算中排除重要的属性来提高性能。 由此产生的哈希函数可能运行得更快，但其质量较差可能会降低哈希表的性能，使其无法使用。具体来说，哈希函数可能会遇到大量不同的实例，这些实例主要在你忽略的区域中有所不同。如果发生这种情况，哈希函数将把所有这些实例映射到少许哈希码上，而应该以线性时间运行的程序将会运行平方级的时间。

这不仅仅是一个理论问题。在 Java 2 之前，String 类哈希函数在整个字符串中最多使用 16 个字符，从第一个字符开始，在整个字符串中均匀地选取。对于大量的带有层次名称的集合（如 URL），此功能正好显示了前面描述的病态行为。

不要为 hashCode 返回的值提供详细的规范，因此客户端不能合理地依赖它；你可以改变它的灵活性。 Java 类库中的许多类（例如 String 和 Integer）都将 hashCode 方法返回的确切值指定为实例值的函数。这不是一个好主意，而是一个我们不得不忍受的错误：它妨碍了在未来版本中改进哈希函数的能力。如果未指定细节并在散列函数中发现缺陷，或者发现了更好的哈希函数，则可以在后续版本中对其进行更改。

总之，每次重写 equals 方法时都必须重写 hashCode 方法，否则程序将无法正常运行。你的 hashCode 方法必须遵从 Object 类指定的常规约定，并且必须执行合理的工作，将不相等的哈希码分配给不相等的实例。如果使用第 51 页的配方，这很容易实现。如条目 10 所述，AutoValue 框架为手动编写 equals 和 hashCode 方法提供了一个很好的选择，IDE 也提供了一些这样的功能。

[1]: https://github.com/google/guava/blob/master/guava/src/com/google/common/hash/Hashing.java

13. 谨慎地重写 clone 方法

发表于 2022-10-29 更新于 2024-06-07

13. 谨慎地重写 clone 方法

Cloneable 接口的目的是作为一个 mixin 接口（详见第 20 条），公布这样的类允许克隆。不幸的是，它没有达到这个目的。它的主要缺点是缺少 clone 方法，而 Object 的 clone 方法是受保护的。你不能，不借助反射（详见第 65 条），仅仅因为它实现了 Cloneable 接口，就调用对象上的 clone 方法。即使是反射调用也可能失败，因为不能保证对象具有可访问的 clone 方法。尽管存在许多缺陷，该机制在合理的范围内使用，所以理解它是值得的。这个条目告诉你如何实现一个行为良好的 clone 方法，在适当的时候讨论这个方法，并提出替代方案。

既然 Cloneable 接口不包含任何方法，那它用来做什么？它决定了 Object 的受保护的 clone 方法实现的行为：如果一个类实现了 Cloneable 接口，那么 Object 的 clone 方法将返回该对象的逐个属性（field-by-field）拷贝；否则会抛出 CloneNotSupportedException 异常。这是一个非常反常的接口使用，而不应该被效仿。通常情况下，实现一个接口用来表示可以为客户做什么。但对于 Cloneable 接口，它会修改父类上受保护方法的行为。

虽然规范并没有说明，但在实践中，实现 Cloneable 接口的类希望提供一个正常运行的公共 clone 方法。为了实现这一目标，该类及其所有父类必须遵循一个复杂的、不可执行的、稀疏的文档协议。由此产生的机制是脆弱的、危险的和不受语言影响的（extralinguistic）：它创建对象而不需要调用构造方法。

clone 方法的通用规范很薄弱的。以下内容是从 Object 规范中复制出来的：

创建并返回此对象的副本。「复制（copy）」的确切含义可能取决于对象的类。一般意图是，对于任何对象 x，表达式 x.clone() != x 返回 true，并且 x.clone().getClass() == x.getClass() 也返回 true，但它们不是绝对的要求，但通常情况下，x.clone().equals(x) 返回 true，当然这个要求也不是绝对的。

根据约定，这个方法返回的对象应该通过调用 super.clone 方法获得的。如果一个类和它的所有父类（Object 除外）都遵守这个约定，情况就是如此，x.clone().getClass() == x.getClass()。

根据约定，返回的对象应该独立于被克隆的对象。为了实现这种独立性，在返回对象之前，可能需要修改由 super.clone 返回的对象的一个或多个属性。

这种机制与构造方法链（chaining）很相似，只是它没有被强制执行；如果一个类的 clone 方法返回一个通过调用构造方法获得而不是通过调用 super.clone 的实例，那么编译器不会抱怨，但是如果一个类的子类调用了 super.clone，那么返回的对象包含错误的类，从而阻止子类 clone 方法正常执行。如果一个类重写的 clone 方法是有 final 修饰的，那么这个约定可以被安全地忽略，因为子类不需要担心。但是，如果一个 final 类有一个不调用 super.clone 的 clone 方法，那么这个类没有理由实现 Cloneable 接口，因为它不依赖于 Object 的 clone 实现的行为。

假设你希望在一个类中实现 Cloneable 接口，它的父类提供了一个行为良好的 clone 方法。首先调用 super.clone。得到的对象将是原始的完全功能的复制品。在你的类中声明的任何属性将具有与原始属性相同的值。如果每个属性包含原始值或对不可变对象的引用，则返回的对象可能正是你所需要的，在这种情况下，不需要进一步的处理。例如，对于条目 11 中的 PhoneNumber 类，情况就是这样，但是请注意，不可变类永远不应该提供 clone 方法，因为这只会浪费复制。有了这个警告，以下是 PhoneNumber 类的 clone 方法：

// Clone method for class with no references to mutable state
@Override public PhoneNumber clone() {
    try {
        return (PhoneNumber) super.clone();
    } catch (CloneNotSupportedException e) {
        throw new AssertionError();  // Can't happen
    }
}

为了使这个方法起作用，PhoneNumber 的类声明必须被修改，以表明它实现了 Cloneable 接口。虽然 Object 类的 clone 方法返回 Object 类，但是这个 clone 方法返回 PhoneNumber 类。这样做是合法和可取的，因为 Java 支持协变返回类型。换句话说，重写方法的返回类型可以是重写方法的返回类型的子类。这消除了在客户端转换的需要。在返回之前，我们必须将 Object 的 super.clone 的结果强制转换为 PhoneNumber，但保证强制转换成功。

super.clone 的调用包含在一个 try-catch 块中。这是因为 Object 声明了它的 clone 方法来抛出 CloneNotSupportedException 异常，这是一个检查时异常。由于 PhoneNumber 实现了 Cloneable 接口，所以我们知道调用 super.clone 会成功。这里引用的需要表明 CloneNotSupportedException 应该是未被检查的（详见第 71条）。

如果对象包含引用可变对象的属性，则前面显示的简单 clone 实现可能是灾难性的。例如，考虑条目 7 中的 Stack 类：

public class Stack {

    private Object[] elements;
    private int size = 0;
    private static final int DEFAULT_INITIAL_CAPACITY = 16;

    public Stack() {
        this.elements = new Object[DEFAULT_INITIAL_CAPACITY];
    }

    public void push(Object e) {
        ensureCapacity();
        elements[size++] = e;
    }

    public Object pop() {
        if (size == 0)
            throw new EmptyStackException();
        Object result = elements[--size];

        elements[size] = null; // Eliminate obsolete reference
        return result;
    }

    // Ensure space for at least one more element.
    private void ensureCapacity() {
        if (elements.length == size)
            elements = Arrays.copyOf(elements, 2 * size + 1);
    }
}

假设你想让这个类可以克隆。如果 clone 方法仅返回 super.clone() 调用的对象，那么生成的 Stack 实例在其 size 属性中具有正确的值，但 elements 属性引用与原始 Stack 实例相同的数组。修改原始实例将破坏克隆中的不变量，反之亦然。你会很快发现你的程序产生了无意义的结果，或者抛出 NullPointerException 异常。

这种情况永远不会发生，因为调用 Stack 类中的唯一构造方法。实际上，clone 方法作为另一种构造方法; 必须确保它不会损坏原始对象，并且可以在克隆上正确建立不变量。为了使 Stack 上的 clone 方法正常工作，它必须复制 stack 对象的内部。最简单的方法是对元素数组递归调用 clone 方法：

// Clone method for class with references to mutable state
@Override public Stack clone() {
    try {
        Stack result = (Stack) super.clone();
        result.elements = elements.clone();
        return result;
    } catch (CloneNotSupportedException e) {
        throw new AssertionError();
    }
}

请注意，我们不必将 elements.clone 的结果转换为 Object[] 数组。在数组上调用 clone 会返回一个数组，其运行时和编译时类型与被克隆的数组相同。这是复制数组的首选习语。事实上，数组是 clone 机制的唯一有力的用途。

还要注意，如果 elements 属性是 final 的，则以前的解决方案将不起作用，因为克隆将被禁止向该属性分配新的值。这是一个基本的问题：像序列化一样，Cloneable 体系结构与引用可变对象的 final 属性的正常使用不兼容，除非可变对象可以在对象和其克隆之间安全地共享。为了使一个类可以克隆，可能需要从一些属性中移除 final 修饰符。

仅仅递归地调用 clone 方法并不总是足够的。例如，假设您正在为哈希表编写一个 clone 方法，其内部包含一个哈希桶数组，每个哈希桶都指向「键-值」对链表的第一项。为了提高性能，该类实现了自己的轻量级单链表，而没有使用 java 内部提供的 java.util.LinkedList：

public class HashTable implements Cloneable {
    private Entry[] buckets = ...;
    private static class Entry {
        final Object key;
        Object value;
        Entry  next;

        Entry(Object key, Object value, Entry next) {
            this.key   = key;
            this.value = value;
            this.next  = next;
        }
    }
    ... // Remainder omitted
}

假设你只是递归地克隆哈希桶数组，就像我们为 Stack 所做的那样：

// Broken clone method - results in shared mutable state!
@Override public HashTable clone() {
    try {
        HashTable result = (HashTable) super.clone();
        result.buckets = buckets.clone();
        return result;
    } catch (CloneNotSupportedException e) {
        throw new AssertionError();
    }
}

虽然被克隆的对象有自己的哈希桶数组，但是这个数组引用与原始数组相同的链表，这很容易导致克隆对象和原始对象中的不确定性行为。要解决这个问题，你必须复制包含每个桶的链表。下面是一种常见的方法：

// Recursive clone method for class with complex mutable state
public class HashTable implements Cloneable {
    private Entry[] buckets = ...;

    private static class Entry {
        final Object key;
        Object value;
        Entry  next;

        Entry(Object key, Object value, Entry next) {
            this.key   = key;
            this.value = value;
            this.next  = next;
        }

        // Recursively copy the linked list headed by this Entry
        Entry deepCopy() {
            return new Entry(key, value,
                next == null ? null : next.deepCopy());
        }
    }

    @Override public HashTable clone() {
        try {
            HashTable result = (HashTable) super.clone();
            result.buckets = new Entry[buckets.length];
            for (int i = 0; i < buckets.length; i++)
                if (buckets[i] != null)
                    result.buckets[i] = buckets[i].deepCopy();
            return result;
        } catch (CloneNotSupportedException e) {
            throw new AssertionError();
        }
    }
    ... // Remainder omitted
}

私有类 HashTable.Entry 已被扩充以支持「深度复制」方法。 HashTable 上的 clone 方法分配一个合适大小的新哈希桶数组，迭代原来哈希桶数组，深度复制每个非空的哈希桶。 Entry 上的 deepCopy 方法递归地调用它自己以复制由头节点开始的整个链表。如果哈希桶不是太长，这种技术很聪明并且工作正常。但是，克隆链表不是一个好方法，因为它为列表中的每个元素消耗一个栈帧（stack frame）。如果列表很长，这很容易导致堆栈溢出。为了防止这种情况发生，可以用迭代来替换 deepCopy 中的递归：

// Iteratively copy the linked list headed by this Entry
Entry deepCopy() {
   Entry result = new Entry(key, value, next);
   for (Entry p = result; p.next != null; p = p.next)
      p.next = new Entry(p.next.key, p.next.value, p.next.next);
   return result;
}

克隆复杂可变对象的最后一种方法是调用 super.clone，将结果对象中的所有属性设置为其初始状态，然后调用更高级别的方法来重新生成原始对象的状态。以 HashTable 为例，bucket 属性将被初始化为一个新的 bucket 数组，并且 put(key, value) 方法（未示出）被调用用于被克隆的哈希表中的键值映射。这种方法通常产生一个简单，合理的优雅 clone 方法，其运行速度不如直接操纵克隆内部的方法快。虽然这种方法是干净的，但它与整个 Cloneable 体系结构是对立的，因为它会盲目地重写构成体系结构基础的逐个属性对象复制。

与构造方法一样，clone 方法绝对不可以在构建过程中，调用一个可以重写的方法（详见第 19 条）。如果 clone 方法调用一个在子类中重写的方法，则在子类有机会在克隆中修复它的状态之前执行该方法，很可能导致克隆和原始对象的损坏。因此，我们在前面讨论的 put(key, value) 方法应该是 final 或 private 修饰的。（如果是 private 修饰，那么大概是一个非 final 公共方法的辅助方法）。

Object 类的 clone 方法被声明为抛出 CloneNotSupportedException 异常，但重写方法时不需要。公共 clone 方法应该省略 throws 子句，因为不抛出检查时异常的方法更容易使用（详见第 71 条）。

在为继承设计一个类时（详见第 19 条），通常有两种选择，但无论选择哪一种，都不应该实现 Clonable 接口。你可以选择通过实现正确运行的受保护的 clone 方法来模仿 Object 的行为，该方法声明为抛出 CloneNotSupportedException 异常。这给了子类实现 Cloneable 接口的自由，就像直接继承 Object 一样。或者，可以选择不实现工作的 clone 方法，并通过提供以下简并 clone 实现来阻止子类实现它：

// clone method for extendable class not supporting Cloneable
@Override
protected final Object clone() throws CloneNotSupportedException {
    throw new CloneNotSupportedException();
}

还有一个值得注意的细节。如果你编写一个实现了 Cloneable 的线程安全的类，记得它的 clone 方法必须和其他方法一样（详见第 78 条）需要正确的同步。 Object 类的 clone 方法是不同步的，所以即使它的实现是令人满意的，也可能需要编写一个返回 super.clone() 的同步 clone 方法。

回顾一下，实现 Cloneable 的所有类应该重写公共 clone 方法，而这个方法的返回类型是类本身。这个方法应该首先调用 super.clone，然后修复任何需要修复的属性。通常，这意味着复制任何包含内部「深层结构」的可变对象，并用指向新对象的引用来代替原来指向这些对象的引用。虽然这些内部拷贝通常可以通过递归调用 clone 来实现，但这并不总是最好的方法。如果类只包含基本类型或对不可变对象的引用，那么很可能是没有属性需要修复的情况。这个规则也有例外。例如，表示序列号或其他唯一 ID 的属性即使是基本类型的或不可变的，也需要被修正。

这么复杂是否真的有必要？很少。如果你继承一个已经实现了 Cloneable 接口的类，你别无选择，只能实现一个行为良好的 clone 方法。否则，通常你最好提供另一种对象复制方法。对象复制更好的方法是提供一个复制构造方法或复制工厂。复制构造方法接受参数，其类型为包含此构造方法的类，例如：

1 2	// Copy constructor public Yum(Yum yum) { ... };

复制工厂类似于复制构造方法的静态工厂：

1 2	// Copy factory public static Yum newInstance(Yum yum) { ... };

复制构造方法及其静态工厂变体与 Cloneable/clone 相比有许多优点：它们不依赖风险很大的语言外的对象创建机制；不要求遵守那些不太明确的惯例；不会与 final 属性的正确使用相冲突; 不会抛出不必要的检查异常; 而且不需要类型转换。

此外，复制构造方法或复制工厂可以接受类型为该类实现的接口的参数。例如，按照惯例，所有通用集合实现都提供了一个构造方法，其参数的类型为 Collection 或 Map。基于接口的复制构造方法和复制工厂（更适当地称为转换构造方法和转换工厂）允许客户端选择复制的实现类型，而不是强制客户端接受原始实现类型。例如，假设你有一个 HashSet，并且你想把它复制为一个 TreeSet。 clone 方法不能提供这种功能，但使用转换构造方法很容易：new TreeSet<>(s)。

考虑到与 Cloneable 接口相关的所有问题，新的接口不应该继承它，新的可扩展类不应该实现它。虽然实现 Cloneable 接口对于 final 类没有什么危害，但应该将其视为性能优化的角度，仅在极少数情况下才是合理的（详见第 67 条）。通常，复制功能最好由构造方法或工厂提供。这个规则的一个明显的例外是数组，它最好用 clone 方法复制。

17. 最小化可变性

发表于 2022-10-29 更新于 2024-06-07

17. 最小化可变性

不可变类简单来说是其实例不能被修改的类。包含在每个实例中的所有信息在对象的生命周期中是固定的，因此不会观察到任何变化。 Java 平台类库包含许多不可变的类，包括 String 类、基本类型包装类以及 BigInteger 类和 BigDecimal 类。有很多很好的理由：不可变类比可变类更易于设计，实现和使用。他们不容易出错，并且更安全。

要使一个类成为不可变类，请遵循以下五条规则：

不要提供修改对象状态的方法（也称为 mutators，设值方法）。
确保这个类不能被继承。 这可以防止粗心或者恶意的子类假装对象的状态已经改变，从而破坏类的不可变行为。防止子类化，通常是通过 final 修饰类，但是我们稍后将讨论另一种方法。
把所有字段设置为 final。 通过系统强制执行的方式，清楚地表达了你的意图。另外，如果一个新创建的实例的引用在缺乏同步机制的情况下从一个线程传递到另一个线程，就必须保证正确的行为，正如内存模型[JLS，17.5; Goetz06 16] 所述。
把所有的字段设置为 private。 这可以防止客户端获得对字段引用的可变对象的访问权限，并直接修改这些对象。虽然技术上允许不可变类具有包含基本类型数值的公有的 final 字段或对不可变对象的引用，但不建议这样做，因为这样使得在以后的版本中无法再改变内部的表示状态（详见第 15 和 16 条）。
确保对任何可变组件的互斥访问。 如果你的类有任何引用可变对象的字段，请确保该类的客户端无法获得对这些对象的引用。切勿将这样的属性初始化为客户端提供的对象引用，或从访问方法返回属性。在构造方法，访问方法和 readObject 方法（详见第 88 条）中进行防御性拷贝（详见第 50 条）。

以前条目中的许多示例类都是不可变的。其中一个例子是条目 11 中的 PhoneNumber 类，它具有每个字段的访问方法（accessors），但没有相应的设值方法（mutators）。下面一个稍微复杂一点的例子：

// Immutable complex number class
public final class Complex {

    private final double re;
    private final double im;

    public Complex(double re, double im) {
        this.re = re;
        this.im = im;
    }

    public double realPart() {
        return re;
    }

    public double imaginaryPart() {
        return im;
    }

    public Complex plus(Complex c) {
        return new Complex(re + c.re, im + c.im);
    }

    public Complex minus(Complex c) {
        return new Complex(re - c.re, im - c.im);
    }

    public Complex times(Complex c) {
        return new Complex(re * c.re - im * c.im,
                re * c.im + im * c.re);
    }

    public Complex dividedBy(Complex c) {
        double tmp = c.re * c.re + c.im * c.im;
        return new Complex((re * c.re + im * c.im) / tmp,
                (im * c.re - re * c.im) / tmp);
    }

    @Override
    public boolean equals(Object o) {
        if (o == this) {
            return true;
        }

        if (!(o instanceof Complex)) {
            return false;
        }

        Complex c = (Complex) o;

        // See page 47 to find out why we use compare instead of ==
        return Double.compare(c.re, re) == 0
                && Double.compare(c.im, im) == 0;
    }

    @Override
    public int hashCode() {
        return 31 * Double.hashCode(re) + Double.hashCode(im);
    }

    @Override
    public String toString() {
        return "(" + re + " + " + im + "i)";
    }
}

这个类代表了一个复数（包含实部和虚部的数字）。除了标准的 Object 方法之外，它还为实部和虚部提供访问方法，并提供四个基本的算术运算：加法，减法，乘法和除法。注意算术运算如何创建并返回一个新的 Complex 实例，而不是修改这个实例。这种模式被称为函数式方法，因为方法返回将操作数应用于函数的结果，而不修改它们。与其对应的过程式的（procedural）或命令式的（imperative）的方法相对比，在这种方法中，将一个过程作用在操作数上，导致其状态改变。请注意，方法名称是介词（如 plus）而不是动词（如 add）。这强调了方法不会改变对象的值的事实。 BigInteger 和 BigDecimal 类没有遵守这个命名约定，并导致许多使用错误。

如果你不熟悉函数式方法，可能会觉得它显得不自然，但它具有不变性，具有许多优点。 不可变对象很简单。 一个不可变的对象可以完全处于一种状态，也就是被创建时的状态。如果确保所有的构造方法都建立了类不变量，那么就保证这些不变量在任何时候都保持不变，使用此类的程序员无需再做额外的工作。另一方面，可变对象可以具有任意复杂的状态空间。如果文档没有提供由设置（mutator）方法执行的状态转换的精确描述，那么可靠地使用可变类可能是困难的或不可能的。

不可变对象本质上是线程安全的；它们不需要同步。 被多个线程同时访问它们时，不会遭到破坏。这是实现线程安全的最简单方法。由于没有线程可以观察到另一个线程对不可变对象的影响，所以不可变对象可以被自由地共享。 因此，不可变类应鼓励客户端尽可能重用现有的实例。一个简单的方法是为常用的值提供公共的静态 final 常量。例如，Complex 类可能提供这些常量：

1
2
3

public static final Complex ZERO = new Complex(0, 0);
public static final Complex ONE  = new Complex(1, 0);
public static final Complex I    = new Complex(0, 1);

这种方法可以更进一步。一个不可变的类可以提供静态的工厂（详见第 1 条）来缓存经常被请求的实例，以避免在现有的实例中创建新的实例。所有基本类型的包装类和 BigInteger 类都是这样做的。使用这样的静态工厂会使客户端共享实例而不是创建新实例，从而减少内存占用和垃圾回收成本。在设计新类时，选择静态工厂代替公共构造方法，可以在以后增加缓存的灵活性，而不需要修改客户端。

不可变对象可以自由分享的结果是，你永远不需要做出防御性拷贝（defensive copies）（详见第 50 条）。事实上，永远不需要做任何拷贝，因为这些拷贝永远等于原始对象。因此，你不需要也不应该在一个不可变的类上提供一个 clone 方法或拷贝构造方法（copy constructor）（详见第 13 条）。这一点在 Java 平台的早期阶段还不是很好理解，所以 String 类有一个拷贝构造方法，但是它应该尽量很少使用（详见第 6 条）。

不仅可以共享不可变的对象，而且可以共享内部信息。 例如，BigInteger 类在内部使用符号数值表示法。符号用 int 值表示，数值用 int 数组表示。 negate 方法生成了一个数值相同但符号相反的新 BigInteger 实例。即使它是可变的，也不需要复制数组；新创建的 BigInteger 指向与原始相同的内部数组。

不可变对象为其他对象提供了很好的构件（building blocks），无论是可变的还是不可变的。如果知道一个复杂组件的内部对象不会发生改变，那么维护复杂对象的不变性就容易多了。不可变对象是优秀的映射键和集合元素是这一原则的重要例子: 一旦不可变对象作为 Map 的键或 Set 里的元素，你就不需要担心Map 或 Set 的不变性被这些对象的值的变化所破坏。

不可变对象无偿地提供了的原子失败机制（详见第 76 条）。 它们的状态永远不会改变，所以不可能出现临时的不一致。

不可变类的主要缺点是对于每个不同的值都需要一个单独的对象。 创建这些对象可能代价很高，特别是是大型的对象下。例如，假设你有一个百万位的 BigInteger ，你想改变它的低位：

1 2	BigInteger moby = ...; moby = moby.flipBit(0);

flipBit 方法创建一个新的 BigInteger 实例，也是一百万位长，与原始位置只有一位不同。该操作需要与 BigInteger 大小成比例的时间和空间。将其与 java.util.BitSet 对比。像 BigInteger 一样，BitSet 表示一个任意长度的位序列，但与 BigInteger 不同，BitSet 是可变的。 BitSet 类提供了一种方法，允许你在固定时间内更改百万位实例中单个位的状态：

1 2	BitSet moby = ...; moby.flip(0);

如果执行一个多步操作，在每一步生成一个新对象，除最终结果之外丢弃所有对象，则性能问题会被放大。这里有两种方式来处理这个问题。第一种办法，先猜测一下会经常用到哪些多步的操作，然后讲它们作为基本类型提供。如果一个多步操作是作为一个基本类型提供的，那么不可变类就不必在每一步创建一个独立的对象。在内部，不可变的类可以是任意灵活的。例如，BigInteger 有一个包级私有的可变的“伙伴类（companion class）”，它用来加速多步操作，比如模幂运算（modular exponentiation）。出于前面所述的所有原因，使用可变伙伴类比使用 BigInteger 要困难得多。幸运的是，你不必使用它：BigInteger 类的实现者为你做了很多努力。

如果你可以准确预测客户端要在你的不可变类上执行哪些复杂的操作，那么包级私有可变伙伴类的方式可以正常工作。如果不是的话，那么最好的办法就是提供一个公开的可变伙伴类。这种方法在 Java 平台类库中的主要例子是 String 类，它的可变伙伴类是 StringBuilder（及其过时的前身 StringBuffer 类）。

现在你已经知道如何创建一个不可改变类，并且了解不变性的优点和缺点，下面我们来讨论几个设计方案。回想一下，为了保证不变性，一个类不得允许子类化。这可以通过使类用 final 修饰，但是还有另外一个更灵活的选择。而不是使不可变类设置为 final，可以使其所有的构造方法私有或包级私有，并添加公共静态工厂，而不是公共构造方法（详见第 1 条）。为了具体说明这种方法，下面以 Complex 为例，看看如何使用这种方法：

// Immutable class with static factories instead of constructors
public class Complex {

    private final double re;
    private final double im;

    private Complex(double re, double im) {
        this.re = re;
        this.im = im;
    }

    public static Complex valueOf(double re, double im) {
        return new Complex(re, im);
    }

    ... // Remainder unchanged
}

这种方法往往是最好的选择。这是最灵活的，因为它允许使用多个包级私有实现类。对于驻留在包之外的客户端，不可变类实际上是 final 的，因为不可能继承来自另一个包的类，并且缺少公共或受保护的构造方法。除了允许多个实现类的灵活性以外，这种方法还可以通过改进静态工厂的对象缓存功能来调整后续版本中类的性能。

当 BigInteger 和 BigDecimal 刚被编写出来的时候，“不可变类必须是 final”的说法还没有得到广泛地理解，因此它们的所有方法都可能被重写。不幸的是，为了保持向后兼容性，这一问题无法得以纠正。如果你编写一个安全性取决于来自不受信任的客户端的 BigInteger 或 BigDecimal 参数的不变类时，则必须检查该参数是否为“真实的”BigInteger 或者 BigDecimal，而不应该是不受信任的子类的实例。如果是后者，则必须在假设可能是可变的情况下保护性拷贝（defensively copy）（详见第 50 条）：

public static BigInteger safeInstance(BigInteger val) {
    return val.getClass() == BigInteger.class ?
            val : new BigInteger(val.toByteArray());
}

在本条目开头关于不可变类的规则说明，没有方法可以修改对象，并且它的所有属性必须是 final 的。事实上，这些规则比实际需要的要强硬一些，其实可以有所放松来提高性能。事实上，任何方法都不能在对象的状态中产生外部可见的变化。然而，一些不可变类具有一个或多个非 final 属性，在第一次需要时将开销昂贵的计算结果缓存在这些属性中。如果再次请求相同的值，则返回缓存的值，从而节省了重新计算的成本。这个技巧的作用恰恰是因为对象是不可变的，这保证了如果重复的话，计算会得到相同的结果。

例如，PhoneNumber 类的 hashCode 方法（详见第 11 条）在第一次调用改方法时计算哈希码，并在再次调用时对其进行缓存。这种延迟初始化（详见第 83 条）的一个例子，String 类也使用到了。

关于序列化应该加上一个警告。如果你选择使您的不可变类实现 Serializable 接口，并且它包含一个或多个引用可变对象的属性，则必须提供显式的 readObject 或 readResolve 方法，或者使用 ObjectOutputStream.writeUnshared 和 ObjectInputStream.readUnshared 方法，即默认的序列化形式也是可以接受的。否则攻击者可能会创建一个可变的类的实例。这个主题会在条目 88 中会详细介绍。

总而言之，坚决不要为每个属性编写一个 get 方法后再编写一个对应的 set 方法。 除非有充分的理由使类成为可变类，否则类应该是不可变的。 不可变类提供了许多优点，唯一的缺点是在某些情况下可能会出现性能问题。你应该始终使用较小的值对象（如 PhoneNumber 和 Complex），使其不可变。（Java 平台类库中有几个类，如 java.util.Date 和 java.awt.Point，本应该是不可变的，但实际上并不是）。你应该认真考虑创建更大的值对象，例如 String 和 BigInteger ，设成不可改变的。只有当你确认有必要实现令人满意的性能（详见第 67 条）时，才应该为不可改变类提供一个公开的可变伙伴类。

对于一些类来说，不变性是不切实际的。如果一个类不能设计为不可变类，那么也要尽可能地限制它的可变性 。减少对象可以存在的状态数量，可以更容易地分析对象，以及降低出错的可能性。因此，除非有足够的理由把属性设置为非 final 的情况下，否则应该每个属性都设置为 final 的。把本条目的建议与条目 15 的建议结合起来，你自然的倾向就是：除非有充分的理由不这样做，否则应该把每个属性声明为私有 final 的。

构造方法应该创建完全初始化的对象，并建立所有的不变性。 除非有令人信服的理由，否则不要提供独立于构造方法或静态工厂的公共初始化方法。同样，不要提供一个“reinitialize”方法，使对象可以被重用，就好像它是用不同的初始状态构建的。这样的方法通常以增加的复杂度为代价，仅仅提供很少的性能优势。

CountDownLatch 类是这些原理的例证。它是可变的，但它的状态空间有意保持最小范围内。创建一个实例，使用它一次，并完成：一旦 countdown 锁的计数器已经达到零，不能再重用它。

在这个条目中，应该添加关于 Complex 类的最后一个注释。这个例子只是为了说明不变性。这不是一个工业强度复杂的复数实现。它对复数使用了乘法和除法的标准公式，这些公式不正确会进行不正确的四舍五入，没有为复数的 NaN 和无穷大提供良好的语义[Kahan91，Smith62，Thomas94]。

14. 考虑实现Comparable接口

发表于 2022-10-29 更新于 2024-06-07

14. 考虑实现Comparable接口

14. 考虑实现 Comparable 接口

与本章讨论的其他方法不同，compareTo 方法并没有在 Object 类中声明。相反，它是 Comparable 接口中的唯一方法。它与 Object 类的 equals 方法在性质上是相似的，除了它允许在简单的相等比较之外的顺序比较，它是泛型的。通过实现 Comparable 接口，一个类表明它的实例有一个自然顺序（natural ordering）。对实现 Comparable 接口的对象数组排序非常简单，如下所示：

1	Arrays.sort(a);

它很容易查找，计算极端数值，以及维护 Comparable 对象集合的自动排序。例如，在下面的代码中，依赖于 String 类实现了 Comparable 接口，去除命令行参数输入重复的字符串，并按照字母顺序排序：

public class WordList {

    public static void main(String[] args) {
        Set<String> s = new TreeSet<>();
        Collections.addAll(s, args);
        System.out.println(s);
    }
}

通过实现 Comparable 接口，可以让你的类与所有依赖此接口的通用算法和集合实现进行互操作。只需少量的努力就可以获得巨大的能量。几乎 Java 平台类库中的所有值类以及所有枚举类型（详见第 34 条）都实现了 Comparable 接口。如果你正在编写具有明显自然顺序（如字母顺序，数字顺序或时间顺序）的值类，则应该实现 Comparable 接口：

1
2
3

public interface Comparable<T> {
    int compareTo(T t);
}

compareTo 方法的通用约定与 equals 相似：

将此对象与指定的对象按照排序进行比较。返回值可能为负整数，零或正整数，因为此对象对应小于，等于或大于指定的对象。如果指定对象的类型与此对象不能进行比较，则引发 ClassCastException 异常。

下面的描述中，符号 sgn(expression) 表示数学中的 signum 函数，它根据表达式的值为负数、零、正数，对应返回-1、0 和 1。

实现类必须确保所有 x 和 y 都满足 sgn(x.compareTo(y)) == -sgn(y. compareTo(x))。（这意味着当且仅当 y.compareTo(x) 抛出异常时，x.compareTo(y) 必须抛出异常。）
实现类还必须确保该关系是可传递的：(x. compareTo(y) > 0 && y.compareTo(z) > 0) 意味着 x.compareTo(z) > 0。
最后，对于所有的 z，实现类必须确保 x.compareTo(y) == 0 意味着 sgn(x.compareTo(z)) == sgn(y.compareTo(z))。
强烈推荐 (x.compareTo(y) == 0) == (x.equals(y))，但不是必需的。一般来说，任何实现了 Comparable 接口的类违反了这个条件都应该清楚地说明这个事实。推荐的语言是「注意：这个类有一个自然顺序，与 equals 不一致」。

与 equals 方法一样，不要被上述约定的数学特性所退缩。这个约定并不像看起来那么复杂。与 equals 方法不同，equals 方法在所有对象上施加了全局等价关系，compareTo 不必跨越不同类型的对象：当遇到不同类型的对象时，compareTo 被允许抛出 ClassCastException 异常。通常，这正是它所做的。约定确实允许进行不同类型间比较，这种比较通常在由被比较的对象实现的接口中定义。

正如一个违反 hashCode 约定的类可能会破坏依赖于哈希的其他类一样，违反 compareTo 约定的类可能会破坏依赖于比较的其他类。依赖于比较的类，包括排序后的集合 TreeSet 和 TreeMap 类，以及包含搜索和排序算法的实用程序类 Collections 和 Arrays。

我们来看看 compareTo 约定的规定。第一条规定，如果反转两个对象引用之间的比较方向，则会发生预期的事情：如果第一个对象小于第二个对象，那么第二个对象必须大于第一个; 如果第一个对象等于第二个，那么第二个对象必须等于第一个; 如果第一个对象大于第二个，那么第二个必须小于第一个。第二项约定说，如果一个对象大于第二个对象，而第二个对象大于第三个对象，则第一个对象必须大于第三个对象。最后一条规定，所有比较相等的对象与任何其他对象相比，都必须得到相同的结果。

这三条规定的一个结果是，compareTo 方法所实施的平等测试必须遵守 equals 方法约定所施加的相同限制：自反性，对称性和传递性。因此，同样需要注意的是：除非你愿意放弃面向对象抽象（详见第 10 条）的好处，否则无法在保留 compareTo 约定的情况下使用新的值组件继承可实例化的类。同样的解决方法也适用。如果要将值组件添加到实现 Comparable 的类中，请不要继承它；编写一个包含第一个类实例的不相关的类。然后提供一个返回包含实例的「视图”方法。这使你可以在包含类上实现任何 compareTo 方法，同时客户端在需要时，把包含类的实例视同以一个类的实例。

compareTo 约定的最后一段是一个强烈的建议，而不是一个真正的要求，只是声明 compareTo 方法施加的相等性测试，通常应该返回与 equals 方法相同的结果。如果遵守这个约定，则 compareTo 方法施加的顺序被认为与 equals 相一致。如果违反，顺序关系被认为与 equals 不一致。其 compareTo 方法施加与 equals 不一致顺序关系的类仍然有效，但包含该类元素的有序集合可能不服从相应集合接口（Collection，Set 或 Map）的一般约定。这是因为这些接口的通用约定是用 equals 方法定义的，但是排序后的集合使用 compareTo 强加的相等性测试来代替 equals。如果发生这种情况，虽然不是一场灾难，但仍是一件值得注意的事情。

例如，考虑 BigDecimal 类，其 compareTo 方法与 equals 不一致。如果你创建一个空的 HashSet 实例，然后添加 new BigDecimal("1.0") 和 new BigDecimal("1.00")，则该集合将包含两个元素，因为与 equals 方法进行比较时，添加到集合的两个 BigDecimal 实例是不相等的。但是，如果使用 TreeSet 而不是 HashSet 执行相同的过程，则该集合将只包含一个元素，因为使用 compareTo 方法进行比较时，两个 BigDecimal 实例是相等的。（有关详细信息，请参阅 BigDecimal 文档。）

编写 compareTo 方法与编写 equals 方法类似，但是有一些关键的区别。因为 Comparable 接口是参数化的，compareTo 方法是静态类型的，所以你不需要输入检查或者转换它的参数。如果参数是错误的类型，那么调用将不会编译。如果参数为 null，则调用应该抛出一个 NullPointerException 异常，并且一旦该方法尝试访问其成员，它就会立即抛出这个异常。

在 compareTo 方法中，比较属性的顺序而不是相等。要比较对象引用属性，请递归调用 compareTo 方法。如果一个属性没有实现 Comparable，或者你需要一个非标准的顺序，那么使用 Comparator 接口。可以编写自己的比较器或使用现有的比较器，如在条目 10 中的 CaseInsensitiveString 类的 compareTo 方法中：

// Single-field Comparable with object reference field
public final class CaseInsensitiveString
        implements Comparable<CaseInsensitiveString> {
    public int compareTo(CaseInsensitiveString cis) {
        return String.CASE_INSENSITIVE_ORDER.compare(s, cis.s);
    }
    ... // Remainder omitted
}

请注意，CaseInsensitiveString 类实现了 Comparable<CaseInsensitiveString> 接口。这意味着 CaseInsensitiveString 引用只能与另一个 CaseInsensitiveString 引用进行比较。当声明一个类来实现 Comparable 接口时，这是正常模式。

在本书第二版中，曾经推荐如果比较整型基本类型的属性，使用关系运算符「<」和「>」，对于浮点类型基本类型的属性，使用 Double.compare 和 Float.compare 静态方法。在 Java 7 中，静态比较方法被添加到 Java 的所有包装类中。在 compareTo 方法中使用关系运算符「<」和「>」是冗长且容易出错的，不再推荐。

如果一个类有多个重要的属性，那么比较他们的顺序是至关重要的。从最重要的属性开始，逐步比较所有的重要属性。如果比较结果不是零（零表示相等），则表示比较完成; 只是返回结果。如果最重要的字段是相等的，比较下一个重要的属性，依此类推，直到找到不相等的属性或比较剩余不那么重要的属性。以下是条目 11 中 PhoneNumber 类的 compareTo 方法，演示了这种方法：

// Multiple-field `Comparable` with primitive fields
public int compareTo(PhoneNumber pn) {
    int result = Short.compare(areaCode, pn.areaCode);
    if (result == 0) {
        result = Short.compare(prefix, pn.prefix);
        if (result == 0)
            result = Short.compare(lineNum, pn.lineNum);
    }
    return result;
}

在 Java 8 中 Comparator 接口提供了一系列比较器方法，可以使比较器流畅地构建。这些比较器可以用来实现 compareTo 方法，就像 Comparable 接口所要求的那样。许多程序员更喜欢这种方法的简洁性，尽管它的性能并不出众：在我的机器上排序 PhoneNumber 实例的数组速度慢了大约 10％。在使用这种方法时，考虑使用 Java 的静态导入，以便可以通过其简单名称来引用比较器静态方法，以使其清晰简洁。以下是 PhoneNumber 的 compareTo 方法的使用方法：

// Comparable with comparator construction methods
private static final Comparator<PhoneNumber> COMPARATOR =
        comparingInt((PhoneNumber pn) -> pn.areaCode)
          .thenComparingInt(pn -> pn.prefix)
          .thenComparingInt(pn -> pn.lineNum);

public int compareTo(PhoneNumber pn) {
    return COMPARATOR.compare(this, pn);
}

此实现在类初始化时构建比较器，使用两个比较器构建方法。第一个是 comparingInt 方法。它是一个静态方法，它使用一个键提取器函数式接口（key extractor function）作为参数，将对象引用映射为 int 类型的键，并返回一个根据该键排序的实例的比较器。在前面的示例中，comparingInt 方法使用 lambda 表达式，它从 PhoneNumber 中提取区域代码，并返回一个 Comparator<PhoneNumber>，根据它们的区域代码来排序电话号码。注意，lambda 表达式显式指定了其输入参数的类型 (PhoneNumber pn)。事实证明，在这种情况下，Java 的类型推断功能不够强大，无法自行判断类型，因此我们不得不帮助它以使程序编译。

如果两个电话号码实例具有相同的区号，则需要进一步细化比较，这正是第二个比较器构建方法，即 thenComparingInt 方法做的。它是 Comparator 上的一个实例方法，接受一个 int 类型键提取器函数式接口（key extractor function）作为参数，并返回一个比较器，该比较器首先应用原始比较器，然后使用提取的键来打破连接。你可以按照喜欢的方式多次调用 thenComparingInt 方法，从而产生一个字典顺序。在上面的例子中，我们将两个调用叠加到 thenComparingInt，产生一个排序，它的二级键是 prefix，而其三级键是 lineNum。请注意，我们不必指定传递给 thenComparingInt 的任何一个调用的键提取器函数式接口的参数类型：Java 的类型推断足够聪明，可以自己推断出参数的类型。

Comparator 类具有完整的构建方法。对于 long 和 double 基本类型，也有对应的类似于 comparingInt 和 thenComparingInt 的方法，int 版本的方法也可以应用于取值范围小于 int 的类型上，如 short 类型，如 PhoneNumber 实例中所示。对于 double 版本的方法也可以用在 float 类型上。这提供了所有 Java 的基本数字类型的覆盖。

也有对象引用类型的比较器构建方法。静态方法 comparing 有两个重载方式。第一个方法使用键提取器函数式接口并按键的自然顺序。第二种方法是键提取器函数式接口和比较器，用于键的排序。thenComparing 方法有三种重载。第一个重载只需要一个比较器，并使用它来提供一个二级排序。第二次重载只需要一个键提取器函数式接口，并使用键的自然顺序作为二级排序。最后的重载方法同时使用一个键提取器函数式接口和一个比较器来用在提取的键上。

有时，你可能会看到 compareTo 或 compare 方法依赖于两个值之间的差值，如果第一个值小于第二个值，则为负；如果两个值相等则为零，如果第一个值大于，则为正值。这是一个例子：

// BROKEN difference-based comparator - violates transitivity!

static Comparator<Object> hashCodeOrder = new Comparator<>() {
    public int compare(Object o1, Object o2) {
        return o1.hashCode() - o2.hashCode();
    }
};

不要使用这种技术！它可能会导致整数最大长度溢出和 IEEE 754 浮点运算失真的危险[JLS 15.20.1,15.21.1]。此外，由此产生的方法不可能比使用上述技术编写的方法快得多。使用静态 compare 方法：

// Comparator based on static compare method
static Comparator<Object> hashCodeOrder = new Comparator<>() {
    public int compare(Object o1, Object o2) {
        return Integer.compare(o1.hashCode(), o2.hashCode());
    }
};

或者使用 Comparator 的构建方法：

1
2
3

// Comparator based on Comparator construction method
static Comparator<Object> hashCodeOrder =
        Comparator.comparingInt(o -> o.hashCode());

总而言之，无论何时实现具有合理排序的值类，你都应该让该类实现 Comparable 接口，以便在基于比较的集合中轻松对其实例进行排序，搜索和使用。比较 compareTo 方法的实现中的字段值时，请避免使用「<」和「>」运算符。相反，使用包装类中的静态 compare 方法或 Comparator 接口中的构建方法。

56. 为所有已公开的 API 元素编写文档注释

发表于 2022-10-29 更新于 2024-06-07

56. 为所有已公开的 API 元素编写文档注释

如果 API 要可用，就必须对其进行文档化。传统上，API 文档是手工生成的，保持文档与代码的同步是一件苦差事。Java 编程环境使用 Javadoc 实用程序简化了这一任务。Javadoc 使用特殊格式的文档注释 (通常称为 doc 注释)，从源代码自动生成 API 文档。

虽然文档注释约定不是 Java 语言的正式一部分，但它们构成了每个 Java 程序员都应该知道的事实上的 API。「如何编写文档注释（How to Write Doc Comments）」的网页[Javadoc-guide] 中介绍了这些约定。虽然自 Java 4 发布以来该页面尚未更新，但它仍然是一个非常宝贵的资源。 Java 9 中添加了一个重要的文档标签，{@ index}； Java 8 中有一个，{@implSpec}；Java 5 中有两个，{@literal} 和 {@code}。上述网页中缺少这些标签的介绍，但在此条目中进行讨论。

要正确地记录 API，必须在每个导出的类、接口、构造方法、方法和属性声明之前加上文档注释。如果一个类是可序列化的，还应该记录它的序列化形式（详见第 87 条）。在没有文档注释的情况下，Javadoc 可以做的最好的事情是将声明重现为受影响的 API 元素的唯一文档。使用缺少文档注释的 API 是令人沮丧和容易出错的。公共类不应该使用默认构造方法，因为无法为它们提供文档注释。要编写可维护的代码，还应该为大多数未导出的类、接口、构造方法、方法和属性编写文档注释，尽管这些注释不需要像导出 API 元素那样完整。

方法的文档注释应该简洁地描述方法与其客户端之间的契约。除了为继承而设计的类中的方法（详见第 19 条）之外，契约应该说明方法做什么，而不是它如何工作的。文档注释应该列举方法的所有前置条件 (这些条件必须为真，以便客户端调用它们)，以及后置条件（这些条件是在调用成功完成后才为真）。通常，对于未检查的异常，前置条件由 @throw 标签隐式地描述；每个未检查异常对应于一个先决条件违反（ precondition violation）。此外，可以在受影响的参数的 @param 标签中指定前置条件。

除了前置条件和后置条件之外，方法还应在文档中记录它的副作用（side effort）。副作用是系统状态的可观察到的变化，这对于实现后置条件而言显然不是必需的。例如，如果方法启动后台线程，则文档应记录它。

完整地描述方法的契约，文档注释应该为每个参数都有一个 @param 标签，一个 @return 标签 (除非方法有 void 返回类型)，以及一个 @throw 标签（无论是检查异常还是非检查异常）（详见第 74 条）。如果 @return 标签中的文本与方法的描述相同，则可以忽略它，这取决于你所遵循的编码标准。

按照惯例，@param 或 @retur 标签后面的文本应该是一个名词短语，描述参数或返回值所表示的值。很少使用算术表达式代替名词短语; 请参阅 BigInteger 的示例。@throw 标签后面的文本应该包含单词「if」，后面跟着一个描述抛出异常的条件的子句。按照惯例，@param 、@return 或 @throw 标签后面的短语或子句不以句号结束。以下的文档注释说明了所有这些约定:

/**
 * Returns the element at the specified position in this list.
 *
 * <p>This method is <i>not</i> guaranteed to run in constant
 * time. In some implementations it may run in time proportional
 * to the element position.
 *
 * @param  index index of element to return; must be
 *         non-negative and less than the size of this list
 * @return the element at the specified position in this list
 * @throws IndexOutOfBoundsException if the index is out of range
 *         ({@code index < 0 || index >= this.size()})
 */
E get(int index);

请注意在此文档注释（<p>和<i>）中使用 HTML 标记。 Javadoc 实用工具将文档注释转换为 HTML，文档注释中的任意 HTML 元素最终都会生成 HTML 文档。有时候，程序员甚至会在他们的文档注释中嵌入 HTML 表格，尽管这种情况很少见。

还要注意在@throw子句中的代码片段周围使用 Javadoc 的 {@code}标签。这个标签有两个目的:它使代码片段以代码字体形式呈现，并且它抑制了代码片段中 HTML 标记和嵌套 Javadoc 标记的处理。后一个属性允许我们在代码片段中使用小于号（<），即使它是一个 HTML 元字符。要在文档注释中包含多行代码示例，请使用包装在 HTML <pre>标记中的 Javadoc{@code}标签。换句话说，在代码示例前面加上字符<pre>{@code，然后在代码后面加上}</pre>。这保留了代码中的换行符，并消除了转义 HTML 元字符的需要，但不需要转义 at 符号（@），如果代码示例使用注释，则必须转义 at 符号（@）。

最后，请注意文档注释中使用的单词「this list」。按照惯例，「this」指的是在实例方法的文档注释中，指向方法调用所在的对象。

正如条目 15 中提到的，当你为继承设计一个类时，必须记录它的自用模式（self-use patterns），以便程序员知道重写它的方法的语义。这些自用模式应该使用在 Java 8 中添加的@implSpec 标签来文档记录。回想一下，普通的问问昂注释描述了方法与其客户端之间的契约；相反，@implSpec 注释描述了方法与其子类之间的契约，如果它继承了方法或通过 super 调用方法，那么允许子类依赖于实现行为。下面是实际应用中的实例：

  /**
 * Returns true if this collection is empty.
 *
 * @implSpec
 * This implementation returns {@code this.size() == 0}.
 *
 * @return true if this collection is empty
 */
public boolean isEmpty() { ... }

从 Java 9 开始，Javadoc 实用工具仍然忽略 @implSpec 标签，除非通过命令行开关：-tag "implSpec:a:Implementation Requirements:"。希望在后续的版本中可以修正这个错误。

不要忘记，你必须采取特殊操作来生成包含 HTML 元字符的文档，例如小于号（<），大于号（>）和 and 符号（&）。将这些字符放入文档的最佳方法是使用{@literal}标签将它们包围起来，该标签禁止处理 HTML 标记和嵌套的 Javadoc 标记。它就像{@code}标签一样，除了不会以代码字体呈现文本以外。例如，这个 Javadoc 片段：

1	* A geometric series converges if {@literal \|r\| < 1}.

它会生成文档：「A geometric series converges if |r| < 1.」。{@literal}标签可能只放在小于号的位置，而不是整个不等式，并且生成的文档是一样的，但是文档注释在源代码中的可读性较差。这说明了文档注释在源代码和生成的文档中都应该是可读的通用原则。如果无法实现这两者，则生成的文档的可读性要胜过在源代码中的可读性。

每个文档注释的第一个「句子」（如下定义）成为注释所在元素的概要描述。例如，第 255 页上的文档注释中的概要描述为：「返回此列表中指定位置的元素」。概要描述必须独立描述其概述元素的功能。为避免混淆，类或接口中的两个成员或构造方法不应具有相同的概要描述。要特别注意重载方法，为此通常使用相同的第一句话是自然的（但在文档注释中是不可接受的）。

请小心，如果预期的概要描述包含句点，因为句点可能会提前终止描述。例如，以「A college degree, such as B.S., M.S. or Ph.D.」会导致概要描述为「A college degree, such as B.S., M.S」。问题在于概要描述在第一个句点结束，然后是空格、制表符或行结束符（或第一个块标签处）[Javadoc-ref]。这里是缩写「M.S.」中的第二个句号后面跟着一个空格。最好的解决方案是用{@literal}标签来包围不愉快的句点和任何相关的文本，这样源代码中的句点后面就不会有空格了:

/**
 * A college degree, such as B.S., {@literal M.S.} or Ph.D.
 */
public class Degree { ... }

说概要描述是文档注释中的第一句子，其实有点误导人。按照惯例，它很少应该是一个完整的句子。对于方法和构造方法，概要描述应该是一个动词短语 (包括任何对象)，描述了该方法执行的操作。例如：

ArrayList(int initialCapacity) —— 构造具有指定初始容量的空列表。
Collection.size() —— 返回此集合中的元素个数。

如这些例子所示，使用第三人称陈述句时态（“returns the number”）而不是第二人称祈使句（“return the number”）。

对于类，接口和属性，概要描述应该是描述由类或接口的实例或属性本身表示的事物的名词短语。例如：

Instant —— 时间线上的瞬时点。
Math.PI—— 更加接近 pi 的 double 类型数值，即圆的周长与其直径之比。

在 Java 9 中，客户端索引被添加到 Javadoc 生成的 HTML 中。这个索引以页面右上角的搜索框的形式出现，它简化了导航大型 API 文档集的任务。当你在框中键入时，得到一个匹配页面的下拉菜单。API 元素 (如类、方法和属性) 是自动索引的。有时，可能希望索引对你的 API 很重要的其他术语。为此添加了{@index}标签。对文档注释中出现的术语进行索引，就像将其包装在这个标签中一样简单，如下面的片段所示:

1	* This method complies with the {@index IEEE 754} standard.

泛型，枚举和注释需要特别注意文档注释。 记录泛型类型或方法时，请务必记录所有类型参数：

/**
 * An object that maps keys to values.  A map cannot contain
 * duplicate keys; each key can map to at most one value.
 *
 * (Remainder omitted)
 *
 * @param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
 */
public interface Map<K, V> { ... }

在记录枚举类型时，一定要记录常量，以及类型和任何公共方法。注意，如果文档很短，可以把整个文档注释放在一行:

/**
 * An instrument section of a symphony orchestra.
 */
public enum OrchestraSection {
    /** Woodwinds, such as flute, clarinet, and oboe. */
    WOODWIND,

    /** Brass instruments, such as french horn and trumpet. */
    BRASS,

    /** Percussion instruments, such as timpani and cymbals. */
    PERCUSSION,

    /** Stringed instruments, such as violin and cello. */
    STRING;
}

在为注解类型记录文档时，一定要记录任何成员，以及类型本身。用名词短语表示的文档成员，就好像它们是属性一样。对于类型的概要描述，请使用动词短语，它表示当程序元素具有此类型注解的所表示的含义:

/**
 * Indicates that the annotated method is a test method that
 * must throw the designated exception to pass.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
     /**
      * The exception that the annotated test method must throw
      * in order to pass. (The test is permitted to throw any
      * subtype of the type described by this class object.)
      */
    Class<? extends Throwable> value();
}

包级别文档注释应放在名为 package-info.java 的文件中。除了这些注释之外，package-info.java 还必须包含一个包声明，并且可以在此声明中包含注解。同样，如果使用模块化系统（详见第 15 条），则应将模块级别注释放在 module-info.java 文件中。

在文档中经常忽略的 API 的两个方面，分别是线程安全性和可序列化性。无论类或静态方法是否线程安全，都应该在文档中描述其线程安全级别，如条目 82 中所述。如果一个类是可序列化的，应该记录它的序列化形式，如条目 87 中所述。

Javadoc 具有「继承（inherit）」方法注释的能力。如果 API 元素没有文档注释，Javadoc 将搜索最具体的适用文档注释，接口文档优先于超类文档。搜索算法的详细信息可以在 The Javadoc Reference Guide [Javadoc-ref] 中找到。还可以使用{@inheritDoc}标签从超类继承部分文档注释。这意味着，除其他外，类可以重用它们实现的接口的文档注释，而不是复制这些注释。该工具有可能减轻维护多组几乎相同的文档注释的负担，但使用起来很棘手并且有一些限制。详细信息超出了本书的范围。

关于文档注释，应该添加一个警告说明。虽然有必要为所有导出的 API 元素提供文档注释，但这并不总是足够的。对于由多个相互关联的类组成的复杂 API，通常需要用描述 API 总体架构的外部文档来补充文档注释。如果存在这样的文档，相关的类或包文档注释应该包含到外部文档的链接。

Javadoc 会自动检查是否符合此条目中的许多建议。在 Java 7 中，需要命令行开关-Xdoclint来获得这种行为。在 Java 8 和 Java 9 中，默认情况下启用了此检查。诸如 checkstyle 之类的 IDE 插件会进一步检查是否符合这些建议[Burn01]。还可以通过 HTML 有效性检查器运行 Javadoc 生成的 HTML 文件来降低文档注释中出现错误的可能性。可以检测 HTML 标记的许多错误用法。有几个这样的检查器可供下载，可以使用 W3C markup validation service 在线验证 HTML 格式。在验证生成的 HTML 时，请记住，从 Java 9 开始，Javadoc 就能够生成 HTML5 和 HTML 4.01，尽管默认情况下仍然生成 HTML 4.01。如果希望 Javadoc 生成 HTML5，请使用-html5命令行开关。

本条目中描述的约定涵盖了基本内容。尽管撰写本文时已经有 15 年的历史，但编写文档注释的最终指南仍然是《How to Write Doc Comments》[Javadoc-guide]。

如果你遵循本项目中的指导原则，生成的文档应该提供对 API 的清晰描述。然而，唯一确定的方法，是阅读 Javadoc 实用工具生成的 web 页面。对于其他人将使用的每个 API，都值得这样做。正如测试程序几乎不可避免地会导致对代码的一些更改一样，阅读文档通常也会导致对文档注释的一些少许的修改。

总之，文档注释是记录 API 的最佳、最有效的方法。对于所有导出的 API 元素，它们的使用应被视为必需的。采用符合标准惯例的一致风格。请记住，在文档注释中允许任意 HTML，但必须转义 HTML 的元字符。