CSV（Comma-Separated Values）是一种常见的数据交换格式。在 Java 中，使用 StringBuilder 拼接 CSV 数据是高效且推荐的做法，尤其在处理大量数据时，其性能远超字符串 + 操作。

一、核心概念

1. 什么是 CSV？

  • CSV 是一种以纯文本形式存储表格数据的格式。
  • 每行代表一条记录，字段之间用分隔符（通常是逗号 ,）分隔。
  • 示例： 
    Name,Age,Email
Alice,30,alice@example.com
Bob,25,bob@example.com

2. 为什么用 StringBuilder 拼接 CSV？

  • 性能优势：避免创建大量中间 String 对象，减少 GC 压力。
  • 可变性：支持动态追加内容，适合循环生成。
  • 灵活性：可轻松处理字段转义、换行等复杂情况。
  • 内存效率：内部数组扩容策略优化了内存使用。

3. CSV 转义规则（关键！）

  • 字段包含分隔符（如 ,）：必须用双引号包裹字段。
    • Alice,Smith → "Alice,Smith"
  • 字段包含双引号（"）：需用两个双引号转义，并用双引号包裹。
    • He said "Hi" → "He said ""Hi"""
  • 字段包含换行符（\n）：必须用双引号包裹。
  • 建议：对所有包含特殊字符（,, ", \n, \r）的字段进行双引号包裹。

二、操作步骤（非常详细）

步骤 1：导入类（可选）

// StringBuilder 在 java.lang 包中，无需导入
// 但若使用 List 等，需导入：
import java.util.List;
import java.util.Arrays;

步骤 2：创建 StringBuilder 实例（推荐预设容量）

// 预估最终 CSV 大小（如 10KB）
StringBuilder sb = new StringBuilder(10240); // 10KB
// 或根据数据量估算：records * avgRecordLength

步骤 3：定义分隔符和换行符

String delimiter = ","; // 字段分隔符
String lineSeparator = "\n"; // 行分隔符（可使用 System.lineSeparator()）

步骤 4：创建 CSV 转义工具方法（核心！）

/**
 * 对 CSV 字段进行转义处理
 * @param field 字段原始值
 * @return 转义后的 CSV 字段
 */
private static String escapeCsvField(String field) {
    if (field == null) {
        return "";
    }
    // 检查是否需要转义
    if (field.contains(",") || field.contains("\"") || 
        field.contains("\n") || field.contains("\r")) {
        // 转义双引号：将 " 替换为 ""
        return "\"" + field.replace("\"", "\"\"") + "\"";
    }
    return field;
}

步骤 5：拼接表头（可选）

List<String> headers = Arrays.asList("Name", "Age", "Email", "Address");
for (int i = 0; i < headers.size(); i++) {
    if (i > 0) sb.append(delimiter);
    sb.append(escapeCsvField(headers.get(i)));
}
sb.append(lineSeparator); // 添加换行

步骤 6：循环拼接数据行

// 假设有 List<List<String>> dataRows 或 List<User> users
List<List<String>> dataRows = getData(); // 获取数据

for (List<String> row : dataRows) {
    for (int i = 0; i < row.size(); i++) {
        if (i > 0) sb.append(delimiter);
        sb.append(escapeCsvField(row.get(i)));
    }
    sb.append(lineSeparator);
}

步骤 7：处理对象列表（更常见）

// 假设有一个 User 类
class User {
    String name; int age; String email; String address;
    // 构造函数、getter 省略
}

List<User> users = getUsers();

for (User user : users) {
    sb.append(escapeCsvField(user.getName()))
      .append(delimiter)
      .append(String.valueOf(user.getAge())) // 基本类型转字符串
      .append(delimiter)
      .append(escapeCsvField(user.getEmail()))
      .append(delimiter)
      .append(escapeCsvField(user.getAddress()))
      .append(lineSeparator);
}

步骤 8：获取最终 CSV 字符串

String csvContent = sb.toString();
// 可直接写入文件或返回

步骤 9：（可选）写入文件

