Apache Commons CLI 入門教程：輕松解析命令行參數

一、什么是 Commons CLI？

Apache Commons CLI 是一個簡單易用的 Java 庫，專門用于解析命令行參數。當我們需要開發命令行工具或應用程序時，它可以幫助我們：

• 定義程序接受的參數格式
• 自動解析用戶輸入的命令行參數
• 生成標準化的幫助信息
• 驗證參數的正確性

二、為什么選擇 Commons CLI？

相比自己編寫參數解析邏輯，使用 Commons CLI 有以下優勢：

1. 標準化：遵循 Unix/Linux 命令行工具的標準慣例
2. 功能完善：支持長短選項、必選/可選參數、參數分組等
3. 易用性：API 設計直觀，學習曲線平緩
4. 健壯性：經過廣泛測試，能處理各種邊界情況

三、快速開始

1. 添加依賴

首先需要在項目中添加 Commons CLI 的依賴：

Maven 項目：

<dependency><groupId>commons-cli</groupId><artifactId>commons-cli</artifactId><version>1.9.0</version>
</dependency>

Gradle 項目：

implementation 'commons-cli:commons-cli:1.9.0'

上述依賴中的版本號 1.9.0 是當前最新版本，以下代碼均以當前版本為準。如果您需要在生產環境使用，請及時更新為最新版本。

2. 基礎示例

讓我們從一個最簡單的例子開始：

