@be-link/ecommerce-backend-bff-service-node-sdk 0.0.5 → 0.0.6

package/{bff → cjs/bff}/request/client.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpClient = void 0;
 const strategy_1 = require("./strategy");
 const env_1 = require("../../utils/env");
+const string_1 = require("../../utils/string");
 /**
  * HttpClient 工厂类，管理平台特定的请求策略
  * 自动检测运行时环境并创建相应的策略
@@ -42,8 +43,8 @@ class HttpClient {
             Promise.resolve(this.options.getUserId()).catch(() => ''),
             Promise.resolve(this.options.getRuleId?.() ?? '').catch(() => ''),
         ]);
-        // 生成唯一的请求 ID
-        const requestId = `b-${crypto.randomUUID()}`;
+        // 生成唯一的请求 ID（兼容所有环境）
+        const requestId = `b-${(0, string_1.generateUUID)()}`;
         // 构造标准请求头
         const standardHeaders = {
             'Content-Type': 'application/json',

package/{utils → cjs/utils}/string.d.ts

@@ -10,3 +10,11 @@
  * camelToKebabCase('myHTTPRequest') // 'my-http-request'
  */
 export declare function camelToKebabCase(str: string): string;
+/**
+ * 生成 UUID v4 格式的唯一标识符
+ * 兼容浏览器、Node.js 和微信小程序环境
+ * @returns UUID 字符串，格式为 xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ * @example
+ * generateUUID() // '550e8400-e29b-41d4-a716-446655440000'
+ */
+export declare function generateUUID(): string;

