## Chapter 11. Concurrency（并发）
### Item 82: Document thread safety（文档应包含线程安全属性）
How a class behaves when its methods are used concurrently is an important part of its contract with its clients. If you fail to document this aspect of a class’s behavior, its users will be forced to make assumptions. If these assumptions are wrong, the resulting program may perform insufficient synchronization (Item 78) or excessive synchronization (Item 79). In either case, serious errors may result.
类在其方法并发使用时的行为是其与客户端约定的重要组成部分。如果你没有记录类在这一方面的行为，那么它的用户将被迫做出假设。如果这些假设是错误的，生成的程序可能缺少足够的同步（[Item-78](/Chapter-11/Chapter-11-Item-78-Synchronize-access-to-shared-mutable-data.md)）或过度的同步（[Item-79](/Chapter-11/Chapter-11-Item-79-Avoid-excessive-synchronization.md)）。无论哪种情况，都可能导致严重的错误。
You may hear it said that you can tell if a method is thread-safe by looking for the synchronized modifier in its documentation. This is wrong on several counts. In normal operation, Javadoc does not include the synchronized modifier in its output, and with good reason. **The presence of the synchronized modifier in a method declaration is an implementation detail, not a part of its API.** It does not reliably indicate that a method is thread-safe.
你可能听说过，可以通过在方法的文档中查找 synchronized 修饰符来判断方法是否线程安全。这个观点有好些方面是错误的。在正常操作中，Javadoc 的输出中没有包含同步修饰符，这是有原因的。方法声明中 synchronized 修饰符的存在是实现细节，而不是其 API 的一部分。**它不能可靠地表明方法是线程安全的。**
Moreover, the claim that the presence of the synchronized modifier is sufficient to document thread safety embodies the misconception that thread safety is an all-or-nothing property. In fact, there are several levels of thread safety. **To enable safe concurrent use, a class must clearly document what level of thread safety it supports.** The following list summarizes levels of thread safety. It is not exhaustive but covers the common cases:
此外，声称 synchronized 修饰符的存在就足以记录线程安全性，这个观点是对线程安全性属性的误解，认为要么全有要么全无。实际上，线程安全有几个级别。**要启用安全的并发使用，类必须清楚地记录它支持的线程安全级别。** 下面的列表总结了线程安全级别。它并非详尽无遗，但涵盖以下常见情况：
- **Immutable** —Instances of this class appear constant. No external synchronization is necessary. Examples include String, Long, and BigInteger (Item 17).
不可变的。这个类的实例看起来是常量。不需要外部同步。示例包括 String、Long 和 BigInteger（[Item-17](/Chapter-4/Chapter-4-Item-17-Minimize-mutability.md)）。
- **Unconditionally thread-safe** —Instances of this class are mutable, but the class has sufficient internal synchronization that its instances can be used concurrently without the need for any external synchronization. Examples include AtomicLong and ConcurrentHashMap.
无条件线程安全。该类的实例是可变的，但是该类具有足够的内部同步，因此无需任何外部同步即可并发地使用该类的实例。例如 AtomicLong 和 ConcurrentHashMap。
- **Conditionally thread-safe** —Like unconditionally thread-safe, except that some methods require external synchronization for safe concurrent use. Examples include the collections returned by the Collections.synchronized wrappers, whose iterators require external synchronization.
有条件的线程安全。与无条件线程安全类似，只是有些方法需要外部同步才能安全并发使用。示例包括 Collections.synchronized 包装器返回的集合，其迭代器需要外部同步。
- **Not thread-safe** —Instances of this class are mutable. To use them concurrently, clients must surround each method invocation (or invocation sequence) with external synchronization of the clients’ choosing. Examples include the general-purpose collection implementations, such as ArrayList and HashMap.
非线程安全。该类的实例是可变的。要并发地使用它们，客户端必须使用外部同步来包围每个方法调用（或调用序列）。这样的例子包括通用的集合实现，例如 ArrayList 和 HashMap。
- **Thread-hostile** —This class is unsafe for concurrent use even if every method invocation is surrounded by external synchronization. Thread hostility usually results from modifying static data without synchronization. No one writes a thread-hostile class on purpose; such classes typically result from the failure to consider concurrency. When a class or method is found to be thread-hostile, it is typically fixed or deprecated. The generateSerialNumber method in Item 78 would be thread-hostile in the absence of internal synchronization, as discussed on page 322.
线程对立。即使每个方法调用都被外部同步包围，该类对于并发使用也是不安全的。线程对立通常是由于在不同步的情况下修改静态数据而导致的。没有人故意编写线程对立类；此类通常是由于没有考虑并发性而导致的。当发现类或方法与线程不相容时，通常将其修复或弃用。[Item-78](/Chapter-11/Chapter-11-Item-78-Synchronize-access-to-shared-mutable-data.md) 中的 generateSerialNumber 方法在没有内部同步的情况下是线程对立的，如第 322 页所述。
These categories (apart from thread-hostile) correspond roughly to the thread safety annotations in Java Concurrency in Practice, which are Immutable, ThreadSafe, and NotThreadSafe [Goetz06, Appendix A]. The unconditionally and conditionally thread-safe categories in the above taxonomy are both covered under the ThreadSafe annotation.
这些类别（不包括线程对立类）大致对应于《Java Concurrency in Practice》中的线程安全注解，分别为 Immutable、ThreadSafe 和 NotThreadSafe [Goetz06, Appendix A]。上面分类中的无条件线程安全和有条件的线程安全都包含在 ThreadSafe 注解中。
Documenting a conditionally thread-safe class requires care. You must indicate which invocation sequences require external synchronization, and which lock (or in rare cases, locks) must be acquired to execute these sequences. Typically it is the lock on the instance itself, but there are exceptions. For example, the documentation for Collections.synchronizedMap says this:
在文档中记录一个有条件的线程安全类需要小心。你必须指出哪些调用序列需要外部同步，以及执行这些序列必须获得哪些锁（在极少数情况下是锁）。通常是实例本身的锁，但也有例外。例如，`Collections.synchronizedMap` 的文档提到：
It is imperative that the user manually synchronize on the returned map when iterating over any of its collection views:
当用户遍历其集合视图时，必须手动同步返回的 Map：
```
Map<K, V> m = Collections.synchronizedMap(new HashMap<>());
Set<K> s = m.keySet(); // Needn't be in synchronized block
...
synchronized(m) { // Synchronizing on m, not s!
for (K key : s)
key.f();
}
```
Failure to follow this advice may result in non-deterministic behavior.
不遵循这个建议可能会导致不确定的行为。
The description of a class’s thread safety generally belongs in the class’s doc comment, but methods with special thread safety properties should describe these properties in their own documentation comments. It is not necessary to document the immutability of enum types. Unless it is obvious from the return type, static factories must document the thread safety of the returned object, as demonstrated by Collections.synchronizedMap (above).
类的线程安全的描述通常属于该类的文档注释，但是具有特殊线程安全属性的方法应该在它们自己的文档注释中描述这些属性。没有必要记录枚举类型的不变性。除非从返回类型可以明显看出，否则静态工厂必须记录返回对象的线程安全性，正如 `Collections.synchronizedMap` 所演示的那样。
When a class commits to using a publicly accessible lock, it enables clients to execute a sequence of method invocations atomically, but this flexibility comes at a price. It is incompatible with high-performance internal concurrency control, of the sort used by concurrent collections such as ConcurrentHashMap. Also, a client can mount a denial-of-service attack by holding the publicly accessible lock for a prolonged period. This can be done accidentally or intentionally.
当一个类使用公共可访问锁时，它允许客户端自动执行一系列方法调用，但是这种灵活性是有代价的。它与诸如 ConcurrentHashMap 之类的并发集合所使用的高性能内部并发控制不兼容。此外，客户端可以通过长时间持有可公开访问的锁来发起拒绝服务攻击。这可以是无意的，也可以是有意的。
To prevent this denial-of-service attack, you can use a private lock object instead of using synchronized methods (which imply a publicly accessible lock):
为了防止这种拒绝服务攻击，你可以使用一个私有锁对象，而不是使用同步方法（隐含一个公共可访问的锁）：
```
// Private lock object idiom - thwarts denial-of-service attack
private final Object lock = new Object();
public void foo() {
synchronized(lock) {
...
}
}
```
Because the private lock object is inaccessible outside the class, it is impossible for clients to interfere with the object’s synchronization. In effect, we are applying the advice of Item 15 by encapsulating the lock object in the object it synchronizes.
因为私有锁对象在类之外是不可访问的，所以客户端不可能干扰对象的同步。实际上，我们通过将锁对象封装在它同步的对象中，是在应用 [Item-15](/Chapter-4/Chapter-4-Item-15-Minimize-the-accessibility-of-classes-and-members.md) 的建议。
Note that the lock field is declared final. This prevents you from inadvertently changing its contents, which could result in catastrophic unsynchronized access (Item 78). We are applying the advice of Item 17, by minimizing the mutability of the lock field. **Lock fields should always be declared final.** This is true whether you use an ordinary monitor lock (as shown above) or a lock from the java.util.concurrent.locks package.
注意，lock 字段被声明为 final。这可以防止你无意中更改它的内容，这可能导致灾难性的非同步访问（[Item-78](/Chapter-11/Chapter-11-Item-78-Synchronize-access-to-shared-mutable-data.md)）。我们正在应用 [Item-17](/Chapter-4/Chapter-4-Item-17-Minimize-mutability.md) 的建议，最小化锁字段的可变性。**Lock 字段应该始终声明为 final。** 无论使用普通的监视器锁（如上所示）还是 `java.util.concurrent` 包中的锁，都是这样。
The private lock object idiom can be used only on unconditionally thread-safe classes. Conditionally thread-safe classes can’t use this idiom because they must document which lock their clients are to acquire when performing certain method invocation sequences.
私有锁对象用法只能在无条件的线程安全类上使用。有条件的线程安全类不能使用这种用法，因为它们必须在文档中记录，在执行某些方法调用序列时要获取哪些锁。
The private lock object idiom is particularly well-suited to classes designed for inheritance (Item 19). If such a class were to use its instances for locking, a subclass could easily and unintentionally interfere with the operation of the base class, or vice versa. By using the same lock for different purposes, the subclass and the base class could end up “stepping on each other’s toes.” This is not just a theoretical problem; it happened with the Thread class [Bloch05, Puzzle 77].
私有锁对象用法特别适合为继承而设计的类（[Item-19](/Chapter-4/Chapter-4-Item-19-Design-and-document-for-inheritance-or-else-prohibit-it.md)）。如果这样一个类要使用它的实例进行锁定，那么子类很容易在无意中干扰基类的操作，反之亦然。通过为不同的目的使用相同的锁，子类和基类最终可能「踩到对方的脚趾头」。这不仅仅是一个理论问题，它就发生在 Thread 类中 [Bloch05, Puzzle 77]。
To summarize, every class should clearly document its thread safety properties with a carefully worded prose description or a thread safety annotation. The synchronized modifier plays no part in this documentation. Conditionally thread-safe classes must document which method invocation sequences require external synchronization and which lock to acquire when executing these sequences. If you write an unconditionally thread-safe class, consider using a private lock object in place of synchronized methods. This protects you against synchronization interference by clients and subclasses and gives you more flexibility to adopt a sophisticated approach to concurrency control in a later release.
总之，每个类都应该措辞严谨的描述或使用线程安全注解清楚地记录其线程安全属性。synchronized 修饰符在文档中没有任何作用。有条件的线程安全类必须记录哪些方法调用序列需要外部同步，以及在执行这些序列时需要获取哪些锁。如果你编写一个无条件线程安全的类，请考虑使用一个私有锁对象来代替同步方法。这将保护你免受客户端和子类的同步干扰，并为你提供更大的灵活性，以便在后续的版本中采用复杂的并发控制方式。
---
**[Back to contents of the chapter（返回章节目录）](/Chapter-11/Chapter-11-Introduction.md)**
- **Previous Item（上一条目）：[Item 81: Prefer concurrency utilities to wait and notify（并发实用工具优于 wait 和 notify）](/Chapter-11/Chapter-11-Item-81-Prefer-concurrency-utilities-to-wait-and-notify.md)**
- **Next Item（下一条目）：[Item 83: Use lazy initialization judiciously（明智地使用延迟初始化）](/Chapter-11/Chapter-11-Item-83-Use-lazy-initialization-judiciously.md)**
- Chapter 2. Creating and Destroying Objects（创建和销毁对象）
- Item 1: Consider static factory methods instead of constructors（考虑以静态工厂方法代替构造函数）
- Item 2: Consider a builder when faced with many constructor parameters（在面对多个构造函数参数时，请考虑构建器）
- Item 3: Enforce the singleton property with a private constructor or an enum type（使用私有构造函数或枚举类型实施单例属性）
- Item 4: Enforce noninstantiability with a private constructor（用私有构造函数实施不可实例化）
- Item 5: Prefer dependency injection to hardwiring resources（依赖注入优于硬连接资源）
- Item 6: Avoid creating unnecessary objects（避免创建不必要的对象）
- Item 7: Eliminate obsolete object references（排除过时的对象引用）
- Item 8: Avoid finalizers and cleaners（避免使用终结器和清除器）
- Item 9: Prefer try with resources to try finally（使用 try-with-resources 优于 try-finally）
- Chapter 3. Methods Common to All Objects（对象的通用方法）
- Item 10: Obey the general contract when overriding equals（覆盖 equals 方法时应遵守的约定）
- Item 11: Always override hashCode when you override equals（当覆盖 equals 方法时，总要覆盖 hashCode 方法）
- Item 12: Always override toString（始终覆盖 toString 方法）
- Item 13: Override clone judiciously（明智地覆盖 clone 方法）
- Item 14: Consider implementing Comparable（考虑实现 Comparable 接口）
- Chapter 4. Classes and Interfaces（类和接口）
- Item 15: Minimize the accessibility of classes and members（尽量减少类和成员的可访问性）
- Item 16: In public classes use accessor methods not public fields（在公共类中，使用访问器方法，而不是公共字段）
- Item 17: Minimize mutability（减少可变性）
- Item 18: Favor composition over inheritance（优先选择复合而不是继承）
- Item 19: Design and document for inheritance or else prohibit it（继承要设计良好并且具有文档，否则禁止使用）
- Item 20: Prefer interfaces to abstract classes（接口优于抽象类）
- Item 21: Design interfaces for posterity（为后代设计接口）
- Item 22: Use interfaces only to define types（接口只用于定义类型）
- Item 23: Prefer class hierarchies to tagged classes（类层次结构优于带标签的类）
- Item 24: Favor static member classes over nonstatic（静态成员类优于非静态成员类）
- Item 25: Limit source files to a single top level class（源文件仅限有单个顶层类）
- Chapter 5. Generics（泛型）
- Item 26: Do not use raw types（不要使用原始类型）
- Item 27: Eliminate unchecked warnings（消除 unchecked 警告）
- Item 28: Prefer lists to arrays（list 优于数组）
- Item 29: Favor generic types（优先使用泛型）
- Item 30: Favor generic methods（优先使用泛型方法）
- Item 31: Use bounded wildcards to increase API flexibility（使用有界通配符增加 API 的灵活性）
- Item 32: Combine generics and varargs judiciously（明智地合用泛型和可变参数）
- Item 33: Consider typesafe heterogeneous containers（考虑类型安全的异构容器）
- Chapter 6. Enums and Annotations（枚举和注解）
- Item 34: Use enums instead of int constants（用枚举类型代替 int 常量）
- Item 35: Use instance fields instead of ordinals（使用实例字段替代序数）
- Item 36: Use EnumSet instead of bit fields（用 EnumSet 替代位字段）
- Item 37: Use EnumMap instead of ordinal indexing（使用 EnumMap 替换序数索引）
- Item 38: Emulate extensible enums with interfaces（使用接口模拟可扩展枚举）
- Item 39: Prefer annotations to naming patterns（注解优于命名模式）
- Item 40: Consistently use the Override annotation（坚持使用 @Override 注解）
- Item 41: Use marker interfaces to define types（使用标记接口定义类型）
- Chapter 7. Lambdas and Streams（λ 表达式和流）
- Item 42: Prefer lambdas to anonymous classes（λ 表达式优于匿名类）
- Item 43: Prefer method references to lambdas（方法引用优于 λ 表达式）
- Item 44: Favor the use of standard functional interfaces（优先使用标准函数式接口）
- Item 45: Use streams judiciously（明智地使用流）
- Item 46: Prefer side effect free functions in streams（在流中使用无副作用的函数）
- Item 47: Prefer Collection to Stream as a return type（优先选择 Collection 而不是流作为返回类型）
- Item 48: Use caution when making streams parallel（谨慎使用并行流）
- Chapter 8. Methods（方法）
- Item 49: Check parameters for validity（检查参数的有效性）
- Item 50: Make defensive copies when needed（在需要时制作防御性副本）
- Item 51: Design method signatures carefully（仔细设计方法签名）
- Item 52: Use overloading judiciously（明智地使用重载）
- Item 53: Use varargs judiciously（明智地使用可变参数）
- Item 54: Return empty collections or arrays, not nulls（返回空集合或数组，而不是 null）
- Item 55: Return optionals judiciously（明智地的返回 Optional）
- Item 56: Write doc comments for all exposed API elements（为所有公开的 API 元素编写文档注释）
- Chapter 9. General Programming（通用程序设计）
- Item 57: Minimize the scope of local variables（将局部变量的作用域最小化）
- Item 58: Prefer for-each loops to traditional for loops（for-each 循环优于传统的 for 循环）
- Item 59: Know and use the libraries（了解并使用库）
- Item 60: Avoid float and double if exact answers are required（若需要精确答案就应避免使用 float 和 double 类型）
- Item 61: Prefer primitive types to boxed primitives（基本数据类型优于包装类）
- Item 62: Avoid strings where other types are more appropriate（其他类型更合适时应避免使用字符串）
- Item 63: Beware the performance of string concatenation（当心字符串连接引起的性能问题）
- Item 64: Refer to objects by their interfaces（通过接口引用对象）
- Item 65: Prefer interfaces to reflection（接口优于反射）
- Item 66: Use native methods judiciously（明智地使用本地方法）
- Item 67: Optimize judiciously（明智地进行优化）
- Item 68: Adhere to generally accepted naming conventions（遵守被广泛认可的命名约定）
- Chapter 10. Exceptions（异常）
- Item 69: Use exceptions only for exceptional conditions（仅在确有异常条件下使用异常）
- Item 70: Use checked exceptions for recoverable conditions and runtime exceptions for programming errors（对可恢复情况使用 checked 异常，对编程错误使用运行时异常）
- Item 71: Avoid unnecessary use of checked exceptions（避免不必要地使用 checked 异常）
- Item 72: Favor the use of standard exceptions（鼓励复用标准异常）
- Item 73: Throw exceptions appropriate to the abstraction（抛出能用抽象解释的异常）
- Item 74: Document all exceptions thrown by each method（为每个方法记录会抛出的所有异常）
- Item 75: Include failure capture information in detail messages（异常详细消息中应包含捕获失败的信息）
- Item 76: Strive for failure atomicity（尽力保证故障原子性）
- Item 77: Don’t ignore exceptions（不要忽略异常）
- Chapter 11. Concurrency（并发）
- Item 78: Synchronize access to shared mutable data（对共享可变数据的同步访问）
- Item 79: Avoid excessive synchronization（避免过度同步）
- Item 80: Prefer executors, tasks, and streams to threads（Executor、task、流优于直接使用线程）
- Item 81: Prefer concurrency utilities to wait and notify（并发实用工具优于 wait 和 notify）
- Item 82: Document thread safety（文档应包含线程安全属性）
- Item 83: Use lazy initialization judiciously（明智地使用延迟初始化）
- Item 84: Don’t depend on the thread scheduler（不要依赖线程调度器）
- Chapter 12. Serialization（序列化）
- Item 85: Prefer alternatives to Java serialization（优先选择 Java 序列化的替代方案）
- Item 86: Implement Serializable with great caution（非常谨慎地实现 Serializable）
- Item 87: Consider using a custom serialized form（考虑使用自定义序列化形式）
- Item 88: Write readObject methods defensively（防御性地编写 readObject 方法）
- Item 89: For instance control, prefer enum types to readResolve（对于实例控制，枚举类型优于 readResolve）
- Item 90: Consider serialization proxies instead of serialized instances（考虑以序列化代理代替序列化实例）