fullstack-dev

全端開發最佳實踐

強制執行工作流程 — 請嚴格按順序執行以下步驟

當觸發此 Skill 時，在撰寫任何程式碼之前，你「必須」嚴格遵循此工作流程。

步驟 0：收集需求

在建立任何專案骨架之前，請先向使用者確認（或從上下文推導）：

1. 技術棧（Stack）：前後端使用的語言與框架（例如：Express + React、Django + Vue、Go + HTMX）
2. 服務類型：純 API、全端單體架構（Monolith）還是微服務（Microservice）？
3. 資料庫：SQL（PostgreSQL、SQLite、MySQL）還是 NoSQL（MongoDB、Redis）？
4. 整合方式：REST、GraphQL、tRPC 還是 gRPC？
5. 即時通訊：是否需要？若需要 — 使用 SSE、WebSocket 還是 Polling（輪詢）？
6. 身份驗證（Auth）：是否需要？若需要 — 使用 JWT、Session、OAuth 還是第三方服務（Clerk、Auth.js）？

若使用者已在需求中明確說明，可跳過詢問直接繼續。

步驟 1：架構決策

根據需求，在撰寫程式碼前先做出並說明以下決策：

架構決策	可選方案	參考章節
專案結構	功能導向 Feature-first（推薦）vs 圖層導向 Layer-first	第 1 節
API 客戶端方案	Typed fetch / React Query / tRPC / OpenAPI codegen	第 5 節
身份驗證策略	JWT + refresh / Session / 第三方服務	第 6 節
即時通訊方式	Polling / SSE / WebSocket	第 11 節
錯誤處理	型別化錯誤階層 + 全域處理常式	第 3 節

簡要解釋每個選擇（每個決策說明 1 句話）。

步驟 2：對照檢查清單建立骨架

使用下方對應的檢查清單。確保所有勾選項均已實作 — 請勿漏掉任何一項。

步驟 3：遵循設計模式進行實作

遵循本文中的設計模式撰寫程式碼。在實作各個模組時，請參考對應的具體章節。

步驟 4：測試與驗證

實作完成後，在宣告完成前請先執行以下檢查：

1. 建置檢查：確保前後端均能無錯編譯

   # 後端 Backend
   cd server && npm run build
   # 前端 Frontend
   cd client && npm run build
   

2. 啟動與冒煙測試：啟動伺服器，驗證核心 API 端點是否回傳預期結果

   # 啟動伺服器，然後進行測試
   curl http://localhost:3000/health
   curl http://localhost:3000/api/<resource>
   

3. 前後端整合檢查：驗證前端是否能正常連線至後端（CORS、API Base URL、身份驗證流程）
4. 即時功能檢查（若適用）：開啟兩個分頁，驗證資料變更是否即時同步

若有任何檢查未通過，請先修復問題再繼續。

步驟 5：交付總結

向使用者提供一份簡要總結：

• 已實作內容：已完成的功能與 API 端點清單
• 如何執行：啟動前後端的精確指令
• 待完善事項 / 後續步驟：延後處理的事項、已知限制或建議改進點
• 關鍵檔案：使用者需要了解的核心檔案清單

---

適用範圍

符合以下情境時使用此 Skill：

• 開發全端應用程式（後端 + 前端）
• 建置全新的後端服務或 API 骨架
• 設計服務層（Service Layer）與模組邊界
• 實作資料庫存取、快取或背景任務（Background Jobs）
• 撰寫錯誤處理、日誌紀錄（Logging）或設定檔管理
• 審查後端程式碼的架構問題
• 進行正式生產環境的安全與效能強化
• 設定 API 客戶端、身份驗證流程、檔案上傳或即時通訊功能

不適用於以下情境：

• 純前端 / UI 層面需求（請參考你使用的前端框架文件）
• 不涉及後端上下文的純資料庫 Schema 設計

---

快速上手 — 全新後端服務檢查清單

• [ ] 專案採用**功能導向（Feature-First）**結構建立骨架
• [ ] 設定檔集中管理，環境變數在啟動時完成驗證（Fail-Fast 快速失敗機制）
• [ ] 定義型別化的錯誤階層結構（而非使用通用的 Error）
• [ ] 配置全域錯誤處理中介軟體（Middleware）
• [ ] 實作結構化 JSON 日誌並傳遞 Request ID
• [ ] 資料庫：建立遷移（Migrations）機制，配置連線池（Connection Pooling）
• [ ] 所有 API 端點均實作輸入驗證（Zod / Pydantic / Go validator）
• [ ] 設定好身份驗證中介軟體
• [ ] 提供健康檢查端點（/health、/ready）
• [ ] 實作**優雅停機（Graceful Shutdown）**機制（處理 SIGTERM）
• [ ] 設定 CORS（指定明確的 Origin 來源，嚴禁使用 *）
• [ ] 配置安全標頭（Security Headers）（如 Helmet 或同等套件）
• [ ] 提交 .env.example（不包含任何真實敏感資訊）

快速上手 — 前後端整合檢查清單

• [ ] 設定好 API 客戶端（具有型別定義的 Fetch 封裝、React Query、tRPC 或 OpenAPI 產生的程式碼）
• [ ] Base URL 來自環境變數（禁止硬編碼）
• [ ] 身份驗證 Token 自動附加至請求（Interceptor / 中介軟體）
• [ ] 錯誤處理 — 將 API 錯誤對射為使用者易懂的提示訊息
• [ ] 處理 Loading 狀態（使用 Skeleton 骨架屏 / Spinner 載入圖示，避免白屏）
• [ ] 跨邊界保持型別安全（共用型別定義、OpenAPI 或 tRPC）
• [ ] CORS 配置明確的 Origin 來源（正式生產環境嚴禁 *）
• [ ] 實作 Refresh Token 流程（httpOnly Cookie + 收到 401 時無感重試）

