生成用于读取/解码和写入/编码 ClickHouse RowBinary 流的 TypeScript/JavaScript 代码， 适用于 ClickHouse HTTP 服务器。当用户需要解析或生成 `RowBinary`、 `RowBinaryWithNames` 或 `RowBinaryWithNamesAndTypes` 时使用此技能。 仅限 Node.js，不涵盖浏览器。
ClickHouse JS RowBinary 编解码器生成器（Node.js）
此技能生成两种方向的线格式：读取器（将字节解码为值）和写入器（将值编码为字节，镜像操作）。通常一个任务只需要其中一侧。本文档是共享入口点——格式门控以及两个方向共用的原则；每个方向的决策、指导以及按类型参考表位于两个同级文件中。
选择你的方向——只阅读你需要的那部分：
- 将 ClickHouse 的
RowBinary*响应解码为 JS 值 → reader.md。流式与全缓冲、行对象与列式、固定模式与运行时模式，以及按类型读取器参考。 - 将 JS 值编码为
RowBinary负载发送给 ClickHouse → writer.md。Sink/writeX构建块、writeRows流式处理，以及按类型写入器参考。
按类型的代码是真实的，按方向分别位于 src/readers/ 和 src/writers/ 下。
首先：RowBinary 是正确的格式吗？
RowBinary 用于提高吞吐量，但并不自动是最快的路径——在投入定制解析器之前，请将格式与数据形状匹配。
当结果主要是字符串/类似 JSON 的值，并且你整体消费它们时，优先选择 JSON* 格式（例如 JSONEachRow）——随机访问几乎所有字段，运行字符串/正则表达式方法，将值视为文本。V8 的原生 JSON.parse 是高度优化的 C++，构建 JS 字符串和对象的速度比 JS 级别的 RowBinary 解码器更快；配合 HTTP 响应压缩（gzip/zstd，可以压缩 JSON 的重复键），网络成本也会降低。
当结果主要由以下类型主导时，RowBinary 明显胜出：
- 宽数值类型——
Int128/Int256/UInt128/UInt256、Decimal128/Decimal256。 - 二进制/固定宽度 blob——
IPv4、IPv6、UUID、FixedString。 - 高容量固定宽度数值列，每个值只需一次
DataView读取。
当主要目标是列式加载和客户端分析时，优先选择 Native 格式（折叠/扫描/过滤列，将类型化数组提供给 Worker 或 WASM）。Native 是列主序的，因此可以直接加载到每列一个类型化数组中，无需转置。
如需帮助选择和使用 JSON* 格式（或 CSV/TSV），请使用 clickhouse-js-node-coding 技能。
核心指导（两个方向）
无论你生成的是读取器还是写入器，这些原则都适用；方向特定的操作指导在 reader.md / writer.md 中。
-
仅限小端序。 RowBinary 是小端序；针对 x86/ARM。使用
DataView访问器读取和写入每个多字节数字时，必须传递字面量true作为littleEndian标志。 -
先正确，再优化。 首先使用简单的按类型 API 生成正确的编解码器。只有在正确（并经过测试）之后，才进行专门化。在正确性之前不要引入性能假设。
-
单态化泛型/复合类型。 为每种类型组合生成专门的、内联的代码，而不是在类型已知的情况下传递函数作为参数。
-
内联叶子操作。 按类型的
readX/writeX函数是正确的、可组合的参考；生成的编解码器应内联它们的主体，而不是调用它们，这样行循环是直线型的，没有每字段的间接调用（并且固定宽度的合并可以折叠偏移量算术）。 -
每列注释类型。 内联会抹去类型结构，因此在每列的编码/解码块上方添加简短注释，指明它处理的 ClickHouse 类型。
-
共享临时缓冲区不可重入。 某些热方法重用模块级临时缓冲区作为写后读对——仅当访问是完全同步时才正确。在填充和读取之间出现
async/yield边界会破坏值。 -
默认使用 TypeScript。 除非用户明确要求纯 JavaScript，否则生成 TypeScript 代码和辅助函数。
工作示例
六个端到端示例及其实际加速效果记录在 EXAMPLES.md 中。
不涵盖的范围
- JSON / CSV / TSV / Parquet 解析 → 使用
clickhouse-js-node-coding。 - 连接错误、挂起、类型不匹配 → 使用
clickhouse-js-node-troubleshooting。 - 浏览器 / Web Worker / Edge → 使用
@clickhouse/client-web。
