@be-link/ecommerce-volcengine-open-api-sdk

Volcengine Node.js SDK（TypeScript 简化版）

说明：这是基于 volc-sdk-java 的核心认证与请求流程，使用 Node.js + TypeScript 实现的一个简化版 SDK，主要包含：

- 签名算法：对齐 Java 版的 V4 签名（HMAC-SHA256，X-Date、X-Content-Sha256、Authorization 等头）
- HTTP 调用：基于 Node 原生 http/https 模块
- 通用客户端：通过传入 region、service、host 等信息发起任意 API 请求

$3

在仓库根目录：

``bash
cd ecommerce-volcengine-open-api-sdk
npm install
npm run build
`

$3

`ts
import { VolcClient } from '@be-link/ecommerce-volcengine-open-api-sdk';

async function main() {
const client = new VolcClient({
region: 'cn-north-1',
service: 'iam', // 与 Java 版 Credentials.service 对齐
host: 'open.volcengineapi.com',
scheme: 'https',
});

const resp = await client.request({
method: 'GET',
path: '/',
query: {
Action: 'ListUsers',
Version: '2018-01-01',
},
});

console.log(resp.statusCode, resp.body.toString('utf8'));
}

main().catch(console.error);
`

$3

- 环境变量：
- VOLC_ACCESSKEY：Access Key
- VOLC_SECRETKEY：Secret Key
- 配置文件（可选，对齐 Java 版行为）：
- 路径：~/.volc/config
- 内容示例：

`json
{
"ak": "your_ak",
"sk": "your_sk",
"service": "iam",
"region": "cn-north-1"
}
`

如果构造 VolcClient 时没有显式传入 accessKeyId / secretAccessKey，SDK 会依次尝试：

1. 环境变量 VOLC_ACCESSKEY / VOLC_SECRETKEY
2. ~/.volc/config 文件

$3

`ts
const url = client.getSignedUrl({
method: 'GET',
path: '/',
query: {
Action: 'ListUsers',
Version: '2018-01-01',
},
});

console.log('signed url:', url);
`

$3

SDK 提供了模块化的 API 封装，使用起来更加便捷：

`ts
import { VolClient, LiveStreamRoomModule } from '@be-link/ecommerce-volcengine-open-api-sdk';

const client = new VolClient({
region: 'cn-beijing',
service: 'livesaas',
host: 'livesaas.volcengineapi.com',
});

// 创建模块实例
const liveStreamRoom = new LiveStreamRoomModule(client);

// 调用 API
const response = await liveStreamRoom.listActivityAPI({
PageNo: 1,
PageItemCount: 10,
});
`

添加新模块 API

SDK 采用模块化设计，每个业务模块在 src/module/ 目录下拥有独立的文件夹。以下说明如何添加一个新的业务模块。

$3

在 src/module/ 目录下创建新模块的文件夹，例如 myModule：

`
src/module/myModule/
├── types.ts # 类型定义和接口
├── api.ts # API 方法实现
├── code.ts # 错误码映射（可选）
└── index.ts # 模块导出
`

$3

在 types.ts 中定义请求参数、响应类型和模块接口：

`ts
import { VolEngineResponse, IRateLimiter, RetryConfig, TimeoutConfig } from '../../types';

// 请求参数类型
export interface MyAPIRequest {
/* 参数说明 /
param1?: string;
param2?: number;
}

// 响应结果类型
export interface MyAPIResult {
/* 结果字段说明 /
data?: any;
}

// 响应类型
export type MyAPIResponse = VolEngineResponse;

// 模块接口：定义所有 API 方法签名
export interface IMyModuleAPI {
/**
* API 方法说明
*/
myAPI(
params: MyAPIRequest,
rateLimiter?: IRateLimiter,
retryConfig?: RetryConfig,
timeoutConfig?: TimeoutConfig
): Promise;
}
`

$3

在 api.ts 中实现接口定义的方法：

`ts
import { IClient } from '../../baseClient';
import { IRateLimiter, RetryConfig, TimeoutConfig } from '../../types';
import {
IMyModuleAPI,
MyAPIRequest,
MyAPIResponse,
} from './types';
import { myModuleErrorCodeMapper } from './code'; // 如果有错误码映射

export class MyModule implements IMyModuleAPI {
constructor(private readonly client: IClient) {}

async myAPI(
params: MyAPIRequest,
rateLimiter?: IRateLimiter,
retryConfig?: RetryConfig,
timeoutConfig?: TimeoutConfig
): Promise {
const response = await this.client.request({
method: 'POST', // 或 'GET'
path: '/',
query: {
Action: 'MyAPI', // API 名称
Version: '2024-01-01', // API 版本
},
body: params,
rateLimiter,
retryConfig,
timeoutConfig,
errorCodeMapper: myModuleErrorCodeMapper, // 可选：错误码映射器
});

// 解析响应体
const bodyStr = response.body.toString('utf8');
return JSON.parse(bodyStr);
}
}
`

$3

如果需要自定义错误码的中文描述，创建 code.ts：

`ts
import { IErrorCodeMapper } from '../../types';

// 错误码映射表
export const ErrorCodeMap: Record = {
'InvalidParameter.Param1Invalid': '参数 param1 无效。请修改后重试。',
'InternalError.InternalReqFailed': '由于未知错误，请求失败。请联系技术支持获取帮助。',
};

// 获取错误信息的辅助函数
export function getErrorMessage(errorCode?: string): string | undefined {
if (!errorCode) {
return undefined;
}

// 精确匹配
if (ErrorCodeMap[errorCode]) {
return ErrorCodeMap[errorCode];
}

// 通配符匹配（例如：InvalidParameter.%sInvalid）
for (const [pattern, message] of Object.entries(ErrorCodeMap)) {
if (pattern.includes('%s')) {
const regexPattern = pattern.replace(/%s/g, '.*');
const regex = new RegExp(^${regexPattern}$);
if (regex.test(errorCode)) {
return message;
}
}
}

return undefined;
}

// 错误码映射器类
export class MyModuleErrorCodeMapper implements IErrorCodeMapper {
getErrorMessage(errorCode?: string): string | undefined {
return getErrorMessage(errorCode);
}
}

// 单例实例
export const myModuleErrorCodeMapper = new MyModuleErrorCodeMapper();
`

$3

在 index.ts 中导出模块的所有内容：

`ts
export * from './types';
export * from './api';
export * from './code'; // 如果有错误码映射
`

$3

在 src/index.ts 中添加新模块的导出：

`ts
export * from './types';
export * from './baseClient';
export * from './client';
export * from './module/liveStreamRoom';
export * from './module/myModule'; // 添加新模块
`

$3

参考 src/module/liveStreamRoom/ 目录下的实现，这是一个完整的模块示例：

- types.ts: 定义了 ListActivityAPIRequest、ListActivityAPIResponse 等类型，以及 ILiveStreamRoomAPI 接口
- api.ts: 实现了 LiveStreamRoomModule 类，包含 listActivityAPI 方法
- index.ts: 导出所有内容

$3

添加完成后，可以这样使用：

`ts
import { VolClient, MyModule } from '@be-link/ecommerce-volcengine-open-api-sdk';

const client = new VolClient({
region: 'cn-beijing',
service: 'myservice',
host: 'myservice.volcengineapi.com',
});

const myModule = new MyModule(client);
const response = await myModule.myAPI({
param1: 'value1',
param2: 123,
});
``