---

快速導覽

需求情境	跳轉至
組織專案資料夾	1. 專案結構與分層架構
管理設定檔與金鑰	2. 設定檔與環境變數
正確處理錯誤	3. 錯誤處理與韌性
撰寫資料庫程式碼	4. 資料庫存取模式
在前端設定 API 客戶端	5. API 客戶端模式
加入身份驗證中介軟體	6. 身份驗證與中介軟體
設定日誌紀錄	7. 日誌與可觀測性
加入背景任務	8. 背景任務
實作快取	9. 快取模式
檔案上傳（Presigned URL, Multipart）	10. 檔案上傳模式
新增即時功能（SSE, WebSocket）	11. 即時通訊模式
在前端 UI 處理 API 錯誤	12. 跨邊界錯誤處理
生產環境安全強化	13. 生產環境強化
設計 API 端點	API 設計
設計資料庫 Schema	資料庫 Schema
身份驗證流程（JWT、Refresh、Next.js SSR、RBAC）	references/auth-flow.md
CORS、環境變數與環境管理	references/environment-management.md

---

核心原則（7 大鐵律）

1. ✅ 按「功能（Feature）」組織專案，而非按技術分層
2. ✅ Controller 嚴禁包含商業邏輯
3. ✅ Service 嚴禁匯入 HTTP request/response 型別
4. ✅ 所有設定皆來自環境變數，並在啟動時完成驗證（Fail-Fast）
5. ✅ 所有錯誤皆經過型別化、記錄日誌並回傳統一格式
6. ✅ 所有輸入皆在邊界完成驗證 — 絕不信任來自客戶端的任何資料
7. ✅ 採用附帶 Request ID 的結構化 JSON 日誌 — 嚴禁使用 console.log

---

1. 專案結構與分層架構（關鍵）

功能導向結構（Feature-First）

✅ Feature-first（功能導向）       ❌ Layer-first（技術分層）
src/                                src/
  orders/                             controllers/
    order.controller.ts                 order.controller.ts
    order.service.ts                    user.controller.ts
    order.repository.ts               services/
    order.dto.ts                        order.service.ts
    order.test.ts                       user.service.ts
  users/                              repositories/
    user.controller.ts                  ...
    user.service.ts
  shared/
    database/
    middleware/

三層架構

Controller (HTTP 層) → Service (商業邏輯層) → Repository (資料存取層)

分層	職責	❌ 嚴禁行為
Controller	解析請求、輸入驗證、呼叫 Service、格式化回應	撰寫商業邏輯、直接進行 DB 查詢
Service	實作商業規則、流程編排、事務管理（Transaction）	引入 HTTP 型別（req/res）、直接存取 DB
Repository	執行資料庫查詢、呼叫外部 API	撰寫商業邏輯、引入 HTTP 型別

依賴注入（Dependency Injection，適用於所有語言）

TypeScript:

class OrderService {
  constructor(
    private readonly orderRepo: OrderRepository,    // ✅ 注入介面（Interface）
    private readonly emailService: EmailService,
  ) {}
}

Python:

class OrderService:
    def __init__(self, order_repo: OrderRepository, email_service: EmailService):
        self.order_repo = order_repo                 # ✅ 注入依賴
        self.email_service = email_service

Go:

type OrderService struct {
    orderRepo    OrderRepository                      // ✅ 介面（Interface）
    emailService EmailService
}

func NewOrderService(repo OrderRepository, email EmailService) *OrderService {
    return &OrderService{orderRepo: repo, emailService: email}
}

---

2. 設定檔與環境變數（關鍵）

集中化、型別化、快速失敗（Fail-Fast）

TypeScript:

const config = {
  port: parseInt(process.env.PORT || '3000', 10),
  database: { url: requiredEnv('DATABASE_URL'), poolSize: intEnv('DB_POOL_SIZE', 10) },
  auth: { jwtSecret: requiredEnv('JWT_SECRET'), expiresIn: process.env.JWT_EXPIRES_IN || '1h' },
} as const;

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing required env var: ${name}`);  // 快速失敗（Fail-Fast）
  return value;
}

Python:

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str                        # 必填項目 — 若未提供應用程式將無法啟動
    jwt_secret: str                          # 必填項目
    port: int = 3000                         # 選填項目，附帶預設值
    db_pool_size: int = 10
    class Config:
        env_file = ".env"

settings = Settings()                        # 若缺少 DATABASE_URL 則立即拋錯（Fail-Fast）

守則

✅ 所有設定皆透過環境變數管理（符合 Twelve-Factor 原則）
✅ 啟動時驗證必要的環境變數 — 快速失敗（Fail-Fast）
✅ 在設定檔層完成型別轉換，而非在調用處轉換
✅ 提交包含虛擬值的 .env.example

❌ 嚴禁將敏感金鑰、URL 或憑證寫死在程式碼中（Hardcode）
❌ 嚴禁提交 .env 檔案
❌ 嚴禁在程式碼各處散落 process.env 或 os.environ

---

3. 錯誤處理與韌性（高）

型別化錯誤階層結構

// Base (TypeScript)
class AppError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly statusCode: number,
    public readonly isOperational: boolean = true,
  ) { super(message); }
}
class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super(`${resource} not found: ${id