开发

添加新服务

1. 创建 types.ts 文件

   # 在模块目录下创建 types.ts
   # 例如：src/bff/modules/product/types.ts

2. 生成服务代码

   # ⚠️ 必须在 packages/sdk 目录下运行
   cd packages/sdk
   npm run generate product

EcommerceBffService SDK

EcommerceBffService Node.js SDK - 统一的 SDK，支持 Web 和微信小程序

特性

• ✅ 统一的 SDK 架构：所有服务模块在同一级别
• ✅ 统一命名空间结构：与后端 SDK 保持一致的类型定义
• ✅ 自动生成 Swagger 文档：使用 tsoa 自动生成 OpenAPI 3.0 文档
• ✅ 双模块格式支持：同时支持 ESM 和 CommonJS，兼容 Vite、Webpack 等现代构建工具
• ✅ 编译时装饰器移除：使用 TypeScript transformer 在编译时移除 tsoa 装饰器，前端零依赖
• ✅ 多平台支持：自动检测并适配 Web/H5 和微信小程序环境
• ✅ 类型安全：完整的 TypeScript 类型定义
• ✅ 标准响应格式：统一的 StandardResponse<T> 响应结构

安装

npm install @be-link/ecommerce-bff-service-node-sdk

使用

Web 应用

import { EcommerceBffSDK } from '@be-link/ecommerce-bff-service-node-sdk'

const sdk = new EcommerceBffSDK({
  getToken: async () => localStorage.getItem('token') || '',
  getUserId: async () => localStorage.getItem('userId') || '',
  getRoleId: async () => localStorage.getItem('roleId') || '',
  environment: 'production'
})

// 使用服务
const result = await sdk.example.getExampleData({ id: '123' })

微信小程序

import { EcommerceBffSDK } from '@be-link/ecommerce-bff-service-node-sdk'

const sdk = new EcommerceBffSDK({
  getToken: async () => wx.getStorageSync('token') || '',
  getUserId: async () => wx.getStorageSync('userId') || '',
  getRoleId: async () => wx.getStorageSync('roleId') || '',
  environment: 'production'
})

// 使用小程序服务
const result = await sdk.demo.getDemoData({ page: 1 })

旧版本兼容（不推荐）

import { EcommerceBffSDK } from '@be-link/ecommerce-bff-service-node-sdk'

// ⚠️ 旧版 SDK
const sdk = new EcommerceBffSDK({
  getToken: async () => localStorage.getItem('token') || '',
  getUserId: async () => localStorage.getItem('userId') || '',
  getRoleId: async () => localStorage.getItem('roleId') || '',
  environment: 'production'
})

// 使用服务
const result = await sdk.demo.demoFunc({ demoParam: 'test' })
console.log(result.data)       // 业务数据
console.log(result.message)    // 响应消息
console.log(result.requestId)  // 请求 ID

微信小程序环境

import { EcommerceBffSDK } from '@be-link/ecommerce-bff-service-node-sdk'

const sdk = new EcommerceBffSDK({
  getToken: async () => wx.getStorageSync('token') || '',
  getUserId: async () => wx.getStorageSync('userId') || '',
  getRoleId: async () => wx.getStorageSync('roleId') || '',
  environment: 'test'
})

// 使用服务
const result = await sdk.example.getUserProfile({ id: 'user123' })

使用类型定义

import { 
  EcommerceBffSDK,
  DemoTypes,
  ExampleTypes 
} from '@be-link/ecommerce-bff-service-node-sdk'

// 使用命名空间类型
type DemoRequest = DemoControllerTypes.Request.demoFunc
type DemoResponse = DemoControllerTypes.Response.demoFunc

type UserProfile = ExampleServiceTypes.Response.getUserProfile

开发

添加新服务

1. 创建 types.ts 文件

   # 在模块目录下创建 types.ts
   # 例如：src/bff/modules/product/types.ts

2. 生成服务代码

   # ⚠️ 必须在 packages/sdk 目录下运行
   cd packages/sdk
   npm run generate product

其他命令

# 构建
npm run build

# 生成 Swagger 文档
npm run swagger

# 构建并生成文档
npm run build:swagger

# 运行测试
npm test

详细的生成器使用说明请查看：Generator README

文档

• 目录结构说明 - 项目目录结构和组织方式
• 架构说明 - 系统架构和设计理念
• Swagger 文档 - API 文档生成和使用指南
• 类型兼容性 - 类型定义和兼容性说明
• SDK vs Server - SDK 和 Server 的区别
• TSOA Transformer - TypeScript 装饰器移除机制说明

API 文档

生成的 Swagger 文档位于 dist/swagger.json，可以使用以下方式查看：

1. Swagger UI：

npm install -g swagger-ui-watcher
swagger-ui-watcher packages/sdk/dist/swagger.json

2. 在线工具：访问 Swagger Editor 并导入 swagger.json

3. VS Code 插件：安装 Swagger Viewer

添加新服务

查看 DIRECTORY_STRUCTURE.md 了解如何添加新的服务模块。

License

ISC