backend-server-playbook

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 · 繁體中文（正本 / 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 — 判準測驗集，驗證接手模型是否照走。不給執行中的模型讀。