---
name: backend-server-playbook
description: Use when designing, changing, or debugging backend server code (REST, Node.js/TypeScript, Go), especially endpoints, response envelopes, pagination, migrations, queries, auth, password hashing, secrets, or deploys; also for N+1 queries, races, IDOR, SSRF/injection, goroutine leaks, unhandled rejections, event-loop blocking, graceful shutdown, or production-only migration failures.
---

> 🌐 [English version](https://github.com/tienenwu/fables/blob/main/en/backend-server/SKILL.md) · 繁體中文（正本 / canonical）

# 後端 Server 開發判準手冊

主線為 Node.js/TypeScript；Go 為獨立參考檔（references/go.md），帶著 Node/TS 思維寫 Go 的坑集中在那。

## 核心原則

1. **邊界不信任、內層信任型別**：所有外部輸入（HTTP body、query、DB 以外的來源）只在進入邊界時驗一次（zod/struct tag），驗過就相信型別，內層不重複防禦性檢查。
2. **狀態碼與錯誤格式是 API 契約**：狀態碼不是裝飾，用錯（把 403 當 404、把驗證失敗回 500）會讓呼叫端無法自動化處理；錯誤一律走單一 envelope 含 machine-readable code。
3. **交易邊界＝一個請求內、一個一致性單位**：跨請求維持交易是紅線；一個 HTTP 請求對應一個交易，出邊界即提交或回滾。
4. **本機綠燈不算數的東西**：graceful shutdown、migration 順序、連線池耗盡、時區、secrets 遮罩——這些只在部署/高併發才爆，本機零證據力。
5. **並發下沒有「應該不會同時發生」**：check-then-act 一定要用 DB 約束、樂觀鎖或 `SELECT FOR UPDATE` 收斂，不能靠「先查再寫中間沒人插入」的祈禱。

## 開工分流

| 情境 | 路徑 | 先讀 |
|------|------|------|
| 設計/改 endpoint、狀態碼、錯誤格式、分頁、冪等 | 先定契約再寫 handler | references/api-design.md |
| 寫 query、加 index、交易、migration | 先問鎖與相容性，再動 schema | references/data-layer.md |
| 列表變慢、query 數暴增 | 不要先加快取，先查 N+1 | references/data-layer.md §N+1 |
| 登入、授權、密碼、token、secrets | 逐條對紅線 | references/auth-security.md |
| Node/TS 的 async、型別、event loop、依賴 | 查傳播模式與邊界驗證 | references/node-ts.md |
| 寫 Go（尤其剛從 Node/TS 過來） | 先讀「Node 思維會踩的坑」 | references/go.md |
| 出 release / 部署 / 改啟動流程 | 逐條跑必查清單 | references/release-checklist.md |
| 部署後才爆、本機正常 | 先假設 shutdown/migration 順序/連線池/env | references/release-checklist.md |

## 紅線（絕對禁止）

- **禁止跨 HTTP 請求持有開著的 DB 交易**——連線被一個使用者鎖住，連線池很快耗盡，全服務 hang。
- **禁止對驗證失敗、找不到、沒權限一律回 500 或一律回 200**——狀態碼是契約，呼叫端靠它決定重試/報錯/導登入。
- **禁止用可逆 hash 或 SHA-256 存密碼**——必須 bcrypt/argon2id；外洩時可逆 hash 等於明文。
- **禁止 secrets 進 git、進日誌、進錯誤回應**——一次 commit 就永久外洩（git 歷史），token 進 logcat/APM 是真實資安事故。
- **禁止 Go 裡 `_ = err` 或空 `if err != nil {}` 吞錯**——每個 error 都要決定處理/包裝上拋/真的可忽略，吞掉＝把生產故障變成靜默資料損毀。
- **禁止 migration 用「先刪舊欄位／改名」一步到位**——舊版程式還在跑時就讀不到欄位，部署窗口內 500 風暴；一律先加後刪兩步走。
- **禁止改測試斷言讓 CI 變綠**——連紅兩次是方向錯誤訊號，退回上一決策點。

## 失敗訊號（該回頭，不是重試）

| 徵兆 | 多半是 | 退回 |
|------|--------|------|
| 每修一個慢 query 又冒出下一個 | ORM lazy-load 造成 N+1，逐條治標 | 改 eager load / batch，見 data-layer §N+1 |
| 競態修了還偶發，加了更多 re-check | check-then-act 沒收斂到 DB 層 | 改約束/樂觀鎖/FOR UPDATE |
| 部署就有一小段 5xx 尖峰 | 沒有 graceful shutdown 或 migrate/deploy 順序錯 | release-checklist §shutdown/順序 |
| 連線池 timeout 偶發於高峰 | 交易開太久或池太小/太大 | data-layer §交易、release §連線池 |
| Go 服務記憶體緩慢上漲 | goroutine 洩漏（沒人讀的 channel、缺 context 取消） | go.md §goroutine 洩漏 |
| catch/error 分支越加越多才不炸 | 錯誤沒在邊界統一，散落各層 | node-ts §錯誤傳播 / go.md §error |

## references 索引

- `references/api-design.md` — 狀態碼裁決表、錯誤 envelope、分頁、冪等、timeout/重試責任、破壞性變更兩步走。設計 API 前讀。
- `references/data-layer.md` — 交易邊界、N+1 決策、migration 安全、何時加 index、競態條件。動 DB 前讀。
- `references/auth-security.md` — session vs JWT、密碼雜湊、輸入驗證位置、secrets、rate limit、OWASP 三重點。碰 auth/安全就讀。
- `references/node-ts.md` — event loop 阻塞、async 錯誤傳播、型別邊界、any 紅線、依賴選擇。寫 Node/TS 前讀。
- `references/go.md` — 帶 Node/TS 思維寫 Go 的坑 + Go 自身判準（error、goroutine、nil interface、context、channel、專案結構）。寫 Go 前讀。
- `references/release-checklist.md` — graceful shutdown、健康檢查、migration 順序、日誌遮罩、fail-fast、連線池、時區。出版前逐條打勾。
- `references/test-scenarios.md` — 判準測驗集，驗證接手模型是否照走。不給執行中的模型讀。