Apache Commons Codec 常用 CLI 命令与工具详解

Commons Codec 无自带 CLI,实测其工具链:javac/java -cp 直跑、jar tf 与 javap 透视 jar、Maven 构建命令,sha512sum、openssl dgst 与 DigestUtils 互验。

Apache Commons CodecApache Commons Codec2026/10/13

Apache Commons Codec 常用 CLI 命令与工具详解

目标:Commons Codec 是纯 Java 库、不自带任何命令行可执行程序,本篇把「使用它时真正会用到的命令行工具链」一次讲透——javac/java 直跑、jar/javap 透视类库、Maven 构建与多版本命令、系统摘要工具与库内 DigestUtils 的交叉验证——已在 Ubuntu 22.04(OpenJDK 17.0.20.1、Maven 3.6.3、Commons Codec 1.23.0)实测通过。

一、环境信息

  • 操作系统:Ubuntu 22.04(jammy),x86_64
  • JDK:OpenJDK 17.0.20.1(javac/java/jar/javap 来自 openjdk-17-jdk-headless)
  • 构建工具:Apache Maven 3.6.3
  • 组件版本:Apache Commons Codec 1.23.0(jar 440773 字节,MANIFEST 实测 Implementation-Version: 1.23.0)
  • 对照工具:coreutils sha512sum/md5sum/sha1sum/sha256sum、OpenSSL 3.0.2
  • 实验目录:/opt/lab/codec-manual(lib/commons-codec-1.23.0.jar、src/、classes/)与 /opt/lab/codec-maven
  • 执行用户:root

二、工具概览

Commons Codec 的「命令行」由 JDK 工具、Maven 与系统校验工具三部分组成,分工如下:

工具所属与 Codec 相关的用途
javac / javaJDK编译、运行调用 Codec 的示例类(-cp 挂载 jar)
jarJDKjar tf 查看包结构、解出 MANIFEST 核对版本
javapJDK查看类与方法的真实签名,核对参数
mvnMaven拉依赖、编译工程、多版本管理
sha512sum / md5sum / sha1sum / sha256sumcoreutils对同一文件求摘要,与 DigestUtils 结果互验
opensslOpenSSLdgst 求摘要、base64 -A 做 Base64 对照

解读:Codec 本体只提供 Java API,所有「命令行能力」都是借用上述工具完成的;其中摘要工具对照(第七节)是最有实用价值的部分——它能证明库的计算结果与系统级工具完全一致。

三、前置条件

所有示例可独立执行,只需 JDK 8+ 与 codec jar。jar 的一键获取与校验:

mkdir -p /opt/lab/codec-manual/lib && cd /opt/lab/codec-manual && wget -q https://downloads.apache.org/commons/codec/binaries/commons-codec-1.23.0-bin.tar.gz && wget -q https://downloads.apache.org/commons/codec/binaries/commons-codec-1.23.0-bin.tar.gz.sha512 && printf '%s  %s\n' "$(cat commons-codec-1.23.0-bin.tar.gz.sha512)" commons-codec-1.23.0-bin.tar.gz | sha512sum -c - && tar xzf commons-codec-1.23.0-bin.tar.gz && cp commons-codec-1.23.0/commons-codec-1.23.0.jar lib/

回显(实测):

commons-codec-1.23.0-bin.tar.gz: OK
java -version 2>&1 | head -1 && javac -version && jar --version | head -1

回显(实测):

openjdk version "17.0.20.1" 2026-08-18
javac 17.0.20.1
jar 17.0.20.1

校验 OK、JDK 三件套版本正常,即可执行本篇全部命令。Maven 相关命令另需 Maven(安装见《Ubuntu 22.04 安装 Apache Commons Codec 指南》方案 A)。

四、javac 与 java -cp:不装构建工具直跑 Codec

本节用最朴素的方式把 Codec 跑起来:javac 编译一个调用类,java 用 -cp 同时挂载「classes 目录 + codec jar」。这一套路也是排查依赖问题时的最小复现手段。

4.1 编译调用类

