大家好 👋，我是 Moment。Zui近这段时间，我正埋头于 DocFlow 的开发工作中。这是一个面向 AI 场景的协同文档平台，技术栈选用了 Next.jsNestJS 以及 LangChain。在这个过程中，我不仅折腾了基于 Tiptap 的富文本编辑器深度定制，还一头扎进了编辑器性Neng优化和协同方案设计的深水区。当然除了前端的这些细活儿，后端工程化建设、React 源码理解以及复杂项目架构实践，也是我日常“搬砖”的重要组成部分。

今天想和大家聊聊的，正是我后端架构选择中的核心一环——NestJS。hen多刚从 Express 或 Koa 转过来的朋友，第一次kan到 NestJS 可Neng会觉得：“这也太繁琐了吧？”但相信我，当你习惯了这种结构化的美感，就再也回不去那个“面条式代码”的时代了。Ru果你对 AI 全栈开发、文档编辑器、前端工程化或者 React 源码相关内容感兴趣，欢迎添加我的微信 yunmz777 一起交流。觉得项目还不错的话，也欢迎给 DocFlow 点个 star ⭐

别急着写代码，先选好你的“兵器”

Ru果你是第一次接触 NestJS，我强烈建议你不要试图手动去搭建目录结构。真的，别去挑战那个枯燥的过程。Zui推荐的方式，也是效率Zui高的方式，就是直接使用官方提供的 CLI 工具。为什么？因为 CLI 不仅仅帮你生成几个文件那么简单，它实际上是把一套经过验证的、标准可运行的项目骨架直接送到了你面前。这样你第一次上手时就Neng把精力集中在核心逻辑上，而不是一上来就被各种配置细节搞得头大。

在终端中执行下面这条命令，你就Ke以开启一段新的旅程：

pnpm dlx @nestjs/cli new hello-nest

这里我得稍微解释一下Ru果你之前没有用过 dlx，Ke以把它理解成“临时工”。它不需要你先在全局安装 @nestjs/cli，而是临时拉起来跑一下这个命令行工具，用完就走，干干净净。这对于第一次体验或者不想污染全局环境的朋友来说简直是神器。

执行之后CLI 会非常贴心地提示你选择包管理器。这时候，直接选择自己当前项目里Zui常用的那个就行。Ru果你平时主要使用 pnpm，那这里继续选 pnpm 肯定会geng顺手。为了方便演示，下面的示例我dou会统一使用 pnpm。当然Ru果你是 npm 或 yarn 的忠实粉丝，只要把命令替换成自己习惯的工具即可，本质上没有任何区别。

这一步完成之后你会得到一个Yi经初始化好的项目目录。依赖会自动安装，基础文件也会一并生成，所以不需要你再从零去创建入口文件、路由文件或者是配置文件。这种“开箱即用”的感觉，真的hen棒。

解构生成的骨架：它为什么长这样？

项目创建完成后先不要急着去写业务代码。磨刀不误砍柴工，geng重要的是先kan一眼默认的目录结构。因为这会直接帮助你理解 NestJS 是怎么组织应用的，这对你后续的开发至关重要。

一个刚生成出来的 NestJS 项目，核心目录大致会像下面这样：

你会发现，哪怕只是一个Zui简单的 Hello World 项目，NestJS 也没有把所有逻辑dou塞进一个文件里。它一开始就把入口、模块、控制器、服务拆开了。这正是前面提到的结构约束，也是 NestJS 的哲学所在。

第一次kan这些文件时Ke以先抓Zui重要的几个角色：

1. 入口 这是整个应用的起点，就像心脏跳动的地方，负责创建应用实例并监听端口。

2. 组织者 比如 AppModule，它像个管家，把 Controller 和 Service 登记到同一个模块里告诉大家我们是一伙的。

3. 接待员 负责接请求，处理 HTTP 层面的细节，比如路由、参数解析，然后把活儿派发给服务层。

4. 工人 负责写逻辑，处理真正的业务计算，比如查数据库、算数据。

这和先把逻辑全塞进一个文件再说的写法差别hen大。NestJS 从第一个接口就在推你把入口、业务和装配拆开。返回值具体写了哪句文案反而不那么重要，geng值得留意的是三件事Yi经成习惯：入口和业务分开、依赖交给框架装配、结构按角色长而不是按临时想法堆。

启动你的第一个服务

一个刚生成出来的 NestJS 项目，本身就是可运行的。进入项目目录后就Ke以把开发环境跑起来了：

cd hello-nest
pnpm run start:dev

这条命令会以开发模式启动项目，并开启监听。也就是说你修改 src 里的代码后服务通常会自动重新编译并重启，不需要你每次手动停掉再启动。这种热重载的体验，在开发调试时Neng省下不少喝咖啡的时间。

项目启动成功后终端一般会kan到类似 Nest application successfully started 的提示。默认情况下服务会监听 3000 端口。

这时候你Ke以先用浏览器打开下面这个地址：

http://localhost:3000

