Apache Commons CSV 怎么强制导出需要引号的字段

如果 CSV 导出要求每个字段都带双引号，不要在业务代码里手工拼接 \"。Apache Commons CSV 把这项策略放在 CSVFormat 中，使用 QuoteMode.ALL 构造格式后，CSVPrinter 会按同一套规则输出整行数据。

官方地址：https://commons.apache.org/proper/commons-csv/

一、先分清 CSV 的加引号策略

CSV 的字段值、分隔符、引号字符和换行符属于不同层次。CSVPrinter 负责把值写成记录，CSVFormat 负责规定如何分隔和包裹，QuoteMode 则只决定“哪些字段需要引号”。因此，字段本身含有逗号时自动加引号，并不等于所有字段都会加引号。

官方 API 将策略分成几类：ALL 引用所有字段，ALL_NON_NULL 引用所有非 null 字段，MINIMAL 只引用含特殊字符的字段，NON_NUMERIC 引用非数字字段，NONE 从不引用字段。默认导出若使用最小包裹思路，像 1001 这种普通值就可能保持裸文本。

二、用 QuoteMode.ALL 强制包裹每个字段

将策略设置在格式对象上，再把格式交给 CSVPrinter。示例使用 Builder.get() 创建不可变的 CSVFormat；较新的 Commons CSV 文档推荐 get()，不要继续使用已标记过时的 build()。

import java.io.IOException;
import java.io.Writer;
import java.nio.file.Files;
import java.nio.file.Path;

import org.apache.commons.csv.CSVFormat;
import org.apache.commons.csv.CSVPrinter;
import org.apache.commons.csv.QuoteMode;

public class QuotedCsvExport {
    public static void write(Path target) throws IOException {
        // ALL 让每个字段都进入引号包裹策略，避免业务层手工拼接双引号。
        CSVFormat format = CSVFormat.Builder.create()
                .setQuoteMode(QuoteMode.ALL)
                .setRecordSeparator("\n")
                .get();

        // CSVPrinter 和 Writer 一起关闭，确保缓冲内容落盘并释放文件句柄。
        try (Writer writer = Files.newBufferedWriter(target);
             CSVPrinter printer = new CSVPrinter(writer, format)) {
            // printRecord 自带记录分隔符，不需要再调用 println。
            printer.printRecord("1001", "Alice", "研发,一组");
            printer.printRecord("1002", "Bob", "普通文本");
        }
    }
}

上面的三列都会按 ALL 的策略输出，概念上的结果是：

"1001","Alice","研发,一组"
"1002","Bob","普通文本"

字段内的逗号仍然会被正确保留，双引号和换行也由 Commons CSV 负责转义。这样做的好处是规则集中在格式对象中，换导出目标或调整分隔符时，不必在每个字段前后重复修改字符串。

三、ALL、ALL_NON_NULL 和 MINIMAL 怎么选

如果数据模型允许 null，先确定接收方希望看到什么。ALL 的目标是所有字段都走引用策略；如果希望 null 不被包裹，可以选择 ALL_NON_NULL，再通过 setNullString 把 null 映射为约定文本，或者保留库的空值表现。这里讨论的是输出格式，不是把空字符串和 null 做业务层清洗。

CSVFormat readableNulls = CSVFormat.Builder.create()
        // 非 null 字段加引号，null 字段不进入引号包裹。
        .setQuoteMode(QuoteMode.ALL_NON_NULL)
        // 明确 null 的文本约定，避免接收方猜测空字段含义。
        .setNullString("NULL")
        .get();

MINIMAL 适合更接近常见 CSV 的紧凑输出：只有字段包含分隔符、引号字符或记录分隔符中的字符时才引用。NON_NUMERIC 适合需要区分数字和文本的接收端，但它不是“所有字符串都带引号”的替代品。NONE 则完全不包裹字段；当数据中出现分隔符时，官方说明要求配置可用的 escape 字符，否则格式参数可能不一致。

四、用固定样例检查导出契约

不要只检查肉眼能看到的逗号。把普通文本、包含分隔符的文本、包含双引号的文本、换行文本和 null 分开作为样例，明确接收方要的是“全部加引号”还是“必要时加引号”。如果使用 printRecord，它会写入记录分隔符；如果逐个调用 print，则要自己管理字段和记录边界。

• 全部字段都要包裹：QuoteMode.ALL。
• 只包裹非 null 字段：QuoteMode.ALL_NON_NULL，并配置 null 约定。
• 接收方只接受紧凑 CSV：QuoteMode.MINIMAL，同时测试逗号、引号和换行。
• 完全禁用引号：QuoteMode.NONE，先确认 escape 和分隔符规则。

资源管理也属于导出契约的一部分。CSVPrinter 实现了 Closeable 和 Flushable，用 try-with-resources 让写入失败以 IOException 暴露，并避免文件句柄长期占用。

相关问题

为什么普通数字没有自动加双引号？

因为当前格式使用的是按需引用策略，例如 MINIMAL。要让数字字段也带双引号，把格式改为 QuoteMode.ALL。

字段里已有双引号还需要手工转义吗？

不需要在业务层重复拼接。把原始字段值交给 CSVPrinter，由选定的 CSVFormat 负责引用和转义；手工加引号反而容易造成重复包裹。