欢迎加入 KMP&CMP 鸿蒙社区：https://atomgit.com/CPF-KMP-CMP

适配后仓库地址（AtomGit，待提交）：https://atomgit.com/oh-tpc/ohos_kotlin-csv

摘要

本文是 KMP 三方库鸿蒙化适配系列，也是"库对平台的隐含假设"这条主线走到第四种样本。第一篇 kotlinx-datetime、第二篇 kotlinx-io 栽在能力假设——库以为平台提供时区数据库、以为路径可以直接 open()，鸿蒙上没有，于是当场回退或抛异常；第三篇 Essenty 换成了时序假设——它什么都不缺，缺的是"平台没在对的时机通知我"，错位不崩、只静默丢状态。kotlin-csv 把这条线推到最难查的第四类：数据契约假设。它假设"送进来的字节流是 UTF-8、换行是 \n 或 \r\n、首列不带 BOM"。这三条在鸿蒙上很可能同时为假，而后果既不是崩溃也不是丢状态，而是流程跑完、每一格都静默错值（乱码）。全文按"是否碰平台 / 是否碰字节"给 kotlin-csv 分层，先接 ohosArm64 target、再用 CsvDataSource 把文件根路径从应用层注入（复用上一篇 kotlinx-io），然后逐条拆掉三个数据契约假设：字段内换行与 CR/CRLF 的状态机解析、BOM 对首列表头的污染、以及 UTF-8-only 的 Kotlin/Native 标准库读不进 GBK 报表这一硬约束，并给出 NAPI 桥 iconv 预转码的落地方案；最后用三组可辨识的真机验证（朴素 split 对照、BOM 下标命中对照、GBK 字节探针）证明适配确实成立。方法论沉淀成一句：分清你遇到的是能力假设、时序假设还是数据契约假设——因为崩溃会喊、丢状态会漏，而错值只会安静地把垃圾一路传到下游。

目录

• 一、接着 Essenty 往下走：从"时序"到"数据契约"
• 二、按"碰不碰平台 / 碰不碰字节"给 kotlin-csv 分层
• 三、第一步：ohosArm64 target 与 source set
• 四、第二步：用 CsvDataSource 把根路径交给应用层
• 五、第三步：换行符契约——状态机 vs 朴素 split
• 六、第四步：BOM 契约——静默污染第一列表头
• 七、第五步：编码契约——UTF-8-only 的 Native 读不进 GBK
• 八、第六步：导出、打包与三组真机验证
• 九、踩坑清单
• 十、小结

一、接着 Essenty 往下走：从"时序"到"数据契约"

前三篇是同一条方法论的三次套用：适配的工作量，几乎与代码体量无关，而与库对平台做了多少隐含假设强相关。 kotlinx-datetime 假设"系统会给时区库"，kotlinx-io 假设"路径可以直接 open"，这两个是能力假设——能力不存在，编译器或运行时会当场告诉你。Essenty 假设"平台会驱动生命周期、会在重建前保存状态"，这是时序假设——它不缺任何能力，缺的是"什么时候通知我"，错位不抛异常，只悄悄丢状态。

kotlin-csv 是第四个样本，假设的性质又变了一次。它假设的是：送进来的这段文本，字节是 UTF-8 编码、行与行之间用 \n 或 \r\n 分隔、第一行表头干净不带 BOM。 这是数据契约假设——库对"喂给它的字节流长什么样"做的假设。它比前两类都阴险：

• 能力假设失效 → 抛异常或回退，你立刻知道；
• 时序假设失效 → 静默丢状态，你下次用到才发现；
• 数据契约假设失效 → 既不崩、也不丢，只是解析出来的每一格都可能是错的（乱码、列名对不上、行被拆歪）。它安静地把垃圾一路传进数据库、传进报表、传给用户。

kotlin-csv 是 Arkadii（这里指社区生态）里典型的"纯 Kotlin、看着最不需要适配"的库——它没有网络、没有文件系统的硬编码路径依赖，甚至很多平台直接 csvReader().read(text) 读一个字符串就行。正因为"看起来不用碰平台"，它的坑全部藏在数据契约这一层，而这一层在鸿蒙上恰好最容易踩。

二、按"碰不碰平台 / 碰不碰字节"给 kotlin-csv 分层

动手前先把模块按"是否碰平台、是否碰字节流"分类，这直接决定工作量分布：