cd /opt/lab/codec-manual && cat > src/HelloCodec.java <<'EOF'
import java.nio.charset.StandardCharsets;
import org.apache.commons.codec.binary.Base64;

public class HelloCodec {
    public static void main(String[] args) {
        String text = "Apache Commons Codec";
        String encoded = Base64.encodeBase64String(text.getBytes(StandardCharsets.UTF_8));
        System.out.println("encoded: " + encoded);
        System.out.println("decoded: " + new String(Base64.decodeBase64(encoded), StandardCharsets.UTF_8));
    }
}
EOF
javac -encoding UTF-8 -cp lib/commons-codec-1.23.0.jar -d classes src/HelloCodec.java

回显(实测,编译成功无输出):

javac -cp 让编译期能找到 org.apache.commons.codec.binary.Base64;-encoding UTF-8 保证源码按 UTF-8 解析。

4.2 运行

cd /opt/lab/codec-manual && java -cp classes:lib/commons-codec-1.23.0.jar HelloCodec

回显(实测):

encoded: QXBhY2hlIENvbW1vbnMgQ29kZWM=
decoded: Apache Commons Codec

运行期 -cp 用冒号(Linux)拼接两个条目,目录与 jar 都可以出现在类路径上。验证要点:输出中编码串以 = 补位结尾、解码与原文一致,说明类路径挂载正确。

4.3 多条目类路径与版本核对

把 jar 解出 MANIFEST 核对实际版本(排查「类路径上到底是谁」最可靠的办法):

cd /tmp && jar xf /opt/lab/codec-manual/lib/commons-codec-1.23.0.jar META-INF/MANIFEST.MF && grep -E "Specification-Version|Implementation-Version" META-INF/MANIFEST.MF

回显(实测):

Specification-Version: 1.23
Implementation-Version: 1.23.0

回显确认版本为 1.23.0;若同环境有多个 codec jar,对每个 jar 重复此命令即可分辨。

五、jar 与 javap:透视类库

5.1 jar tf:查看包结构与条目数

jar tf /opt/lab/codec-manual/lib/commons-codec-1.23.0.jar | wc -l

回显(实测):

312
jar tf /opt/lab/codec-manual/lib/commons-codec-1.23.0.jar | head -12

回显(实测):

META-INF/
META-INF/MANIFEST.MF
org/
org/apache/
org/apache/commons/
org/apache/commons/codec/
org/apache/commons/codec/binary/
org/apache/commons/codec/cli/
org/apache/commons/codec/digest/
org/apache/commons/codec/language/
org/apache/commons/codec/language/bm/
org/apache/commons/codec/net/
jar tf /opt/lab/codec-manual/lib/commons-codec-1.23.0.jar | grep -c '\.class$'

回显(实测):

163

解读:全包 312 个条目、163 个 class,顶层功能包为 binary(Base64/Base32/Hex 等字节编码)、digest(摘要)、language(语音编码,含 language.bm 多语言变体)、net(URL 编码)、cli(一个内部值对象)。想快速确认「某功能在不在包里」,jar tf 加 grep 是最直接的手段。

5.2 javap:查看真实方法签名

核对 DigestUtils 提供的 hex 摘要方法全集:

javap -cp /opt/lab/codec-manual/lib/commons-codec-1.23.0.jar org.apache.commons.codec.digest.DigestUtils | grep "Hex("

输出节选(实测首尾):

  public static java.lang.String md2Hex(byte[]);
  public static java.lang.String md5Hex(java.io.InputStream) throws java.io.IOException;
  public static java.lang.String sha1Hex(java.lang.String);
  public static java.lang.String sha256Hex(byte[]);
  public static java.lang.String sha3_256Hex(java.io.InputStream) throws java.io.IOException;
  public static java.lang.String sha512Hex(java.lang.String);
  public static java.lang.String shake256_512Hex(java.io.InputStream) throws java.io.IOException;

每个算法都有 byte[]、InputStream、String 三种入参重载,且 1.23 还包含 SHA3、SHAKE 等新族。再看 Hex 类构造器:

javap -cp /opt/lab/codec-manual/lib/commons-codec-1.23.0.jar org.apache.commons.codec.binary.Hex | grep "public org"

