用Java实现业务数据CSV导入导出,如何兼容中文编码?

发布人:A5数据发布时间:2026-11-17 09:35阅读量:2

导入端统一按明确的字符集解码,导出端统一按明确的字符集编码,是 Java CSV 中文不乱码的基础。新文件通常使用 UTF-8;如果文件要直接交给部分表格软件打开,可以在 UTF-8 内容前加入 BOM。BOM 只解决部分软件识别编码的问题,不能代替正确的读写编码,也不能修复已经按错误字符集保存的数据。

下面用 Apache Commons CSV 实现一个订单 CSV 的导入和导出。示例按 Java 17 编写,包含 UTF-8 BOM 处理、表头校验、金额转换和 CSV 字段转义。

添加 CSV 依赖

在 Maven 项目的 pom.xml 中加入 Apache Commons CSV:

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-csv</artifactId>
    <version>1.10.0</version>
</dependency>

示例文件的表头为“订单号、客户名称、金额、备注”。带逗号、双引号或换行的字段必须遵循 CSV 规则,例如:

订单号,客户名称,金额,备注
A1001,星河商贸,128.50,普通订单
A1002,示例客户,256.00,"地址包含逗号,需加引号"
A1003,远山科技,89.90,"备注第一行
备注第二行"

不要通过 String.split(",") 读取这种文件:引号内的逗号和换行属于字段内容,不是列分隔符。Commons CSV 会按 CSV 规则解析这些字段。

导入:按 UTF-8 解码并校验表头

先定义用于承接 CSV 数据的对象。这里使用 BigDecimal 保存金额,避免用 double 处理业务金额时引入二进制浮点误差。

import java.math.BigDecimal;

public record OrderCsvRow(
        String orderNo,
        String customerName,
        BigDecimal amount,
        String remark) {
}

导入时先检查表头是否完整且顺序符合约定,再逐行读取。示例将 UTF-8 解码器设置为遇到非法字节时报告错误,而不是悄悄替换字符;这样可以尽早发现文件实际编码不符合约定的情况。

import org.apache.commons.csv.CSVFormat;
import org.apache.commons.csv.CSVParser;
import org.apache.commons.csv.CSVRecord;

import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.PushbackInputStream;
import java.io.Reader;
import java.math.BigDecimal;
import java.nio.charset.CodingErrorAction;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;

public class OrderCsvService {

    private static final List<String> HEADERS =
            List.of("订单号", "客户名称", "金额", "备注");

    private static final CSVFormat IMPORT_FORMAT =
            CSVFormat.DEFAULT.builder()
                    .setHeader()
                    .setSkipHeaderRecord(true)
                    .setIgnoreEmptyLines(true)
                    .build();

    /**
     * 本方法会读取并关闭传入的 InputStream。
     */
    public List<OrderCsvRow> readOrders(InputStream input) throws IOException {
        InputStream bomAwareInput = stripUtf8Bom(input);

        Reader reader = new InputStreamReader(
                bomAwareInput,
                StandardCharsets.UTF_8.newDecoder()
                        .onMalformedInput(CodingErrorAction.REPORT)
                        .onUnmappableCharacter(CodingErrorAction.REPORT));

        List<OrderCsvRow> rows = new ArrayList<>();

        try (CSVParser parser = IMPORT_FORMAT.parse(reader)) {
            if (!HEADERS.equals(parser.getHeaderNames())) {
                throw new IOException(
                        "CSV表头不符合约定,应为:" + String.join(",", HEADERS));
            }

            for (CSVRecord record : parser) {
                if (record.size() != HEADERS.size()) {
                    throw new IOException(
                            "第 " + record.getRecordNumber() + " 条记录的列数不正确");
                }

                String orderNo = record.get("订单号").trim();
                String customerName = record.get("客户名称").trim();
                String amountText = record.get("金额").trim();
                String remark = record.get("备注");

                if (orderNo.isEmpty()) {
                    throw new IOException(
                            "第 " + record.getRecordNumber() + " 条记录缺少订单号");
                }

                BigDecimal amount = null;
                if (!amountText.isEmpty()) {
                    try {
                        amount = new BigDecimal(amountText);
                    } catch (NumberFormatException e) {
                        throw new IOException(
                                "第 " + record.getRecordNumber()
                                        + " 条记录的金额格式不正确",
                                e);
                    }
                }

                rows.add(new OrderCsvRow(
                        orderNo,
                        customerName,
                        amount,
                        remark));
            }
        }

        return rows;
    }