package org.hbin.cli;import org.apache.commons.cli.*;public class GreetApp {public static void main(String[] args) {// 1. 創建選項定義Options options = new Options();options.addOption("n", "name", true, "指定您的名字");// 2. 創建解析器CommandLineParser parser = new DefaultParser();HelpFormatter formatter = new HelpFormatter();try {// 3. 解析參數CommandLine cmd = parser.parse(options, args);// 4. 處理參數if (cmd.hasOption("n")) {String name = cmd.getOptionValue("n");System.out.println("你好, " + name + "!");} else {System.out.println("你好, 世界!");}} catch (ParseException e) {System.err.println("參數錯誤: " + e.getMessage());formatter.printHelp("greet", options);System.exit(1);}}
}

3. 運行示例

1. 在Idea中運行

2. 命令行中運行

> java org.hbin.cli.GreetApp -n Haley

注意，直接運行上述命令可能會報錯 java.lang.NoClassDefFoundError，如下圖：

這是因為運行時classpath中缺少Commons CLI的jar文件，需要指定其路徑。

> java -cp .;%MAVEN_HOME%\repo\commons-cli\commons-cli\1.9.0\commons-cli-1.9.0.jar org.hbin.cli.GreetApp -n Haley

3. 使用 Maven/Gradle 運行（推薦）

如果是Maven項目：

mvn compile exec:java -Dexec.mainClass="org.hbin.cli.GreetApp" -Dexec.args="-n Haley"

如果是Gradle項目：

gradle run --args="-n Haley"

4. 使用可運行jar運行

上述代碼也可以使用Maven Assembly Plugin制作成一個可運行jar，然后再運行。步驟如下：

1. 配置pom.xml

<build><plugins><!-- 配置 maven-assembly-plugin --><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-assembly-plugin</artifactId><version>3.3.0</version><configuration><archive><manifest><!-- 指定主類 --><mainClass>org.hbin.cli.GreetApp</mainClass></manifest></archive><descriptorRefs><!-- 使用預定義的 jar-with-dependencies 描述符 --><descriptorRef>jar-with-dependencies</descriptorRef></descriptorRefs></configuration><executions><execution><id>make-assembly</id><phase>package</phase><goals><goal>single</goal></goals></execution></executions></plugin></plugins>
</build>

2. 執行打包任務

雙擊 maven 面板中的 package 執行打包或使用命令行打包：mvn clean package。

3. 查看生成的jar文件

打包完成后，在項目的 target 目錄下會生成兩個 Jar 文件：

• CliExample-1.0-SNAPSHOT.jar - 不包含依賴的基本 Jar
• CliExample-1.0-SNAPSHOT-jar-with-dependencies.jar - 包含所有依賴的可運行 Jar

4. 運行jar文件

java -jar target/CliExample-1.0-SNAPSHOT-jar-with-dependencies.jar -n Haley

四、核心概念詳解

1. 選項定義

Commons CLI 使用 Options 類來定義程序接受的參數：

Options options = new Options();// 簡單選項
options.addOption("h", "help", false, "顯示幫助信息");// 帶參數的選項
options.addOption("n", "name", true, "指定輸入名稱");// 使用構建器模式創建復雜選項
options.addOption(Option.builder("n").longOpt("name").hasArg().argName("NAME").desc("指定名稱").build());

2. 選項類型

類型	示例	說明
無參選項	-h, --help	只表示一個開關狀態
帶參選項	-n Haley	需要接收一個參數
可選參數	-d [debugLevel]	參數可有可無
多值選項	-Dkey1=value1 -Dkey2=value2	可以接收多個鍵值對

3. 參數解析

使用 DefaultParser 解析命令行參數：

CommandLineParser parser = new DefaultParser();
try {CommandLine cmd = parser.parse(options, args);// 檢查選項是否存在if (cmd.hasOption("h")) {// 處理幫助選項}// 獲取選項值String name = cmd.getOptionValue("n");
} catch (ParseException e) {// 處理解析錯誤
}

4. 幫助信息

HelpFormatter 可以生成標準化的幫助信息：

HelpFormatter formatter = new HelpFormatter();
formatter.printHelp("greet", options, true);

輸出示例：

五、實戰案例

1. 文件處理工具

package org.hbin.cli;import org.apache.commons.cli.CommandLine;
import org.apache.commons.cli.CommandLineParser;
import org.apache.commons.cli.DefaultParser;
import org.apache.commons.cli.HelpFormatter;
import org.apache.commons.cli.Option;
import org.apache.commons.cli.Options;
import org.apache.commons.cli.ParseException;public class FileProcessor {public static void main(String[] args) {Options options = new Options();// 必選輸入文件options.addOption(Option.builder("i").longOpt("input").required().hasArg().desc("輸入文件路徑(必選)").build());// 可選輸出文件options.addOption(Option.builder("o").longOpt("output").hasArg().desc("輸出文件路徑").build());// 詳細模式options.addOption("v", "verbose", false, "顯示詳細日志");CommandLineParser parser = new DefaultParser();HelpFormatter formatter = new HelpFormatter();try {CommandLine cmd = parser.parse(options, args);String inputFile = cmd.getOptionValue("i");System.out.println("處理文件: " + inputFile);if (cmd.hasOption("o")) {String outputFile = cmd.getOptionValue("o");System.out.println("輸出到: " + outputFile);}if (cmd.hasOption("v")) {System.out.println("詳細模式已啟用");}// 實際文件處理邏輯...} catch (ParseException e) {System.err.println("錯誤: " + e.getMessage());formatter.printHelp("fileprocessor", options, true);System.exit(1);}}
}

2. 配置加載工具

package org.hbin.cli;import java.util.Properties;
import org.apache.commons.cli.CommandLine;
import org.apache.commons.cli.DefaultParser;
import org.apache.commons.cli.HelpFormatter;
import org.apache.commons.cli.Option;
import org.apache.commons.cli.Options;
import org.apache.commons.cli.ParseException;public class ConfigLoader {public static void main(String[] args) {Options options = new Options();// 配置文件選項options.addOption("c", "config", true, "配置文件路徑");// 多值系統屬性options.addOption(Option.builder("D").hasArgs().valueSeparator().desc("系統屬性，格式為-Dkey=value").build());try {CommandLine cmd = new DefaultParser().parse(options, args);if (cmd.hasOption("c")) {String configFile = cmd.getOptionValue("c");System.out.println("加載配置文件: " + configFile);}if (cmd.hasOption("D")) {Properties props = cmd.getOptionProperties("D");System.out.println("系統屬性:");props.forEach((k, v) -> System.out.println("  " + k + " = " + v));}} catch (ParseException e) {new HelpFormatter().printHelp("configloader", options);System.exit(1);}}
}

六、最佳實踐

1. 必選參數檢查：使用 required(true) 標記必選參數
2. 友好的幫助信息：為每個選項提供清晰的描述
3. 參數驗證：解析后應對參數值進行額外驗證
4. 錯誤處理：捕獲 ParseException 并提供有用的錯誤信息
5. 代碼組織：將選項定義、解析和處理邏輯分開

七、常見問題解答

Q1: 如何處理未知選項？

A: DefaultParser 默認會拋出 ParseException，你可以在 catch 塊中處理這種情況。

Q2: 如何支持子命令？

A: Commons CLI 本身不直接支持子命令，但可以通過組合多個 Options 對象來實現類似功能。

Q3: 如何設置選項的默認值？

A: 可以在獲取選項值時提供默認值：

String value = cmd.getOptionValue("option", "default");

Q4: 如何處理多個相同的選項？

A: 使用 getOptionValues() 方法：

String[] values = cmd.getOptionValues("option");

八、總結

通過本教程，你已經學會了：

1. 如何在項目中引入 Commons CLI
2. 如何定義各種類型的命令行選項
3. 如何解析和處理命令行參數
4. 如何生成標準化的幫助信息
5. 幾個實用的實戰案例

Commons CLI 是 Java 開發命令行工具的利器，掌握它能讓你快速構建出專業級的命令行應用。現在，嘗試為你自己的項目添加命令行支持吧！