Buffer 模块

Buffer 模块为 XScript 提供二进制数据处理和多种编码格式转换功能,支持 Base58、Base64、Base85 等编码方式。

功能特性

二进制数据处理 - 创建和操作二进制缓冲区

Base58 编码 - 比特币地址常用的编码格式

Base64 编码 - 标准的二进制到文本编码

Base85 编码 - ASCII85 高效编码格式

字符串转换 - 支持多种字符编码

Buffer 操作 - 拼接、切片、比较等操作

基本使用

引入模块

链式编码转换（推荐使用）

Buffer 模块通过 encoding.from() 提供强大的链式编码转换功能：

传统方法编码/解码

也可以使用传统的函数式 API：

支持的所有编码格式

通过 encoding.from() 支持以下编码格式的链式转换：

Base 系列编码：

HEX (十六进制) - toHEX.encoding() / toHEX.decoding()

Base32 - Base32.encoding() / Base32.decoding()

Base58 - Base58.encoding() / Base58.decoding()

Base64 - Base64.encoding() / Base64.decoding()

Base64 URL Safe - Base64.url.encoding() / Base64.url.decoding()

Base85 - Base85.encoding() / Base85.decoding()

Base91 - Base91.encoding() / Base91.decoding()

数据格式转换：

toString() - 转为字符串

toBytes() / toArrayBuffer() - 转为字节数组

toObject() - JSON 字符串转对象

toQR(quality) - 生成二维码

slice(start, end) - 切片操作

append(data) - 追加数据

API 参考

Node.js 兼容 API

`Buffer.isBuffer(obj)`

检查一个对象是否为 Buffer 实例。此方法与 Node.js 的 Buffer.isBuffer() 完全兼容。

参数:

obj (any) - 要检查的对象

返回: (boolean) 如果对象是 Buffer 实例返回 true，否则返回 false

示例:

注意事项:

Buffer 在 xScript 中基于 Uint8Array 实现

此方法可用于类型检查和输入验证

与 Node.js 的 Buffer.isBuffer() 行为完全一致

编码方法

`buffer.base64Encode(data)`

将数据编码为 Base64 格式。

参数:

data (string|Buffer) - 要编码的数据

返回: (string) Base64 编码后的字符串

`buffer.base64Decode(encoded)`

解码 Base64 字符串。

参数:

encoded (string) - Base64 编码的字符串

返回: (string) 解码后的原始数据

`buffer.base58Encode(data)`

将数据编码为 Base58 格式(比特币风格)。

参数:

data (string|Buffer) - 要编码的数据

返回: (string) Base58 编码后的字符串

`buffer.base58Decode(encoded)`

解码 Base58 字符串。

参数:

encoded (string) - Base58 编码的字符串

返回: (string) 解码后的原始数据

`buffer.base85Encode(data)`

将数据编码为 Base85 (ASCII85) 格式。

参数:

data (string|Buffer) - 要编码的数据

返回: (string) Base85 编码后的字符串

`buffer.base85Decode(encoded)`

解码 Base85 字符串。

参数:

encoded (string) - Base85 编码的字符串

返回: (string) 解码后的原始数据

Buffer 操作方法

`buffer.create(size)`

创建指定大小的 Buffer。

参数:

size (number) - Buffer 大小(字节)

返回: (Buffer) 新创建的 Buffer

`buffer.from(data, encoding)`

从数据创建 Buffer。

参数:

data (string|array|Buffer) - 源数据

encoding (string) - 字符编码,可选 'utf8', 'hex', 'base64' 等

返回: (Buffer) 新创建的 Buffer

`buffer.concat(buffers)`

拼接多个 Buffer。

参数:

buffers (Array <Buffer>) - Buffer 数组

返回: (Buffer) 拼接后的 Buffer

注意事项

编码选择 - Base64 适合通用场景,Base58 适合无歧义场景(如区块链),Base85 效率更高

字符集 - 默认使用 UTF-8 编码,确保数据一致性

性能考虑 - 大数据量编码时考虑内存占用

错误处理 - 解码时注意处理无效的编码字符串

Buffer 大小 - 创建 Buffer 时注意内存限制

实际应用场景

文件编码传输

区块链地址编码

数据加密传输

二进制数据处理

最佳实践

编码格式统一 - 在项目中统一使用同一种编码格式

错误处理 - 始终捕获解码错误

性能优化 - 对于大文件考虑流式处理

安全性 - 敏感数据编码后仍需加密

文档说明 - 在 API 文档中明确说明使用的编码格式

编码格式对比

编码格式	字符集大小	效率	可读性	适用场景
Base64	64	75%	中等	通用数据传输
Base58	58	73%	较好	区块链地址、无歧义标识
Base85	85	80%	较差	高效二进制编码

与 Encoding 模块的集成

Buffer 模块为 encoding 模块提供了底层的 Buffer 创建和转换功能：

encoding.from() 方法

encoding.from() 方法实际上是调用 buffer 模块的功能来创建 Buffer：

转发的功能

Buffer 模块提供以下核心功能给 encoding 模块：

Conv(value) - 将各种类型转换为字节数组

支持: string, array, ArrayBuffer, Object, 数字类型

Format(bytes) - 将字节数组格式化为 Buffer 对象

返回标准的 Buffer 实例

Bytes(value) - 从 Value 中提取字节数组

用于编码转换操作

使用建议

如果只需要创建 Buffer，可以直接使用 Buffer.from() 或 encoding.from()

如果需要编码转换功能，使用 encoding 模块

如果需要 Base64/Base58/Base85 编码，使用 buffer 模块

buffer

Buffer 模块#

功能特性#

基本使用#

引入模块#

链式编码转换（推荐使用）#

传统方法编码/解码#

支持的所有编码格式#

API 参考#

Node.js 兼容 API#

Buffer.isBuffer(obj)#

编码方法#

buffer.base64Encode(data)#

buffer.base64Decode(encoded)#

buffer.base58Encode(data)#

buffer.base58Decode(encoded)#

buffer.base85Encode(data)#

buffer.base85Decode(encoded)#

Buffer 操作方法#

buffer.create(size)#

buffer.from(data, encoding)#

buffer.concat(buffers)#

注意事项#

实际应用场景#

文件编码传输#

区块链地址编码#

数据加密传输#

二进制数据处理#

最佳实践#

编码格式对比#

与 Encoding 模块的集成#

encoding.from() 方法#

转发的功能#

使用建议#

相关模块#

Buffer 模块

功能特性

基本使用

引入模块

链式编码转换（推荐使用）

传统方法编码/解码

支持的所有编码格式

API 参考

Node.js 兼容 API

`Buffer.isBuffer(obj)`

编码方法

`buffer.base64Encode(data)`

`buffer.base64Decode(encoded)`

`buffer.base58Encode(data)`

`buffer.base58Decode(encoded)`

`buffer.base85Encode(data)`

`buffer.base85Decode(encoded)`

Buffer 操作方法

`buffer.create(size)`

`buffer.from(data, encoding)`

`buffer.concat(buffers)`

注意事项

实际应用场景

文件编码传输

区块链地址编码

数据加密传输

二进制数据处理

最佳实践

编码格式对比

与 Encoding 模块的集成

encoding.from() 方法

转发的功能

使用建议

相关模块