第 1 章:NestJS 入门

学习目标

• 理解 NestJS 是什么、解决什么问题
• 掌握 CLI 初始化项目
• 跑通第一个 Hello World
• 避开 3 个安装和启动坑

一、NestJS 是什么

NestJS 是一个渐进式 Node.js 服务端框架,完全用 TypeScript 编写,底层默认基于 Express(可选 Fastify)。它的设计参考了 Angular 的模块化和依赖注入思想。

// app.controller.ts
import { Controller, Get } from '@nestjs/common';

@Controller()                     // 控制器装饰器
export class AppController {
  @Get()                          // 路由装饰器
  getHello(): string {
    return 'Hello NestJS!';
  }
}

和 Express/Koa 相比,NestJS 提供了开箱即用的架构约束:模块、依赖注入、AOP(守卫/管道/拦截器)、统一异常处理。

二、安装 Node.js 和包管理器

NestJS 需要 Node.js 18+。

# 检查版本
node -v    # 应 >= v18

# 推荐用 pnpm(快、磁盘省)
npm i -g pnpm

# 备选:npm 或 yarn

⚠️ 坑 1:Node 16 以下会报 SyntaxError: Unexpected token,升 Node 再试。

三、用 CLI 创建项目

# 全局安装 CLI
npm i -g @nestjs/cli

# 创建项目(不要叫 nestjs,会和 CLI 包名冲突)
nest new my-app

# 进入并启动
cd my-app
pnpm run start:dev

CLI 会问包管理器,选 pnpm。然后会自动 git init 并装依赖。

四、目录结构

my-app/
├── src/
│   ├── app.controller.ts    # 控制器(路由)
│   ├── app.controller.spec.ts
│   ├── app.service.ts       # 服务(业务逻辑)
│   ├── app.module.ts        # 根模块
│   └── main.ts              # 启动入口
├── test/
├── nest-cli.json
├── package.json
├── tsconfig.json
└── tsconfig.build.json

五、main.ts 启动入口

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);                  // 监听 3000
}
bootstrap();

启动后访问 http://localhost:3000,看到 Hello World! 即成功。

六、常用命令

pnpm run start          # 普通启动
pnpm run start:dev      # 开发模式(热重载)
pnpm run start:prod     # 生产模式
pnpm run build          # 编译到 dist/
pnpm run test           # 跑单元测试

⚠️ 坑 2:改完代码不生效?确认用 start:dev(带 watch),不是 start。 ⚠️ 坑 3:端口被占用 → Error: listen EADDRINUSE → 杀掉进程 lsof -i:3000 或换端口 app.listen(4000)。

七、第一个自定义路由

修改 src/app.controller.ts:

import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';

@Controller('api')                 // 路径前缀 /api
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get('hello')                    // GET /api/hello
  getHello(): string {
    return this.appService.getHello();
  }

  @Get('ping')                     // GET /api/ping
  ping(): object {
    return { ok: true, ts: Date.now() };
  }
}

// src/app.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class AppService {
  getHello(): string {
    return 'Hello from Service!';
  }
}

测试:

curl http://localhost:3000/api/hello
# Hello from Service!

curl http://localhost:3000/api/ping
# {"ok":true,"ts":1700000000000}

八、本章小结

要点	关键
NestJS 定位	Node.js 服务端框架,TS 优先,默认 Express
CLI	nest new <name> 创建项目
启动	main.ts 调 NestFactory.create(AppModule)
启动脚本	start:dev 热重载,start:prod 生产模式
装饰器	@Controller()、@Get()、@Injectable()
端口冲突	EADDRINUSE → 改端口或杀进程

动手练习

1. 改欢迎语:把 getHello() 改成返回你的名字 + 当前时间
2. 加路由:再加一个 @Get('time') 返回 ISO 时间字符串
3. 改端口:把 main.ts 改成监听 8080 并验证

---

下一章:第 2 章:控制器 →