後端開發

症狀：資料明明在，前端就是拿不到 一個 CMS 系統的文件列印預覽，每份文件 header 都固定顯示「上傳者：—」。DB 裡明明有資料，API 回 HTTP 200 OK，回應裡的其他欄位（日期、文件類型、附件）都對——唯獨 uploadedBy 是 null。 沒錯誤、沒警告，伺服器 log 也乾淨。前端碰到 uploadedBy?.realName || '-' 就乖乖畫 dash。使用者以為這份文件沒指派擁有者，作者本人以為畫面壞了。大家都錯，但系統看起來好好的。 這是最難纏的 bug——靜默失敗。 先看 ORM 層在整個架構哪裡 要理解為什麼這類 bug 發生、也為什麼解法是「繞過 ORM」，先把架構分層看清楚： 為什麼 bug 只會發生在 ORM 層？ 上面的業務邏輯只負責說「給我文件，順便帶上傳者」——它不知道要怎麼 JOIN。下面的 DB 只回應被問到的 SQL——你沒 SELECT 的欄位它不會主動給你。只有 ORM 層有權力決定「要翻譯成什麼 SQL」，也只有它遇到不會處理的組合時，會選擇「悄悄回你 null」而不是「拋錯給你看」。 這就是為什麼靜默失敗只會出現在這一層。 用 curl 逼它露餡 把 query 簡化到只剩 filter + populate 兩件事，一個一個比對： # A: 用 id filter → 關聯欄位變 null ❌ curl "$URL?filters[owner][id][\$eq]=3807&populate[uploadedBy]=true" # { "uploadedBy": null } # B: 用 documentId filter → 關聯正常回來 ✅ curl "$URL?filters[owner][documentId][\$eq]=abc123&populate[uploadedBy]=true" # { "uploadedBy": { "id": 85, "realName": "J. Chen" } } 同樣的 populate、同樣的文件集合，差別只在「怎麼辨認 owner」。這種事應該是 ORM 內部細節，對使用者不該有差。但就是有。 ...

Symptom: A Relation Everyone Believes Is Empty A document management print preview kept rendering “Uploader: —” for every report. The database had the data. The API returned HTTP 200 OK. Yet the uploadedBy relation came back as null, with no error or warning anywhere. Users assumed reports had no uploader assigned. Authors assumed the UI was broken. Nobody suspected the API, because it was perfectly silent. Where the Bug Lives in the Stack Before the curl session, it helps to fix where the failure happens: ...

問題現場：一個「成功」卻收不到信的忘記密碼 某個週一下午，QA 回報：在一個 Flutter + Strapi 架構的 App 上，用測試帳號 testuser@example.com 點「忘記密碼」，畫面跳出 Success: Reset password link sent successfully on your email account.，但信箱（包含垃圾郵件匣）一封信都沒有。 直覺先排除幾個明顯可能：SMTP 設定壞掉、用戶被 block、信件被 Gmail 擋。但真正的答案比這些都有趣 — 這不是 bug，是 Strapi 一個刻意的安全設計，只是 App 前端把它翻譯錯了。 kubectl 診斷：20ms 與 800ms 的兩種人生 進 Strapi pod 撈 log，找 forgot-password 請求： kubectl logs -n default strapi-prod-xxxxxxxxx-xxxxx --since=6h \ | grep -E 'forgot-password|Reset password URL' 抽出的關鍵幾行： 04:04:52 info: Reset password URL generated: https://example.com/... 04:04:53 http: POST /api/auth/forgot-password (948 ms) 200 05:15:44 http: POST /api/auth/forgot-password (20 ms) 200 05:16:53 info: Reset password URL generated: https://example.com/... 05:16:54 http: POST /api/auth/forgot-password (664 ms) 200 05:17:30 http: POST /api/auth/forgot-password (26 ms) 200 一眼看出兩種節奏：800ms 級別的請求伴隨「Reset password URL generated」log，而 20-30ms 的請求則完全沒有。同一支 API，為什麼耗時差 30 倍？ ...

症狀：選完手機照片，畫面卻還是貼圖 使用者回報的步驟很簡單：點頭像 → 選「從手機圖庫」→ 選張照片 → 儲存。跳回會員中心，頭像還是原本的系統貼圖。 再點進去編輯頁，看到的又是手機照片。明明存成功了，為什麼 UI 顯示不一致？ 這個 bug 表面上是前端畫面問題，但用 log 逼出來的真相，藏在三層之外——包括一個會在幾乎所有 admin-panel 型後端都出現的經典陷阱。 偵錯：跟著 log 走，別信錯誤訊息 第一步是打開前端 log 重現流程。關鍵幾行： StickerService -> Deactivating all stickers StickerService -> Error: status code of 403 StickerService -> Error Response: {status: 403, message: Forbidden} StickerService -> Deactivate all failed: You do not own this sticker 最後這句「You do not own this sticker」幾乎讓我停在錯誤方向——去查使用者到底擁有哪幾個貼圖。但翻前端程式碼才發現：那不是後端回的訊息，是前端 _handleDioError 把「403 Forbidden」硬翻譯成這句。 **這是第一個教訓：HTTP 狀態碼與文字訊息之間的語意對應是會說謊的。**真正的錯誤只有一個字——Forbidden。跟 ownership 無關，純粹是權限問題。 第一層根因：Admin Panel 的權限設定漂移 翻 Strapi admin → Settings → Users & Permissions → Roles → Authenticated → Sticker section，發現 deactivateAll 這支 route 的權限沒勾。 ...

