Google Guava Preconditions 參數檢查最佳實踐

為什麼需要 Preconditions？

在方法進入點驗證參數合法性，是防禦性程式設計的核心。Java 原生 assert 在生產環境預設關閉，且缺乏豐富的錯誤訊息格式化。Guava Preconditions 提供：

• 運行時始終啟用，不受編譯旗標影響。
• 支援格式化錯誤訊息（類似 String.format）。
• 堆疊追蹤清晰，易於定位呼叫處。
• 語義化方法名，程式碼可讀性高。

常用方法速查

程式碼範例

import com.google.common.base.Preconditions;
import java.util.List;

public class UserService {
    public boolean findElement(List elements, String target) {
        // 非空檢查，自動拋出 NPE 並附帶預設訊息
        Preconditions.checkNotNull(elements, "元素列表不可為 null");
        Preconditions.checkNotNull(target, "查詢目標不可為 null");

        // 邏輯條件檢查，支援格式化訊息
        Preconditions.checkArgument(!elements.isEmpty(), "列表不可為空，大小：%s", elements.size());

        return elements.contains(target);
    }

    public void setAge(int age) {
        // 狀態檢查：假設此方法只能呼叫一次
        Preconditions.checkState(this.age == 0, "年齡已設定為 %s，不可重複設定", this.age);
        Preconditions.checkArgument(age > 0 && age < 150, "年齡 %s 不在合理範圍 (1-149)", age);
        this.age = age;
    }
    private int age = 0;
}

與 Java 原生斷言比較

有人質疑：Java 已經很慢，多幾次檢查無所謂。實際上，Guava 內部高度優化，且參數驗證的開銷遠低於因無效參數導致的深層錯誤排查成本。明確失敗優於悄悄產生錯誤資料。

總結

將 Preconditions 作為方法防衛第一道防線，能顯著提升程式碼健壯性與可維護性。建議在專案規範中強制要求公共 API 進入點使用。

1. 上一篇文章： Java 資料結構與演算法：三角數列遞歸實作
2. 下一篇文章： Java Swing 文本框與文本區輸入輸出完整指南

Java 相關知識

Java 抽象類與抽象方法：強制契約與禁止實例化的編譯期保障

從「偽方法」到抽象方法 早期基類提供空方法體（偽方法），調用

Eclipse 同步本地項目到 GitHub 完整教程（Java EE 版內建 Git 支持）

本教程基於 Eclipse Java EE 版（內建 EGi

Java 中啟發式搜索優化：A* 算法高性能實現實踐

啟發式搜索是解決狀態空間問題的核心技術，A* 算法作為最廣泛

Spring 屬性注入全攻略：三種基本方式與複雜類型注入詳解

前言 Spring 框架的核心特性之一是依賴注入，提供多樣化