前言

套件 是 Java 程式碼組織的基本單位，Javadoc 是專案文檔化的標準工具。良好的套件結構與完整的 API 文檔，能大幅提升團隊協作效率、降低維護成本、支援自動化發流程。本文系統整理套件設計原則、常用標準套件、自建套件流程、Javadoc 標記規範與現代化文檔生成最佳實務。

一、套件 核心概念

本質與作用

• 命名空間隔離：避免類別名稱衝突 (com.company.project.module.ClassName)
• 存取控制：package-private (預設) 限制同套件可見性
• 邏輯分組：依功能、層級、領域劃分模組
• 物理對應：目錄結構 = 套件結構 (src/main/java/com/example/User.java → com.example.User)

命名規範

// 反向域名 + 專案 + 模組 + 層
com.company.project.module.layer

// 實例
com.acme.ecommerce.order.service    // 領域服務
com.acme.ecommerce.order.repository // 資料存取
com.acme.ecommerce.order.controller // Web 入口
com.acme.ecommerce.common.util      // 共用工具
com.acme.ecommerce.config           // 設定類別

二、JDK 常用標準套件速查

擴展套件

• javax.swing、java.awt：桌面 GUI (維護模式)
• javax.servlet、javax.servlet.http：Servlet API (現由 Jakarta EE 維護 jakarta.servlet)
• javax.persistence：JPA (現 jakarta.persistence)
• javax.validation：Bean Validation (現 jakarta.validation)

三、自建套件完整流程

1. 定義公用類別

// 檔案：src/main/java/com/example/math/Calculator.java
package com.example.math; // 必須是第一行非註解敘述

public class Calculator {
    public int add(int a, int b) {
        return a + b;
    }
    
    public int multiply(int a, int b) {
        return a * b;
    }
}

2. 編譯並輸出到指定目錄

# -d 指定輸出根目錄，會自動建立套件目錄結構
javac -d ./out src/main/java/com/example/math/Calculator.java

# 結果：
# out/
# └── com/
#     └── example/
#         └── math/
#             └── Calculator.class

3. 打包成 JAR

# 建立可執行 JAR (含 Manifest)
jar cvfe math-lib.jar com.example.math.Calculator -C out .

# 或建立庫 JAR
jar cvf math-lib.jar -C out .

4. 使用套件

// 檔案：src/main/java/com/example/app/Main.java
package com.example.app;

import com.example.math.Calculator; // 匯入特定類別
// import com.example.math.*;       // 匯入整個套件 (不推薦)

public class Main {
    public static void main(String[] args) {
        Calculator calc = new Calculator();
        System.out.println("3 + 5 = " + calc.add(3, 5));
    }
}

5. 編譯執行 (設定 Classpath)

# 編譯
javac -cp math-lib.jar -d ./app-out src/main/java/com/example/app/Main.java

# 執行
java -cp math-lib.jar:./app-out com.example.app.Main
# Windows 用分號 ; 分隔 classpath

四、Javadoc 文檔規範與實務

文檔註解格式

/**
 * 計算器核心服務，提供基本算術運算。
 * 
 * @author Chen Wei
 * @version 2.1.0
 * @since 1.0.0
 * @see API 文檔
 */
package com.example.math;

/**
 * 簡易計算器實作，執行緒安全、無狀態。
 * 
 * 
使用範例：
 * 
{@code
 * Calculator calc = new Calculator();
 * int sum = calc.add(10, 20); // 30
 * }
 * 
 * @author Chen Wei
 * @version 2.1.0
 * @since 1.0.0
 */
public class Calculator {
    
    /**
     * 兩整數相加。
     * 
     * @param a 第一加數
     * @param b 第二加數
     * @return 兩數之和
     * @throws ArithmeticException 若結果超出 int 範圍 (理論上不會)
     * @see #subtract(int, int)
     * @see Math#addExact(int, int)
     */
    public int add(int a, int b) {
        return Math.addExact(a, b); // Java 8+ 溢位檢查
    }
    
    /**
     * 兩整數相減。
     * 
     * @param a 被減數
     * @param b 減數
     * @return 差值
     */
    public int subtract(int a, int b) {
        return Math.subtractExact(a, b);
    }
}

核心標記完整表

模組/套件級文檔

// 檔案：src/main/java/com/example/math/package-info.java
/**
 * 數學運算核心模組，提供高效能、執行緒安全的基礎算術服務。
 * 
 * 
主要功能：
 * 

 *   
基本四則運算 (溢位安全)
 *   
進制轉換工具
 *   
常用數學常數
 * 
 * 
 * @since 1.0.0
 * @author Math Team
 */
package com.example.math;

五、Javadoc 命令列與自動化

基本指令

# 生成文檔到 docs 目錄
javadoc -d docs -sourcepath src/main/java -subpackages com.example

# 完整參數範例
javadoc -d docs \
  -sourcepath src/main/java \
  -subpackages com.example \
  -encoding UTF-8 \
  -charset UTF-8 \
  -docencoding UTF-8 \
  -author -version -since \
  -windowtitle "My Project API" \
  -doctitle "
My Project API 文檔
" \
  -header "My Project
v2.1.0" \
  -footer "Copyright © 2024" \
  -link https://docs.oracle.com/javase/8/docs/api/ \
  -linkoffline ../javafx-doc https://openjfx.io/javadoc/ \
  -excludepkg com.example.internal \
  -nodeprecated \
  -nonavbar \
  -noindex

Maven 整合

    org.apache.maven.plugins
    maven-javadoc-plugin
    3.5.0
    
        UTF-8
        UTF-8
        UTF-8
        protected           
        true
        false
        false
        
            https://docs.oracle.com/javase/8/docs/api/
            https://docs.spring.io/spring-framework/docs/current/javadoc-api/
        
        
            
                apiNote
                a
                API 註記：
            
        
    
    
        
            attach-javadocs
            
                jar       
            
        
    

Gradle 整合

tasks.withType(Javadoc) {
    options.encoding = 'UTF-8'
    options.charSet = 'UTF-8'
    options.author = true
    options.version = true
    options.links("https://docs.oracle.com/javase/8/docs/api/")
    options.links("https://docs.spring.io/spring-framework/docs/current/javadoc-api/")
    // 自定義標記
    options.addBooleanOption('apiNote', 'API Note:')
}

task javadocJar(type: Jar, dependsOn: javadoc) {
    from javadoc.destinationDir
    archiveClassifier.set('javadoc')
}

六、現代文檔生成最佳實務

1. 文檔即代碼：Javadoc 隨代碼版本控制，CI/CD 自動發布到 GitHub Pages / Nexus / Confluence
2. 模組化文檔：多模組專案各模組獨立生成，聚合時用 -subpackages 或 Maven 彙總
3. 包含內部 API 選項：內部開發環境生成 -private 完整文檔，對外發布 -public 或 -protected
4. 連結外部 JDK/框架文檔：-link 參數讓 {@link} 自動跳轉官方文檔
5. 自定義標記：如 @apiNote、@implSpec、@implNote (Java 8+ 標準) 區分用途
6. 檢查文檔品質：javadoc -Xdoclint:all 嚴格檢查遺漏參數、錯誤連結、HTML 語法
7. 測試程式碼片段：@snippet (Java 18+) 或 @example 整合測試驗證範例正確性

七、常見問題排查

總結

套件與 Javadoc 是 Java 專案工程化的基石。遵循反向域名命名、模組化分層、完整標記規範、建構自動化整合，能讓專案文檔成為資產而非負擔。現代開發更應善用 @snippet、@apiNote、模組系統、DocLint 等新特性，構建可信賴、可驗證、可演進的 API 文檔體系。