Ru果一切正常，你会kan到默认返回的 Hello World!。这说明项目Yi经跑起来了环境没有任何问题。这一步的意义不只是确认环境没问题，geng重要的是让你先建立一个非常直接的印象：我写的代码，真的变成了网页上的内容。

深入核心：Controller 与 Service 的博弈

默认项目Yi经有一个Zui基础的接口，只是它的业务非常简单。为了真正理解 NestJS 的组织方式，Zui好的Zuo法不是新建一堆复杂模块，而是先把这个默认接口改一遍。通过 CLI 创建项目，你拿到的是一套标准初始结构；通过修改默认接口，你Nengkan到 ControllerService依赖注入和应用入口是如何协同工作的。

接下来会从这个Zui小项目出发，kan Controller 和路由是怎么对应起来的。

第一步：改造服务层

先kan服务层。把 src/app.service.ts 改成下面这样：

import { Injectable } from "@nestjs/common";
@Injectable
export class AppService {
  getHello: { message: string; from: string } {
    return {
      message: "Hello NestJS",
      from: "AppService",
    };
  }
}

这段代码的重点不是返回什么内容，而是让你kan到，真正的业务结果是由 AppService 提供的。控制器不直接写死所有内容，而是去调用服务层。这种分离，让你的代码在以后变复杂时依然Neng保持清晰。

第二步：让控制器动起来

接着修改 src/app.controller.ts

import { Controller, Get } from "@nestjs/common";
import { AppService } from "./app.service";
@Controller
export class AppController {
  constructor {}
  @Get
  getHello: { message: string; from: string } {
    return this.appService.getHello;
  }
}

这里有两个点值得第一次接触时特别留意。

第一，@Controller 和 @Get 这类装饰器，标的是这个类、这个方法在 HTTP 这一层各自干什么。它们就像路标，告诉框架：“当有人访问 /hello 路径时就用这个方法来处理”。

第二，控制器通过构造函数拿到 AppService，而不是自己手动 new AppService。这就是依赖注入Zui直观的体现。你声明自己需要什么框架负责把依赖准备好。你不需要操心服务是怎么实例化的，你只需要用它。

验证成果：请求的生命周期

改完之后重新访问下面这个地址：

http://localhost:3000/hello

Ru果一切正常，你会kan到类似下面这样的返回结果：

{
  "message": "Hello NestJS",
  "from": "AppService"
}

kan到这里其实你Yi经完成了自己的第一个 NestJS 接口。虽然它非常简单，但Zui关键的骨架Yi经出现了。

一个Zui简单的 Hello World 也Nengkan出 NestJS 的分层习惯，请求不会随便落进某个函数，而是按约定往前走。Zui短路径Ke以先想成下面五步：

请求到达浏览器访问 /hello。

路由匹配AppController 上的 @Get 捕获了请求。

依赖调用控制器调用 this.appService.getHello。

业务处理AppService 执行逻辑，返回数据对象。

响应返回框架自动将对象序列化为 JSON，发回给浏览器。

在这五步之上还要叠上两块，根 Module把 Controller 和 Service 登记到同一个模块里src/main.ts 创建应用实例并监听端口，进程才真正跑起来。接请求、写业务、Zuo装配、拉起监听，是同一条Zui小链路上的不同环节。

把这套形状刻在脑子里

第一个 NestJS 项目的重点，不是把服务跑起来本身，而是借这个Zui小示例kan清它的基本骨架。也就是说NestJS 希望你从第一个项目开始，就用一种geng接近真实业务系统的方式来组织代码，而不是先随便写，等项目变大后再重构。

Ru果你现在只记一句话，Ke以先记这个：Controller 接客，Service 干活，Module 管家，Main.ts 开门。

把这条轮廓记熟，后面再学模块拆分、参数校验、异常处理、数据库接入，dou容易挂回同一套形状里。在这五步之上还要叠上两块，根 Module把 Controller 和 Service 登记到同一个模块里src/main.ts 创建应用实例并监听端口，进程才真正跑起来。接请求、写业务、Zuo装配、拉起监听，是同一条Zui小链路上的不同环节。

Ru果你现在Yi经Neng理解下面这几件事，这一篇的目标就达到了：

为什么推荐用 CLI 而不是手动建文件？

main.tsapp.module.tsapp.controller.tsapp.service.ts 各自扮演什么角色？

依赖注入在代码里大概长什么样？

一个请求从进入到返回，大概经过了哪几层？

后面无论项目变得多复杂，这套基础分工dou不会变。也正因为默认项目Neng立刻跑起来后面改代码时你Nenghen直观地对照改了哪个文件、行为发生了什么变化。在这个项目的持续打磨过程中，我积累了不少实战经验，不只是 Tiptap 的深度定制、编辑器性Neng优化和协同方案设计，也包括前端工程化建设、React 源码理解以及复杂项目架构实践。

希望这篇指南Neng帮你顺利迈出 NestJS 的第一步。Ru果你在搭建过程中遇到任何问题，或者想聊聊 DocFlow 的实现细节，随时欢迎来找我。祝大家编码愉快！

---