回显(实测):

  public org.apache.commons.codec.binary.Hex();
  public org.apache.commons.codec.binary.Hex(java.nio.charset.Charset);
  public org.apache.commons.codec.binary.Hex(java.lang.String);

解读:写代码前用 javap 确认签名,可以避免「参数顺序记反」「重载选错」两类常见错误,这比翻网页文档更可信——它就是字节码里的真身。

六、Maven 工具链命令

6.1 mvn compile:编译含 codec 依赖的工程

cd /opt/lab/codec-maven && mvn clean compile

回显(实测):

[INFO] Scanning for projects...
[INFO] 
[INFO] --------------------------< demo:codec-demo >---------------------------
[INFO] Building codec-demo 1.0.0
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ codec-demo ---
Downloading from central: https://repo.maven.apache.org/maven2/org/codehaus/plexus/plexus-utils/3.0/plexus-utils-3.0.pom
Progress (1): 4.1 kB
                    
Downloaded from central: https://repo.maven.apache.org/maven2/org/codehaus/plexus/plexus-utils/3.0/plexus-utils-3.0.pom (4.1 kB at 3.3 kB/s)
Downloading from central: https://repo.maven.apache.org/maven2/org/codehaus/plexus/plexus-utils/3.0/plexus-utils-3.0.jar
Progress (1): 2.3/226 kB
Progress (1): 5.0/226 kB
Progress (1): 7.7/226 kB
Progress (1): 10/226 kB 
Progress (1): 13/226 kB
Progress (1): 15/226 kB
Progress (1): 18/226 kB
Progress (1): 21/226 kB
Progress (1): 24/226 kB
Progress (1): 26/226 kB
Progress (1): 29/226 kB
Progress (1): 32/226 kB
Progress (1): 35/226 kB
Progress (1): 37/226 kB
Progress (1): 40/226 kB
Progress (1): 43/226 kB
Progress (1): 46/226 kB
Progress (1): 48/226 kB
Progress (1): 52/226 kB
Progress (1): 57/226 kB
Progress (1): 61/226 kB
Progress (1): 65/226 kB
Progress (1): 69/226 kB
Progress (1): 73/226 kB
Progress (1): 75/226 kB
Progress (1): 79/226 kB
Progress (1): 83/226 kB
Progress (1): 87/226 kB
Progress (1): 91/226 kB
Progress (1): 96/226 kB
Progress (1): 100/226 kB
Progress (1): 104/226 kB
Progress (1): 108/226 kB
Progress (1): 112/226 kB
Progress (1): 116/226 kB
Progress (1): 120/226 kB
Progress (1): 124/226 kB
Progress (1): 128/226 kB
Progress (1): 132/226 kB
Progress (1): 137/226 kB
Progress (1): 141/226 kB
Progress (1): 143/226 kB
Progress (1): 147/226 kB
Progress (1): 151/226 kB
Progress (1): 155/226 kB
Progress (1): 159/226 kB
Progress (1): 163/226 kB
Progress (1): 167/226 kB
Progress (1): 171/226 kB
Progress (1): 176/226 kB
Progress (1): 180/226 kB
Progress (1): 184/226 kB
Progress (1): 188/226 kB
Progress (1): 192/226 kB
Progress (1): 196/226 kB
Progress (1): 200/226 kB
Progress (1): 204/226 kB
Progress (1): 208/226 kB
Progress (1): 210/226 kB
Progress (1): 214/226 kB
Progress (1): 219/226 kB
Progress (1): 223/226 kB
Progress (1): 226 kB    
                    