package/cjs/utils/string.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.camelToKebabCase = camelToKebabCase;
+exports.generateUUID = generateUUID;
+/**
+ * 将驼峰命名字符串转换为短横线命名
+ * @param str 驼峰命名字符串
+ * @returns 短横线命名字符串
+ * @example
+ * camelToKebabCase('fetchConfig') // 'fetch-config'
+ * camelToKebabCase('getCosTempSecret') // 'get-cos-temp-secret'
+ * camelToKebabCase('getUserProfile') // 'get-user-profile'
+ * camelToKebabCase('API') // 'api'
+ * camelToKebabCase('myHTTPRequest') // 'my-http-request'
+ */
+function camelToKebabCase(str) {
+    return str
+        .replace(/([A-Z])/g, '-$1')
+        .toLowerCase()
+        .replace(/^-/, ''); // 如果存在则移除前导连字符
+}
+/**
+ * 生成 UUID v4 格式的唯一标识符
+ * 兼容浏览器、Node.js 和微信小程序环境
+ * @returns UUID 字符串，格式为 xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ * @example
+ * generateUUID() // '550e8400-e29b-41d4-a716-446655440000'
+ */
+function generateUUID() {
+    // 优先使用原生 crypto.randomUUID（浏览器和 Node.js 18+）
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    // 降级方案：使用 Math.random() 生成 UUID v4
+    // 格式：xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}

package/esm/bff/modules/BaseService.d.ts

@@ -0,0 +1,41 @@
+import { HttpClient } from '../request/client';
+/**
+ * BaseService 基类
+ * 所有服务类都应该继承此类
+ * 提供通过 HttpClient 发起 API 请求的通用功能
+ */
+export default abstract class BaseService {
+    /**
+     * 服务的 URL 前缀路径（例如 '/api/v1/user'）
+     * 必须由子类定义
+     */
+    protected abstract prefixUrl: string;
+    /**
+     * 用于发起请求的 HttpClient 实例
+     * 通过构造函数注入
+     */
+    protected http: HttpClient;
+    /**
+     * 使用 HttpClient 初始化 BaseService
+     * @param http - 用于发起 API 请求的 HttpClient 实例
+     */
+    constructor(http: HttpClient);
+    /**
+     * 将函数引用转换为短横线命名的 API 路径
+     * @param func - 函数引用（通常是服务类的方法）
+     * @returns 从函数名派生的短横线命名路径段
+     * @example
+     * getPath(this.getUserProfile) // 返回 'get-user-profile'
+     */
+    protected getPath(func: Function): string;
+    /**
+     * 通过组合 prefixUrl 和方法路径执行 API 请求
+     * @param func - 用于派生 API 路径的函数引用
+     * @param data - 请求负载数据（可选）
+     * @returns Promise，解析为响应数据
+     * @throws SdkError 如果请求失败
+     * @example
+     * await this.request(this.getUserProfile, { id: '123' })
+     */
+    protected request<T>(func: Function, data?: any): Promise<T>;
+}

package/esm/bff/modules/BaseService.mjs

@@ -0,0 +1,38 @@
+import { camelToKebabCase } from '../../utils/string.mjs';
+/**
+ * BaseService 基类
+ * 所有服务类都应该继承此类
+ * 提供通过 HttpClient 发起 API 请求的通用功能
+ */
+export default class BaseService {
+    /**
+     * 使用 HttpClient 初始化 BaseService
+     * @param http - 用于发起 API 请求的 HttpClient 实例
+     */
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * 将函数引用转换为短横线命名的 API 路径
+     * @param func - 函数引用（通常是服务类的方法）
+     * @returns 从函数名派生的短横线命名路径段
+     * @example
+     * getPath(this.getUserProfile) // 返回 'get-user-profile'
+     */
+    getPath(func) {
+        return camelToKebabCase(func.name);
+    }
+    /**
+     * 通过组合 prefixUrl 和方法路径执行 API 请求
+     * @param func - 用于派生 API 路径的函数引用
+     * @param data - 请求负载数据（可选）
+     * @returns Promise，解析为响应数据
+     * @throws SdkError 如果请求失败
+     * @example
+     * await this.request(this.getUserProfile, { id: '123' })
+     */
+    async request(func, data) {
+        const path = `${this.prefixUrl}/${this.getPath(func)}`;
+        return this.http.request({ path, data });
+    }
+}

package/esm/bff/modules/demo/service.d.ts

@@ -0,0 +1,22 @@
+import { Service } from './types';
+import BaseService from '../BaseService';
+import type { StandardResponse } from '../../../types';
+/**
+ * DemoService - Demo 服务模块
+ * 提供 Demo 相关的 API 方法
+ */
+declare class DemoService extends BaseService {
+    protected prefixUrl: string;
+    /**
+     * Demo 方法
+     * @param request - 请求参数
+     * @returns Promise，解析为标准响应格式
+     * @example
+     * const result = await sdk.demo.demoFunc({ demoParam: 'test' })
+     * console.log(result.data)       // 业务数据
+     * console.log(result.message)    // 响应消息
+     * console.log(result.requestId)  // 请求 ID
+     */
+    demoFunc(request: Service.Request.demoFunc): Promise<StandardResponse<Service.Response.demoFunc>>;
+}
+export default DemoService;

package/esm/bff/modules/demo/service.mjs

@@ -0,0 +1,25 @@
+import BaseService from '../BaseService.mjs';
+/**
+ * DemoService - Demo 服务模块
+ * 提供 Demo 相关的 API 方法
+ */
+class DemoService extends BaseService {
+    constructor() {
+        super(...arguments);
+        this.prefixUrl = '/demo';
+    }
+    /**
+     * Demo 方法
+     * @param request - 请求参数
+     * @returns Promise，解析为标准响应格式
+     * @example
+     * const result = await sdk.demo.demoFunc({ demoParam: 'test' })
+     * console.log(result.data)       // 业务数据
+     * console.log(result.message)    // 响应消息
+     * console.log(result.requestId)  // 请求 ID
+     */
+    demoFunc(request) {
+        return this.request(this.demoFunc, request);
+    }
+}
+export default DemoService;

package/esm/bff/modules/demo/types.d.ts

@@ -0,0 +1,28 @@
+export declare namespace Service {
+    namespace Entity { }
+    namespace Request {
+        /**
+         * 获取配置请求参数
+         */
+        interface demoFunc {
+            /** 参数 */
+            demoParam: string;
+        }
+    }
+    namespace Response {
+        interface demoFunc {
+        }
+    }
+    /**
+     * Config Controller 接口定义
+     */
+    interface DemoController {
+        /**
+         * 示例接口
+         * @param request 请求参数
+         * @param req 请求上下文
+         * @returns 响应数据
+         */
+        demoFunc(request: Service.Request.demoFunc, req: any): Promise<Service.Response.demoFunc>;
+    }
+}

package/esm/bff/modules/demo/types.mjs

@@ -0,0 +1 @@
+export {};

package/esm/bff/modules/example/service.d.ts

@@ -0,0 +1,46 @@
+import BaseService from '../BaseService';
+import type { StandardResponse } from '../../../types';
+import { Service } from './types';
+/**
+ * ExampleService - 演示如何创建服务模块
+ * 此服务提供用户资料和订单管理的示例方法
+ */
+export declare class ExampleService extends BaseService {
+    /**
+     * 此服务的 API 路径前缀
+     * 此服务中的所有方法都将使用此前缀
+     */
+    protected prefixUrl: string;
+    /**
+     * 根据 ID 获取用户资料
+     * @param request - 请求参数
+     * @returns Promise，解析为标准响应格式，包含用户资料数据
+     * @example
+     * const result = await exampleService.getUserProfile({ id: 'user123' })
+     * console.log(result.data)       // 用户资料数据
+     * console.log(result.message)    // 响应消息
+     * console.log(result.requestId)  // 请求 ID
+     */
+    getUserProfile(request: Service.Request.getUserProfile): Promise<StandardResponse<Service.Response.getUserProfile>>;
+    /**
+     * 更新用户资料
+     * @param request - 请求参数
+     * @returns Promise，解析为标准响应格式
+     * @example
+     * const result = await exampleService.updateProfile({ name: 'John Doe', email: 'john@example.com' })
+     * console.log(result.message)    // 'success'
+     * console.log(result.success)    // true
+     */
+    updateProfile(request: Service.Request.updateProfile): Promise<StandardResponse<Service.Response.updateProfile>>;
+    /**
+     * 获取分页订单列表
+     * @param request - 请求参数
+     * @returns Promise，解析为标准响应格式，包含订单列表数据
+     * @example
+     * const result = await exampleService.getOrderList({ page: 1, pageSize: 20 })
+     * console.log(result.data.orders)  // 订单列表
+     * console.log(result.data.total)   // 总数
+     * console.log(result.requestId)    // 请求 ID
+     */
+    getOrderList(request: Service.Request.getOrderList): Promise<StandardResponse<Service.Response.getOrderList>>;
+}

package/esm/bff/modules/example/service.mjs

@@ -0,0 +1,53 @@
+import BaseService from '../BaseService.mjs';
+/**
+ * ExampleService - 演示如何创建服务模块
+ * 此服务提供用户资料和订单管理的示例方法
+ */
+export class ExampleService extends BaseService {
+    constructor() {
+        super(...arguments);
+        /**
+         * 此服务的 API 路径前缀
+         * 此服务中的所有方法都将使用此前缀
+         */
+        this.prefixUrl = '/api/v1/user';
+    }
+    /**
+     * 根据 ID 获取用户资料
+     * @param request - 请求参数
+     * @returns Promise，解析为标准响应格式，包含用户资料数据
+     * @example
+     * const result = await exampleService.getUserProfile({ id: 'user123' })
+     * console.log(result.data)       // 用户资料数据
+     * console.log(result.message)    // 响应消息
+     * console.log(result.requestId)  // 请求 ID
+     */
+    async getUserProfile(request) {
+        return this.request(this.getUserProfile, request);
+    }
+    /**
+     * 更新用户资料
+     * @param request - 请求参数
+     * @returns Promise，解析为标准响应格式
+     * @example
+     * const result = await exampleService.updateProfile({ name: 'John Doe', email: 'john@example.com' })
+     * console.log(result.message)    // 'success'
+     * console.log(result.success)    // true
+     */
+    async updateProfile(request) {
+        return this.request(this.updateProfile, request);
+    }
+    /**
+     * 获取分页订单列表
+     * @param request - 请求参数
+     * @returns Promise，解析为标准响应格式，包含订单列表数据
+     * @example
+     * const result = await exampleService.getOrderList({ page: 1, pageSize: 20 })
+     * console.log(result.data.orders)  // 订单列表
+     * console.log(result.data.total)   // 总数
+     * console.log(result.requestId)    // 请求 ID
+     */
+    async getOrderList(request) {
+        return this.request(this.getOrderList, request);
+    }
+}

package/esm/bff/modules/example/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Example Service 的类型定义
+ * 使用命名空间组织类型，与后端 SDK 保持一致
+ */
+export declare namespace Service {
+    /**
+     * 实体定义
+     */
+    namespace Entity {
+        /**
+         * 用户资料数据结构
+         */
+        interface UserProfile {
+            id: string;
+            name: string;
+            email: string;
+            phone?: string;
+            avatar?: string;
+            createdAt: string;
+            updatedAt: string;
+        }
+        /**
+         * 订单项结构
+         */
+        interface Order {
+            id: string;
+            userId: string;
+            orderNumber: string;
+            status: string;
+            totalAmount: number;
+            items: OrderItem[];
+            createdAt: string;
+            updatedAt: string;
+        }
+        /**
+         * 订单项详情
+         */
+        interface OrderItem {
+            id: string;
+            productId: string;
+            productName: string;
+            quantity: number;
+            price: number;
+        }
+    }
+    /**
+     * 请求参数定义
+     */
+    namespace Request {
+        /**
+         * 获取用户资料的请求参数
+         */
+        interface getUserProfile {
+            /** 用户 ID */
+            id: string;
+        }
+        /**
+         * 更新用户资料的请求负载
+         */
+        interface updateProfile {
+            name?: string;
+            email?: string;
+            phone?: string;
+            avatar?: string;
+        }
+        /**
+         * 获取订单列表的请求负载
+         */
+        interface getOrderList {
+            page: number;
+            pageSize?: number;
+            status?: string;
+        }
+    }
+    /**
+     * 响应数据定义
+     */
+    namespace Response {
+        /**
+         * 获取用户资料的响应
+         */
+        interface getUserProfile {
+            id: string;
+            name: string;
+            email: string;
+            phone?: string;
+            avatar?: string;
+            createdAt: string;
+            updatedAt: string;
+        }
+        /**
+         * 更新用户资料的响应
+         */
+        interface updateProfile {
+        }
+        /**
+         * 订单列表的响应结构
+         */
+        interface getOrderList {
+            orders: Entity.Order[];
+            total: number;
+            page: number;
+            pageSize: number;
+        }
+    }
+    /**
+     * Example Controller 接口定义
+     * 用于后端 Server 实现
+     */
+    interface ExampleController {
+        /**
+         * 获取用户资料
+         * @param request 请求参数
+         * @param req 请求上下文
+         * @returns 用户资料数据
+         */
+        getUserProfile(request: Service.Request.getUserProfile, req: any): Promise<Service.Response.getUserProfile>;
+        /**
+         * 更新用户资料
+         * @param request 请求参数
+         * @param req 请求上下文
+         * @returns 响应数据
+         */
+        updateProfile(request: Service.Request.updateProfile, req: any): Promise<Service.Response.updateProfile>;
+        /**
+         * 获取订单列表
+         * @param request 请求参数
+         * @param req 请求上下文
+         * @returns 订单列表数据
+         */
+        getOrderList(request: Service.Request.getOrderList, req: any): Promise<Service.Response.getOrderList>;
+    }
+}

package/esm/bff/modules/example/types.mjs

@@ -0,0 +1 @@
+export {};

package/esm/bff/request/client.d.ts

@@ -0,0 +1,45 @@
+import { SdkOptions } from '../../types';
+/**
+ * HttpClient 工厂类，管理平台特定的请求策略
+ * 自动检测运行时环境并创建相应的策略
+ */
+export declare class HttpClient {
+    /**
+     * 请求策略实例（Web 或小程序）
+     */
+    private strategy;
+    /**
+     * 标识 SDK 是否运行在微信小程序环境中
+     */
+    readonly isMiniProgram: boolean;
+    /**
+     * SDK 配置选项，包含凭证回调函数
+     */
+    private options;
+    /**
+     * 运行环境配置
+     */
+    private environment;
+    /**
+     * 使用 SDK 选项初始化 HttpClient
+     * 自动检测平台并创建相应的请求策略
+     * @param options - SDK 配置，包含 getToken、getUserId 回调函数和 environment
+     */
+    constructor(options: SdkOptions);
+    /**
+     * 工厂方法，根据平台创建相应的请求策略
+     * @returns BaseRequestStrategy 实例（WebRequestStrategy 或 MiniProgramRequestStrategy）
+     */
+    private createStrategy;
+    /**
+     * 执行 API 请求，自动获取凭证并构造请求头
+     * @param opts - 请求选项，包含路径、数据和可选的自定义请求头
+     * @returns Promise，解析为响应数据
+     * @throws SdkError 如果请求失败
+     */
+    request<T>(opts: {
+        path: string;
+        data?: any;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+}

package/esm/bff/request/client.mjs

@@ -0,0 +1,61 @@
+import { WebRequestStrategy, MiniProgramRequestStrategy } from './strategy.mjs';
+import { isMiniProgram } from '../../utils/env.mjs';
+import { generateUUID } from '../../utils/string.mjs';
+/**
+ * HttpClient 工厂类，管理平台特定的请求策略
+ * 自动检测运行时环境并创建相应的策略
+ */
+export class HttpClient {
+    /**
+     * 使用 SDK 选项初始化 HttpClient
+     * 自动检测平台并创建相应的请求策略
+     * @param options - SDK 配置，包含 getToken、getUserId 回调函数和 environment
+     */
+    constructor(options) {
+        this.options = options;
+        this.environment = options.environment;
+        this.isMiniProgram = isMiniProgram();
+        this.strategy = this.createStrategy();
+    }
+    /**
+     * 工厂方法，根据平台创建相应的请求策略
+     * @returns BaseRequestStrategy 实例（WebRequestStrategy 或 MiniProgramRequestStrategy）
+     */
+    createStrategy() {
+        if (this.isMiniProgram) {
+            return new MiniProgramRequestStrategy(this.environment);
+        }
+        return new WebRequestStrategy(this.environment);
+    }
+    /**
+     * 执行 API 请求，自动获取凭证并构造请求头
+     * @param opts - 请求选项，包含路径、数据和可选的自定义请求头
+     * @returns Promise，解析为响应数据
+     * @throws SdkError 如果请求失败
+     */
+    async request(opts) {
+        // 并发获取凭证，带错误处理
+        const [token, userId, ruleId] = await Promise.all([
+            Promise.resolve(this.options.getToken()).catch(() => ''),
+            Promise.resolve(this.options.getUserId()).catch(() => ''),
+            Promise.resolve(this.options.getRuleId?.() ?? '').catch(() => ''),
+        ]);
+        // 生成唯一的请求 ID（兼容所有环境）
+        const requestId = `b-${generateUUID()}`;
+        // 构造标准请求头
+        const standardHeaders = {
+            'Content-Type': 'application/json',
+            'X-Request-Id': requestId,
+            'x-belink-authorization': token,
+            'x-belink-pandora-userId': userId,
+            'x-belink-pandora-ruleId': ruleId,
+        };
+        // 合并自定义请求头（自定义请求头优先）
+        const headers = {
+            ...standardHeaders,
+            ...(opts.headers || {}),
+        };
+        // 委托给平台特定的策略
+        return this.strategy.request(opts.path, opts.data, headers);
+    }
+}

package/esm/bff/request/strategy.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 请求策略的抽象基类
+ * 定义所有请求策略的公共契约和共享实现
+ */
+export declare abstract class BaseRequestStrategy {
+    /**
+     * 运行环境配置
+     */
+    protected environment: 'production' | 'test';
+    /**
+     * 创建请求策略实例
+     * @param environment - 运行环境 ('production' 或 'test')
+     */
+    constructor(environment: 'production' | 'test');
+    /**
+     * 子类必须实现的请求方法
+     */
+    abstract request<T>(path: string, data?: any, headers?: Record<string, string>): Promise<T>;
+}
+/**
+ * Web/H5 请求策略，使用 axios 进行 HTTP 请求
+ * 为浏览器环境实现请求策略
+ */
+export declare class WebRequestStrategy extends BaseRequestStrategy {
+    /**
+     * 使用 axios 执行 HTTP POST 请求
+     * @param path - API 端点路径
+     * @param data - 请求负载（可选）
+     * @param headers - 要包含在请求中的额外请求头（可选）
+     * @returns Promise，解析为响应数据
+     * @throws BizError 如果是 4xx 客户端错误
+     * @throws SystemError 如果是 5xx 服务器错误或网络错误
+     */
+    request<T>(path: string, data?: any, headers?: Record<string, string>): Promise<T>;
+}
+/**
+ * 微信小程序请求策略，使用 wx.cloud.callContainer
+ * 为微信小程序环境实现请求策略
+ */
+export declare class MiniProgramRequestStrategy extends BaseRequestStrategy {
+    /**
+     * 使用微信云托管容器 API 执行请求
+     * @param path - API 端点路径
+     * @param data - 请求负载（可选）
+     * @param headers - 要包含在请求中的额外请求头（可选）
+     * @returns Promise，解析为响应数据
+     * @throws BizError 如果是 4xx 客户端错误
+     * @throws SystemError 如果是 5xx 服务器错误或微信 API 错误
+     */
+    request<T>(path: string, data?: any, headers?: Record<string, string>): Promise<T>;
+}