    private static InputStream stripUtf8Bom(InputStream input)
            throws IOException {
        PushbackInputStream in = new PushbackInputStream(input, 3);

        int first = in.read();
        int second = in.read();
        int third = in.read();

        boolean hasUtf8Bom =
                first == 0xEF && second == 0xBB && third == 0xBF;

        if (!hasUtf8Bom) {
            if (third != -1) {
                in.unread(third);
            }
            if (second != -1) {
                in.unread(second);
            }
            if (first != -1) {
                in.unread(first);
            }
        }

        return in;
    }
}

stripUtf8Bom 只识别 UTF-8 BOM。文件开头没有 BOM 时,读取到的字节会被放回流中,不影响正常解析。导入端如果不处理 BOM,部分解析器可能把 BOM 当成第一个表头字符,造成“订单号”列匹配失败。

表头检查采用严格匹配:表头名称或顺序不一致时直接报错,而不是继续读取并把数据写入错误字段。如果业务确实允许列顺序变化,可以按表头名称建立映射,再逐列读取;但仍应检查必需列是否存在,以及是否出现重复表头。

金额字段允许为空,并在有值时转换为 BigDecimal。如果业务规定金额必填,可以在转换前检查空值并报出记录位置。实际导入数据库时,也应先完成字段校验,再按业务规则决定如何写入;不要在读到每一行时无条件提交,以免后续记录出错后留下部分导入结果。

导出:写成 UTF-8 CSV

导出时把 OutputStream 明确包装为 UTF-8 的 Writer,并让 CSV 库负责字段转义。下面的代码支持可选 BOM:传入 true 时,文件开头会写入 UTF-8 BOM,适合需要兼顾部分表格软件直接打开的场景;传入 false 时,文件是没有 BOM 的标准 UTF-8 内容。

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

import java.io.IOException;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.Writer;
import java.nio.charset.StandardCharsets;
import java.util.List;

public class OrderCsvExporter {

    private static final String[] HEADERS =
            {"订单号", "客户名称", "金额", "备注"};

    private static final CSVFormat EXPORT_FORMAT =
            CSVFormat.DEFAULT.builder()
                    .setHeader(HEADERS)
                    .setRecordSeparator("\r\n")
                    .build();

    /**
     * 本方法不会关闭 output,调用方负责关闭或管理输出流。
     */
    public void writeOrders(
            OutputStream output,
            List<OrderCsvRow> rows,
            boolean writeUtf8Bom) throws IOException {

        Writer writer =
                new OutputStreamWriter(output, StandardCharsets.UTF_8);

        if (writeUtf8Bom) {
            writer.write('\uFEFF');
        }

        CSVPrinter printer = new CSVPrinter(writer, EXPORT_FORMAT);

        for (OrderCsvRow row : rows) {
            printer.printRecord(
                    row.orderNo(),
                    row.customerName(),
                    row.amount() == null
                            ? ""
                            : row.amount().toPlainString(),
                    row.remark());
        }

        printer.flush();
    }
}

该方法不会关闭调用方传入的流,但会在结束时执行 flush(),把编码器和输出缓冲区中的内容写出。调用方需要负责关闭文件流或管理 HTTP 响应流。发生写入异常时,文件可能只包含部分数据;如果导出结果要保存为正式文件,可先写入临时文件,确认完整写出后再替换目标文件。

CSVPrinter 会处理字段中包含的逗号、引号和换行。例如备注为 地址包含逗号,需加引号 时,导出的 CSV 会自动为该字段加引号;字段本身有双引号时,也会按 CSV 规则转义。不要自行拼接逗号和换行来生成 CSV,否则容易在特殊字符处破坏列结构。

在文件和下载接口中调用

文件导入可以直接把文件流交给读取方法。读取方法会关闭传入流,因此不需要在外层重复管理同一个流:

import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

Path csvPath = Path.of("orders.csv");

List<OrderCsvRow> rows;
try (InputStream input = Files.newInputStream(csvPath)) {
    rows = new OrderCsvService().readOrders(input);
}

如果项目需要由调用方统一管理输入流,应调整读取方法的所有权约定,避免调用方和方法内部同时关闭或重复使用同一个流。示例中的 readOrders 会关闭传入流,而导出方法则不会关闭传入的 OutputStream,这两种约定都应在接口文档中明确。

下载接口通常还需要设置响应类型和下载文件名。以 Servlet 响应为例:

