工具函式 | ArcBlock

@blocklet/did-space-js 函式庫匯出一系列工具函式，旨在簡化您在建構應用程式時會遇到的常見任務。這些輔助函式處理 DID 格式化、URL 標準化、編碼和錯誤解析等操作，讓您能專注於核心應用程式邏輯。

您可以直接從套件中匯入這些工具函式：

Import Utilities

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

DID 格式化

DID Space 使用帶有 did:abt: 前綴的 DID。這些工具函式幫助您在標準 DID 和 ABT 特定格式之間進行轉換，確保相容性和正確的驗證。

toABTDid

為一個有效的 DID 字串添加 did:abt: 前綴。當您需要從一個基礎 DID 建構一個完整的 ABT DID 時，這個函式很有用。

參數

did string (required) — 一個有效的標準 DID 字串。

傳回值

abtDid string — 帶有 'did:abt:' 前綴的 DID 字串

範例

toABTDid Example

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 Example

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 Example

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 Example

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 Example

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）。

範例

Error Handling Example

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 參考文件。