大家好，我是 Moment。Zui近我一直在捣鼓我的开源项目 DocFlow，这是一个基于 Next.js 和 NestJS 构建的 AI 协同文档平台。在开发过程中，我深刻体会到，一个清晰的后端架构对于全栈开发来说是多么重要。今天我想和大家聊聊 NestJS 中Zui基础，但也Zui容易让初学者感到困惑的部分——Controller和路由。

hen多刚从 Express 或者 Spring Boot 转过来的朋友，一开始可Neng会有些不适应。在 NestJS 的世界里路由并不是像某些传统框架那样，被孤零零地写在一张巨大的配置表或者单独的路由文件里。相反，它们geng像是某种“贴纸”，直接贴在了控制器类和它的方法上。这种设计虽然一开始kan起来有点“魔幻”，但一旦你习惯了就会发现它在团队协作和代码维护上有着巨大的优势。

路由的本质：装饰器的艺术

我们要明白的第一件事就是：NestJS 对常见 HTTP 方法dou提供了对应的装饰器。这不仅仅是语法糖，geng是框架设计哲学的体现。

Zui常用的无非就是 @Get@Post@Put@Delete 这几位老伙计。它们的作用非常直观——告诉框架，当收到特定类型的 HTTP 请求时应该由哪个方法来处理。

让我们kan一个简单的例子，这比说一堆废话要管用得多：

import { Controller, Get, Redirect } from "@nestjs/common";
@Controller
export class AppController {
  @Get
  @Redirect
  goDocs: void {
    // 这里甚至不需要写任何逻辑，重定向会自动处理
  }
}

这段代码非常简单，但信息量hen大。当用户在浏览器里敲下 /docs 这个路径时服务端不会傻乎乎地去查找文件，而是直接通过 HTTP 协议告诉浏览器：“嘿，你要的东西不在这去 docs.nestjs.com 找吧。”这就是 @Redirect 装饰器的威力。

当然这只是一个引子。在实际的业务开发中，比如我在Zuo DocFlow 的文档编辑器同步功Neng时路由的设计会复杂得多。

类装饰器与方法装饰器的配合

在 NestJS 中，@Controller 装饰器通常加在类上面用来定义这一组接口的“公共前缀”。而方法上的装饰器，则负责定义具体的子路径。

比如我们要管理用户相关的接口：

import { Controller, Get } from "@nestjs/common";
@Controller
export class UsersController {
  @Get
  findAll: string {
    return "This action returns all users";
  }
  @Get
  findProfile: string {
    return "This action returns user profile";
  }
}

这里有个小细节值得注意：@Controller 给整个类定了个基调，意味着下面所有方法的路径dou会以 /users 开头。所以 findAll 实际上监听的是 GET /users，而 findProfile 监听的是 GET /users/profile。

这种组织方式非常符合人类的直觉——把用户相关的逻辑dou塞进 UsersController，把订单相关的逻辑塞进 OrdersController。代码结构和 URL 路径结构保持一致，维护起来简直是享受。

数据去哪了？参数解析的奥秘

写接口的时候，除了路径匹配，Zui头疼的往往是怎么把数据从请求里“抠”出来。浏览器或者客户端把数据藏在 URL 路径里、问号后面的查询串里或者是请求体里。Ru果不搞清楚这些，写出来的代码就会像一团乱麻。

在 NestJS 里我们有一套非常顺口的“口诀”：

路径段里的参数，用 @Param；

问号后面的查询串，用 @Query；

请求包体里的 JSON 数据，用 @Body。

为了让大家geng直观地理解，我把这三种情况写在一个 PostsController 里大家Ke以对比着kan：

import { Body, Controller, Get, Param, Post, Query } from "@nestjs/common";
// 定义一个简单的数据传输对象
interface CreatePostDto {
  title: string;
  content: string;
}
@Controller
export class PostsController {
  // 场景1：获取特定ID的文章，可Neng带有一个预览模式的查询参数
  @Get
  findOne(
    @Param id: string, 
    @Query preview?: string
  ): { id: string; preview?: string } {
    console.log;
    return { id, preview };
  }
  // 场景2：创建新文章，数据dou在 JSON 体里
  @Post
  create body: CreatePostDto): CreatePostDto {
    console.log;
    return body;
  }
}

kan到没？findOne 方法里id 是从 URL 路径 /posts/123 里拿出来的，而 preview 则是从 ?preview=true 这种查询串里拿的。到了 create 方法，我们直接用 @Body 把整个 JSON 对象映射成了 CreatePostDto。

这种写法的好处在于，你的方法签名非常清晰。一眼就Nengkan出这个接口需要什么参数，数据从哪来而不需要在方法体里到处去翻 req.params 或者 req.query，代码的可读性瞬间提升了一个档次。

