@be-link/ecommerce-backend-bff-service-node-sdk 0.0.1

package/README.md

@@ -0,0 +1,115 @@
+# EcommerceBackendBffService SDK
+
+EcommerceBackendBffService Node.js SDK - 统一平台 SDK，支持 Web/H5 和微信小程序
+
+## 特性
+
+- ✅ **统一命名空间结构**：与后端 SDK 保持一致的类型定义
+- ✅ **自动生成 Swagger 文档**：使用 tsoa 自动生成 OpenAPI 3.0 文档
+- ✅ **多平台支持**：自动检测并适配 Web/H5 和微信小程序环境
+- ✅ **类型安全**：完整的 TypeScript 类型定义
+- ✅ **标准响应格式**：统一的 `StandardResponse<T>` 响应结构
+
+## 安装
+
+```bash
+npm install @be-link/ecommerce-backend-bff-service-node-sdk
+```
+
+## 使用
+
+### Web/H5 环境
+
+```typescript
+import { EcommerceBackendBffSDK } from '@be-link/ecommerce-backend-bff-service-node-sdk'
+
+const sdk = new EcommerceBackendBffSDK({
+  getToken: async () => localStorage.getItem('token') || '',
+  getUserId: async () => localStorage.getItem('userId') || '',
+  environment: 'production'
+})
+
+// 使用服务
+const result = await sdk.demo.demoFunc({ demoParam: 'test' })
+console.log(result.data)       // 业务数据
+console.log(result.message)    // 响应消息
+console.log(result.requestId)  // 请求 ID
+```
+
+### 微信小程序环境
+
+```typescript
+import { EcommerceBackendBffSDK } from '@be-link/ecommerce-backend-bff-service-node-sdk'
+
+const sdk = new EcommerceBackendBffSDK({
+  getToken: async () => wx.getStorageSync('token') || '',
+  getUserId: async () => wx.getStorageSync('userId') || '',
+  environment: 'test'
+})
+
+// 使用服务
+const result = await sdk.example.getUserProfile({ id: 'user123' })
+```
+
+### 使用类型定义
+
+```typescript
+import { 
+  EcommerceBackendBffSDK,
+  DemoControllerTypes,
+  ExampleServiceTypes 
+} from '@be-link/ecommerce-backend-bff-service-node-sdk'
+
+// 使用命名空间类型
+type DemoRequest = DemoControllerTypes.Request.demoFunc
+type DemoResponse = DemoControllerTypes.Response.demoFunc
+
+type UserProfile = ExampleServiceTypes.Response.getUserProfile
+```
+
+## 开发
+
+```bash
+# 构建
+npm run build
+
+# 生成 Swagger 文档
+npm run swagger
+
+# 构建并生成文档
+npm run build:swagger
+
+# 运行测试
+npm test
+```
+
+## 文档
+
+- [目录结构说明](./DIRECTORY_STRUCTURE.md) - 项目目录结构和组织方式
+- [架构说明](./ARCHITECTURE.md) - 系统架构和设计理念
+- [Swagger 文档](./SWAGGER.md) - API 文档生成和使用指南
+- [类型兼容性](./TYPES_COMPATIBILITY.md) - 类型定义和兼容性说明
+- [SDK vs Server](./SDK_VS_SERVER.md) - SDK 和 Server 的区别
+
+## API 文档
+
+生成的 Swagger 文档位于 `dist/swagger.json`，可以使用以下方式查看：
+
+1. **Swagger UI**：
+```bash
+npm install -g swagger-ui-watcher
+swagger-ui-watcher packages/sdk/dist/swagger.json
+```
+
+2. **在线工具**：访问 [Swagger Editor](https://editor.swagger.io/) 并导入 `swagger.json`
+
+3. **VS Code 插件**：安装 [Swagger Viewer](https://marketplace.visualstudio.com/items?itemName=Arjun.swagger-viewer)
+
+## 添加新服务
+
+查看 [DIRECTORY_STRUCTURE.md](./DIRECTORY_STRUCTURE.md) 了解如何添加新的服务模块。
+
+## License
+
+ISC
+

package/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/bff/modules/BaseService.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const string_1 = require("../../utils/string");
+/**
+ * BaseService 基类
+ * 所有服务类都应该继承此类
+ * 提供通过 HttpClient 发起 API 请求的通用功能
+ */
+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 (0, string_1.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 });
+    }
+}
+exports.default = BaseService;

package/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/bff/modules/demo/service.js

@@ -0,0 +1,49 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const tsoa_1 = require("tsoa");
+const BaseService_1 = __importDefault(require("../BaseService"));
+/**
+ * DemoService - Demo 服务模块
+ * 提供 Demo 相关的 API 方法
+ */
+let DemoService = class DemoService extends BaseService_1.default {
+    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);
+    }
+};
+__decorate([
+    (0, tsoa_1.OperationId)('示例接口'),
+    (0, tsoa_1.Post)('demo-func'),
+    __param(0, (0, tsoa_1.Body)())
+], DemoService.prototype, "demoFunc", null);
+DemoService = __decorate([
+    (0, tsoa_1.Route)('demo'),
+    (0, tsoa_1.Tags)('Demo')
+], DemoService);
+exports.default = DemoService;

package/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/bff/modules/demo/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/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/bff/modules/example/service.js

@@ -0,0 +1,89 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExampleService = void 0;
+const tsoa_1 = require("tsoa");
+const BaseService_1 = __importDefault(require("../BaseService"));
+/**
+ * ExampleService - 演示如何创建服务模块
+ * 此服务提供用户资料和订单管理的示例方法
+ */
+let ExampleService = class ExampleService extends BaseService_1.default {
+    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);
+    }
+};
+exports.ExampleService = ExampleService;
+__decorate([
+    (0, tsoa_1.OperationId)('获取用户资料'),
+    (0, tsoa_1.Post)('get-user-profile'),
+    __param(0, (0, tsoa_1.Body)())
+], ExampleService.prototype, "getUserProfile", null);
+__decorate([
+    (0, tsoa_1.OperationId)('更新用户资料'),
+    (0, tsoa_1.Post)('update-profile'),
+    __param(0, (0, tsoa_1.Body)())
+], ExampleService.prototype, "updateProfile", null);
+__decorate([
+    (0, tsoa_1.OperationId)('获取订单列表'),
+    (0, tsoa_1.Post)('get-order-list'),
+    __param(0, (0, tsoa_1.Body)())
+], ExampleService.prototype, "getOrderList", null);
+exports.ExampleService = ExampleService = __decorate([
+    (0, tsoa_1.Route)('api/v1/user'),
+    (0, tsoa_1.Tags)('User')
+], ExampleService);

package/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/bff/modules/example/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/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/bff/request/client.js

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