前言：手動維護 53 種食物的極限 我正在開發一款健康追蹤 App，核心功能之一是飲食記錄。一開始，食物資料庫是手動維護的 JSON — 53 種台灣常見小吃，從滷肉飯到珍珠奶茶。 53 種夠用嗎？使用者搜尋「鮭魚」找不到、搜尋「優格」找不到、搜尋「oatmeal」更不用說。手動新增不可能跟上需求，我需要一條自動化管線，把全世界的食物營養資料拉進來。 這就是 ETL 管線登場的時機。 什麼是 ETL？用食物資料庫解釋 ETL 是 Extract（擷取）、Transform（轉換）、Load（載入） 的縮寫，是資料工程最基礎的設計模式。與其抽象解釋，直接用這個專案的食物資料庫來看： 四個來源的原始資料格式完全不同 — 台灣用中文欄位名（粗蛋白）、日本用 FAO 代碼（prot）、USDA 用數字編號（203）。Transform 階段把它們統一成 App 需要的 {id, name, emoji, category, nutrition} 結構。 為什麼不直接在 App 端串接 API？因為食物營養資料是靜態的 — 雞蛋的蛋白質含量不會每天變。離線 JSON 零延遲、不吃流量、無網路也能用。ETL 只在開發階段跑一次，產出的 JSON 跟著 App 一起發布。 USDA API 的格式陷阱：同一個服務，兩套規則 USDA FoodData Central 是美國農業部的食物營養資料庫，涵蓋近 8,000 種食物。我選擇 foods/list endpoint 批量下載 SR Legacy 和 Foundation Foods 資料。 然而，這個 API 有一個文件沒有明確說明的陷阱：foods/list 和 foods/search 兩個 endpoint 回傳的營養素格式完全不同。 ...

症狀：App 開啟 15 分鐘後被強制登出 使用者回報一個詭異的問題：App 正常使用一段時間後，突然被強制登出。重新登入後又好了，但過一陣子又被踢出去。 時間規律很明確——正好 15 分鐘。這恰好是我們 JWT 的過期時間。 直覺反應是去查前端的 token refresh 邏輯：interceptor 有沒有正確攔截 401？refresh token 有沒有正確儲存？重試機制有沒有 bug？ 查了一輪，全部正常。 錯誤的除錯方向 這個問題前前後後花了不少時間，方向一直在前端打轉： 排查方向 結果 Flutter interceptor 邏輯 正常，有攔截 401 並觸發 refresh Token 儲存機制（SecureStorage） 正常，refresh token 有正確保存 JWT 過期時間設定 確認是 15 分鐘，符合預期 網路連線問題 排除，其他 API 都正常 每個環節看起來都沒問題，但結果就是 refresh 失敗。問題出在哪？ 轉折點：看 HTTP Status Code 直到有人（或者說，終於有人）去看了 /auth/refresh 實際回傳的 HTTP status code： # JWT 過期後呼叫 refresh curl -X POST https://api.example.com/api/auth/refresh \ -H "Content-Type: application/json" \ -d '{"refreshToken": "valid-refresh-token-here"}' # 預期：200 OK（新的 JWT） # 實際：403 Forbidden 403，不是 401。 ...

前言：當 Banner 在眾目睽睽下消失 如果你曾經盯著一個「昨天還好好的」功能，然後花了幾小時才發現問題根本不在你想的地方——恭喜你，你已經正式成為資深工程師了。 這次的主角是一個 Flutter App 的首頁輪播 Banner。用戶回報說「Banner 不見了」，而我的第一反應是：「一定是最近的 commit 搞壞的！」 （劇透：不是。） 第一階段：追蹤嫌疑犯 嫌疑人一號：最近的 Git Commit 最近剛好有一個 commit 修改了後端的 middleware，用來處理認證相關的端點。自然而然，我先從這裡開始查： git show abc123 # fix: add middleware to strip auth header for public endpoints 看起來這個 middleware 只處理 /api/auth/forgot-password 這類認證端點，跟 Banner API 完全無關。 結論：無罪釋放。 嫌疑人二號：Strapi 權限設定 接下來檢查 Strapi Admin 的權限設定。Public 角色的 app-home-page 權限： 角色 find 權限 Authenticated ✅ 已開啟 Public ✅ 已開啟 權限設定完全正確。 結論：也不是兇手。 第二階段：真相大白 測試 REST API 直接用 curl 測試 REST API： ...