第一层：纯解析逻辑，一行不改。 CsvRow、解析状态机、写出时的引号转义（RFC4180 那套：字段含分隔符/引号/换行才加引号，内部引号翻倍）。这是纯字符串→结构体的运算，不含任何平台 API，commonMain 里编译一次所有平台通用。

第二层：数据源与落盘，平台注入层。 kotlin-csv 把"文本从哪来"抽象成 CsvDataSource（可以是 String、Reader、也可以从文件读）。落盘/读取那部分，在鸿蒙上必须借上一篇 kotlinx-io 的 SystemFileSystem，且根路径要由应用层 context.filesDir 注入——这条约束和 kotlinx-io 那篇完全一致，直接复用结论。

第三层：编码与 BOM，成本最高、也最容易被忽略。 这是本文的重心。Kotlin/Native 的 String 是 UTF-16，字节↔字符串只走 UTF-8（encodeToByteArray() / decodeToString()）——没有内置的 GBK/GB18030 编解码器。所以"读一段用户用 Excel 导出的 GBK 报表"这件事，在纯 Kotlin/Native 上根本做不到，必须下探到 NAPI 桥一个 iconv。BOM 同理：库不保证替你把开头的 0xEF 0xBB 0xBF（解成字符是 \uFEFF）剥掉。

分层清楚后，工作量就落在第二、三层：解析器不动，注意力全在"把字节流规约成库假设的那个样子"。

三、第一步：ohosArm64 target 与 source set

前提和前三篇一致——接入 HarmonyOS Kotlin 定制版，ohosArm64() 不在官方主线里。这里只列 target 与 source set：

// build.gradle.kts（kotlin-csv 模块）
kotlin {
    jvm()
    js(IR) { nodejs() }
    linuxX64()
    macosArm64()
    iosArm64()

    // 本次新增：OpenHarmony
    ohosArm64()

    sourceSets {
        val commonMain by getting   // kotlin-csv 的解析状态机就在 commonMain，跨端共享
        val ohosArm64Main by creating {
            dependsOn(commonMain)   // 挂到 commonMain 即可，逻辑与平台无关
        }
    }
}

补完 target 先编一次，编译器报的缺口通常很小——因为解析核心是纯 Kotlin。真正的活，是下面"数据源注入 + 编码/BOM 规约"这三块平台相关、且编译器不会替你兜底的部分。

四、第二步：用 CsvDataSource 把根路径交给应用层

kotlin-csv 读文件的入口，最佳实践不是"传一个路径字符串"，而是"传一个已经拿到内容的数据源"，这样库就不碰文件系统、也就不会去猜路径：

// ohosArm64Main：从沙箱读出来再喂给 csvReader，绝不在库里拼绝对路径
import kotlinx.io.files.Path
import kotlinx.io.files.SystemFileSystem
import kotlinx.io.buffered
import kotlinx.io.source

fun readCsvFromSandbox(filesDir: String, name: String, opts: CsvReadOption): List<CsvRow> {
    val file = Path(filesDir, "kcsv", name)                 // filesDir 由应用层 context 注入
    if (!SystemFileSystem.exists(file)) return emptyList()
    val text = SystemFileSystem.source(file).buffered().use { it.buffer.readString() } // UTF-8
    // 交给 commonMain 的解析器；kotlin-csv 不感知路径
    return csvReader { this.opts = opts }.readAll(text)
}

关键点：根路径 filesDir 从 UIAbilityContext 注入，绝不写死 /data/local/tmp——这是 kotlinx-io 那篇验证过的沙箱边界，这里原样复用。写出同理，落盘也走 kotlinx-io 的 sink。

五、第三步：换行符契约——状态机 vs 朴素 split

很多"我自己手写个 CSV 解析"的工程会栽在换行符上。看两组数据：

输入片段	朴素 split("\n")	kotlin-csv 状态机
"备注" 字段内含真实换行	被拆成两行（错）	识别引号，仍是一行（对）
行尾是 CRLF（\r\n，Excel 常见）	每格末尾多一个 \r	正确切分
行尾是只有 CR 的老 Mac 格式（\r）	整份文本塌成一行	正确切分

