site logo

Marico's space

site logo

Marico's space

首页
我的日志
我的游记
世界·视野
编程技术

技术合作:

look@marico.cc

+86 18660050334

 

使用 Candy-Nest-CLI 构建生产就绪的 NestJS 微服务架构 🍬

前端技术 2026-05-19 11:31:04 1

最近折腾 NestJS 微服务，发现每次新建项目都要重复配置一堆基础设施：Docker 环境、数据库连接、消息队列、日志系统……光这些准备工作就够磨半天性子了。正好手头写了个脚手架工具 Candy-Nest-CLI，把这些流程自动化了，这篇把踩坑经历和工具用法说清楚。

用 NestJS 写微服务的同学应该都清楚，这框架确实结构清晰、功能强大。但每次新起一个服务，前期配置的工作量并不少：

  • 本地数据库的 docker-compose.yml 要从头写
  • TypeORM、Prisma 或者 Mongoose 要一套配置
  • Kafka 或者 RabbitMQ 消息队列要对接
  • 本地环境启动时各种依赖顺序问题
  • 日志和监控要接入

等你真正开始写业务逻辑，大把时间已经花在脚手架上了。

与其让 AI 帮你生成这些配置（一个项目轻松烧掉 3000 到 5000+ 的 token，还不算调试配置错误吃掉上下文窗口的损耗），不如用这个 CLI 直接跳过这些重复劳动，把 token 用在真正的业务代码上。

所以我写了这个 Candy-Nest-CLI——一个开源的交互式脚手架工具，专门用来生成生产就绪的 NestJS 微服务。

🛠️ 构建服务：一步一步来

从头走一遍，看看用这个 CLI 起一个带 PostgreSQL 数据库和 Kafka 消息队列的后端服务有多简单。

第一步：安装与初始化

CLI 可以全局安装，也可以直接在线跑。

方式一：全局安装（推荐）
打开终端，执行：

# 使用 npm
npm install -g candy-nest-cli # 或者用 yarn
yarn global add candy-nest-cli

安装完成后，运行命令生成新项目：

candy-nest-cli init user-service

方式二：用 npx 免安装
不想全局安装的话，直接跑：

npx candy-nest-cli init user-service

第二步：选择你的技术栈

CLI 使用 @inquirer/prompts 引导你完成详细的配置流程。我们给目标微服务这样配置：

  1. 项目名称是什么？ user-service
  2. 使用哪个包管理器？ npm
  3. 选择要支持的通信协议： REST
  4. 使用哪个 HTTP 适配器？ Express
  5. 是否包含数据库？ 是
  6. 选择要包含的数据库： PostgreSQL（关系型数据库）
  7. PostgreSQL 用哪个 ORM？ TypeORM
  8. 是否配置消息队列？ 是
  9. 使用哪个消息队列？ Kafka
  10. 是否配置死信队列（DLQ）和重试机制？ 是
  11. 是否包含 Redis 缓存？ 是
  12. 配置哪个日志工具？ Pino
  13. 选择哪个链路追踪和指标方案？ Prometheus
  14. 是否生成 API 文档（Swagger）？ 是
  15. 是否包含熔断器（Opossum）？ 是

1. 包管理器选择

选择你喜欢的包管理器（npm、yarn 或 pnpm）。我们选 npm。

Package Manager Selection

2. 协议选择

选择微服务要支持的通信协议。CLI 支持多协议组合：REST、GraphQL、gRPC 和 WebSockets。我们选 REST 做标准 HTTP 路由。

Protocol Selection

3. HTTP 适配器选择

在 Express（业界标准）和 Fastify（高性能）之间选择。我们选 Express 确保最大兼容性。

Adapter Selection

4. 数据库集成

选择是否包含数据库模块。我们选 是 来配置持久化。

Database Option Selection

5. 数据库选型

选择使用哪个数据库（PostgreSQL、MySQL 或 MongoDB）。我们选 PostgreSQL 做健壮的关系型数据库管理。

Database Choice Selection

6. ORM 选择

选择你偏好的 ORM。CLI 支持 TypeORM 或 Prisma 用于 SQL 数据库。我们选 TypeORM。

ORM Selection

7. 消息队列集成

选择是否配置事件驱动的消息队列。我们选 是。

Queue Option Selection

8. 队列选型

在 Kafka、RabbitMQ 和 BullMQ 之间选择消息代理。我们选 Kafka 来构建事件驱动的流处理微服务。

Queue Choice Selection

9. 死信队列和重试机制

选择是否配置带死信队列（DLQ）和自定义重试循环的健壮消息处理，确保开箱即用的事件韧性。我们选 是。

DLQ Prompt Selection

10. Redis 缓存

选择是否设置 Redis 作为高速内存分布式缓存。我们选 是。

Redis Prompt Selection

11. 日志选择

选择日志方案（Winston、Pino 或默认的 NestJS 日志）。我们选 Pino 做高速 JSON 日志记录。

Logger Selection

12. 可观测性与链路追踪

选择可观测性技术栈（Prometheus 或 OpenTelemetry）。我们将配置 Prometheus 指标。

Observability Selection

13. API 文档

选择是否需要功能完整的自动生成 Swagger 文档来记录 REST API。我们选 是。

Swagger Prompt Selection

14. 熔断器

启用基于 Opossum 的熔断器，保护你的对外 HTTP 请求和 RPC 调用免受下游故障影响。我们选 是。

Circuit Breaker Prompt Selection

确认最终选择后，CLI 会输出进度，自动生成文件、写入配置并安装依赖。

Generation Progress Scaffolding Complete

默认选项与极致灵活

