Moleculer 微服务框架上手指南：核心概念、首个服务示例与项目脚手架

• 后端
• RPC框架
• 服务注册发现

Moleculer 是面向 Node.js 的快速、现代且功能强大的微服务框架，本指南以其官方 README 为核心，结合仓库源码（src、examples）深入讲解框架的核心设计、安装方式、第一个服务的编写与调用、基于 CLI 的项目脚手架搭建，以及内建的能力矩阵。读完本文，你将具备独立创建一个 Moleculer 微服务项目、编写并调用服务 Action、并根据需求选型传输器、缓存、日志、序列化器等组件的能力。

本仓库当前版本为 0.15.1（见 package.json），要求 Node.js >= 22.x。

Moleculer 是什么

Moleculer 是一个基于 Promise 的微服务框架，天然兼容async/await。它帮助你构建高效、可靠且可水平扩展的分布式服务集群。与部分“主从式”微服务框架不同，Moleculer 采用无主（master-less）架构——集群中所有节点地位平等，没有中心协调节点，服务注册表（Service Registry）在每个节点上以分布式的方式同步维护。

这一设计体现在源码结构中：核心入口 index.js 导出ServiceBroker、Service、Context、Transit、Registry、Cachers、Transporters、Serializers、Strategies、Middlewares、Errors等全部核心构件，任何功能都可以按需取用。

框架围绕几个核心抽象展开：

• ServiceBroker：框架的心脏，负责管理服务、处理调用、维护集群状态；
• Service：一个业务单元的载体，内部由一组 Action（可远程调用的方法）与 Event（事件处理）构成；
• Context：一次调用的上下文对象，携带参数、元数据、调用链信息等；
• Transit：节点间通信的传输层，抽象了各类 Transporter；
• Registry：服务与节点的注册发现中心，配合负载均衡策略分发请求。

框架功能全景（What's included）

README 明确列出了框架内建的能力，这些特性在 src 目录中均有对应实现，可逐一对照：

• Promise 化与 async/await 兼容：broker 的start()、call()、stop()等核心方法全部返回 Promise，见 service-broker.js 中start()的链式实现；
• request-reply 请求-响应模型：通过broker.call()发起同步远程调用；
• 支持带负载均衡的事件驱动架构：事件可广播到多个节点，并按策略均衡消费；
• 内建服务注册表与动态服务发现：由 registry 模块实现；
• 负载均衡的请求与事件分发：内置 round-robin、random、cpu-usage、latency、sharding 五种策略（见 src/strategies 与 endpoint-list.js 中的策略选择逻辑）；
• 丰富的容错能力：Circuit Breaker（熔断）、Bulkhead（舱壁隔离）、Retry（重试）、Timeout（超时）、Fallback（降级）；
• 插件 / 中间件系统：内置中间件清单见 middlewares/index.js，涵盖熔断、超时、重试、缓存、校验、指标、追踪、防抖、节流、热重载、加密压缩与调试日志等；
• 版本化服务支持：同一服务可发布多个版本，便于灰度发布；
• Streams 流式传输支持：可传递 Node.js 流对象；
• 服务 Mixin 混入机制：实现代码复用；
• 内建缓存方案：Memory、MemoryLRU、Redis（src/cachers）；
• 可插拔日志器：Console、File、Pino、Bunyan、Winston、Debug、Datadog、Log4js（src/loggers）；
• 可插拔传输器：TCP、NATS、MQTT、Redis、Kafka、AMQP 0.9、AMQP 1.0（src/transporters）；
• 可插拔序列化器：JSON、JSONExt、MsgPack、CBOR、Notepack（src/serializers）；
• 可插拔参数校验器：默认内置基于 fastest-validator）；
• 单个节点 / 服务器上可运行多个服务：一个 broker 进程可注册任意多个服务；
• 内建 Metrics 指标功能：Console、CSV、Datadog、Event、Prometheus、StatsD 报告器（src/metrics）；
• 内建 Tracing 追踪功能：Console、Datadog、Event、Jaeger、Zipkin、NewRelic 导出器（src/tracing/exporters）。

此外还有官方的 API 网关（moleculer-web）、数据库访问（moleculer-db）等模块生态，可通过官方模块列表页进一步查阅。

