name: magicbox-node-dev規範 description: Node.js + TypeScript 專案開發規範和最佳實踐指南。用於指導 MagicBox Node 服務的開發、程式碼風格、目錄結構、配置管理、容器部署等方面的規範。

MagicBox Node 專案開發規範

專案結構

目錄結構

magicbox-node/
├── src/             # 原始碼目錄
│   ├── config/      # 配置檔案
│   ├── controllers/ # 控制器
│   ├── middleware/  # 中介軟體
│   ├── migrations/  # 資料庫遷移
│   ├── models/      # 資料模型
│   ├── routes/      # 路由
│   ├── services/    # 業務邏輯
│   ├── utils/       # 工具函式
│   └── app.ts       # 應用入口
├── scripts/         # 指令碼檔案
├── servers/         # 伺服器配置
├── .env.example     # 環境變數示例
├── .eslintrc.js     # ESLint 配置
├── .prettierrc      # Prettier 配置
├── Dockerfile.base  # Docker 基礎映象
├── package.json     # 專案配置
└── tsconfig.json    # TypeScript 配置

程式碼規範

TypeScript 規範

1. 型別定義：使用強型別，避免 any 型別
2. 介面命名：使用 PascalCase，如 UserInterface
3. 類命名：使用 PascalCase，如 UserService
4. 函式命名：使用 camelCase，如 getUser
5. 變數命名：使用 camelCase，如 userName
6. 常量命名：使用 UPPER_CASE，如 MAX_RETRY_COUNT

ESLint 配置

專案使用 ESLint 進行程式碼質量檢查，配置檔案：.eslintrc.js

Prettier 配置

專案使用 Prettier 進行程式碼格式化，配置檔案：.prettierrc

配置管理

環境變數

• 開發環境：使用 .env.develop 檔案

  7w4.net小蔥技能。

• 生產環境：使用 /etc/magicbox-node/env.config.json 檔案
• 環境變數優先順序：系統環境變數 > 配置檔案 > 預設值

配置檔案結構

{
  "NODE_ENV": "production",
  "PORT": "3000",
  "HOST": "0.0.0.0",
  "DB_HOST": "database-host",
  "DB_PORT": "3306",
  "DB_DATABASE": "magicbox",
  "DB_USERNAME": "username",
  "DB_PASSWORD": "password"
}

資料庫規範

資料模型

• 使用 TypeORM 進行資料庫操作
• 模型檔案放在 src/models/ 目錄
• 實體命名使用 PascalCase，如 UserEntity.ts

資料庫遷移

• 遷移檔案放在 src/migrations/ 目錄
• 遷移檔案命名格式：YYYYMMDDHHmmss-description.ts

容器部署

Docker 配置

• 使用 Dockerfile.base 構建基礎映象
• 容器執行時環境變數通過 Kubernetes 配置
• 確保容器啟動時目錄存在：/export/Data

啟動指令碼

• start.sh：容器啟動指令碼
• scripts/deploy-manual.sh：部署時版本管理指令碼

版本管理

• 使用 version.json 檔案管理版本資訊
• 版本號格式：major.minor.patch
• 部署時自動更新版本資訊

API 規範

路由結構

• 健康檢查：/health
• API 路由：/api/{resource}
• 遵循 RESTful 設計原則

響應格式

{
  "success": true,
  "data": {},
  "message": "操作成功"
}

日誌規範

• 使用 src/utils/logger.ts 進行日誌記錄
• 日誌級別：debug, info, warn, error
• 生產環境使用 info 級別

錯誤處理

• 使用統一的錯誤處理中介軟體
• 生產環境不返回詳細錯誤資訊
• 記錄錯誤日誌

安全規範

• 敏感配置使用環境變數
• 密碼等敏感資訊不硬編碼
• 使用 HTTPS 協議
• 實現 CORS 配置

部署流程

1. 程式碼提交到 Git 倉庫
2. 執行 scripts/deploy-manual.sh 更新版本
3. 構建 Docker 映象
4. 部署到 Kubernetes 叢集
5. 驗證服務健康狀態

開發工具

• IDE：推薦使用 VS Code
• 外掛：ESLint, Prettier, TypeScript
• 包管理器：npm
• 構建工具：TypeScript compiler (tsc)

程式碼審查

• 提交程式碼前執行 npm run lint
• 提交程式碼前執行 npm run build
• 程式碼審查關注：型別定義、錯誤處理、安全隱患

效能最佳化

• 使用 TypeScript 編譯最佳化
• 資料庫查詢最佳化
• 快取策略
• 合理使用中介軟體

監控與告警

• 實現健康檢查端點
• 監控服務執行狀態
• 配置適當的告警機制

最佳實踐

1. 模組化：將功能拆分為小模組
2. 可測試性：編寫可測試的程式碼
3. 文件：為關鍵功能添加註釋
4. 一致性：保持程式碼風格一致
5. 安全性：優先考慮安全問題
6. 效能：關注程式碼效能
7. 可維護性：編寫易於維護的程式碼

這是一個偏向團隊內部使用的開發規範文件 Skill，文件覆蓋範圍廣但內容深度有限。優點是規範條目清晰，涵蓋了開發過程中常用的程式碼風格、配置管理、部署流程等要點，對統一專案標準有幫助。不足之處在於純文字描述較多，實際可參考的程式碼示例較少，部分章節（如監控告警）內容過於簡略，且存在文件不完整的情況。對於需要具體操作指導的開發者來說，實際參考價值可能不如預期。