Nest.js 快速启动 API 项目过程详解
本文详细解析使用 Nest.js 快速启动 API 项目的完整流程。内容涵盖通过 CLI 或 Starter 项目初始化、Controller 与 Service 的分层创建、基于 HttpModule 和 RxJS 的异步请求处理、Config 模块配置环境变量，以及利用 Swagger 自动生成 API 文档并集成 Postman。旨在帮助开发者高效搭建符合企业级规范的后端服务。
快速启动
近期启动的新项目需管理庞大的任务与团队集群，且不同流程涉及 Salesforce、HubSpot 等不同系统。本项目旨在两个平台间进行交互，当前阶段仅需封装其中一个平台的 API，因此决定采用 Node.js 框架 Nest.js 来实现该 API 服务。
启动 NestJS 项目主要有三种便捷方式。
使用 nest 自带的命令行工具
npm i -g @nestjs/cli
nest new project-name即使不直接采用此方式，也建议在 Node.js 全局环境中安装命令行工具，以便方便地生成各种 NestJS 模块，例如 Controller 和 Service 等。
直接使用 starter 项目
此外，官方提供了一个用于启动的示例项目，可直接使用。
git clone https://github.com/nestjs/typescript-starter.git my-app
cd my-app
npm install
npm run start该项目已附带 TypeScript 支持，但请注意删除原有的 Git 信息。
用 npm 安装所需的包
npm i --save @nestjs/core @nestjs/common rxjs reflect-metadata直接安装 NestJS 的 core 和 common 包即可，rxjs 和 reflect-metadata 也是必需的依赖。
这种方式生成的目录结构较为干净，需自行创建目录，但也可使用命令行生成 Controller 等，目录会自动创建好。
总体而言，NestJS 与其他语言的 API 框架类似，许多功能可自动生成或无需编写，因此遵循约定俗成的习惯至关重要，尽量避免创建“独特”的结构，以免后续开发中遇到不必要的麻烦。
创建 controller
项目创建完成后，我创建了一个 Controller。在 Nest.js 中，Controller 可通过修饰器直接提供路由，因此无需单独的 route 文件来配置路由。
nest g controller projectsNest.js 的目录约定是按业务模块划分，例如在 src 目录中会出现一个 projects 目录，该目录下会生成 projects.controller 以及附带的单元测试。
创建 service
接着创建 Service，用于封装目标任务管理平台关于 Projects 的 API 逻辑。
nest g service projects创建 Controller 和 Service 时，它们会自动注册到 Module 中。建议在每次生成后使用 git diff 查看生成的代码，以便清楚了解变更内容。
import { Controller, Get, Req } from '@nestjs/common';
import { Request } from 'express';
import { Project } from 'src/interfaces/project.interface';
import { ProjectsService } from './projects.service';
@Controller('projects')
export class ProjectsController {
constructor(private projectsService: ProjectsService) {}
@Get()
findAll(@Req() request: Request): Project[] {
return this.projectsService.findAll();
}
}import { Injectable } from '@nestjs/common';
import { Project } from 'src/interfaces/project.interface';
@Injectable()
export class ProjectsService {
findAll(): Project[] {
return [];
}
}结构和命名
需要特别说明的是，虽然我为 Controller 和 Service 使用了相同的名称，但这并不意味着它们是一一对应的关系。许多项目为了分层而强行一一对应，这并不正确。分层是因为它们拥有不同的语义，只有明确语义，才能在思维过程中更好地掌握代码，实现更好的复用。层次的作用是一种认知转换，若只是将底层对象毫无变化地映射出来，则过程毫无意义。
在 Nest.js 中，Service 实际上是 Provider 的一种，而 Provider 的意义是从不同地方提供数据或其他资源。我使用的 ProjectsService 旨在封装另一个 API，因此其名称 projects 来源于目标任务管理平台的 API 名称。而 Controller 的名称 projects 指的是我创建的 API 所提供的数据类型是 project，尽管在此处它们指向同一事物，故名称相同。
假设业务逻辑需要从目标任务管理平台获取 projects，随后过滤出两种不同特性的 projects：一种叫 task（任务），需分配给人员；另一种叫 note（记录），仅作标记。它们拥有不同的特性。此时，我会创建两个 Controller：taskController 和 noteController，但它们都调用 ProjectsService 以不同的过滤条件获取数据。
HTTP 请求
使用 Nest.js 官方的 HttpModuleHttpModule即可向其他 API 发出请求。该模块封装了 Axios，使用便捷。需先安装相关模块。
npm i --save @nestjs/axios axios然后在 app.module 中引入该模块。
import { HttpModule } from '@nestjs/axios';
...
@Module({
imports: [HttpModule], // 引入Http模块
controllers: [ProjectsController],
providers: [ProjectsService],
})
export class AppModule {}处理 Axios 对象
在 Service 中可按如下方式处理 HTTP 请求的返回值。
import { HttpService } from '@nestjs/axios';
import { Injectable } from '@nestjs/common';
import { map, Observable } from 'rxjs';
import { Project } from 'src/interfaces/project.interface';
import { AxiosResponse } from 'axios';
@Injectable()
export class ProjectsService {
constructor(
private readonly httpService: HttpService
) {}
findAll(): Observable<Project[]> {
return this.httpService.get('http://localhost:3000/api-json').pipe(
map((axiosResponse: AxiosResponse) => {
return axiosResponse.data;
})
);
}
}由于 Axios 会包裹一层响应，统一使用 data 作为 key，因此需要通过 map 提取数据。这里的 pipe 和 map 方法均来自 rxjs。RxJS 的核心是 Observable，采用响应式编程方式封装了回调和异步代码。因此，此处看不到 promise 或 await/async 等关键字。
配置
上述请求仅使用本地 JSON 接口进行测试。若要真正调用目标平台的 API，还需配置项，因为包括 API token 等重要字符串的值需放在环境变量中，不能直接硬编码在代码中提交至 Git。
因此，我需要添加 config 配置，安装 Nest.js 的 config 包，它封装了 dotenv 包，熟悉 Node.js 开发的开发者应对其很熟悉。
npm i --save @nestjs/config同样在 app.module 中引入 config 模块。
import { ConfigModule } from '@nestjs/config';
import configuration from './config/configuration';
...
imports: [
HttpModule,
ConfigModule.forRoot({
load: [configuration],
})
],
...这里使用 forRoot 是因为该模块采用单例模式。传入的参数load可将 config 对象载入。
引入的config/configuration文件是新创建的配置对象。
export default () => ({
port: parseInt(process.env.PORT, 10) || 3000,
runn: {
url: process.env.RUNN_API_URL,
token: process.env.RUNN_API_TOKEN
}
});我配置了端口，以及 API 的 URL 和 Token。
随后可能需要用到 TypeScript 的接口，可使用 Nest 命令生成文件。
nest g interface runn-configexport interface RunnConfig {
url: string
token: string
}在 Service 中即可获取这些配置项。
import { ConfigService } from '@nestjs/config';
import { RunnConfig } from 'src/interfaces/runn-config.interface';
...
constructor(
private readonly httpService: HttpService,
private configService: ConfigService
) {}
...
const config = this.configService.get<RunnConfig>('runn');... const config = this.configService.get<RunnConfig>('runn');
不要忘记在根目录下创建.env文件填入配置的值。另外，按习惯可创建 .env.sample 文件，仅包含 key 而无值，作为模板提交至 Git 管理。而 .env 文件则被 .gitignore 忽略，仅在本地保留。在服务器上需另行生成一份。
全局添加 headers
URL 已使用，但 Token 需在 headers 中添加。在 app.module 中使用 HttpModule 的 register 方法即可配置其中封装的 Axios。但由于 token 来自 config，需使用较复杂的 registerAsync，注入 config 后，在 useFactory 中使用。
...
imports: [
HttpModule.registerAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (configService: ConfigService) => ({
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer ' + configService.get('runn.token')
}
})
}),
...
],
...这样，我便创建了一个基本 API 框架，并请求了一个简单的目标任务管理系统的 API 以获取数据。
API 文档
此外，由于客户需要了解和测试我们的 API，因此需要一个 Postman 的 API 集合。我准备使用 Swagger，这是一个 API 文档的自动生成工具，它会根据框架中定义的 API 和参数，自动生成一个页面，包含所有 API 和参数说明，并支持直接请求该 API。当然，这需要修饰器的辅助。先安装 NestJS 的 Swagger 包。
npm i --save @nestjs/swagger然后在main.ts中引入并配置。
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
// swagger
const config = new DocumentBuilder()
.setTitle('My APIs')
.setDescription('My APIs documents')
.setVersion('1.0')
.build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api', app, document);
// swagger end
await app.listen(3000);
}
bootstrap();
随后即可通过 http://localhost:3000/api 访问该 API 文档页面。不过目前所有 API 都会出现在 default 默认标签下。官方示例中使用的 addTag 方法虽可添加标签，但并不能指定某些 API 放入该标签。我需要通过修饰器实现。
在 Controller 的方法上使用@ApiTags('Project')即可，该方法会被放置在 Project 标签下。
除了 API 文档的页面形式外，http://localhost:3000/api-json 的 JSON 格式才是最重要的，可使用它在 Postman 中直接导入。
以上就是 Nest.js 快速启动 API 项目过程详解的详细内容，更多关于 Nest.js 快速启动 API 的资料请关注本站其它相关文章！
JS脚本在App中运行报错怎么解决
2026-11-04 23:11:03
JS怎么使用padStart方法给数字补零
2026-11-04 11:12:03
JS是什么意思？JavaScript全称及基本定义
2026-11-04 08:05:29
JS 使用 toFixed(1) 保留一位小数的基本用法与注意事项
2026-11-03 18:34:57
JS字符串转整数：parseInt与Number的区别及用法
2026-11-03 17:26:54