第一条最要命：只要有一个字段里出现过换行，split('\n') 就会把逻辑行拆错，后面所有列全部错位——但它不报错。kotlin-csv 的价值恰恰是这个状态机：在引号内不响应分隔符与换行。适配时的做法不是改库，而是别用 split 自己糊弄，老老实实调 csvReader()，并把解析后的行列数做一次可辨识校验（见第八节）。

写出侧同理：行结束符要显式选 \r\n 还是 \n——面向 Excel 的报表建议 \r\n。

六、第四步：BOM 契约——静默污染第一列表头

UTF-8 BOM 是文件开头的 0xEF 0xBB 0xBF 三字节。解码成字符后是 \uFEFF——零宽、看不见。它最坑的地方在表头：

原始首行：  姓名,年龄
带 BOM 时： <\uFEFF>姓名,年龄

如果解析前不剥离 BOM，第一列的列名会变成 "\uFEFF姓名"。于是：

val headers = rows.first()
val idx = headers.indexOf("姓名")   // -1 ！ 因为 headers[0] == "\uFEFF姓名"

idx == -1 不抛异常，只会让"按列名取值"全线取到 null 或默认值——典型的静默错值。适配规约很简单，且必须在解析前做：

private const val BOM = '\uFEFF'
fun stripBom(text: String): String = if (text.isNotEmpty() && text[0] == BOM) text.substring(1) else text

写侧则反过来：要让 Windows Excel 双击打开不乱码，往往需要主动写一个 UTF-8 BOM（writeString("\uFEFF" + csv)）。于是 BOM 成了一个"读要剥、写要加"的双向开关——很多适配只做了读侧，导出的报表在 Excel 里照样乱码，就是这个开关只按了一半。

七、第五步：编码契约——UTF-8-only 的 Native 读不进 GBK

这是本篇真正的硬骨头，也是"数据契约假设"最纯粹的一次失效。

事实：Kotlin/Native 的 String 内部是 UTF-16，字节↔字符串只提供 UTF-8 一套（encodeToByteArray() / decodeToString()）。没有 Charset.forName("GBK") 这种东西——那是 JVM 的 java.nio.charset，Native 上没有。

后果：用户拿 Excel（简体中文 Windows 默认 GBK/ANSI）导出一份"订单.csv"，你把它拷进鸿蒙沙箱，用上面的 readCsvFromSandbox（内部 readString() 按 UTF-8 解）去读——GBK 字节不是合法 UTF-8，解出来是乱码或替换字符 \uFFFD，而且不一定抛异常。举例：中文"中文"的 GBK 字节是 0xD6 0xD0 0xCE 0xC4，其中 0xD6 是 UTF-8 的两字节前导、要求后跟一个 0x80–0xBF 续字节，但 0xD0 不是，直接判非法。

这不是改改配置能解决的，是平台根本没有这个能力——能力假设在此刻和数据契约假设重叠了。两条落地路径：

1. 约定输入编码（推荐，成本低）：要求导出侧存 UTF-8（Excel 另存为时选 “CSV UTF-8”），沙箱内全程 UTF-8，库直接能读。
2. NAPI 桥 iconv 预转码（要兼容任意来源时）：ArkTS 侧用 native 模块把字节流按 GBK→UTF-8 转好，再交给 csvReader()。

// 方案二的桥：入参是沙箱里的原始字节，出参是已转成 UTF-8 的 String
@CName("kcsv_transcode_to_utf8")
fun kcsvTranscodeToUtf8(srcPath: String, charset: String): String {
    // C++/NAPI 侧：open(srcPath) → iconu_open(charset)→UTF-8 → 返回 UTF-8 字符串
    // 这里只是契约，真实现在 .so 内用 libiconv / ICU
    return nativeIconvToUtf8(srcPath, charset)
}

判断要不要上方案二，取决于"数据来源是否可控"。能控就约定 UTF-8（99% 的新报表场景），控不了（历史 GBK 文件、第三方导出）才动用 iconv。别假装 Kotlin/Native 支持 GBK——它不支持，这是平台事实。

八、第六步：导出、打包与三组真机验证

导出/打包与前几篇一致：@CName 导出符号 → C++ NAPI 注册 → .so 进 HAR 的 libs/arm64-v8a/。验证顺序仍是先核符号、再排查调用：

llvm-nm -D libkcsv.so | findstr kcsv_

三组真机验证，缺一组都不算过——因为它们各自对应一类会"静默"的失效：

