NestJS 開發模式
適用於生產級、模組化 TypeScript 後端的 NestJS 模式。
啟用時機
- 建置 NestJS API 或服務時
- 組織模組、控制器和提供者時
- 加入 DTO 驗證、守衛、攔截器或例外過濾器時
- 配置環境感知設定和資料庫整合時
- 測試 NestJS 單元或 HTTP 端點時
專案結構
src/
├── app.module.ts
├── main.ts
├── common/
│ ├── filters/
│ ├── guards/
│ ├── interceptors/
│ └── pipes/
├── config/
│ ├── configuration.ts
│ └── validation.ts
├── modules/
│ ├── auth/
│ │ ├── auth.controller.ts
│ │ ├── auth.module.ts
│ │ ├── auth.service.ts
│ │ ├── dto/
│ │ ├── guards/
│ │ └── strategies/
│ └── users/
│ ├── dto/
│ ├── entities/
│ ├── users.controller.ts
│ ├── users.module.ts
│ └── users.service.ts
└── prisma/ or database/
- 將領域程式碼保留在特徵模組內。
- 將跨層級的過濾器、裝飾器、守衛和攔截器放在
common/中。 - 讓 DTO 停留在它所屬的模組附近。
啟動與全域驗證
async function bootstrap() {
const app = await NestFactory.create(AppModule, { bufferLogs: true });
app.useGlobalPipes(
new ValidationPipe({
whitelist: true,
forbidNonWhitelisted: true,
transform: true,
transformOptions: { enableImplicitConversion: true },
}),
);
app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
app.useGlobalFilters(new HttpExceptionFilter());
await app.listen(process.env.PORT ?? 3000);
}
bootstrap();
- 對於公開 API，一律啟用
whitelist和forbidNonWhitelisted。 - 優先使用單一的全域驗證管線，而不是在每個路由重複驗證配置。
模組、控制器與提供者
@Module({
controllers: [UsersController],
providers: [UsersService],
exports: [UsersService],
})
export class UsersModule {}
@Controller('users')
export class UsersController {
constructor(private readonly usersService: UsersService) {}
@Get(':id')
getById(@Param('id', ParseUUIDPipe) id: string) {
return this.usersService.getById(id);
}
@Post()
create(@Body() dto: CreateUserDto) {
return this.usersService.create(dto);
}
}
@Injectable()
export class UsersService {
constructor(private readonly usersRepo: UsersRepository) {}
async create(dto: CreateUserDto) {
return this.usersRepo.create(dto);
}
}
- 控制器應保持精簡：解析 HTTP 輸入、呼叫提供者、回傳回應 DTO。
- 將業務邏輯放在可注入的服務中，而非控制器。
- 僅匯出其他模組真正需要的提供者。
DTO 與驗證
export class CreateUserDto {
@IsEmail()
email!: string;
@IsString()
@Length(2, 80)
name!: string;
@IsOptional()
@IsEnum(UserRole)
role?: UserRole;
}
- 使用
class-validator驗證每個請求 DTO。 - 使用專用的回應 DTO 或序列化器，而不是直接回傳 ORM 實體。
- 避免洩漏內部欄位，例如密碼雜湊、令牌或稽核欄位。
身份驗證、守衛與請求上下文
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('admin')
@Get('admin/report')
getAdminReport(@Req() req: AuthenticatedRequest) {
return this.reportService.getForUser(req.user.id);
}
- 保留身份驗證策略和守衛在模組內，除非它們確實是共用的。
- 在守衛中編碼粗粒度的存取規則，然後在服務中進行資源特定的授權。
- 對已驗證的請求物件，偏好使用明確的請求類型。
例外過濾器與錯誤形狀
@Catch()
export class HttpExceptionFilter implements ExceptionFilter {
catch(exception: unknown, host: ArgumentsHost) {
const response = host.switchToHttp().getResponse<Response>();
const request = host.switchToHttp().getRequest<Request>();
if (exception instanceof HttpException) {
return response.status(exception.getStatus()).json({
path: request.url,
error: exception.getResponse(),
});
}
return response.status(500).json({
path: request.url,
error: '內部伺服器錯誤',
});
}
}
- 在整個 API 中保持一致的錯誤封裝格式。
- 對預期的客戶端錯誤拋出框架例外；集中記錄並包裝未預期的失敗。
配置與環境驗證
ConfigModule.forRoot({
isGlobal: true,
load: [configuration],
validate: validateEnv,
});
- 在啟動時驗證環境變數，而不是在第一次請求時惰性驗證。
- 將配置存取保留在型別化的輔助函式或配置服務之後。
- 在配置工廠中拆分開發/暫存/生產的關注點，而不是在功能程式碼中分支。
持久化與交易
- 將儲存庫 / ORM 程式碼保留在使用領域語言的提供者之後。
- 對於 Prisma 或 TypeORM，在擁有工作單位的服務中隔離交易工作流程。
- 不要讓控制器直接協調多步驟寫入操作。
測試
describe('UsersController', () => {
let app: INestApplication;
beforeAll(async () => {
const moduleRef = await Test.createTestingModule({
imports: [UsersModule],
}).compile();
app = moduleRef.createNestApplication();
app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
await app.init();
});
});
- 使用模擬的依賴項隔離測試提供者。
- 為守衛、驗證管線和例外過濾器新增請求層級的測試。
- 在測試中重複使用與生產環境相同的全域管線/過濾器。
生產預設
- 啟用結構化日誌和請求相關性 ID。
- 遇到無效環境/配置時終止，而非部分啟動。
- 對於資料庫/快取客戶端，偏好明確健康檢查的非同步提供者初始化。
- 將背景工作和事件消費者保留在自己的模組中，而不是放在 HTTP 控制器內。
- 對公開端點明確設定速率限制、身份驗證和稽核日誌。