response.setContentType("text/csv; charset=UTF-8");
response.setHeader(
        "Content-Disposition",
        "attachment; filename=\"orders.csv\"");

new OrderCsvExporter().writeOrders(
        response.getOutputStream(),
        rows,
        true);

这里使用 ASCII 文件名,避免不同浏览器对中文文件名编码处理不一致。如果要使用中文文件名,应按项目使用的 Servlet 和浏览器兼容方案正确编码 Content-Disposition,不要直接把未经编码的中文拼进响应头。

中文编码容易出错的几个环节

读写时不要依赖系统默认字符集。 new InputStreamReader(input) 和 new OutputStreamWriter(output) 如果没有指定字符集,会使用运行环境的默认值。开发机、容器和服务器的默认字符集可能不同,文件就可能在一个环境正常、换到另一个环境后乱码。读写时明确使用 StandardCharsets.UTF_8,并要求上下游对文件编码达成一致。

UTF-8 BOM 和字符集不是一回事。 UTF-8 BOM 是文件开头的三个字节,部分表格软件会用它识别 UTF-8;它不会把 GBK 内容转换为 UTF-8。上例的导入方法能去掉 UTF-8 BOM,但不能据此判断文件采用了哪种字符集。

旧系统导出的 GBK 文件要明确指定编码。 如果文件生产方确认使用 GBK,应使用对应字符集读取,例如:

Reader reader = new InputStreamReader(input, java.nio.charset.Charset.forName("GBK"));

该写法不能直接套用上例的 UTF-8 BOM 处理逻辑。不要在 UTF-8 解码失败后无条件切换到 GBK:字符集自动猜测并不可靠,错误的回退可能让文件“看起来可读”,实际内容却已被错误解码。对同一导入入口支持多种编码时,最好通过配置、文件类型选项或明确的业务约定选择编码,并对非法字节给出可定位的错误。

中文编码容易出错的几个环节配图

乱码若发生在导入前,改 Java 代码未必能修复。 例如源数据已经按错误字符集保存,或者数据库写入时使用了错误字符集,之后再用 UTF-8 导出也只会输出已经损坏的字符。排查时可以依次确认文件实际编码、读取时指定的字符集、字段写入时的处理,以及数据库连接和列的字符集设置。

大文件和表格软件的注意事项

上例把全部记录收集到 List 中,便于展示字段校验和后续处理,适合文件规模受控的场景。记录较多时,列表会持续占用堆内存;可以改成逐条校验并交给业务处理器,或按固定批次处理。若导入要写数据库,建议先明确失败策略,例如整批回滚、分批提交并记录失败行,避免文件只导入了一部分却没有可追踪的结果。

对于面向表格软件的人工查看文件,还要区分“CSV 字段转义”和“表格公式处理”。字段加引号可以保证逗号等字符按 CSV 规则读取,但不一定能防止表格软件把以 =, +, - 或 @ 等字符开头的文本当成公式。对外提供人工查看文件时,应根据目标软件和安全要求制定文本字段处理策略;对系统间交换文件则应避免随意修改原始值,否则可能影响数据回读和对账。

验收时核对这些结果

可以用一份包含中文、英文、逗号、双引号和换行的样例文件验证导入导出流程。重点检查:

  • 中文列名和字段内容往返后保持一致。
  • 有 BOM 和无 BOM 的 UTF-8 文件都能按约定读取。
  • 缺失表头、列数不符和金额格式错误时能指出记录位置。
  • 字段内的逗号、双引号及换行不会导致列错位。
  • 由旧系统提供的非 UTF-8 文件,只有在确认其编码后才切换字符集处理。

如果输出文件要由其他程序读取,优先确认对方接受的编码和是否需要 BOM;如果主要供表格软件打开,再针对目标软件验证 BOM 行为。将编码约定、表头和字段格式写入接口文档后,CSV 导入导出的兼容问题通常更容易定位,也不必依赖“换一个服务器再试”的方式排查。

CSV 导入导出通常是业务后台与数据存储链路的一环。A5idc数据提供香港、美国、日本、中国台湾、新加坡、韩国及马来西亚等地的物理服务器,涵盖不同 CPU、内存、SSD/NVMe 存储和线路配置,可为 Java 接口服务、业务后台及数据库部署提供资源基础;面向不同地区的业务访问,也有相应地域与网络方案可选,支持文件处理服务与业务数据系统按实际架构部署。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9880.html

相关推荐