跳至主要内容

CSV API

CSV 模組提供 CSV 檔案的讀取和寫入功能。

套件: io.leandev.appfuse.csv

核心類別​

CsvReader​

CSV 檔案讀取器。

public class CsvReader implements AutoCloseable {
    CsvReader(InputStream inputStream)
    CsvReader(InputStream inputStream, CsvReaderSettings settings)
    CsvReader(InputStream inputStream, CsvReaderSettings settings, Charset charset)
}

主要方法​

方法說明
readHeaders()讀取標題列
read()讀取單筆記錄
readAll()讀取所有記錄
stream()取得串流
skip(long offset)跳過指定行數
close()關閉讀取器

CsvWriter​

CSV 檔案寫入器。

public class CsvWriter implements AutoCloseable {
    CsvWriter(OutputStream outputStream)
    CsvWriter(OutputStream outputStream, CsvWriterSettings settings)
    CsvWriter(OutputStream outputStream, CsvWriterSettings settings, Charset charset)
}

主要方法​

方法說明
writeHeaders(String...)寫入標題列
write(List<?>)寫入單筆記錄（List）
write(Object)寫入單筆記錄（Bean）
flush()刷新緩衝區
close()關閉寫入器

CsvRecord​

CSV 資料記錄。

public class CsvRecord {
    String get(String key)
    <T> T getAs(String key, Class<T> type)
    int indexOf(String key)
    <T> T getValue(int index, Class<T> type)
    Object getValue(int index)
    int size()
    List<String> getValues()
}

設定類別​

CsvReaderSettings​

public class CsvReaderSettings {
    private char delimiter = ',';
    private char quote = '"';
    private char quoteEscape = '\\';
    private String lineSeparator;
    private boolean trimValues = false;
    private boolean emptyStringsAsNull = false;
}

CsvWriterSettings​

public class CsvWriterSettings {
    private char delimiter = ',';
    private char quote = '"';
    private String lineSeparator;
    private boolean quoteAllFields = false;
}

使用範例​

讀取 CSV​

try (CsvReader reader = new CsvReader(inputStream)) {
    // 讀取標題
    List<String> headers = reader.readHeaders();

    // 逐筆讀取
    CsvRecord record;
    while ((record = reader.read()) != null) {
        String name = record.get("name");
        int age = record.getAs("age", Integer.class);
        // 處理記錄...
    }
}

串流處理​

try (CsvReader reader = new CsvReader(inputStream)) {
    reader.readHeaders();

    List<User> users = reader.stream()
        .map(record -> new User(
            record.get("name"),
            record.getAs("email", String.class),
            record.getAs("age", Integer.class)
        ))
        .collect(Collectors.toList());
}

讀取所有記錄​

try (CsvReader reader = new CsvReader(inputStream)) {
    reader.readHeaders();
    List<CsvRecord> records = reader.readAll();

    for (CsvRecord record : records) {
        // 處理記錄...
    }
}

寫入 CSV​

try (CsvWriter writer = new CsvWriter(outputStream)) {
    // 寫入標題
    writer.writeHeaders("name", "email", "age");

    // 寫入資料（List 方式）
    writer.write(Arrays.asList("Alice", "alice@example.com", 25));
    writer.write(Arrays.asList("Bob", "bob@example.com", 30));

    writer.flush();
}

使用 Bean 寫入​

try (CsvWriter writer = new CsvWriter(outputStream)) {
    writer.setHeaders("name", "email", "age");
    writer.writeHeaders();

    for (User user : users) {
        writer.write(user);
    }

    writer.flush();
}

自訂設定​

// 自訂讀取設定
CsvReaderSettings readerSettings = CsvReaderSettings.builder()
    .delimiter(';')
    .quote('\'')
    .trimValues(true)
    .emptyStringsAsNull(true)
    .build();

try (CsvReader reader = new CsvReader(inputStream, readerSettings)) {
    // ...
}

// 自訂寫入設定
CsvWriterSettings writerSettings = CsvWriterSettings.builder()
    .delimiter('\t')
    .quoteAllFields(true)
    .build();

try (CsvWriter writer = new CsvWriter(outputStream, writerSettings)) {
    // ...
}

跳過資料列​

try (CsvReader reader = new CsvReader(inputStream)) {
    reader.readHeaders();

    // 跳過前 100 筆
    reader.skip(100);

    // 讀取剩餘資料
    List<CsvRecord> records = reader.readAll();
}

型別轉換​

CsvRecord.getAs() 支援以下型別自動轉換：

目標型別說明
String原始字串
Integer / int整數
Long / long長整數
Double / double浮點數
BigDecimal精確小數
Boolean / boolean布林值
LocalDate日期（yyyy-MM-dd）
LocalDateTime日期時間

最佳實踐​

  1. 使用 try-with-resources - 確保資源正確關閉
  2. 大檔案用串流 - 避免一次載入全部資料
  3. 設定適當的字元編碼 - 預設 UTF-8
  4. 處理空值 - 啟用 emptyStringsAsNull

相關連結​