nest-template/README.md

NestJS Template

生產就緒的 NestJS 起始模板，內建常用基礎設施與規範，開新專案時直接 fork 使用。

技術棧

分類	套件
框架	NestJS 11
語言	TypeScript 5（ESM + NodeNext）
資料庫	PostgreSQL + TypeORM
快取	Redis（ioredis）
設定管理	@nestjs/config
驗證	class-validator + class-transformer
日誌	nestjs-pino + pino-roll
認證	@nestjs/jwt
API 文件	@nestjs/swagger
流量控制	@nestjs/throttler
資安	helmet + CORS

內建功能

• 統一回傳格式 — 所有端點自動包裝為 { code, message, data }
• 全域 JWT 驗證 — 預設所有路由需要 Bearer token，公開路由加 @Public()
• 全域 Rate Limiting — 透過環境變數設定 TTL 與上限次數
• 全域 ValidationPipe — 自動過濾多餘欄位、型別轉換，自訂錯誤訊息
• 統一例外處理 — 所有例外回傳一致的錯誤格式
• 結構化日誌 — 開發環境 pretty print，production 寫檔並自動輪替
• Swagger UI — 非 production 環境自動啟用，路徑 /api/docs
• Graceful Shutdown — 服務停止時正常關閉 DB / Redis 連線

快速開始

前置需求

• Node.js 22+
• pnpm
• PostgreSQL
• Redis

安裝

pnpm install
cp .env.example .env

編輯 .env，填入資料庫、Redis、JWT 等設定值。

啟動

# 開發模式
pnpm start:dev

# 生產模式（需先 build）
pnpm build
pnpm start:prod

環境變數

變數	說明	預設值
NODE_ENV	環境	development
PORT	監聽埠	3000
CORS_ORIGINS	允許的 CORS 來源，逗號分隔	空（全封）
DB_HOST	PostgreSQL 主機	—
DB_PORT	PostgreSQL 埠	5432
DB_USER	使用者名稱	—
DB_PASSWORD	密碼	—
DB_NAME	資料庫名稱	—
REDIS_HOST	Redis 主機	—
REDIS_PORT	Redis 埠	6379
REDIS_USER	Redis 使用者（選填）	—
REDIS_PASSWORD	Redis 密碼（選填）	—
JWT_SECRET	JWT 簽名金鑰	—
JWT_EXPIRES_IN	Token 有效期	7d
THROTTLE_TTL	Rate limit 時間窗口（毫秒）	—
THROTTLE_LIMIT	時間窗口內最大請求數	—

目錄結構

src/
├── core/               # 生命週期類別 + 基礎設施模組
│   ├── db/             # TypeORM 設定
│   ├── redis/          # Redis 設定
│   ├── logger/         # Pino 日誌設定
│   ├── throttler/      # Rate limiting 設定
│   ├── filter/         # 全域例外 filter
│   ├── interceptor/    # 回應包裝 interceptor
│   ├── guard/          # JWT guard
│   └── pipe/           # Validation exception factory
├── common/             # 跨模組共用（不掛生命週期）
│   ├── decorator/      # @Public() 等自訂裝飾器
│   ├── token/          # 注入 token 常數
│   └── type/           # 共用型別（ApiResponse、JwtPayload）
└── module/             # 業務功能模組（每個領域一個子目錄）

新業務模組放在 src/module/<模組名>/，結構參考 CLAUDE.md。

常用指令

pnpm start:dev       # 開發模式（watch）
pnpm start:debug     # 除錯模式
pnpm build           # 編譯
pnpm typecheck       # 型別檢查
pnpm lint            # Lint 檢查
pnpm format          # 格式化
pnpm test            # 單元測試
pnpm test:cov        # 測試覆蓋率
pnpm test:e2e        # E2E 測試

開發規範

詳見 CLAUDE.md。