Hao程式筆記

Web Day 44 專案：文件與交接 執行需求：CPU 可跑 。Stack、監控、備份、壓測都做完了，今天要把這套預約管理系統變成「可以被別人接手」的狀態。今天要做四件事：第一，寫一份 README.md（開發者上手指南、安裝指令、常用操作）；第二，寫一份 runbook.md（事件處置手冊：磁碟滿、PostgreSQL 沒起來、API 5xx 飆升時的 step-by-step 復原流程）；第三，整理一份 OpenAPI 規格摘要（從 FastAPI 0.116 的 /openapi.json 自動生成）；第四，把 Day 40 的驗收清單（acceptance checklist）升級為正式上線文件，列為 PR 模板的一部分。所有文件都用 Markdown 寫，UTF-8 編碼，繁體中文（術語沿用 README 的台灣用語對照表）；資料仍是虛構示範。今天是 Day 45 系列總結前的倒數第二天，把整套 stack 的可維運性做最後一次打磨。 引言 「寫文件」是工程師最常拖延的工作，原因是「現在沒時間」與「以後再寫」。但真正出事的時候，文件就是工程師最重要的武器：一份結構完整的 runbook 能讓接手的人凌晨三點不必打電話給原作者就能復原系統；一份更新過的 README 能讓新人第一天就上手。這些文件不是「bonus」，而是 production 系統的基本配備。 貫穿專案的預約管理系統是小型服務業線上預約平台（情境涵蓋攝影棚、健身教練、諮詢工作室，所有資料都是虛構示範）。經過 Day 35–43，我們已經有了：可跑的 stack（Docker Compose v2、PostgreSQL 17、FastAPI 0.116、Caddy 2.8）；可監控（ /metrics 、JSON log）；可備份（每日 pg_dump + 還原演練）；可壓力測試（locust + 純 Python）；可驗收（8 支 E2E + 驗收清單）。這些成果沒有文件，就只是「在原作者電腦裡跑得動」；有了文件，才是「可以被別人接手」的系統。 今天的內容分四段：第一段說明文件化策略（哪些文件、給誰看、如何維護）；第二段寫 README.md 與 RUNBOOK.md 的範本；第三段用 Python 腳本從 /openapi.json 自動產生 API 規格摘要；第...

Web Day 45 系列總結與延伸路線 執行需求：CPU 可跑 。今天是「Web 系統實戰：用 FastAPI 打造能上線的後端」45 篇系列的最後一篇。我們從 Day 1 的 FastAPI hello world 起步，用七個主題區塊（導論、基礎、安全、品質、前端整合、上線、貫穿專案）走到 Day 44 的 runbook 與交接文件，最後用 Day 45 這篇把整個路徑索引起來，並列出三條值得繼續深入的延伸學習方向：分散式系統、可觀察性棧、與團隊工程化。整個系列用「預約管理系統」做貫穿專案，把資料模型、衝突檢查、HTMX 後台、Docker Compose 部署、Prometheus 監控、locust 壓測、runbook 交接都走過一輪。所有資料都是虛構示範，目的是讓你在沒有真實客戶資料的情況下也能練完整個流程。本文是系列的收束、不是結束，後續建議的延伸內容才是真正的下一段路。 引言 回顧整個 45 天的學習地圖，我們從 Day 1 的「為什麼需要從腳本走到系統」開始，一路建到 Day 35–44 的「預約管理系統 end-to-end 可上線」。這不是一條單一路徑，而是七個主題區塊互相交織的學習旅程：基礎（Day 3–10）讓你會寫 HTTP API；安全（Day 11–15）讓你會保護使用者資料；品質（Day 16–22）讓你會寫測試、跑背景任務、寫日誌；前端整合（Day 23–28）讓你會把 API 接到介面上；上線（Day 29–34）讓你會用 Docker 部署、寫 CI、設監控；貫穿專案（Day 35–44）則把這些全部串起來，每天解決一個現實問題。 這個系列刻意只用 2025 年 7 月之前已存在且具知名度的工具：Python 3.13、FastAPI 0.116、SQLModel 0.0.24、PostgreSQL 17、Redis 8、HTMX 2.0、Next.js 15、Streamlit 1.46、Docker Compose v2、locust 2.3。我們不教你追逐新框架，而是教你把這些穩定的主流工具用到能撐 production。這也是讀者從「會寫腳本」走到「能獨立上線後端」需要的最短路徑。 今天的內容分四段：第一段把 45 天的學習地圖索引起來；第二段列出三條延伸學習方向；第三段用一支 Python 腳...