import java.nio.file.*;
// ...
Files.write(Paths.get("output.csv"), csvContent.getBytes(), 
            StandardOpenOption.CREATE);

三、常见错误

错误 1：未处理特殊字符

// ❌ 错误：直接拼接，导致 CSV 格式错误
sb.append("Alice,Smith"); // 包含逗号，会被拆成两列！

// ✅ 正确：使用 escapeCsvField
sb.append(escapeCsvField("Alice,Smith"));

错误 2：忘记换行

// ❌ 错误：所有数据在一行
for (row : rows) {
    // ... 拼接字段
    // 忘记 sb.append("\n");
}

// ✅ 正确：每行结束后添加换行符
sb.append(lineSeparator);

错误 3：空值处理不当

// ❌ 错误：append(null) 会添加 "null"
sb.append(user.getEmail()); // 如果 email 为 null → "null"

// ✅ 正确：在 escapeCsvField 中处理 null
private static String escapeCsvField(String field) {
    if (field == null) return "";
    // ... 其他逻辑
}

错误 4：容量不足导致频繁扩容

// ❌ 低效：默认容量 16，大数据量会频繁扩容
StringBuilder sb = new StringBuilder();

// ✅ 优化：预设足够容量
StringBuilder sb = new StringBuilder(expectedSize);

四、注意事项

  1. 字符编码：确保生成的 CSV 字符串使用正确的编码（如 UTF-8）写入文件。
  2. 换行符：Windows 用 \r\n，Unix 用 \n。推荐使用 System.lineSeparator() 或统一用 \n。
  3. 性能监控：大数据量时，关注 StringBuilder 的 capacity() 和扩容次数。
  4. 内存占用：超大 CSV 可能占用大量内存，考虑分批生成或流式输出。
  5. 线程安全：StringBuilder 非线程安全。多线程生成 CSV 时，使用 StringBuffer 或 ThreadLocal。

五、使用技巧

技巧 1：预估容量提升性能

// 粗略估算：每行平均 100 字符，共 10000 行
int estimatedSize = 100 * 10000;
StringBuilder sb = new StringBuilder(estimatedSize);

技巧 2：复用 StringBuilder（谨慎）

// 在循环外创建，每次清空复用
StringBuilder sb = new StringBuilder(1000);
for (task : tasks) {
    sb.setLength(0); // 清空内容，复用对象
    // 拼接 CSV ...
    String csv = sb.toString();
    // 处理 csv ...
}

注意：仅当每次生成的 CSV 大小相近时有效。

技巧 3：使用 StringJoiner 简化单行拼接（JDK 8+）

// 适用于简单场景，无复杂转义
StringJoiner row = new StringJoiner(",");
row.add(escapeCsvField(name))
   .add(String.valueOf(age))
   .add(escapeCsvField(email));
sb.append(row.toString()).append(lineSeparator);

技巧 4：流式生成（避免内存溢出）

// 对于超大数据集，边生成边写入文件
try (BufferedWriter writer = Files.newBufferedWriter(Paths.get("large.csv"))) {
    // 写表头
    writer.write("Name,Age,Email\n");
    
    for (User user : users) {
        StringBuilder line = new StringBuilder();
        line.append(escapeCsvField(user.getName()))
            .append(",")
            .append(user.getAge())
            .append(",")
            .append(escapeCsvField(user.getEmail()))
            .append("\n");
        writer.write(line.toString());
    }
}
// 优点：内存占用恒定，适合大数据

六、最佳实践与性能优化

1. 优先使用 StringBuilder

  • 绝对避免在循环中使用 String + 拼接。

2. 强制转义策略（推荐）

  • 为简化逻辑，可对所有文本字段统一用双引号包裹： 
    private static String quoteField(String field) {
    if (field == null) return "\"\"";
    return "\"" + field.replace("\"", "\"\"") + "\"";
}
  • 优点：逻辑简单，不易出错。
  • 缺点：CSV 文件稍大。

3. 避免创建中间字符串

