## Chapter 10. Exceptions（異常）
### Item 75: Include failure capture information in detail messages（異常詳細消息中應包含捕獲失敗的信息）
When a program fails due to an uncaught exception, the system automatically prints out the exception’s stack trace. The stack trace contains the exception’s string representation, the result of invoking its toString method. This typically consists of the exception’s class name followed by its detail message. Frequently this is the only information that programmers or site reliability engineers will have when investigating a software failure. If the failure is not easily reproducible, it may be difficult or impossible to get any more information. Therefore, it is critically important that the exception’s toString method return as much information as possible concerning the cause of the failure. In other words, the detail message of an exception should capture the failure for subsequent analysis.
當程序由于未捕獲異常而失敗時，系統可以自動打印出異常的堆棧跟蹤。堆棧跟蹤包含異常的字符串表示，這是調用其 toString 方法的結果。這通常包括異常的類名及其詳細信息。通常，這是程序員或管理員在調查軟件故障時所掌握的唯一信息。如果失敗不容易重現，想獲得更多的信息會非常困難。因此，異常的 toString 方法返回盡可能多的關于失敗原因的信息是非常重要的。換句話說，由失敗導致的異常的詳細信息應該被捕獲，以便后續分析。
**To capture a failure, the detail message of an exception should contain the values of all parameters and fields that contributed to the exception.** For example, the detail message of an IndexOutOfBoundsException should contain the lower bound, the upper bound, and the index value that failed to lie between the bounds. This information tells a lot about the failure. Any or all of the three values could be wrong. The index could be one less than the lower bound or equal to the upper bound (a “fencepost error”), or it could be a wild value, far too low or high. The lower bound could be greater than the upper bound (a serious internal invariant failure). Each of these situations points to a different problem, and it greatly aids in the diagnosis if you know what sort of error you’re looking for.
**要捕獲失敗，異常的詳細消息應該包含導致異常的所有參數和字段的值。** 例如，IndexOutOfBoundsException 的詳細消息應該包含下界、上界和未能位于下界之間的索引值。這些信息說明了很多關于失敗的信息。這三個值中的任何一個或所有值都可能是錯誤的。索引可以小于或等于上界（「越界錯誤」），也可以是一個無效值，太小或太大。下界可能大于上界（嚴重的內部故障）。每一種情況都指向一個不同的問題，如果你知道你在尋找什么樣的錯誤，這對診斷有很大的幫助。
One caveat concerns security-sensitive information. Because stack traces may be seen by many people in the process of diagnosing and fixing software issues, **do not include passwords, encryption keys, and the like in detail messages.**
提及一個與安全敏感信息有關的警告。因為許多人在診斷和修復軟件問題的過程中可能會看到堆棧跟蹤，所以 **不應包含密碼、加密密鑰等詳細信息。**
While it is critical to include all of the pertinent data in the detail message of an exception, it is generally unimportant to include a lot of prose. The stack trace is intended to be analyzed in conjunction with the documentation and, if necessary, source code. It generally contains the exact file and line number from which the exception was thrown, as well as the files and line numbers of all other method invocations on the stack. Lengthy prose descriptions of the failure are superfluous; the information can be gleaned by reading the documentation and source code.
雖然在異常的詳細信息中包含所有相關數據非常重要，但通常不需要包含大量的描述。堆棧跟蹤將與文檔一起分析，如果需要，還將與源代碼一起分析。它通常包含拋出異常的確切文件和行號，以及堆棧上所有方法調用的文件和行號。冗長的描述對一個失敗問題而言是多余的；可以通過閱讀文檔和源代碼來收集信息。
The detail message of an exception should not be confused with a user-level error message, which must be intelligible to end users. Unlike a user-level error message, the detail message is primarily for the benefit of programmers or site reliability engineers, when analyzing a failure. Therefore, information content is far more important than readability. User-level error messages are often localized, whereas exception detail messages rarely are. One way to ensure that exceptions contain adequate failure-capture information in their detail messages is to require this information in their constructors instead of a string detail message. The detail message can then be generated automatically to include the information. For example, instead of a String constructor, IndexOutOfBoundsException could have had a constructor that looks like this:
異常的詳細信息不應該與用戶層的錯誤消息混淆，因為用戶層錯誤消息最終必須被用戶理解。與用戶層錯誤消息不同，詳細消息主要是為程序員或管理員在分析故障時提供的。因此，信息內容遠比可讀性重要。用戶層錯誤消息通常是本地化的，而異常詳細信息消息很少本地化。確保異常在其詳細信息中包含足夠的故障捕獲信息的一種方法是，在其構造函數中配置，而不是以傳入字符串方式引入這些信息。之后可以自動生成詳細信息來包含細節。例如，IndexOutOfBoundsException 構造函數不包含 String 參數，而是像這樣：
```
/**
* Constructs an IndexOutOfBoundsException.
**
@param lowerBound the lowest legal index value
* @param upperBound the highest legal index value plus one
* @param index the actual index value
*/
public IndexOutOfBoundsException(int lowerBound, int upperBound, int index) {
// Generate a detail message that captures the failure
super(String.format("Lower bound: %d, Upper bound: %d, Index: %d",lowerBound, upperBound, index));
// Save failure information for programmatic access
this.lowerBound = lowerBound;
this.upperBound = upperBound;
this.index = index;
}
```
As of Java 9, IndexOutOfBoundsException finally acquired a constructor that takes an int valued index parameter, but sadly it omits the lowerBound and upperBound parameters. More generally, the Java libraries don’t make heavy use of this idiom, but it is highly recommended. It makes it easy for the programmer throwing an exception to capture the failure. In fact, it makes it hard for the programmer not to capture the failure! In effect, the idiom centralizes the code to generate a high-quality detail message in the exception class, rather than requiring each user of the class to generate the detail message redundantly.
從 Java 9 開始，IndexOutOfBoundsException 最終獲得了一個接受 int 值索引參數的構造函數，但遺憾的是它忽略了下界和上界參數。更一般地說，Java 庫不會大量使用這個習慣用法，但是強烈推薦使用它。它使程序員很容易通過拋出異常來捕獲失敗。事實上，它使程序員不想捕獲失敗都難！實際上，這個習慣用法將集中在異常類中生成高質量的詳細信息，而不是要求該類的每個用戶都生成冗余的詳細信息。
**譯注：IndexOutOfBoundsException 有關 int 參數的構造函數源碼**
```
/**
* Constructs a new {@code IndexOutOfBoundsException} class with an
* argument indicating the illegal index.
*
* <p>The index is included in this exception's detail message. The
* exact presentation format of the detail message is unspecified.
*
* @param index the illegal index.
* @since 9
*/
public IndexOutOfBoundsException(int index) {
super("Index out of range: " + index);
}
```
As suggested in Item 70, it may be appropriate for an exception to provide accessor methods for its failure-capture information (lowerBound, upperBound, and index in the above example). It is more important to provide such accessor methods on checked exceptions than unchecked, because the failure-capture information could be useful in recovering from the failure. It is rare (although not inconceivable) that a programmer might want programmatic access to the details of an unchecked exception. Even for unchecked exceptions, however, it seems advisable to provide these accessors on general principle (Item 12, page 57).
正如 [Item-70](/Chapter-10/Chapter-10-Item-70-Use-checked-exceptions-for-recoverable-conditions-and-runtime-exceptions-for-programming-errors.md) 中建議的，異常為其故障捕獲信息提供訪問器方法是適合的（上面示例中的下界、上界和索引）。在 checked 異常上提供此類訪問器方法比 unchecked 異常上提供此類訪問器方法更為重要，因為故障捕獲信息可能有助于程序從故障中恢復。程序員可能希望通過編程訪問 unchecked 異常的詳細信息，但這是很少見的（盡管是可以想象的）。然而，即使對于 unchecked 異常，根據一般原則，提供這些訪問器也是可以的（[Item-12](/Chapter-3/Chapter-3-Item-12-Always-override-toString.md)，第 57 頁）。
---
**[Back to contents of the chapter（返回章節目錄）](/Chapter-10/Chapter-10-Introduction.md)**
- **Previous Item（上一條目）：[Item 74: Document all exceptions thrown by each method（為每個方法記錄會拋出的所有異常）](/Chapter-10/Chapter-10-Item-74-Document-all-exceptions-thrown-by-each-method.md)**
- **Next Item（下一條目）：[Item 76: Strive for failure atomicity（盡力保證故障原子性）](/Chapter-10/Chapter-10-Item-76-Strive-for-failure-atomicity.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（考慮以序列化代理代替序列化實例）