安装 Moleculer

Moleculer 通过 npm 或 yarn 安装，使用任意包管理器执行其一即可：

$ npm i moleculer

或

$ yarn add moleculer

安装后，框架以 CommonJS 为默认模块形式（"type": "commonjs"，见 package.json），同时通过exports字段同时提供require（index.js）与import（index.mjs）两种入口，ESM 环境下可直接import使用。仓库中还提供了 ESM 运行器moleculer-runner-esm（bin/moleculer-runner.mjs）与 ESM 示例（examples/esm、test/esm）。

创建你的第一个微服务

README 给出了一个经典的入门示例：创建一个包含addAction（可将两个数字相加）的服务，并调用它。以下为完整代码：

const { ServiceBroker } = require("moleculer"); // 创建 broker const broker = new ServiceBroker(); // 创建服务 broker.createService({ name: "math", actions: { add(ctx) { return Number(ctx.params.a) + Number(ctx.params.b); } } }); // 启动 broker broker.start() // 调用服务 .then(() => broker.call("math.add", { a: 5, b: 3 })) .then(res => console.log("5 + 3 =", res)) .catch(err => console.error(`Error occurred! ${err.message}`));

执行后控制台将输出5 + 3 = 8。这段代码虽然简短，却完整走过了微服务框架的四个核心阶段：创建 broker → 注册服务 → 启动 → 调用。

关键 API 的源码级解读

new ServiceBroker(options)：构造函数（见 service-broker.js）负责组装框架的全部子系统。从源码可以看到，构造阶段会依次完成：合并默认配置、初始化日志工厂、创建 Metrics 注册表、加载中间件处理器、初始化服务注册表、解析并初始化 Cacher（缓存器）、Serializer（序列化器）、Validator（校验器）、Tracer（追踪器），并依据transporter配置创建 Transit 传输层。因此即使不做任何配置，new ServiceBroker()也会带上完整的本地能力——只是默认不启用网络传输（transporter: null）。

broker.createService(schema)：注册一个服务，服务名（name）与 Action 名称一起组成全局唯一的调用名，例如math.add。仓库中的 examples/math.service.js 展示了更完整的服务定义：一个 Action 可以简写为add(ctx) { ... }这样的函数，也可以扩展为{ params: {...}, handler(ctx) {...} }对象形式，为 Action 声明参数校验规则。例如div使用params: { a: { type: "number", convert: true }, b: { type: "number", notEqual: 0, convert: true } }，既校验类型又禁止除数为零，体现内建校验器的用法。

broker.start()：启动过程在 service-broker.js 中完整呈现，典型调用链为：触发starting中间件钩子 → 连接 Transit（若配置了传输器）→ 启动所有已注册服务的started生命周期 → 广播$broker.started内部事件 → 触发started中间件钩子。它返回 Promise，这正是示例中broker.start().then(...)链式调用的来源。

broker.call(actionName, params, opts)：调用逻辑见 service-broker.js。源码显示，call()会先创建（或复用）一个Context，然后通过findNextActionEndpoint()结合负载均衡策略选出目标端点（本地节点或远程节点），最后执行ctx.endpoint.action.handler(ctx)并返回 Promise。也就是说，对调用方而言，本地调用与远程调用的 API 完全一致——框架在内部完成路由与分发，这是 Moleculer“透明 RPC”的核心体验。

一个可运行的完整变体

仓库中的 examples/simple/index.js 提供了上述示例的“多 Action 版本”，并演示了错误处理与异常携带的上下文信息：

const ServiceBroker = require("../../src/service-broker"); const broker = new ServiceBroker({ logger: console, transporter: null }); broker.loadService(__dirname + "/../math.service.js"); broker .start() .then(() => broker.call("math.add", { a: 5, b: 3 })) .then(res => broker.logger.info(" 5 + 3 =", res)) .then(() => broker.call("math.div", { a: 5, b: 0 })) .catch(err => { broker.logger.error(`Error occurred! Action: '${err.ctx.action.name}', Message: ${err.code} - ${err.message}`); });

注意其中两点：一是通过logger: console将日志直接输出到控制台；二是当math.div触发“除零”错误时，err.ctx中携带了触发该错误的 Action 名称与调用参数（异常由 src/errors 中的MoleculerError抛出，见 math.service.js），便于错误定位。

