Java EE 專案實戰經驗總結：註釋、防禦性編程、異常設計與工具效能

Java EE 專案實戰經驗總結：註釋、防禦性編程、異常設計與工具效能

從兩個 Java EE 小專案的踩坑歷程中萃取出的四大核心實踐，涵蓋代碼規範、健壯性設計、工程效能，適合初中級開發者建立專業開發習慣。

1. 註釋是給未來的自己與團隊的文檔契約

強制標準： 所有 public/protected 方法、實體類、核心邏輯類 必須 包含：

• 方法用途（@Description 或首行摘要）
• 參數說明（@param 名稱 + 業務含義 + 約束）
• 返回值說明（@return 含義 + 異常情況）
• 作者與日期（@author / @date）

/**
 * 計算訂單優惠後金額
 * @param orderId 訂單ID，必須為有效且未支付訂單
 * @param couponCode 優惠碼，允許 null 表示不使用優惠
 * @return 實付金額（分），若優惠碼無效拋出 CouponException
 * @author ZhangSan
 * @date 2024-01-15
 */
public long calculatePayableAmount(Long orderId, String couponCode) { ... }

工程化落地： 配置 Checkstyle/SpotBugs 強制檢查，CI 流程阻攔無註釋提交。

2. 防禦性編程：永不信任外部輸入

MVC 分層架構下，Controller → Service → DAO 每層邊界都是契約驗證點。

// ❌ 野人寫法：假設參數合法
public User getUser(Long id) {
    return userDao.findById(id).getName(); // NPE 風險
}

// ✅ 專業寫法：契約前置檢查
public User getUser(Long id) {
    // 1. 基礎校驗
    if (id == null || id <= 0) {
        throw new IllegalArgumentException("用戶ID必須為正數");
    }
    // 2. 業務存在性校驗
    return userDao.findById(id)
        .orElseThrow(() -> new UserNotFoundException("用戶不存在: " + id));
}

分層驗證策略：

3. 異常設計：讓錯誤可被感知、可被處理、可被追蹤

分層異常體系：

// 基礎異常
public abstract class BizException extends RuntimeException {
    private final String errorCode; // 業務錯誤碼，前端友好提示用
    public BizException(String errorCode, String message) { ... }
}

// 業務異常
public class InsufficientBalanceException extends BizException {
    public InsufficientBalanceException(String accountId) {
        super("ACCT_001", "賬戶餘額不足: " + accountId);
    }
}

// 系統異常
public class SystemException extends RuntimeException { ... }

除法案例重構：

// ❌ 吞掉異常，調用方不知情
public float div(float a, float b) {
    return b != 0 ? a / b : 0;
}

// ✅ 顯式拋出業務異常
public float div(float a, float b) {
    if (b == 0) throw new BizException("MATH_001", "除數不能為零");
    return a / b;
}

全局異常處理： @ControllerAdvice 統一映射錯誤碼 → HTTP 狀態碼 + 結構化響應。

4. 善用 IDE 任務管理：將「待辦」可視化、可追蹤

Eclipse/IntelliJ Tasks/TODO 面板 是輕量級需求追蹤器：

• // TODO [優先級] 模塊-功能點: 具體描述
• // FIXME BugID: 臨時修補，需重構
• // REVIEW 架構評審: 設計決策記錄

// TODO [P0] OrderService-拆單邏輯: 支援多倉拆單路由
// FIXME [BUG-20240115] PaymentCallback: 幂等性校驗缺失
// REVIEW [ARCH] UserRepository: 是否引入 CQRS 讀寫分離

最佳實踐：

1. 每日下班前清理/更新 TODO，避免沉積
2. 代碼評審時必過 Tasks 面板
3. 關聯 Issue Tracker（Jira/GitLab Issue）編號，實現雙向追蹤

持續演進清單

• 引入 ArchUnit 測試架構約束（層級依賴、命名規範）
• 建立團隊代碼模板：Service/DAO/Controller 統一骨架
• 推廣「契約測試」替代傳統集成測試，提升反饋速度

專業不是寫出能跑的代碼，而是寫出可維護、可擴展、可被團隊信任的代碼。從註釋、防禦、異常、工具四個維度起步，構建工程化思維。