FileStorage 类文档

本文档提供了 FileStorage 类的 JavaScript 接口。该类用于处理文件的存储和缓存，支持将 Base64 编码的数据存储到磁盘或缓存，并返回文件的访问链接。

类描述

FileStorage 提供两种文件存储方式：磁盘存储（disk 方法）和 缓存存储（cache 方法）。磁盘存储将 Base64 编码的数据解码后写入文件系统，缓存存储将数据直接存储到缓存中。两种方式均支持设置文件后缀和名称，并通过异步线程执行存储操作以提高性能。

方法

disk(base64Encode, ...params)

将 Base64 编码的字符串解码并写入磁盘文件。

参数

• base64Encode (string): Base64 编码的字符串，包含文件内容。
• ...params (string[]): 可变参数，最多接受两个参数：
• params[0] (string): 文件后缀（如 jpg、png）。
• params[1] (string, 可选): 文件名称。如果未提供，使用 8 位 UUID 作为文件名；如果提供，将覆盖同名文件。

返回值

• string: 文件的访问链接，基于网关访问 URL 和文件路径生成。

异常

• 如果消息解析模拟输入，则抛出错误："当前模拟输入暂不支持文件存储！"。
• 如果 base64Encode 或 params 为空或无效，抛出错误："参数不能为空"。
• 如果文件大小超过 100MB，抛出错误："文件大小超过限制，请上传小于 100MB 的文件"。
• 如果解码或写入文件失败，抛出错误："将 Base64 编码的字符串解码并写入指定路径的文件时出错"。

行为

• 异步解码 Base64 数据并写入文件，文件路径格式为：{yyyyMMdd}/{fileName}.{suffix}。
• 记录文件过期时间，默认为7天。
• 返回的访问链接。

示例

const base64Encode = "data:image/jpeg;base64,...";
const fileUrl = FileStorage.disk(base64Encode, "jpg");
// 返回: "http://gateway-url/uploadFile/20250416/xxxxxxxx.jpg"

const fileUrlWithName = FileStorage.disk(base64Encode, "jpg", "customImage");
// 返回: "http://gateway-url/uploadFile/20250416/customImage.jpg"

cache(base64Encode, ...params)

将 Base64 编码的字符串存储到缓存中。

参数

• base64Encode (string): Base64 编码的字符串，包含文件内容。
• ...params (string[]): 可变参数，最多接受两个参数：
• params[0] (string): 文件后缀（如 jpg、png）。
• params[1] (string, 可选): 文件名称。如果未提供，使用 8 位 UUID 作为文件名；如果提供，将覆盖同名文件。

返回值

• string: 文件的访问链接，格式为 “/api/cache/download/“ + fileName。

异常

• 如果 base64Encode 或 params 为空或无效，抛出错误："参数不能为空"。
• 如果文件大小超过 10MB，抛出错误："文件大小超过限制，请上传小于 10MB 的文件或使用disk存储"。
• 如果缓存失败，抛出错误："缓存资源数据时出错"。

行为

• 异步解码 Base64 数据以检查大小，之后将原始 Base64 字符串存储到缓存。
• 记录文件过期时间，默认为7天。
• 返回的访问链接。

示例

const base64Encode = "data:image/jpeg;base64,...";
const fileUrl = FileStorage.cache(base64Encode, "jpg");
// 返回: "http://gateway-url/api/cache/download/xxxxxxxx.jpg"

const fileUrlWithKey = FileStorage.cache(base64Encode, "jpg", "customKey");
// 返回: "http://gateway-url/api/cache/download/customKey.jpg"

注意事项

• 文件大小限制：
• disk 方法限制文件大小为 100MB。
• cache 方法限制文件大小为 10MB，超出时建议使用 disk 方法。