AI 全栈指南：NestJs 中的 Service Provider 和 Module

大家好 👋，我是 Moment，目前正在使用 Next.js、NestJS、LangChain 开发 DocFlow。这是一个面向 AI 场景的协同文档平台，集成了基于 Tiptap 的富文本编辑、NestJS 后端服务、实时协作与智能化工作流等核心模块。

在这个项目的持续打磨过程中，我积累了不少实战经验，不只是 Tiptap 的深度定制、编辑器性能优化和协同方案设计，也包括前端工程化建设、React 源码理解以及复杂项目架构实践。

如果你对 AI 全栈开发、Agent、长期记忆、文档编辑器、前端工程化或者 React 源码相关内容感兴趣，欢迎添加我的微信 yunmz777 一起交流。觉得项目还不错的话，也欢迎给 DocFlow 点个 star ⭐

上一节里，Controller 负责接请求、取参数、返回结果。真正撑起接口价值的，多半不是"把请求接进来"，而是背后的业务逻辑。

这段逻辑默认放在 Service 里。

先把 Service 想成"业务处理层"。它不太关心路由怎么对齐，也不太关心这次是 GET 还是 POST，更常琢磨的是下面这些：

数据怎么查、怎么写
规则怎么判定
结果怎么拼装
同一套逻辑别处还要不要复用

拿创建用户来说，麻烦往往不在收参数，而在查重、密码策略、默认状态、要不要发欢迎邮件。这些都更适合收紧 Service，而不是摊在控制器里。

下面的 UsersService 只在内存里摆个数组示意，重点看职责怎么收拢：

typescript 复制代码

import { Injectable } from "@nestjs/common";

/** 内存里的用户结构，仅作示意 */
interface User {
  id: string;
  name: string;
}

@Injectable()
export class UsersService {
  private readonly users: User[] = [
    { id: "1", name: "汤姆" },
    { id: "2", name: "杰瑞" },
  ];

  /** 返回全部用户 */
  findAll(): User[] {
    return this.users;
  }

  /** 按主键查找，没有则 undefined */
  findById(id: string): User | undefined {
    return this.users.find((user) => user.id === id);
  }
}

数组只是替身，要紧的是"查全部"、"按 id 查"已经归进 UsersService。控制器只管调方法，不必过问细节。

Service 带来的直接好处主要是两条：

控制器变薄，一层里不塞满所有事
业务逻辑方便复用、写测试、以后改实现

习惯可以记得很短：控制器对齐请求，Service 扛起业务。

`Provider` 的本质

不少人初学时会把 Provider 和 Service 混着说，其实分清也不难：Service 是很常见的一种 Provider，Provider 这个词包住的是所有"可注入实现"。

凡是能交给 NestJS 容器创建、保管，再注入给别的类的，都归在这一类里。常见例子包括：

业务服务，例如 UsersService
仓储或数据访问类，例如 UsersRepository
横切能力，例如 MailService
配置对象、工厂返回值、自定义 token 绑定的实例，也都算

框架把它们统称 Provider，并不是纠结类名该叫 Service 还是 Repository，而是在管三件事：

要不要由容器负责实例化
能不能被别人注入
生命周期怎么配合作用域

写进模块的 providers 数组，就是在向容器挂号。只有挂上的实现才会按作用域被实例化，并有机会出现在别人的构造函数里。类名是服务还是仓储，只影响阅读，不影响这条规则。

下面两个类分工不同，在容器眼里却一视同仁，都是 Provider：

typescript 复制代码

import { Injectable } from "@nestjs/common";

@Injectable()
export class UsersService {
  findAll(): string[] {
    return ["汤姆", "杰瑞"];
  }
}

@Injectable()
export class MailService {
  sendWelcomeMail(email: string): string {
    return `已向 ${email} 发送欢迎邮件（示意）`;
  }
}

命名上你仍可以一个叫用户服务、一个叫邮件服务，登记方式没有区别。

记关系时只要两句就够：Provider 是框架侧的通用身份，Service 是业务里最常见的实现形态。以后遇到 Repository、工厂型 Provider 或自定义 token，仍然在同一个注入体系里处理。

`Module` 是什么

Service 扛业务，Provider 被容器托管，Module 则要再往上管一层：划清功能边界，把同一领域的控制器、Provider、对外约定装进一个盒子里。

在 NestJS 里，模块不是摆设，而是结构的基本单元，应用多半就是许多模块拼起来的东西。

用户、订单、认证可以各自落在 UsersModule、OrdersModule、AuthModule 上，每个模块维护自己的控制器、内部 Provider、以及愿意被别人用到的出口。

最小模块长这样：

typescript 复制代码

import { Module } from "@nestjs/common";
import { UsersController } from "./users.controller";
import { UsersService } from "./users.service";

