Apache Commons CSV 常用 CLI 命令与工具详解
以命令行实操演示 Commons CSV 1.14.1：jshell 交互、javac 与 java -cp 编译运行、格式探测、awk/cut/column 对照、CSVPrinter 写出对齐查看与三种方言读写往返，全程实测。
Apache Commons CSVApache Commons CSV2026/10/13
Apache Commons CSV 常用 CLI 命令与工具详解
目标：在不开 IDE 的纯命令行环境下，用 jshell、javac/java -cp 熟练操作 Apache Commons CSV 1.14.1，包括格式探测、与 awk/cut/column 等系统命令的能力对照、CSVPrinter 写出与对齐查看、三种方言读写往返与大文件流式验证。已在 Ubuntu 22.04 / CentOS 8（JDK 17 + Maven）实测通过。
一、环境信息
先备好 jar 与目录，本文全部命令可逐条复现。
cat /etc/os-release | head -2 && uname -m
回显：
NAME="Ubuntu"
PRETTY_NAME="Ubuntu 22.04.5 LTS"
x86_64
java -version | head -1
回显：
openjdk version "17.0.20.1" 2026-08-18
下载三个 jar（主包 + 两个运行期依赖，1.14.1 缺依赖会在运行期报 NoClassDefFoundError）：
mkdir -p /opt/csvlib && cd /opt/csvlib
curl -fsSLO https://downloads.apache.org/commons/csv/binaries/commons-csv-1.14.1-bin.tar.gz
curl -fsSLO https://downloads.apache.org/commons/csv/binaries/commons-csv-1.14.1-bin.tar.gz.sha512
echo "$(cat commons-csv-1.14.1-bin.tar.gz.sha512) commons-csv-1.14.1-bin.tar.gz" | sha512sum -c -
tar xzf commons-csv-1.14.1-bin.tar.gz
curl -fsSLO https://repo1.maven.org/maven2/commons-io/commons-io/2.20.0/commons-io-2.20.0.jar
curl -fsSLO https://repo1.maven.org/maven2/commons-codec/commons-codec/1.19.0/commons-codec-1.19.0.jar
回显：
commons-csv-1.14.1-bin.tar.gz: OK
mkdir -p /opt/csvwork && cd /opt/csvwork
export CP=/opt/csvlib/commons-csv-1.14.1/commons-csv-1.14.1.jar:/opt/csvlib/commons-io-2.20.0.jar:/opt/csvlib/commons-codec-1.19.0.jar
回显无输出。本章后续所有 javac/java/jshell 命令都基于这个已导出的 CP 变量；新开终端需重新 export。
二、jshell 交互实操
jshell 是 JDK 自带的交互式 REPL，适合在写正式类之前快速试 CSV API。
2.1 确认版本并挂载类路径
jshell --version
回显（输出节选，实测）：
jshell 17.0.20.1
进入 jshell 后用 /env 挂类路径（或启动时用 --class-path，效果相同）：
jshell -q
随后在交互界面输入：
/env -class-path /opt/csvlib/commons-csv-1.14.1/commons-csv-1.14.1.jar:/opt/csvlib/commons-io-2.20.0.jar:/opt/csvlib/commons-codec-1.19.0.jar
import org.apache.commons.csv.*;
try (CSVParser p = CSVParser.parse("id,name\n1,Alice\n2,Bob\n", CSVFormat.DEFAULT.builder().setHeader().setSkipHeaderRecord(true).get())) { p.forEach(r -> System.out.println("row " + r.getRecordNumber() + ": " + r.get("id") + " / " + r.get("name"))); }
CSVFormat.MYSQL.getDelimiterString().codePointAt(0)
/exit
回显（已省略欢迎横幅）：
jshell> jshell> jshell> row 1: 1 / Alice
row 2: 2 / Bob
jshell> $3 ==> 9
jshell>
说明：静默模式（-q）下变量声明与 import 不回显，只有表达式结果输出；$3 ==> 9 证明 MYSQL 分隔符是制表符（ASCII 9）。把上面五行存成 .jsh 脚本也能非交互执行：jshell -q --class-path "$CP" demo.jsh，成功时同样只打印表达式结果。
2.2 jshell 的类路径注意点
只挂主 jar 不挂依赖，jshell 内同样报错（实测）：
Exception java.lang.NoClassDefFoundError: org/apache/commons/io/output/AppendableOutputStream
at do_it$Aux (#2:1)
at (#2:1)
Caused by: java.lang.ClassNotFoundException: org.apache.commons.io.output.AppendableOutputStream
at BuiltinClassLoader.loadClass (BuiltinClassLoader.java:641)
结论：jshell 的 --class-path 必须写全三个 jar，与 java -cp 规则一致。
三、javac 与 java -cp 命令行编译运行
最小闭环：单个源文件、一条编译、一条运行。
cd /opt/csvwork && cat > CsvDemo.java <<'EOF'
import org.apache.commons.csv.*;
import java.io.*;
public class CsvDemo {
public static void main(String[] args) throws IOException {
String data = "name,age\n\"Zhang, San\",28\nLi Si,31\n";
CSVFormat fmt = CSVFormat.DEFAULT.builder().setHeader().setSkipHeaderRecord(true).get();
try (CSVParser parser = CSVParser.parse(data, fmt)) {
for (CSVRecord r : parser) {
System.out.println(r.get("name") + " | " + r.get("age"));
}
}
}
}
EOF
javac -cp "$CP" CsvDemo.java && java -cp ".:$CP" CsvDemo
回显：
Zhang, San | 28
Li Si | 31
要点逐项说明：编译时 -cp "$CP" 提供 API 符号；运行时 classpath 必须把当前目录 . 放最前（否则找不到 CsvDemo）；带引号的 "Zhang, San" 被解析为单列，说明引号语义正确。依赖齐全时编译运行均无告警。
四、格式探测
拿到陌生 CSV 先判断方言：分别用多种预设解析，看哪种能切出列数一致且数量合理的记录。写一个通用探测器：
cd /opt/csvwork && cat > Probe.java <<'EOF'
import org.apache.commons.csv.*;
import java.io.*;
import java.nio.charset.StandardCharsets;
import java.util.*;
public class Probe {
public static void main(String[] args) throws Exception {
String file = args[0];
String data = String.join("\n", java.nio.file.Files.readAllLines(java.nio.file.Path.of(file), StandardCharsets.UTF_8));
Map<String, CSVFormat> candidates = new LinkedHashMap<>();
candidates.put("DEFAULT", CSVFormat.DEFAULT);
candidates.put("EXCEL", CSVFormat.EXCEL);
candidates.put("RFC4180", CSVFormat.RFC4180);
candidates.put("TDF", CSVFormat.TDF);
candidates.put("MYSQL", CSVFormat.MYSQL);
for (var e : candidates.entrySet()) {
try (CSVParser p = CSVParser.parse(data, e.getValue())) {
int n = 0;
boolean consistent = true;
int firstSize = -1;
for (CSVRecord r : p) {
if (firstSize < 0) firstSize = r.size();
if (r.size() != firstSize) consistent = false;
n++;
}
System.out.printf("%-16s records=%-5d firstRowFields=%-3d consistent=%s%n",
e.getKey(), n, firstSize, consistent);
} catch (Exception ex) {
System.out.printf("%-16s PARSE-ERROR: %s%n", e.getKey(), String.valueOf(ex.getMessage()).split("\n")[0]);
}
}
}
}
EOF
javac -cp "$CP" Probe.java
回显无输出（编译成功）。构造两个样本分别探测：
printf 'a\tb\tc\n1\t2\t3\n' > tabbed.tsv && printf 'a,b,c\n1,2,3\n' > comma.csv
回显无输出。
java -cp ".:$CP" Probe tabbed.tsv
回显：
DEFAULT records=2 firstRowFields=1 consistent=true
EXCEL records=2 firstRowFields=1 consistent=true
RFC4180 records=2 firstRowFields=1 consistent=true
TDF records=2 firstRowFields=3 consistent=true
MYSQL records=2 firstRowFields=3 consistent=true
java -cp ".:$CP" Probe comma.csv
回显：
DEFAULT records=2 firstRowFields=3 consistent=true
EXCEL records=2 firstRowFields=3 consistent=true
RFC4180 records=2 firstRowFields=3 consistent=true
TDF records=2 firstRowFields=1 consistent=true
MYSQL records=2 firstRowFields=1 consistent=true
判读方法：逗号文件只有逗号系预设切出 3 列，tab 文件只有 TDF/MYSQL 切出 3 列，firstRowFields 与实际列数吻合且 consistent=true 的预设即为候选方言。
五、与系统命令对照
💡 技术拓展：CSV 是"带引号语义的文本"，系统命令按纯文本处理时能力边界如下。
| 工具/写法 | 引号感知 | 含引号逗号字段 | 适用 |
|---|---|---|---|
| cut -d, | 无 | 切错列 | 简单无引号 CSV |
| awk -F, | 无 | 切错列 | 同上 |
| gawk -v FPAT | 有（正则模拟） | 引号逗号/转义引号正确，内嵌换行断行 | 单行记录为主的数据 |
| column -s, -t | 无 | 对齐错位、多行字段断行 | 快速人读对齐 |
| Commons CSV | 完整 RFC 4180 语义 | 正确 | 校验/加工/格式转换 |
5.1 用一个"陷阱文件"实测
cd /opt/csvwork && cat > tricky_lf.csv <<'EOF'
a,"say ""hi"""
b,"line1
line2"
"c,d",e
EOF
回显无输出（字段依次含转义引号、内嵌换行、引号内逗号）。先看各命令表现：
cut -d, -f2 tricky_lf.csv
回显：
"say ""hi"""
"line1
line2"
d"
awk -F, '{print $1}' tricky_lf.csv
回显：
a
b
line2"
"c
awk -v FPAT='([^,]*)|("[^"]*")' '{print "[" $1 "]"}' tricky_lf.csv
回显（Ubuntu 22.04 默认 awk 是 mawk，不支持 FPAT，按默认空格分列输出错误）：
[a,"say]
[b,"line1]
[line2"]
["c,d",e]
先确认默认 awk 的真实身份：
readlink -f $(which awk)
回显（安装 gawk 前）：
/usr/bin/mawk
mawk 把 FPAT 当普通变量忽略，退回默认的空格分列，所以第 1 行切出了 a,"say 这样的残片。安装 gawk 后重试：
apt-get install -y gawk
which gawk
回显：
/usr/bin/gawk
gawk -v FPAT='([^,]*)|("[^"]*")' '{print "[" $1 "]"}' tricky_lf.csv
回显：
[a]
[b]
[line2"]
["c,d"]
gawk 的 FPAT 正确解析了第 1 行（转义引号字段）与第 3 行（引号内逗号），但第 2 行的内嵌换行把一条记录拆成了两行（[b] 与 [line2"]），这是 awk 按 \n 分记录的模型决定的，FPAT 无法跨越记录边界。
column -s, -t -o ' | ' tricky_lf.csv
回显：
a | "say ""hi""" |
b | "line1 |
line2" | |
"c | d" | e
实测结论：cut 与 awk -F, 把引号内逗号当分隔符，第三行字段 d" 属于切错；mawk 不支持 FPAT（Ubuntu 默认 awk 即 mawk，装 gawk 后语法生效）；column 无法理解引号包裹与内嵌换行，对齐视图断行错位。要正确解析请回到 Commons CSV（第三章 CsvDemo 已演示）。
六、CSVPrinter 写出与对齐查看
用 CSVPrinter 生成规范 CSV，再用 column 快速人读。
cd /opt/csvwork && cat > PrintDemo.java <<'EOF'
import org.apache.commons.csv.*;
import java.io.*;
public class PrintDemo {
public static void main(String[] args) throws Exception {
try (CSVPrinter p = new CSVPrinter(new FileWriter("employees.csv"),
CSVFormat.DEFAULT.builder().setHeader("id", "name", "dept").get())) {
p.printRecord(1, "Zhang San", "R&D");
p.printRecord(2, "Li Si, Jr.", "Sales");
p.printRecord(3, "Wang Wu", "Logistics");
}
try (CSVPrinter p = new CSVPrinter(new FileWriter("tricky.csv"), CSVFormat.DEFAULT)) {
p.printRecord("a", "say \"hi\"");
p.printRecord("b", "line1\nline2");
p.printRecord("c,d", "e");
}
System.out.println("done");
}
}
EOF
javac -cp "$CP" PrintDemo.java && java -cp ".:$CP" PrintDemo
回显：
done
cat employees.csv
回显：
id,name,dept
1,Zhang San,R&D
2,"Li Si, Jr.",Sales
3,Wang Wu,Logistics
cat -A tricky.csv
回显（^M$ 即 CRLF，引号转义与内嵌换行都符合 RFC 4180）：
a,"say ""hi"""^M$
b,"line1$
line2"^M$
"c,d",e^M$
用 column 对齐查看（先去 \r 避免 CR 干扰列宽计算）：
tr -d '\r' < employees.csv | column -s, -t -o ' | '
回显：
id | name | dept |
1 | Zhang San | R&D |
2 | "Li Si | Jr." | Sales
3 | Wang Wu | Logistics |
说明：DEFAULT 写出按 MINIMAL 语义只在需要时加引号（Li Si, Jr. 被引）；column 对齐视图中 "Li Si / Jr." 被拆成两列，印证 column 不懂引号语义，仅作人读辅助。
七、三种方言读写往返
用同一份员工数据在 DEFAULT、TDF、MYSQL、EXCEL 之间往返，验证方言转换。
7.1 逗号转 TDF 并读回
cd /opt/csvwork && cat > RoundTrip.java <<'EOF'
import org.apache.commons.csv.*;
import java.io.*;
import java.nio.charset.StandardCharsets;
public class RoundTrip {
public static void main(String[] args) throws Exception {
try (CSVParser in = CSVParser.parse(new File("employees.csv"), StandardCharsets.UTF_8,
CSVFormat.DEFAULT.builder().setHeader().setSkipHeaderRecord(true).get());
CSVPrinter out = new CSVPrinter(new FileWriter("employees_tdf.tsv"), CSVFormat.TDF)) {
for (CSVRecord r : in) out.printRecord((Object[]) r.values());
}
java.nio.file.Files.readAllLines(java.nio.file.Path.of("employees_tdf.tsv")).forEach(System.out::println);
try (CSVParser in = CSVParser.parse(new File("employees_tdf.tsv"), StandardCharsets.UTF_8, CSVFormat.TDF)) {
for (CSVRecord r : in) System.out.println("TDF read: " + r.size() + " fields: " + String.join(" / ", r.values()));
}
}
}
EOF
javac -cp "$CP" RoundTrip.java && java -cp ".:$CP" RoundTrip
回显：
1 Zhang San R&D
2 Li Si, Jr. Sales
3 Wang Wu Logistics
TDF read: 3 fields: 1 / Zhang San / R&D
TDF read: 3 fields: 2 / Li Si, Jr. / Sales
TDF read: 3 fields: 3 / Wang Wu / Logistics
说明：TDF 用 tab 分隔，"Li Si, Jr." 无需引号即可安全携带逗号，读回仍是 3 列。
7.2 MYSQL 方言往返（null 值）
cd /opt/csvwork && cat > MysqlRT.java <<'EOF'
import org.apache.commons.csv.*;
import java.io.*;
import java.nio.charset.StandardCharsets;
public class MysqlRT {
public static void main(String[] args) throws Exception {
File f = new File("rt_mysql.txt");
try (CSVPrinter out = new CSVPrinter(new FileWriter(f), CSVFormat.MYSQL)) {
out.printRecord(1, "Zhang San", "R&D");
out.printRecord(2, "Li Si", null);
}
java.nio.file.Files.readAllLines(f.toPath()).forEach(System.out::println);
try (CSVParser in = CSVParser.parse(f, StandardCharsets.UTF_8, CSVFormat.MYSQL)) {
for (CSVRecord r : in) {
System.out.println("MYSQL read: get(2)=" + r.get(2) + (r.get(2) == null ? " (null)" : ""));
}
}
}
}
EOF
javac -cp "$CP" MysqlRT.java && java -cp ".:$CP" MysqlRT
回显：
1 Zhang San R&D
2 Li Si \N
MYSQL read: get(2)=R&D
MYSQL read: get(2)=null (null)
说明：写 null 输出字面 \N（与 MySQL LOAD DATA 约定一致），读回还原为 Java null，可直接对接数据库导入导出。
7.3 EXCEL 方言往返（引号字段）
cd /opt/csvwork && cat > ExcelRT.java <<'EOF'
import org.apache.commons.csv.*;
import java.io.*;
import java.nio.charset.StandardCharsets;
public class ExcelRT {
public static void main(String[] args) throws Exception {
try (CSVPrinter out = new CSVPrinter(new FileWriter("rt_excel.csv"), CSVFormat.EXCEL)) {
out.printRecord("a", "x,y", "say \"ok\"");
}
java.nio.file.Files.readAllLines(java.nio.file.Path.of("rt_excel.csv")).forEach(System.out::println);
try (CSVParser in = CSVParser.parse(new File("rt_excel.csv"), StandardCharsets.UTF_8, CSVFormat.EXCEL)) {
for (CSVRecord r : in) System.out.println("EXCEL read: " + String.join(" | ", r.values()));
}
}
}
EOF
javac -cp "$CP" ExcelRT.java && java -cp ".:$CP" ExcelRT
回显：
a,"x,y","say ""ok"""
EXCEL read: a | x,y | say "ok"
说明：EXCEL 写出行尾 CRLF（cat -A 可见 ^M$），引号转义与 RFC 4180 一致，读回完整还原。
7.4 方言不匹配时的报错
拿逗号文件用 TDF 解析，实测异常信息（探测循环中的真实输出）：
EXCEPTION: java.io.UncheckedIOException: org.apache.commons.csv.CSVException: Invalid character between encapsulated token and delimiter at line: 3, position: 45
结论：方言不匹配不总是静默错切，引号出现位置不合法时直接抛 CSVException，消息带行号与列位置，可用于快速定位。
八、大文件流式验证
生成 100 万行 CSV 并流式解析计时。本实验目的是验证功能正确性与内存形态，数值仅供参考，非生产性能基准。
8.1 生成大文件
cd /opt/csvwork && cat > BigGen.java <<'EOF'
import org.apache.commons.csv.*;
import java.io.*;
public class BigGen {
public static void main(String[] args) throws Exception {
try (CSVPrinter p = new CSVPrinter(new BufferedWriter(new FileWriter("big.csv"), 1 << 16),
CSVFormat.DEFAULT.builder().setHeader("id", "name", "city", "amount").get())) {
for (int i = 1; i <= 1_000_000; i++) {
p.printRecord(i, "user-" + i, i % 2 == 0 ? "Beijing" : "Shanghai", i * 0.5);
}
}
}
}
EOF
javac -cp "$CP" BigGen.java && java -cp ".:$CP" BigGen
回显无输出。
ls -lh big.csv && wc -l big.csv && head -3 big.csv && tail -2 big.csv
回显：
-rw-r--r-- 1 root root 36M big.csv
1000001 big.csv
id,name,city,amount
1,user-1,Shanghai,0.5
2,user-2,Beijing,1.0
999999,user-999999,Shanghai,499999.5
1000000,user-1000000,Beijing,500000.0
8.2 流式解析计时（-Xmx256m）
cd /opt/csvwork && cat > BigParse.java <<'EOF'
import org.apache.commons.csv.*;
import java.io.*;
import java.nio.charset.StandardCharsets;
public class BigParse {
public static void main(String[] args) throws Exception {
long t0 = System.currentTimeMillis();
long sum = 0;
int count = 0;
try (CSVParser parser = CSVParser.parse(new File("big.csv"), StandardCharsets.UTF_8,
CSVFormat.DEFAULT.builder().setHeader().setSkipHeaderRecord(true).get())) {
for (CSVRecord r : parser) {
sum += Long.parseLong(r.get("id"));
count++;
}
}
long t1 = System.currentTimeMillis();
Runtime rt = Runtime.getRuntime();
System.out.println("rows=" + count + " sum=" + sum + " elapsed=" + (t1 - t0) + " ms");
System.out.println("heapUsed=" + (rt.totalMemory() - rt.freeMemory()) / 1024 / 1024 + " MB, maxHeap=" + rt.maxMemory() / 1024 / 1024 + " MB");
}
}
EOF
javac -cp "$CP" BigParse.java && java -Xmx256m -cp ".:$CP" BigParse
回显：
rows=1000000 sum=500000500000 elapsed=617 ms
heapUsed=42 MB, maxHeap=256 MB
8.3 对照：全量加载 getRecords 的内存风险
cd /opt/csvwork && cat > BigParseAll.java <<'EOF'
import org.apache.commons.csv.*;
import java.io.*;
import java.nio.charset.StandardCharsets;
public class BigParseAll {
public static void main(String[] args) throws Exception {
try (CSVParser parser = CSVParser.parse(new File("big.csv"), StandardCharsets.UTF_8,
CSVFormat.DEFAULT.builder().setHeader().setSkipHeaderRecord(true).get())) {
var all = parser.getRecords();
System.out.println("loaded=" + all.size());
}
}
}
EOF
javac -cp "$CP" BigParseAll.java && java -Xmx256m -cp ".:$CP" BigParseAll 2>&1 | head -4
回显：
Exception in thread "main" java.lang.OutOfMemoryError: Java heap space
at java.base/java.util.Arrays.copyOfRange(Arrays.java:3822)
at java.base/java.lang.StringLatin1.newString(StringLatin1.java:769)
at java.base/java.lang.StringBuilder.toString(StringBuilder.java:453)
结论：for-each 流式遍历在 256MB 堆下稳定完成（约 0.6 秒解析百万行）；getRecords() 把全部记录驻留内存直接 OOM。命令行处理大文件务必用迭代方式，堆上限给到 256 至 512MB 足够。
九、参考链接
- jshell 官方文档：https://docs.oracle.com/en/java/javase/17/jshell/introduction-jshell.html
- Commons CSV javadoc CSVParser：https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVParser.html
- Commons CSV javadoc CSVPrinter：https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVPrinter.html
- Commons CSV 用户指南：https://commons.apache.org/proper/commons-csv/user-guide.html
- GNU awk 手册（FPAT 说明）：https://www.gnu.org/software/gawk/manual/gawk.html
- util-linux column 手册：https://man7.org/linux/man-pages/man1/column.1.html
- RFC 4180（CSV 格式规范）：https://datatracker.ietf.org/doc/html/rfc4180
章节目录