Apache Commons Codec 常用 CLI 命令与工具详解
Commons Codec 无自带 CLI,实测其工具链:javac/java -cp 直跑、jar tf 与 javap 透视 jar、Maven 构建命令,sha512sum、openssl dgst 与 DigestUtils 互验。
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 / java | JDK | 编译、运行调用 Codec 的示例类(-cp 挂载 jar) |
| jar | JDK | jar tf 查看包结构、解出 MANIFEST 核对版本 |
| javap | JDK | 查看类与方法的真实签名,核对参数 |
| mvn | Maven | 拉依赖、编译工程、多版本管理 |
| sha512sum / md5sum / sha1sum / sha256sum | coreutils | 对同一文件求摘要,与 DigestUtils 结果互验 |
| openssl | OpenSSL | dgst 求摘要、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
回显(实测):
[[1;34mINFO[m] Scanning for projects...
[[1;34mINFO[m]
[[1;34mINFO[m] [1m--------------------------< [0;36mdemo:codec-demo[0;1m >---------------------------[m
[[1;34mINFO[m] [1mBuilding codec-demo 1.0.0[m
[[1;34mINFO[m] [1m--------------------------------[ jar ]---------------------------------[m
[[1;34mINFO[m]
[[1;34mINFO[m] [1m--- [0;32mmaven-clean-plugin:2.5:clean[m [1m(default-clean)[m @ [36mcodec-demo[0;1m ---[m
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)
[[1;34mINFO[m] Deleting /opt/lab/codec-maven/target
[[1;34mINFO[m]
[[1;34mINFO[m] [1m--- [0;32mmaven-resources-plugin:2.6:resources[m [1m(default-resources)[m @ [36mcodec-demo[0;1m ---[m
[[1;34mINFO[m] Using 'UTF-8' encoding to copy filtered resources.
[[1;34mINFO[m] skip non existing resourceDirectory /opt/lab/codec-maven/src/main/resources
[[1;34mINFO[m]
[[1;34mINFO[m] [1m--- [0;32mmaven-compiler-plugin:3.1:compile[m [1m(default-compile)[m @ [36mcodec-demo[0;1m ---[m
[[1;34mINFO[m] Changes detected - recompiling the module!
[[1;34mINFO[m] Compiling 1 source file to /opt/lab/codec-maven/target/classes
[[1;33mWARNING[m] /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.
[[1;33mWARNING[m] /opt/lab/codec-maven/src/main/java/demo/CodecDemo.java: Recompile with -Xlint:deprecation for details.
[[1;34mINFO[m] [1m------------------------------------------------------------------------[m
[[1;34mINFO[m] [1;32mBUILD SUCCESS[m
[[1;34mINFO[m] [1m------------------------------------------------------------------------[m
[[1;34mINFO[m] Total time: 3.559 s
[[1;34mINFO[m] Finished at: 2026-10-13T04:23:00Z
[[1;34mINFO[m] [1m------------------------------------------------------------------------[m
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 长度(本节实测) 安全现状 适用 MD5 128 位 32 已可构造碰撞 非安全校验、旧协议 SHA-1 160 位 40 已实质攻破 遗留兼容(git 对象) SHA-256 256 位 64 目前安全 通用推荐 SHA-512 512 位 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 是为了静默拉取后直接展示结果文件,属正常用法。
十、参考链接
- JDK java 命令手册(类路径规范):https://docs.oracle.com/en/java/javase/17/docs/specs/man/java.html
- JDK jar 命令手册:https://docs.oracle.com/en/java/javase/17/docs/specs/man/jar.html
- Apache Commons Codec 项目主页:https://commons.apache.org/proper/commons-codec/
- Maven 依赖插件 dependency:get 文档:https://maven.apache.org/plugins/maven-dependency-plugin/get-mojo.html
- OpenSSL dgst 文档:https://docs.openssl.org/3.0/man1/openssl-dgst/