/** 用户领域：对外入口 + 可注入服务 */
@Module({
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

行数不多，信息量不小：这几个人同属于一块业务边界；控制器对外接请求，UsersService 在本模块内可注入，再往下还可以继续挂别的 Provider。

从结构上看，可以先扫一眼下面这张图。

节点不是漂在全局，而是先归进各自模块，再由 AppModule 一类根模块把业务模块接起来。

别把 Module 当成应付编译器的样板，它就是在替你划"这块功能从哪开始、到哪结束"。

`imports` 等四个字段各管什么

第一次看 @Module() 里的配置，最容易缠在一起的是 imports、providers、controllers、exports。拆开看就顺了。

下面在有用户模块的基础上多接了一个 DatabaseModule，并把 UsersService 对外导出，方便别的模块注入：

typescript 复制代码

import { Module } from "@nestjs/common";
import { DatabaseModule } from "../database/database.module";
import { UsersController } from "./users.controller";
import { UsersService } from "./users.service";

/** 依赖数据库模块，并把用户服务暴露给 import 本模块的一方 */
@Module({
  imports: [DatabaseModule],
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}

四个键可以先记成功能分工：

imports 本模块依赖哪些别的模块已经 exports 出来的能力
providers 本模块自己要注册、仅供内部（默认可注入范围）使用的 Provider
controllers 本模块声明哪些 HTTP 入口
exports 本模块对外放行哪些 Provider，供在别处 imports 了本模块的代码继续注入

最常绊脚的一对是 providers 和 exports：

providers 是"家里有哪些实现"
exports 是"门口挂牌、准许邻居借用的有哪些"

留在 providers 里但没进 exports 的，别模块默认看不见。只有当别人也要注入这份实现，才需要把它写进 exports。

这有点像团队分工：内部实现可以多，对外接口要收束；别人要用，只能走你声明过的模块边界。

分文件夹只是把文件挪个地方，模块是在声明"谁允许依赖谁、谁对外可见"。

为什么业务逻辑不能全写在 `Controller`

新手很容易图省事，把业务全堆进 Controller：参数在手，就地校验、拼装、返回，看起来一气呵成。

项目一大，这样最容易长胖的是控制器。

下面这个例子能跑，但已经在兼职干 Service 的活：

typescript 复制代码

import { Body, Controller, Post } from "@nestjs/common";

/** 创建用户时客户端传入的字段 */
interface CreateUserDto {
  name: string;
  email: string;
}

@Controller("users")
export class UsersController {
  @Post()
  create(@Body() body: CreateUserDto): { message: string } {
    const exists = body.email === "tom@example.com";

    if (exists) {
      return { message: "该邮箱已存在" };
    }

    const user = {
      id: Date.now().toString(),
      name: body.name,
      email: body.email,
      status: "正常",
    };

    return { message: `已创建用户：${user.name}` };
  }
}

收参、判重、造对象、定响应格式挤在同一层，后面要复用、单测、接库、发信、上事务，只能继续往控制器里糊。

把规则挪进 Service，控制器只做转发，形态会干净很多：

typescript 复制代码

import { Body, Controller, Post } from "@nestjs/common";
import { UsersService } from "./users.service";

interface CreateUserDto {
  name: string;
  email: string;
}

@Controller("users")
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Post()
  create(@Body() body: CreateUserDto): { message: string } {
    // 业务规则交给服务层
    return this.usersService.create(body);
  }
}

改完后的控制器基本只做四件事：接请求、拿参数、喊 Service、把结果交出去。

收益不只是顺眼，而是业务落在更容易复用和测试的一层，项目越复杂越省劲。

为什么 `Module` 是 `NestJS` 里最核心的那一层边界

Controller 管入口，Service 管业务落地，Module 管的是再底下那层：系统边界哪里画、依赖往哪收敛。

维护噩梦常常不是少写了类，而是边界糊掉：模块互相穿透实现细节，调用网越织越密。

NestJS 把 Module 摆得这么重，是要你把应用想成"多模块协作"，而不是"一大撮控制器加一大撮服务"。

边界划清楚以后，好处很实在：

用户、订单、支付、认证各自有落脚模块
依赖不容易随便渗透到别的模块内部
拆分、复用、补测试都更顺手
新人找功能时有目录感
大重构可以按模块切块推进

反过来，模块若只是分文件夹，Service 和 Controller 再多也可能是一盘散沙。

所以 Module 不只是凑齐装饰器清单，而是在体积涨上去之前，逼你先想清楚谁能见谁、谁能用谁。

顺口溜可以记成 "Controller 开门口，Service 做生意，Module 砌围墙"。

这三层站稳以后，依赖注入、模块导入导出、动态模块、可插拔架构都会沿同一套边界往下长。

小结

这篇的重点不是多记几个词，而是把三条线拧到一根绳上：

Service 承接大部分业务
Provider 是容器能注入的那类东西的统称
Module 划边界、装箱、再决定对外露什么

判断习惯可以压成四句：入口给控制器，规则给服务，可注入项进 Provider 列表，单元边界交给模块。

下一节讲 DTO 和校验。你会看到，光靠"拿到字段就用"在真实项目里往往不够。

AI 全栈指南：NestJs 中的 Service Provider 和 Module

Provider 的本质

Module 是什么

imports 等四个字段各管什么

为什么业务逻辑不能全写在 Controller

为什么 Module 是 NestJS 里最核心的那一层边界

小结

`Provider` 的本质

`Module` 是什么

`imports` 等四个字段各管什么

为什么业务逻辑不能全写在 `Controller`

为什么 `Module` 是 `NestJS` 里最核心的那一层边界