前言：編輯器與前端的排版不一致之謎 在開發多平台醫療健康應用時，我們採用了現代化的技術棧： 後端 CMS：Strapi v5.15.1（Headless CMS） 前端框架：Vue.js 3 富文本編輯器：CKEditor 5 資料傳輸：GraphQL API 這個組合在大多數情況下運作良好，編輯者可以在 Strapi 後台使用 CKEditor 輕鬆編輯富文本內容，前端 Vue.js 應用透過 GraphQL 獲取並渲染這些內容。 然而，我們遇到了一個令人困惑的問題： 在 Strapi 後台使用 CKEditor 精心排版的水平並排圖片，到了前端網頁卻變成了垂直排列。 這個問題不僅影響了內容的視覺呈現，也破壞了編輯者的排版意圖。更重要的是，這讓非技術背景的內容編輯者感到困惑：「為什麼我在後台看到的排版，到了網站上就變了？」 這篇文章將深入探討這個問題的根本原因，並提供系統性的解決方案。 問題現象與環境說明 內容流程架構 我們的內容從編輯到展示的完整流程如下： 問題的具體表現 預期行為： 在 Strapi CKEditor 後台，編輯者將兩張圖片設定為水平並排： <!-- CKEditor 生成的 HTML 結構 --> <figure class="image" style="float:left"> <img src="/uploads/image1.webp" alt="圖片1"> <figcaption>圖片1說明</figcaption> </figure> <figure class="image" style="float:left"> <img src="/uploads/image2.webp" alt="圖片2"> <figcaption>圖片2說明</figcaption> </figure> 實際現象： 前端 Vue.js 渲染後，圖片變成垂直排列： 兩張圖片沒有並排顯示，而是一張接著一張垂直堆疊。 技術環境詳情 Strapi CKEditor 配置（config/schema.json）： { "kind": "collectionType", "collectionName": "articles", "info": { "singularName": "article", "pluralName": "articles", "displayName": "文章" }, "attributes": { "title": { "type": "string" }, "content": { "type": "customField", "options": { "preset": "defaultHtml" }, "customField": "plugin::ckeditor5.CKEditor" } } } Vue.js 前端渲染組件（ServiceDetailView.vue）： ...

前言：那個令人抓狂的錯誤訊息 在開發前後端分離的 Web 應用時，幾乎每位工程師都曾遇過這個令人頭痛的錯誤： Access to fetch at 'http://localhost:1337/api/auth/local' from origin 'http://localhost:5173' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. 這個錯誤通常發生在最關鍵的時刻： 前端登入功能即將完成，卻無法呼叫後端 API 串接第三方服務時，資料無法正常取得 部署到測試環境後，原本運作正常的功能突然失效 CORS（Cross-Origin Resource Sharing，跨來源資源共用）是現代 Web 開發中的核心安全機制，但也是許多開發者的痛點。這篇文章將從基礎原理到實戰應用，帶你完整理解 CORS 的運作方式，並提供實際可用的解決方案。 為什麼需要 CORS？從同源政策說起 同源政策的誕生 在理解 CORS 之前，我們需要先認識「同源政策」（Same-Origin Policy, SOP）。這是瀏覽器最基本的安全機制，在 1995 年 Netscape Navigator 2.0 引入 JavaScript 時就已經存在。 同源政策的目的：防止惡意網站讀取另一個網站的敏感資料。 想像一個情境：你登入了網路銀行（https://bank.com），此時你的瀏覽器保存了銀行的登入 Cookie。如果沒有同源政策，當你不小心訪問了一個惡意網站（https://evil.com），該網站的 JavaScript 就能透過你的瀏覽器向 https://bank.com 發送請求，並讀取你的帳戶資料。 同源政策阻止了這種攻擊：https://evil.com 的 JavaScript 無法讀取 https://bank.com 的回應內容。 什麼是「同源」？ 兩個 URL 被視為同源，必須滿足以下三個條件： ...

前言 在現代 Web 應用開發中，提供第三方登入（Social Login）已經成為標準配備。相比傳統的帳號密碼註冊流程，使用 Google、Facebook、GitHub 等服務登入不僅能降低使用者註冊門檻，還能提升安全性（由大廠處理密碼儲存與驗證）。 當我們決定為 Strapi CMS 後台加入 Google OAuth 登入時，原本以為只是個簡單的設定任務： 在 Google Cloud Console 建立 OAuth 2.0 憑證 在 Strapi 填入 Client ID 和 Client Secret 點擊「Login with Google」按鈕，完成！ 但現實總是更複雜。當應用部署到 Kubernetes 叢集後，我們遇到了一個令人困惑的錯誤訊息： Error: Cannot send secure cookie over unencrypted connection 這個錯誤訊息背後，牽涉到 HTTP/HTTPS 協定、Proxy Trust 機制、Kubernetes Ingress 架構、以及瀏覽器 Cookie 安全策略等多層知識。這篇文章將完整記錄我如何一步步拆解問題、理解根本原因、並最終在生產環境中實現安全可靠的 Google 登入功能。 OAuth 2.0 授權碼流程基礎 在深入問題之前，我們先理解 Google OAuth 登入的完整流程。OAuth 2.0 提供了多種授權模式（Grant Types），而 Web 應用最常使用的是「授權碼模式（Authorization Code Flow）」。 這個流程中有幾個關鍵點： ...