工具函数 | ArcBlock

@blocklet/did-space-js 库导出了一系列工具函数，旨在简化您在构建应用程序时遇到的常见任务。这些辅助函数处理诸如 DID 格式化、URL 规范化、编码和错误解析等操作，让您可以专注于核心应用程序逻辑。

您可以直接从包中导入这些工具函数：

导入工具函数

import {
  toABTDid,
  toDid,
  normalizeEndpoint,
  getSpaceServiceEndpoint,
  encode,
  getErrorMessage,
  getErrorStatusCode,
} from '@blocklet/did-space-js';

DID 格式化

DID Space 使用带有 did:abt: 前缀的 DID。这些工具函数可以帮助您在标准 DID 和 ABT 特定格式之间进行转换，以确保兼容性和正确的验证。

toABTDid

将 did:abt: 前缀添加到一个有效的 DID 字符串中。当您需要从一个基础 DID 构建一个完整的 ABT DID 时，此函数非常有用。

参数

did string (required) — 一个有效的标准 DID 字符串。

abtDid string — 带有 'did:abt:' 前缀的 DID 字符串

示例

toABTDid 示例

import { toABTDid } from '@blocklet/did-space-js';

const baseDid = 'z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr';
const abtDid = toABTDid(baseDid);

console.log(abtDid); // "did:abt:z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr"

try {
  toABTDid('invalid-did');
} catch (error) {
  console.error(error.message); // "did(invalid-did) is not a valid did"
}

toDid

从 DID 字符串中移除 did:abt: 前缀，返回基础 DID。它还会验证结果字符串是否为有效的 DID。

参数

did string (required) — 一个 DID 字符串，通常带有 'did:abt:' 前缀。

baseDid string — 不带前缀的基础 DID 字符串。

示例

toDid 示例

import { toDid } from '@blocklet/did-space-js';

const abtDid = 'did:abt:z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr';
const baseDid = toDid(abtDid);

console.log(baseDid); // "z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr"

try {
  toDid('did:abt:invalid-did');
} catch (error) {
  console.error(error.message); // "did(invalid-did) is not a valid did"
}

端点和 URL 工具函数

这些函数可帮助您管理和解析与 DID Space 通信所需的端点。

normalizeEndpoint

通过移除查询参数和任何末尾的 /object/ 段来清理 DID Space 端点 URL。这可以确保您在进行 API 调用时拥有一个一致的基础 URL。

参数

endpoint string (required) — 一个完整的 DID Space 端点 URL。

normalizedEndpoint string — 清理后的基础端点 URL。

示例

normalizeEndpoint 示例

import { normalizeEndpoint } from '@blocklet/did-space-js';

const fullEndpoint =
  'https://73aa3e87-znkjt5vbgnezh4p6v4dsaye61e7pxxn3vk4j.did.abtnet.io/app/api/space/z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr/app/zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F/object/?some=query';
const normalized = normalizeEndpoint(fullEndpoint);

console.log(normalized); // "https://73aa3e87-znkjt5vbgnezh4p6v4dsaye61e7pxxn3vk4j.did.abtnet.io/app/api/space/z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr/app/zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F/"

getSpaceServiceEndpoint

解析给定 DID Space 的实际服务端点。某些空间可能会使用一个网关 URL，该 URL 会重定向到另一个用于文件操作的服务 URL。此函数会为您处理该解析过程。

参数

normalizedEndpoint string (required) — 一个规范化的 DID Space 端点 URL，通常来自 normalizeEndpoint。
defaultValue string — 如果端点无法解析，则返回此备用值。默认为 normalizedEndpoint 本身。

serviceEndpoint Promise<string> — 一个解析为实际服务端点 URL 的 promise。

示例

getSpaceServiceEndpoint 示例

import { getSpaceServiceEndpoint } from '@blocklet/did-space-js';

async function resolveEndpoint(endpoint: string) {
  const serviceEndpoint = await getSpaceServiceEndpoint(endpoint);
  console.log(`Service URL for ${endpoint} is ${serviceEndpoint}`);
}

const spaceUrl =
  'https://73aa3e87-znkjt5vbgnezh4p6v4dsaye61e7pxxn3vk4j.did.abtnet.io/app/api/space/z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr/app/zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F/';
resolveEndpoint(spaceUrl);

编码

encode

将字符串编码为 URL 安全的 Base64 格式。这对于编码将在 URL 中使用的文件路径或密钥特别有用，可确保特殊字符不会引起问题。

参数

key string (required) — 要编码的字符串，例如文件路径。

encodedKey string — URL 安全的 Base64 编码字符串。

示例

encode 示例

import { encode } from '@blocklet/did-space-js';

const filePath = 'path/to/my important file.txt';
const encodedPath = encode(filePath);

console.log(encodedPath); // "cGF0aC90by9teSBpbXBvcnRhbnQgZmlsZS50eHQ"

错误处理

当 API 调用失败时，SDK 会抛出一个错误。这些工具函数可以帮助您解析错误对象，以提取人类可读的消息和 HTTP 状态码，从而简化您的错误处理逻辑。

getErrorMessage

从底层 HTTP 客户端（got）可能抛出的各种类型的错误对象中提取最相关的错误消息。

参数

error Error | RequestError (required) — 在 catch 块中捕获的错误对象。

errorMessage string — 一个用户友好的错误消息。

getErrorStatusCode

从 HTTP 错误对象中提取 HTTP 状态码。

参数

error HTTPError (required) — 在 catch 块中捕获的错误对象。

statusCode number — HTTP 状态码（例如，404、500）。

示例

错误处理示例

import { SpaceClient, GetObjectCommand } from '@blocklet/did-space-js';
import { getErrorMessage, getErrorStatusCode } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

const wallet = getWallet();
const client = new SpaceClient({
  endpoint: 'https://www.didspaces.com/app/api/space/...',
  wallet,
});

async function fetchNonExistentFile() {
  try {
    const command = new GetObjectCommand({ key: 'non-existent-file.txt' });
    await client.send(command);
  } catch (error) {
    const message = getErrorMessage(error);
    const statusCode = getErrorStatusCode(error);

    console.error(`Operation failed with status ${statusCode}: ${message}`);
    // 预期输出可能为：“Operation failed with status 404: Not Found”
  }
}

fetchNonExistentFile();

此示例展示了如何在 try...catch 块中使用 getErrorMessage 和 getErrorStatusCode 来优雅地处理 API 错误，例如文件未找到。

借助这些工具函数，您可以处理与 DID Space 交互时所需的许多常见数据转换和错误处理场景。要了解如何在更复杂的场景中使用这些工具函数，请查看 API 参考。