Builder6 Services Module

Builder6 Services 模块为 Builder6 框架提供通用的 Moleculer 微服务 API 网关。它通过统一的 HTTP 端点允许经过身份验证的管理员动态调用任意 Moleculer 微服务和操作，是 HTTP 客户端与内部 Moleculer 服务网格之间的桥梁。

功能特性

• 通用服务调用: 通过 REST API 调用任意 Moleculer 服务和操作
• 动态路由: 根据服务名和操作名动态路由请求
• 参数传递: 支持查询参数和请求体参数
• 权限控制: 所有操作都需要管理员权限保护
• 微服务集成: 与 Builder6 的 Moleculer 微服务生态系统无缝集成
• 灵活调用: 无需为每个服务创建专门的 HTTP 端点

安装

npm install @builder6/services

或

yarn add @builder6/services

主要 API

服务调用端点

POST /api/v6/services/:serviceName/:actionName

通过 HTTP 调用任意 Moleculer 服务操作。

• serviceName: Moleculer 服务名称
• actionName: 服务操作名称
• 查询参数和请求体都会作为操作参数传递

使用示例

在 NestJS 应用中集成

import { Module } from '@nestjs/common';
import { ServicesModule } from '@builder6/services';

@Module({
  imports: [ServicesModule],
})
export class AppModule {}

调用 Moleculer 服务

假设有一个名为 users 的 Moleculer 服务，包含 list 操作：

# 调用 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
  }'

调用带查询参数的服务

# 使用查询参数
curl -X POST "http://localhost:5100/api/v6/services/users/get?id=12345" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

调用数据处理服务

# 调用数据转换服务
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 类：

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 文档

开发

构建

npm run build

监听模式

npm run build:watch

格式化代码

npm run format

安全注意事项

1. 仅限管理员访问: 此模块允许调用任意微服务，必须严格限制为管理员使用
2. 参数验证: 在 Moleculer 服务层进行参数验证，不要信任来自 HTTP 的输入
3. 审计日志: 建议记录所有服务调用以进行审计
4. 速率限制: 考虑在生产环境中添加速率限制

License

MIT