Web Day 43 專案：壓力測試與效能調校 執行需求：CPU 可跑 。昨天的監控日誌備份做完，stack 可以撐一段時間。今天要把這套 stack 真正拿去「壓」一下，找出容量邊界：在不同併發等級下，這套預約管理系統每秒能回應多少 request、P50 / P95 延遲落在哪裡、哪條端點最先撐不住。我們要用 locust 2.3 寫一隻壓測腳本（模擬「瀏覽可預約時段」、「建立預約」、「管理者確認」三種典型行為），再用 httpx 0.28 + asyncio 寫一隻純 Python 版壓測工具（方便併入 pytest 與 CI）。所有數字都會標「實際數字會略有不同」，因為硬體、PostgreSQL 設定、API 內容都會影響結果。今天也會用 Day 42 的 metrics 端點，把壓測期間的 QPS、P95、錯誤率一起抓出來，產出一份可重現的容量報告。所有資料延續 Day 35–42 的虛構示範。 引言 效能調校是「沒有測量就沒有改善」這句話的最佳示範。在沒壓測之前，工程師對「這套 API 能撐多少」通常只有模糊的印象；壓測一跑，結果往往令人意外：原本以為很穩的 endpoint 反而第一個掛掉、以為會很慢的查詢其實飛快、以為資料庫是瓶頸結果真的是、但不是預期的那個查詢卡住而是 index 沒命中。這些訊息只有「真的去壓」才會浮現。 貫穿專案的預約管理系統是小型服務業線上預約平台（情境涵蓋攝影棚、健身教練、諮詢工作室，所有資料都是虛構示範）。它的三條主要路徑：使用者查可預約時段（GET）、使用者下訂（POST /bookings）、管理員確認（POST /admin/bookings/{id}/confirm）。前兩者是公開 API、第三條是後台行為。我們今天會用 locust 與 httpx 並發模擬真實流量：60 秒內 50 個虛擬使用者（users）每 1–2 秒送一個 request，觀察 QPS、P95、錯誤率，找出可以調校的空間。 今天的內容分四段：第一段說明 locust 與 httpx 並發的差異、各自適合的場景；第二段寫 locustfile 模擬三種典型行為；第三段寫純 Python 壓測腳本（含 asyncio gather）併入 pytest；第四段讀 /metrics 、寫一份可重現的容量報告。讀完這篇你會了解：...

Web Day 42 專案：監控、日誌與備份 執行需求：CPU 可跑 。昨天的 Docker Compose 把服務跑起來了，今天要把「這個服務還活著嗎」、「有沒有人出錯」、「資料庫能不能還原」三件事變成可自動化的常駐腳本。今天要做四件事：第一，用 Python 標準庫的 logging 寫結構化 JSON log（每行一個 JSON 物件，欄位統一，方便 log collector 解析）；第二，用 FastAPI 寫 /metrics 端點，回傳 Prometheus exposition format 文字（含 API 呼叫次數、延遲直方圖、錯誤次數）；第三，寫一支 PostgreSQL 備份腳本（ pg_dump + 日期檔名 + 保留 14 天 + 上傳到本地 backup 目錄），並用 cron 排程每天 03:00 跑；第四，用 pytest 寫兩支測試驗證 log 格式與 metrics 端點。整個 stack 加進來後仍然在 CPU 上跑得動，所有資料都是虛構示範。這也是 Day 43 壓力測試前的基本功。 引言 「系統跑起來」與「系統能維運」是兩件事。前者只看能不能回應 API、能不能寫進資料庫；後者要求出問題時三分鐘內定位、十分鐘內復原、資料遺失量小於一小時。差異全在監控、日誌、備份三件事：監控告訴你「現在有沒有事」、日誌告訴你「事發當時發生什麼」、備份告訴你「資料還救得回來」。三者缺一不可：少了監控你會半夜被叫醒、少了日誌你會兩小時抓不到 root cause、少了備份你會在某次硬碟損壞後失去所有訂單。 貫穿專案的預約管理系統是小型服務業線上預約平台（情境涵蓋攝影棚、健身教練、諮詢工作室，所有資料都是虛構示範）。我們的監控需求非常具體：API 200/4xx/5xx 計數、P50/P95 延遲、活躍預約數、通知佇列長度。日誌需求：每行 JSON、有 request_id、能 trace 一個 request 從進入到結束。備份需求：每日 03:00 跑 pg_dump 、保留 14 天、檔名含日期。這些工業界的標配，今天會在小型專案規模上完整實現一遍。 今天的內容分四段：第一段說明結構化 log 的設計；第三段寫 Prometheus metrics 端點；第三段寫 PostgreSQL 排程備份與復原演練腳本；第四...