1. 换行契约（朴素 vs 状态机对照）：构造一条"字段内含换行 + CRLF 结尾"的 CSV，分别用 split('\n') 和 csvReader() 解析，确认行数差异符合预期（朴素版多出行 = 拆错了）。用一个能被一眼数出的行，别用恰好整除的数据。
2. BOM 契约（列名命中对照）：读一份带 BOM 的报表，打印 headers.indexOf("姓名")，确认不剥离时 = -1、剥离后 = 0。这一组专治"按列名取值取到空"。
3. 编码契约（GBK 探针）：把"中文"以 GBK 字节 D6 D0 CE C4 写入沙箱，用 UTF-8 路径读，确认得到 \uFFFD/乱码；再走 iconv 桥读，确认得到正确的"中文"。这一步同时证明了"约定 UTF-8"和"桥 iconv"两条路的分界。

图 1：真机运行截图 —— 朴素 split 与状态机解析的行数对照
图 2：BOM 污染下 indexOf("姓名") = -1、剥离后 = 0 的日志
图 3：hdc shell 查看沙箱内 kcsv/report.csv 的首字节 ef bb bf
图 4：GBK 字节经 iconv 桥转码前后，界面从乱码变"中文"的对照
（投稿前请补入上述四张真实截图）

九、踩坑清单

坑一：ohosArm64() 报未定义。 同前几篇，还在用 Kotlin 官方主线插件；这个 target 只在 HarmonyOS Kotlin 定制版里存在。

坑二：用 split('\n') 自己糊解析。 遇到字段内换行会把一行拆两行、列全部错位，且不报错。要么用 csvReader()，要么至少实现"引号内不分隔"的状态机。

坑三：硬编码文件路径。 承接 kotlinx-io——沙箱越界会权限拒绝；根路径必须由 context.filesDir 注入，CsvDataSource 优先给内容不给路径。

坑四：不剥 BOM。 首列表头被 \uFEFF 污染，indexOf("列名") 静默返回 -1，整列取空。读侧务必先 stripBom()。

坑五：只按 BOM 开关的一半。 读侧剥了、写侧没加，导致自己 App 里正常、导出的报表被同事的 Excel 双击打开时中文乱码。要互通就在写侧补 UTF-8 BOM。

坑六：以为 Native 能读 GBK。 Kotlin/Native 只有 UTF-8，没有 Charset.forName。GBK 来源要么约定成 UTF-8 导出，要么 NAPI 桥 iconv，别无他法。

坑七：改完代码产物没更新。 同前几篇，Kotlin/Native 编译缓存激进，产物与代码不一致时先 ./gradlew clean 再构建。

十、小结

四篇走下来，"隐含假设"这条主线分成了清清楚楚的三类，而且失效方式一个比一个安静：

类型	样本	失效表现	谁兜底
能力假设	kotlinx-datetime / kotlinx-io	抛异常 / 回退 / 权限拒绝	编译器与运行时会喊，最好查
时序假设	Essenty	不崩，静默丢状态	靠验证用例
数据契约假设	kotlin-csv	不崩不丢，每格静默错值	只能靠可辨识的对拍

kotlin-csv 把方法论钉死成一句更完整的话：先分清你遇到的是能力假设、时序假设还是数据契约假设——因为崩溃会喊、丢状态会漏，而错值只会安静地把垃圾一路传下去。识别对了类型，你就知道该去补 target、该去接宿主时序、还是该去规约编码与 BOM。这次三组验证我特意都做成"对照"（朴素 vs 状态机、不剥 vs 剥离、UTF-8 直读 vs iconv），因为对付"静默错值"这种失效，唯一的办法就是让对的那一侧和错的那一侧同框出现，让评审一眼看出差异。

欢迎加入 KMP&CMP 鸿蒙社区，一起共建 OpenHarmony 跨平台生态：
https://atomgit.com/CPF-KMP-CMP

推荐使用码道进行 KMP/CMP 工程的代码补全与适配辅助，专属邀请入口：
https://developer.huaweicloud.com/codeartsco.html?source=dmzntgwatomgit1&sourcead=dmzntgwatomgiths

---

环境信息：DevEco Studio 26.0.0 Release / HarmonyOS Kotlin 2.2.21-1.0.0 / Gradle 8.14.1 / JDK 21 / 真机 ROM 6.1+ / kotlin-csv 1.9.1