响应的艺术：自动处理 vs 手动接管

聊完了请求，我们再来kankan响应。这也是hen多新手容易踩坑的地方。

在大多数情况下NestJS 非常智Neng。你只需要在方法里 return 一个对象、数组或者字符串，框架就会自动帮你序列化成 JSON，并设置好相应的响应头。这是Zui推荐的默认方式，简洁又优雅。

但是生活总是充满了意外。有时候你需要手动控制响应的细节，比如你想实现流式传输文件下载，或者你需要设置一些非常特殊的 Cookie 和响应头。这时候，你就需要拿到原生的响应对象。

这时候就要用到 @Res 装饰器了。kan下面这个例子：

import { Controller, Get, Res } from "@nestjs/common";
import type { Response } from "express";
@Controller
export class DownloadController {
  @Get
  download res: Response): void {
    // 一旦使用了 @Res，就意味着这一段响应由你自己全权接管
    res.status.json;
  }
}

这里有个极其重要的注意事项：一旦你在某个方法里注入了 @Res，NestJS 就会认为“好吧，这个家伙想自己动手，我就不插手了”。Ru果你这时候还用了 return，框架是不会帮你自动发送响应的。这就像是你抢过了方向盘，司机就只Neng把手放下了。所以用了 @Res，记得一定要手动调用 res.send 或者 res.json，否则请求会一直挂起直到超时。

除了手动控制，有时候我们还需要修改状态码。比如登录接口，虽然可Neng是 POST 请求，但我们成功时通常返回 200，而不是 201。这时候Ke以用 @HttpCode

import { Controller, HttpCode, Post } from "@nestjs/common";
@Controller
export class AuthController {
  @Post
  @HttpCode // 显式指定状态码
  login: { message: string } {
    return { message: "Login successful" };
  }
}

请求头与元数据

除了路径和包体，请求头也是我们经常打交道的地方。比如我们要根据 User-Agent 来判断客户端类型，或者读取 Authorization 头来Zuo身份验证。

在 NestJS 里读取请求头简直易如反掌：

import { Controller, Get, Headers } from "@nestjs/common";
@Controller
export class InfoController {
  @Get
  getClientInfo userAgent?: string): { userAgent?: string } {
    // 直接通过装饰器就Neng拿到指定的 header 值
    return { userAgent };
  }
}

这里的 @Headers 就像是一个精准的镊子，直接从 HTTP 请求头里夹出了你想要的数据。

架构思维：Controller 的边界在哪里？

讲了这么多具体的 API 和装饰器，我想升华一下聊聊架构层面的东西。

hen多初学者容易把 Controller 写得非常臃肿，里面塞满了各种业务逻辑：查数据库、Zuo计算、甚至发邮件。这其实是一种反模式。

Ru果用一句话来概括 Controller 的职责，那就是：“把 HTTP 请求接进来把结果返回出去”。

Controller 应该是“薄”的。它只负责：

路由匹配；

参数解析；

调用 Service 处理业务；

返回响应。

至于真正的业务逻辑，比如“用户余额是否充足”、“文章发布是否需要审核”，这些dou应该交给 Service 层去处理。

这种分层的好处是显而易见的。你的 Controller 只关注 HTTP 协议层面的东西，而 Service 只关注业务逻辑。这样当你需要把业务逻辑复用到 CLI 工具或者定时任务里时你完全不需要 HTTP 这一层，直接调用 Service 就行了。

实战中的

回顾一下我们今天聊了 NestJS 中路由的声明方式、各种参数装饰器的用法、响应的控制方式，以及 Controller 应该承担的职责。

在 DocFlow 项目的开发过程中，我深刻体会到，遵循这些约定俗成的规则，Neng让代码变得非常干净。比如当我们需要给接口添加拦截器、异常过滤器或者管道的时候，一个结构清晰的 Controller Neng让我们少掉hen多头发。

下一节，我们将继续深入，kankan ServiceProvider 以及 Module 是如何像积木一样把业务Neng力真正组织起来的。毕竟光有入口是不够的，还得有强大的“心脏”和“血管”。

Ru果你对 AI 全栈开发、文档编辑器的底层实现、前端工程化或者 React 源码感兴趣，欢迎添加我的微信 yunmz777 一起交流。我也在持续打磨 DocFlow，在这个过程中积累了大量关于 Tiptap 深度定制、编辑器性Neng优化以及协同方案设计的实战经验，希望Neng和大家一起探讨。

觉得这篇文章还不错的话，别忘了给 DocFlow 点个 star ⭐，你的支持是我持续输出的Zui大动力！

---