candy-nest-cli 设计了合理的默认选项，大多数情况下一直回车就能快速完成。在我们的教程中，只定制了几个选项（比如选了 Pino 做更快的日志记录，启用了 Kafka 的死信队列）。

我们的选择和 CLI 的默认设置、其他替代集成的对比如下：

选项 教程中选择 默认预设 其他选择
包管理器 npm npm yarn, pnpm
协议 REST [REST] GraphQL, gRPC, WebSockets
HTTP 适配器 Express Express Fastify
数据库 PostgreSQL（关系型数据库） PostgreSQL MySQL, MongoDB
SQL ORM TypeORM TypeORM Prisma
消息队列 Kafka Kafka RabbitMQ, BullMQ
死信队列和重试 是（已定制） 否 否
Redis 缓存 是 是 否
日志工具 Pino（已定制） Winston Winston, 无
可观测性 Prometheus Prometheus OpenTelemetry, 无
Swagger API 文档 是 是 否
熔断器 是 是 否

第三步：启动基础设施

CLI 生成代码完成后，所有基础设施都已就绪，不需要从头写 Docker 文件。

cd user-service
cp .env.example .env
docker-compose up -d
npm run start:dev

由于 CLI 脚手架的方式，Kafka 以 KRaft 模式启动，带有特殊的初始化容器。你会看到 Postgres、Redis 和 Kafka 都完美启动，没有任何竞态条件。

Docker Compose Up

第四步：运行应用

基础设施运行后，直接启动 NestJS 应用：

npm run start:dev
NestJS Startup Logs

就这样，一个生产就绪的微服务在 2 分钟内就跑起来了。

注意：启动时可能会遇到 kafka-topic 相关的错误，稍等几秒后重启应用即可解决，topic 会被自动创建。你也可以进入 Docker 容器手动创建 topic。

🌐 交互式开发者 Playground

如果启用了 Swagger API 文档或 GraphQL，CLI 会预配置并暴露丰富的交互式 Playground，让你立即执行和测试操作：

Swagger API Playground（REST）

访问自动生成的 Swagger UI：http://localhost:3000/api/docs，查看你的 REST 端点、数据库 CRUD 示例和健康检查。

Swagger API Documentation

Apollo Sandbox Playground（GraphQL）

如果启用了 GraphQL，打开 http://localhost:3000/graphql 查看 Apollo Sandbox，可以运行查询、检查 schema 和测试 mutations。

Apollo GraphQL Sandbox

🏗️ 到底生成了什么？

candy-nest-cli 只动态生成你选择的功能模块。

看一下刚才构建的服务的项目结构：

Generated Project Structure 
user-service/
├── dist/
├── logs/
├── node_modules/
├── src/
│ ├── database/ # 数据库配置和连接模块
│ ├── examples/ # REST CRUD 数据库示例
│ ├── graphql/ # GraphQL 解析器和 schema 设置
│ ├── grpc/ # gRPC 控制器和服务实现
│ ├── health/ # Terminus 健康指标
│ ├── kafka/ # Kafka 微服务控制器和提供者
│ ├── logger/ # Pino/Winston 日志配置
│ ├── redis/ # Redis 缓存模块和服务
│ ├── resiliency/ # 熔断器（Opossum）配置
│ ├── websockets/ # WebSockets 网关和适配器
│ ├── app.controller.spec.ts
│ ├── app.controller.ts
│ ├── app.module.ts
│ ├── app.service.ts
│ ├── app.throttler.guard.ts # 跨协议限流守卫
│ ├── main.ts # 微服务混合引导器（HTTP、gRPC、Kafka）
│ └── schema.gql # 自动生成的 GraphQL schema
├── test/ # E2E 测试套件
├── .env
├── .env.example
├── .prettierrc
├── docker-compose.yml # 本地开发栈（PostgreSQL、Kafka、Redis）
├── Dockerfile # 多阶段生产构建定义
├── eslint.config.mjs
├── nest-cli.json
├── package-lock.json
├── package.json
├── README.md
├── tsconfig.build.json
└── tsconfig.json

完整的代码模块

  • 数据库：生成 database.module.ts，注入 ConfigService，创建示例 Entity 或 Schema。
  • 消息代理：脚手架微服务传输层，包括客户端发布者和消费事件的控制器装饰器。
  • 测试套件：为每个选中的模块生成完整的单元测试（.spec.ts）（包括数据库服务、Kafka 生产者/消费者、Pino 日志和 Redis）。还包含专门的回归 E2E 测试文件（regression.e2e-spec.ts），让你可以直接跑 npm run test！
  • API 文档：因为选了 REST，Swagger 自动接入到 main.ts！

🚀 快速启动备忘单

启动新的交互式项目：

npx candy-nest-cli init my-awesome-microservice

跳过交互提示，直接生成所有功能（Kitchen Sink 模式）：

npx candy-nest-cli init my-kitchen-sink-service --all

向现有 CLI 生成的项目添加新功能：

npx candy-nest-cli add

为什么选 Candy-Nest-CLI？

NestJS 生态很棒，但在大型微服务架构中保持一致性有时候挺让人头疼的。

这个 CLI 的目标是提供一种标准化、快速的方式来启动服务，从第一天起就遵循常见最佳实践。

如果你用 NestJS，可以试试看。我正在积极维护，欢迎反馈和贡献！

  • 📦 NPM：https://www.npmjs.com/package/candy-nest-cli
  • ⭐ GitHub：https://github.com/knight-koder/candy-cli

有什么想法欢迎留言讨论。Happy coding! 🚀

原文链接：https://dev.to/knight_koder/production-ready-nestjs-microservice-setup-with-candy-nest-cli-4bl5