Downloaded from central: https://repo.maven.apache.org/maven2/org/codehaus/plexus/plexus-utils/3.0/plexus-utils-3.0.jar (226 kB at 263 kB/s)
[INFO] Deleting /opt/lab/codec-maven/target
[INFO] 
[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ codec-demo ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] skip non existing resourceDirectory /opt/lab/codec-maven/src/main/resources
[INFO] 
[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ codec-demo ---
[INFO] Changes detected - recompiling the module!
[INFO] Compiling 1 source file to /opt/lab/codec-maven/target/classes
[WARNING] /opt/lab/codec-maven/src/main/java/demo/CodecDemo.java: /opt/lab/codec-maven/src/main/java/demo/CodecDemo.java uses or overrides a deprecated API.
[WARNING] /opt/lab/codec-maven/src/main/java/demo/CodecDemo.java: Recompile with -Xlint:deprecation for details.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.559 s
[INFO] Finished at: 2026-10-13T04:23:00Z
[INFO] ------------------------------------------------------------------------

BUILD SUCCESS 表示依赖解析与编译都成功。两条 WARNING 是因为 CodecDemo 故意演示了 1.23 中已 @Deprecated 的旧构造器(如 new Base64(int)),按提示加 -Xlint:deprecation 重新编译即可看到明细,属预期现象;pom 内容见《Ubuntu 22.04 安装 Apache Commons Codec 指南》4.2 节(依赖为 commons-codec:commons-codec:1.23.0)。命令中的 clean 先清空 target 再编译,保证看到完整编译过程;若省略 clean,增量编译会提示 Nothing to compile - all classes are up to date(实测第二跑即如此)。

BUILD SUCCESS 表示依赖解析与编译都成功;pom 内容见《Ubuntu 22.04 安装 Apache Commons Codec 指南》4.2 节(依赖为 commons-codec:commons-codec:1.23.0)。

6.2 mvn dependency:get:按坐标拉任意版本

不需要工程,直接把指定版本拉进本地仓库(多版本管理最常用的命令):

cd /opt/lab/codec-maven && mvn -q dependency:get -Dartifact=commons-codec:commons-codec:1.18.0 && ls ~/.m2/repository/commons-codec/commons-codec/

回显(实测):

1.18.0
1.23.0

6.3 mvn dependency:build-classpath:导出依赖类路径

cd /opt/lab/codec-maven && mvn -q dependency:build-classpath -Dmdep.outputFile=/tmp/cp.txt >/dev/null 2>&1; cat /tmp/cp.txt

回显(实测):

/root/.m2/repository/commons-codec/commons-codec/1.23.0/commons-codec-1.23.0.jar

导出的路径可直接拼进 java -cp,实现「Maven 管依赖、java 直跑」的混合用法。

七、系统摘要与编码工具对照(最有价值的互验)

Codec 的计算结果能否与系统级工具对上?本节用同一个文件(commons-codec-1.23.0-bin.tar.gz,4329713 字节)做四方互验:库内 DigestUtils、coreutils、OpenSSL、官方 .sha512。

7.1 Java 侧:DigestUtils 文件摘要

cd /opt/lab/codec-manual && cat > src/CliCompare.java <<'EOF'
import java.io.FileInputStream;
import java.io.InputStream;
import org.apache.commons.codec.digest.DigestUtils;

public class CliCompare {
    public static void main(String[] args) throws Exception {
        try (InputStream in = new FileInputStream(args[0])) {
            System.out.println("md5Hex    = " + DigestUtils.md5Hex(in));
        }
        try (InputStream in = new FileInputStream(args[0])) {
            System.out.println("sha1Hex   = " + DigestUtils.sha1Hex(in));
        }
        try (InputStream in = new FileInputStream(args[0])) {
            System.out.println("sha256Hex = " + DigestUtils.sha256Hex(in));
        }
        try (InputStream in = new FileInputStream(args[0])) {
            System.out.println("sha512Hex = " + DigestUtils.sha512Hex(in));
        }
    }
}
EOF
javac -cp lib/commons-codec-1.23.0.jar -d classes src/CliCompare.java && java -cp classes:lib/commons-codec-1.23.0.jar CliCompare commons-codec-1.23.0-bin.tar.gz

回显(实测):

md5Hex    = 018f2ea63b2319ec852a716a5fb1aea8
sha1Hex   = ae114d3ba1ae694eae8827a130b1ac2ef96bb02a
sha256Hex = 32af8585924eda935c05e171d5f96c2ef8c3f108ef05f96080253dc68f800816
sha512Hex = 34a8cb4bafd3bb56fed56f1609b9c45f8cc25c31d7fdc9fca8df498d9b73efb4b8636b5f8a1c7d6439cca200b35a991867287b4ca14159af8cef4ca56a04559a

💡 技术拓展:摘要算法横向对比——

算法摘要长度hex 长度(本节实测)安全现状适用
MD5128 位32已可构造碰撞非安全校验、旧协议
SHA-1160 位40已实质攻破遗留兼容(git 对象)
SHA-256256 位64目前安全通用推荐
SHA-512512 位128目前安全高安全、官方发行包校验

本节四方互验对四种算法同时进行,实际选型建议:新系统 SHA-256 起步,校验官方发行包跟随官方的 SHA-512。

7.2 coreutils 侧:sha512sum / md5sum / sha1sum / sha256sum

cd /opt/lab/codec-manual && sha512sum commons-codec-1.23.0-bin.tar.gz

回显(实测):

34a8cb4bafd3bb56fed56f1609b9c45f8cc25c31d7fdc9fca8df498d9b73efb4b8636b5f8a1c7d6439cca200b35a991867287b4ca14159af8cef4ca56a04559a  commons-codec-1.23.0-bin.tar.gz
cd /opt/lab/codec-manual && md5sum commons-codec-1.23.0-bin.tar.gz && sha1sum commons-codec-1.23.0-bin.tar.gz && sha256sum commons-codec-1.23.0-bin.tar.gz

回显(实测):

018f2ea63b2319ec852a716a5fb1aea8  commons-codec-1.23.0-bin.tar.gz
ae114d3ba1ae694eae8827a130b1ac2ef96bb02a  commons-codec-1.23.0-bin.tar.gz
32af8585924eda935c05e171d5f96c2ef8c3f108ef05f96080253dc68f800816  commons-codec-1.23.0-bin.tar.gz

与 7.1 节 Java 侧输出逐字符一致,四种算法全部对上。官方校验文件同样通过:

cd /opt/lab/codec-manual && printf '%s  %s\n' "$(cat commons-codec-1.23.0-bin.tar.gz.sha512)" commons-codec-1.23.0-bin.tar.gz | sha512sum -c -

回显(实测):

commons-codec-1.23.0-bin.tar.gz: OK

7.3 OpenSSL 侧:openssl dgst 与 openssl base64

cd /opt/lab/codec-manual && openssl dgst -sha512 commons-codec-1.23.0-bin.tar.gz

回显(实测):

SHA2-512(commons-codec-1.23.0-bin.tar.gz)= 34a8cb4bafd3bb56fed56f1609b9c45f8cc25c31d7fdc9fca8df498d9b73efb4b8636b5f8a1c7d6439cca200b35a991867287b4ca14159af8cef4ca56a04559a
cd /opt/lab/codec-manual && openssl dgst -md5 commons-codec-1.23.0-bin.tar.gz && openssl dgst -sha256 commons-codec-1.23.0-bin.tar.gz

回显(实测):

MD5(commons-codec-1.23.0-bin.tar.gz)= 018f2ea63b2319ec852a716a5fb1aea8
SHA2-256(commons-codec-1.23.0-bin.tar.gz)= 32af8585924eda935c05e171d5f96c2ef8c3f108ef05f96080253dc68f800816

Base64 对照(-A 表示单行输出):

printf 'Apache Commons Codec' | openssl base64 -A

回显(实测):

QXBhY2hlIENvbW1vbnMgQ29kZWM=
printf 'QXBhY2hlIENvbW1vbnMgQ29kZWM=' | openssl base64 -d -A

回显(实测):

Apache Commons Codec

openssl 的 Base64 编解码结果与 Codec Base64.encodeBase64String/decodeBase64 完全一致(4.2 节的编码串即 QXBhY2hlIENvbW1vbnMgQ29kZWM=)。

7.4 字符串摘要对照:printf | md5sum 与 md5Hex

printf 'hello commons codec' | md5sum

回显(实测):

0de51781c71760acea105104c0460127  -
printf 'hello commons codec' | sha256sum

回显(实测):

194a3449ab8c2a0649f03e6b73fd919d08fcd0730dcbd5269c998ff3a4b0d8ca  -

这两个值与 DigestUtils.md5Hex("hello commons codec")、DigestUtils.sha256Hex("hello commons codec") 的返回值完全相同(String 入参固定按 UTF-8 取字节)。验证要点:shell 侧必须用 printf(不带换行);换成 echo 会多一个换行字节,摘要立即不同。

八、注意事项

  • 类路径分隔符是平台相关的:Linux/Mac 用冒号 :,Windows 用分号 ;,混用会静默丢类。
  • 摘要对照时保证「字节完全一致」:文件比文件没问题;字符串比字符串必须用 printf 且两端字符集一致(Java String 入参固定 UTF-8)。
  • openssl dgst 一次只认一个摘要算法标志,同时给 -md5 -sha256 时只有最后一个生效(实测踩过:仅输出 SHA2-256),多算法要分多条命令。
  • jar tf/javap 只读不改,可放心对生产 jar 使用;jar xf 会解出文件,请在临时目录操作。
  • Maven 命令需在含 pom.xml 的目录执行,否则报「no POM in this directory」;dependency:get 是唯一例外,它不依赖工程。

九、常见问题(FAQ)

Q1:为什么 java -cp 明明写了 jar 还是报 NoClassDefFoundError? 三个高频原因:一是多个条目间漏了冒号(例如该写 classes:lib 却写成 classeslib,两个路径会被当成一个);二是相对路径的基准目录不对(java 必须在类路径相对的目录执行,或改用绝对路径);三是 Windows 下用了冒号(应改分号)。排查时把 -cp 值原样 echo 出来逐个核对,再用 jar tf <jar> | grep <类名> 确认类确实在该 jar 里。

Q2:openssl dgst 同时给 -md5 -sha1 -sha256 为什么只出一个结果? 实测复现:

cd /opt/lab/codec-manual && openssl dgst -md5 -sha1 -sha256 commons-codec-1.23.0-bin.tar.gz

回显(实测):

SHA2-256(commons-codec-1.23.0-bin.tar.gz)= 32af8585924eda935c05e171d5f96c2ef8c3f108ef05f96080253dc68f800816

openssl dgst 的算法标志互相覆盖,只有最后一个生效。需要多种摘要就分多条命令执行(7.3 节做法),这一点与 coreutils 的 sha1sum/sha256sum 独立命令风格不同。

Q3:Java 程序中文输出变 ?,怎么在命令行层面解决? 系统 locale 是 POSIX 时 JVM 默认编码非 UTF-8。运行时加 LANG=C.UTF-8(如 LANG=C.UTF-8 java -cp classes:lib/commons-codec-1.23.0.jar HelloCodec),javac 侧加 -encoding UTF-8。本篇涉及中文输出的示例均在该设置下实测。

Q4:怎么确认跑的是哪个版本的 codec jar? 最可靠的两条命令:jar tf 确认类存在(5.1 节),解 MANIFEST 看版本(4.3 节,实测 Implementation-Version: 1.23.0)。只看文件名不可靠——文件名可以随意改,MANIFEST 不会说谎。

Q5:mvn -q 与 mvn 输出差很多,哪个是正常的? -q 只在出错时输出(quiet 模式),日常核对用不带 -q 的完整输出看 BUILD SUCCESS。本篇 6.2/6.3 节用 -q 是为了静默拉取后直接展示结果文件,属正常用法。

十、参考链接

  1. JDK java 命令手册(类路径规范):https://docs.oracle.com/en/java/javase/17/docs/specs/man/java.html
  2. JDK jar 命令手册:https://docs.oracle.com/en/java/javase/17/docs/specs/man/jar.html
  3. Apache Commons Codec 项目主页:https://commons.apache.org/proper/commons-codec/
  4. Maven 依赖插件 dependency:get 文档:https://maven.apache.org/plugins/maven-dependency-plugin/get-mojo.html
  5. OpenSSL dgst 文档:https://docs.openssl.org/3.0/man1/openssl-dgst/