API

症狀：資料明明在，前端就是拿不到 一個 CMS 系統的文件列印預覽，每份文件 header 都固定顯示「上傳者：—」。DB 裡明明有資料，API 回 HTTP 200 OK，回應裡的其他欄位（日期、文件類型、附件）都對——唯獨 uploadedBy 是 null。 沒錯誤、沒警告，伺服器 log 也乾淨。前端碰到 uploadedBy?.realName || '-' 就乖乖畫 dash。使用者以為這份文件沒指派擁有者，作者本人以為畫面壞了。大家都錯，但系統看起來好好的。 這是最難纏的 bug——靜默失敗。 先看 ORM 層在整個架構哪裡 要理解為什麼這類 bug 發生、也為什麼解法是「繞過 ORM」，先把架構分層看清楚： flowchart TD A[前端 / Client<br/>Vue, React, App] --> B[Web / API 層<br/>Controller, Route, 權限檢查] B --> C[業務邏輯層<br/>Service / Use Case] C --> D[ORM 層 ⭐<br/>Strapi Entity Service, Prisma, TypeORM,<br/>Mongoose, SQLAlchemy ORM] D --> E[Query Builder 層 可選<br/>knex, SQLAlchemy Core] E --> F[DB Driver<br/>pg, mysql2, mongodb] F --> G[資料庫<br/>PostgreSQL, MongoDB, ...] classDef default fill:#f5f5f5,stroke:#333,color:#333 classDef orm fill:#d1ecf1,stroke:#17a2b8,color:#0c5460 classDef db fill:#d4edda,stroke:#28a745,color:#155724 class D orm class G db 為什麼 bug 只會發生在 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 上，用測試帳號 [email protected] 點「忘記密碼」，畫面跳出 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（載入） 的縮寫，是資料工程最基礎的設計模式。與其抽象解釋，直接用這個專案的食物資料庫來看： flowchart LR subgraph Extract A1[🇹🇼 台灣食藥署 API] A2[🇯🇵 日本 GitHub] A3[🇨🇳 中國 GitHub] A4[🇺🇸 USDA API] end subgraph Transform B[統一格式化<br/>營養素映射<br/>分類標準化<br/>名稱清理] end subgraph Load C[合併去重<br/>驗證完整性] D[(foods_database.json<br/>13,152 種食物)] end A1 --> B A2 --> B A3 --> B A4 --> B B --> C --> D 四個來源的原始資料格式完全不同 — 台灣用中文欄位名（粗蛋白）、日本用 FAO 代碼（prot）、USDA 用數字編號（203）。Transform 階段把它們統一成 App 需要的 {id, name, emoji, category, nutrition} 結構。 ...

問題背景 最近在開發過程中遇到一個詭異的問題：呼叫某個 API 後，某個常數 name 的值居然是 nil，但從 raw data 看起來明明有值。 症狀檢查清單： ✅ Console 印出 raw data 看起來正常 ✅ jsonDecode 解碼成功 ✅ Enum 對應的 JSON key (_Name_Ch) 完全相同 ✅ 瀏覽器中直接訪問 API，name 確實有值 ❌ Swift 中取得的 name 卻是 nil 經過反覆檢查，終於發現問題根源：不可見的 BOM (Byte-Order Mark) 字元。 什麼是 BOM？ BOM (Byte-Order Mark)，中文稱為位元組順序記號，是一個不可見的 Unicode 字元，用於標示文字檔的編碼位元組順序。 常見的 BOM 字元： UTF-8 BOM: 0xEF 0xBB 0xBF (Unicode: U+FEFF) UTF-16 BE BOM: 0xFE 0xFF UTF-16 LE BOM: 0xFF 0xFE 問題診斷 根據問題分析，name 為 nil 的原因是： ...