// ❌ 低效：创建多个临时 String
String line = name + "," + age + "," + email;

// ✅ 高效：直接追加到 StringBuilder
sb.append(name).append(",").append(age).append(",").append(email);

4. 使用 ensureCapacity()

// 在开始拼接前，确保足够容量
sb.ensureCapacity(estimatedSize);

5. 性能对比测试

// 测试 StringBuilder vs String +
long start = System.nanoTime();
StringBuilder sb = new StringBuilder();
for (int i = 0; i < 10000; i++) {
    sb.append("data").append(",").append(i).append("\n");
}
long timeSb = System.nanoTime() - start;

// String + 方式（极慢，仅作对比）
String s = "";
for (int i = 0; i < 10000; i++) {
    s += "data," + i + "\n";
}
// StringBuilder 通常快 10-100 倍

6. 考虑专用库（复杂场景）

  • 对于非常复杂的 CSV 操作（如读取、验证、特殊编码），可考虑使用：
  • 优点：功能完整，处理边界情况。
  • 缺点：引入依赖，简单拼接无需使用。

七、完整示例代码

import java.util.*;

public class CsvGenerator {
    private static final String DELIMITER = ",";
    private static final String LINE_SEPARATOR = "\n";

    public static void main(String[] args) {
        List<User> users = Arrays.asList(
            new User("Alice", 30, "alice@example.com", "123 Main St"),
            new User("Bob, Jr.", 25, null, "456 \"Oak\" Ave\nSuite 100"),
            new User("Charlie", 35, "charlie@test.com", null)
        );

        String csv = generateCsv(users);
        System.out.println(csv);
        // 可写入文件：Files.write(...)
    }

    public static String generateCsv(List<User> users) {
        // 预估容量：假设平均每行 50 字符
        int estimatedSize = Math.max(1024, users.size() * 50);
        StringBuilder sb = new StringBuilder(estimatedSize);

        // 表头
        sb.append("Name").append(DELIMITER)
          .append("Age").append(DELIMITER)
          .append("Email").append(DELIMITER)
          .append("Address")
          .append(LINE_SEPARATOR);

        // 数据行
        for (User user : users) {
            sb.append(escapeCsvField(user.getName())).append(DELIMITER)
              .append(user.getAge()).append(DELIMITER)
              .append(escapeCsvField(user.getEmail())).append(DELIMITER)
              .append(escapeCsvField(user.getAddress()))
              .append(LINE_SEPARATOR);
        }

        return sb.toString();
    }

    private static String escapeCsvField(String field) {
        if (field == null) return "";
        if (field.contains(",") || field.contains("\"") || 
            field.contains("\n") || field.contains("\r")) {
            return "\"" + field.replace("\"", "\"\"") + "\"";
        }
        return field;
    }

    static class User {
        String name; int age; String email; String address;
        User(String name, int age, String email, String address) {
            this.name = name; this.age = age; 
            this.email = email; this.address = address;
        }
        // getter 省略
    }
}

输出：

Name,Age,Email,Address
Alice,30,alice@example.com,"123 Main St"
"Bob, Jr.",25,,456 "Oak" Ave
Suite 100
Charlie,35,charlie@test.com,

总结

要点 说明
核心工具 StringBuilder + 转义逻辑
关键步骤 预设容量 → 定义分隔符 → 转义方法 → 拼接表头 → 循环拼接行 → 获取结果
核心规则 特殊字符（,, ", \n）必须用双引号包裹，" 转义为 ""
性能关键 预设容量、避免中间字符串、减少扩容
常见错误 忽略转义、忘记换行、null 处理不当
最佳实践 强制转义策略、流式生成（大数据）、使用专用库（复杂需求）

最终建议：

使用 StringBuilder 拼接 CSV 是高效且可靠的方法。掌握转义规则是成功的关键。在大多数场景下，遵循“预设容量 + 安全转义 + 链式追加”的模式，即可快速生成正确、高效的 CSV 数据。对于超大数据集，优先考虑流式生成以控制内存。