创建完整的 Moleculer 项目

手写服务固然简单，但生产级项目往往需要标准的目录结构、开发环境与样板代码。Moleculer 官方提供了 CLI 脚手架工具moleculer-cli，只需四步即可搭建一个开箱即用的项目：

1. 创建新项目（项目名moleculer-demo）：

$ npx moleculer-cli -c moleculer init project moleculer-demo

其中-c moleculer指定项目模板（moleculer 默认模板），init project <name>为初始化命令。

2. 进入项目目录：

$ cd moleculer-demo

3. 启动项目：

$ npm run dev

dev脚本通常以开发模式运行（nodemon 热重载），代码变更后服务自动重启，非常适合开发迭代。

4. 打开欢迎页：浏览器访问 http://localhost:3000/，页面会展示项目信息，并可直接在网页上测试脚手架生成的服务。

至此，你的第一个基于 Moleculer 的微服务项目已创建完成。脚手架会生成 broker 配置、服务目录、API 网关等标准结构，后续可在此基础上按业务扩展。

与脚手架项目对应的可运行配置，仓库中亦有若干参照：

• 简单多服务示例：examples/index.js（含 math.service.js、user.service.js 等）；
• 客户端-服务端分离调用：examples/client-server/client.js 与 examples/client-server/server.js；
• Docker 化部署：完整配置见 examples/docker，其中客户端与工作节点各有独立的 moleculer.config.js，并通过 docker-compose.yml 编排；
• 多节点集群：节点脚本与编排见 examples/multi-nodes；
• TypeScript 项目：examples/typescript（含tsconfig.json与index.ts、mixin.ts）；
• ESM 项目：examples/esm（含.mjs与.cjs配置/服务文件）。

框架源码结构速览

要在真实项目中用好 Moleculer，理解源码布局会事半功倍。本仓库 src 目录即框架全部实现，核心模块如下：

其中负载均衡策略的选择发生在注册表层：EndpointList构造时实例化策略，select()时调用this.strategy.select(list, ctx)选出下一个端点（见 endpoint-list.js），而具体使用哪种策略既可在 broker 全局配置，也可通过strategy/strategyOptions按 Action 或事件单独指定（见 action-catalog.js 与 event-catalog.js）。

测试与验证

仓库自带完善的测试体系，可用于验证框架行为、作为二次开发的参照：

• 单元测试：test/unit 覆盖各模块，例如 service-broker.spec.js、transit.spec.js、各传输器 / 缓存 / 策略的*.spec.js；
• 集成测试：test/integration 覆盖多服务协作、熔断、事件均衡、流式传输、追踪等场景；
• 端到端测试：test/e2e 通过 start.sh 启动多节点真实集群场景（如 test/e2e/scenarios/balancing）；
• 类型测试：test/typescript/tsd 使用tsd校验 TypeScript 类型定义。

从 package.json 的 scripts 可以看到对应的运行命令，例如单元测试npm run test:unit、集成测试npm run test:int、类型测试npm run test:ts、代码规范npm run lint。

官方文档、变更记录与安全

• 完整文档：Moleculer 的官方文档站点提供了从基础到进阶的完整指南，是深入学习每个配置项与中间件的首选；
• 变更记录：本仓库的 CHANGELOG.md 记录了各版本的功能演进与破坏性变更；针对 0.13 / 0.14 / 0.15 的升级指引见 docs 目录下的三份 MIGRATION_GUIDE 文档；
• 安全报告：若发现安全漏洞，请按 SECURITY.md 中的指引通过 Tidelift 安全联系渠道上报，由维护者协调修复与披露；
• 贡献指南：参与开发前请阅读 CONTRIBUTING.md，并遵循仓库的 eslint 与 prettier 配置。

Moleculer 采用 MIT 许可证，可自由用于个人或商业项目。从“几行代码启动一个服务”到“数十节点的高可用集群”，Moleculer 提供的 request-reply、事件驱动、服务发现、负载均衡、容错与可观测性能力，足以支撑一套渐进式演进的微服务架构——这也正是其官方定位“Progressive microservices framework”的题中之义。

• 后端
• RPC框架
• 服务注册发现