@builder6/services 3.2.1 → 3.2.12

package/README.md

@@ -1,21 +1,182 @@
-# Builder6 Email Module
+# Builder6 Services Module
 
+Builder6 Services 模块为 Builder6 框架提供通用的 Moleculer 微服务 API 网关。它通过统一的 HTTP 端点允许经过身份验证的管理员动态调用任意 Moleculer 微服务和操作，是 HTTP 客户端与内部 Moleculer 服务网格之间的桥梁。
 
-## Environment Variables
+## 功能特性
 
-```shell
-B6_EMAIL_FROM=Steedos <noreply@steedos.com>
-B6_EMAIL_HOST=email.xxxx.amazonaws.com
-B6_EMAIL_PORT=465
-B6_EMAIL_USERNAME=xxxxx
-B6_EMAIL_PASSWORD=xxxxx
-B6_EMAIL_SECURE=false
-B6_EMAIL_DEBUG=true
-B6_EMAIL_LOGGER=true
+- **通用服务调用**: 通过 REST API 调用任意 Moleculer 服务和操作
+- **动态路由**: 根据服务名和操作名动态路由请求
+- **参数传递**: 支持查询参数和请求体参数
+- **权限控制**: 所有操作都需要管理员权限保护
+- **微服务集成**: 与 Builder6 的 Moleculer 微服务生态系统无缝集成
+- **灵活调用**: 无需为每个服务创建专门的 HTTP 端点
+
+## 安装
+
+```bash
+npm install @builder6/services
+```
+
+或
+
+```bash
+yarn add @builder6/services
+```
+
+## 主要 API
+
+### 服务调用端点
+
+**POST `/api/v6/services/:serviceName/:actionName`**
+
+通过 HTTP 调用任意 Moleculer 服务操作。
+
+- `serviceName`: Moleculer 服务名称
+- `actionName`: 服务操作名称
+- 查询参数和请求体都会作为操作参数传递
+
+## 使用示例
+
+### 在 NestJS 应用中集成
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ServicesModule } from '@builder6/services';
+
+@Module({
+  imports: [ServicesModule],
+})
+export class AppModule {}
 ```
 
-## 配置定时发送
+### 调用 Moleculer 服务
+
+假设有一个名为 `users` 的 Moleculer 服务，包含 `list` 操作：
 
+```bash
+# 调用 users.list 操作
+curl -X POST http://localhost:5100/api/v6/services/users/list \
+  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "limit": 10,
+    "offset": 0
+  }'
 ```
-STEEDOS_CRON_MAILQUEUE_INTERVAL=3000 # 邮件定时器，单位：毫秒
-```
+
+### 调用带查询参数的服务
+
+```bash
+# 使用查询参数
+curl -X POST "http://localhost:5100/api/v6/services/users/get?id=12345" \
+  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"
+```
+
+### 调用数据处理服务
+
+```bash
+# 调用数据转换服务
+curl -X POST http://localhost:5100/api/v6/services/dataprocessor/transform \
+  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "input": "raw data",
+    "format": "json"
+  }'
+```
+
+## 架构说明
+
+### MoleculerApiService
+
+核心服务类，继承自 Moleculer 的 `Service` 类：
+
+```typescript
+import { MoleculerApiService } from '@builder6/services';
+
+// 服务提供 call() 方法来调用其他服务
+async callService(serviceName: string, actionName: string, params: any) {
+  return await this.moleculerApiService.call(
+    `${serviceName}.${actionName}`,
+    params
+  );
+}
+```
+
+### MoleculerApiController
+
+HTTP 控制器，将 REST 请求转换为 Moleculer 服务调用：
+
+- 从 URL 路径提取服务名和操作名
+- 合并查询参数和请求体作为服务参数
+- 通过 MoleculerApiService 调用目标服务
+- 返回服务响应给客户端
+
+## 权限控制
+
+所有 API 端点都受 `AdminGuard` 保护，确保只有管理员用户才能通过 HTTP 调用 Moleculer 服务。这提供了一个安全的服务访问层。
+
+## 使用场景
+
+### 1. 后台管理界面
+
+为管理员提供调用后端微服务的能力，无需为每个服务单独创建 HTTP 端点。
+
+### 2. 服务编排
+
+通过 HTTP 接口组合多个微服务调用，实现复杂的业务流程。
+
+### 3. 快速原型开发
+
+快速暴露 Moleculer 服务为 HTTP API，加速原型开发和测试。
+
+### 4. 第三方集成
+
+为外部系统提供标准的 REST API 访问内部微服务的能力。
+
+## 集成的模块
+
+- **AuthModule** (from `@builder6/core`): 提供认证和授权功能
+- **MongodbModule** (from `@builder6/core`): 提供数据库访问
+- **ServiceBroker** (from `@builder6/moleculer`): Moleculer 服务代理
+
+## 依赖项
+
+### Peer Dependencies
+
+- `@builder6/core`: ^3.0.10 - 核心功能模块
+- `@builder6/moleculer`: ^3.0.10 - Moleculer 微服务框架
+- `@nestjs/common`: ^11.0.0 - NestJS 核心
+- `@nestjs/core`: ^11.0.0 - NestJS 核心
+- `@nestjs/swagger`: ^11.0.7 - API 文档
+
+## 开发
+
+### 构建
+
+```bash
+npm run build
+```
+
+### 监听模式
+
+```bash
+npm run build:watch
+```
+
+### 格式化代码
+
+```bash
+npm run format
+```
+
+## 安全注意事项
+
+1. **仅限管理员访问**: 此模块允许调用任意微服务，必须严格限制为管理员使用
+2. **参数验证**: 在 Moleculer 服务层进行参数验证，不要信任来自 HTTP 的输入
+3. **审计日志**: 建议记录所有服务调用以进行审计
+4. **速率限制**: 考虑在生产环境中添加速率限制
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder6/services",
-  "version": "3.2.1",
+  "version": "3.2.12",
   "main": "dist/plugin.module.js",
   "license": "MIT",
   "files": [
@@ -21,5 +21,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "da86657f07eb4bf3124bb090c6bc1b76b2cebeb0"
+  "gitHead": "6d6e13fed8d4b3c6de14f84dcb6287c5661ea6f6"
 }