Backend

現在 code 都讓 AI 寫了，這種判斷它靠得住嗎？ 你在資料庫改了一筆設定——權限、feature flag、某個閾值——接著要決定：改完到底要不要重啟服務才生效？ 放在以前，你會憑經驗猜：保守派一律重啟（常常多此一舉、白白製造一次中斷），樂觀派賭它即時生效（結果改半天前端還吃舊行為，debug 一小時才發現要重啟）。但現在多了一個選項，也是大多數人實際在做的——直接問 AI。於是真正的問題變成：這種「要不要重啟」的判斷，AI 答得對嗎？ AI 會怎麼判斷——而且為什麼常常自信地答錯 先說結論：這題剛好是 AI 最容易出錯的類型，而且會錯得很有自信。 AI 寫 code 的本質，是從訓練資料的 pattern 推測最可能的答案。而「改設定要重啟」在無數系統裡都成立，於是它傾向很篤定地叫你重新部署，卻沒去確認你眼前這份程式碼到底是 live 讀還是快取。版本差異更是重災區——同一個框架舊版快取、新版改成 live 讀，AI 常常混為一談，給你一個「看起來很對」的錯答案。 問題的本質其實沒變，只是換了位置：從前要自己判斷，現在要判斷「AI 的判斷對不對」。而要驗證它、或反過來把它導對，你得先有一把尺——一條不靠經驗、可以拿原始碼直接對答案的準則。 那把尺：即時讀，還是啟動時快取？ 決定「改完要不要重啟」的，從來不是設定存在哪裡，而是程式什麼時候去讀它： 讀取時機 改完是否即時生效 典型例子 每個請求即時讀（per-request live read） ✅ 即時，不必重啟 每次查 DB 的權限、即時拉的 feature flag 啟動時載入記憶體後快取（boot / in-memory cache） ❌ 必須重啟或等過期 bootstrap 載入的設定、process 內的計數器 換句話說：改 DB 要不要重啟，等於問「這個值是 live 讀還是被快取了」。把這句話記住，後面所有案例都是它的推論。 麻煩的是，框架很少在文件裡明講某個值屬於哪一類，AI 也答不準。所以正確的態度不是查文件、更不是憑經驗猜，而是翻原始碼，看那個值是在「請求路徑」上被讀，還是在「啟動路徑」上被讀。下面用一正一反兩個真實案例，把這把尺磨利。 實例一：Strapi 權限「改 DB 即刻生效」 需求很單純：把兩個 content-type（就叫它 article 與 category）的 CUD（Create / Update / Delete，建立／更新／刪除）權限，授給幾個自訂角色。Strapi（一個 Node.js 的 headless CMS）的權限存在資料庫的 up_permissions 表，所以最直接的做法就是下 SQL 把對應的 grant 寫進去。 ...

前言：帳密明明正確，卻回 500 某天收到回報：使用者從手機點開官網登入，帳號密碼都對，卻跳出 Internal Server Error。換其他瀏覽器再登入就成功了。 「帳密正確卻 500」這種錯誤特別惱人，因為它不是身分驗證的問題，而是驗證通過之後才出事。本文記錄怎麼從一行日誌追到根因，以及背後三個值得每個後端工程師記住的設計教訓。 從日誌追根因：三條線索 先分清楚登入失敗的兩種回應：帳密錯誤會回 400 Invalid identifier or password；而這次是 500。光這一點就暗示——帳密其實是對的，問題出在登入流程的後半段。 線索一：500 只在帳密正確時出現 撈出該帳號當天的登入紀錄，發現 500 全部集中在某個時段，之後突然出現一次成功，再之後才是幾筆「帳密錯誤」的 400。換句話說，那串 500 本身就證明了帳密一直是對的——錯的不是驗證。 線索二：那行 PostgreSQL 錯誤訊息 日誌裡每筆 500 都附帶同一句資料庫錯誤： insert into "refresh_tokens" (..., "user_agent") values (...) - value too long for type character varying(255) 真相浮現：登入驗證通過後，後端要寫一筆 refresh token 進資料庫，其中 user_agent 欄位是 varchar(255)，而這次要寫入的值超過 255 字元，PostgreSQL 直接拒絕，未被攔截的例外往上冒成了 500。 線索三：為什麼有時成功、有時失敗 成功那次寫進資料庫的 user_agent 長度是 128；失敗那幾次的值都超過 255。差別就在 User-Agent 字串的長度——而它由「使用者用什麼瀏覽器」決定。 根本原因：varchar(255) 塞不下 in-app 瀏覽器的 UA 寫入 refresh_tokens 的欄位中，token 是固定長度的隨機字串、expires_at 是時間、device_type 是短列舉、ip_address 也很短。唯一長度會劇烈變動、且可能爆掉的，只有 user_agent。 ...

引言:當業務主表需要翻轉 某個 SaaS 系統長期以「客戶資料表」為核心:所有訂單、文件、操作紀錄都用客戶 ID 當外鍵。但這個客戶表的資料來源是外部 POS 系統匯入,每天同步幾百筆,schema 由廠商定義。 業務發展後問題浮現:自己 SaaS 的會員表(users)才是真正的「人」 — 有登入、有偏好、有應用內行為。新功能(個人化推薦、訂閱管理、社交綁定)都需要以 users 為主軸。 於是有了一個經典的 schema migration 需求:主表翻轉(primary table pivot)。把業務邏輯的中心從 customers(外部 POS 匯入)轉到 users(SaaS 自家會員),但歷史資料、新進資料、系統相依、回滾風險全部都要顧到。 名詞解釋 開始拆解之前,定義幾個會反覆出現的詞: 詞 定義 主表翻轉(Primary table pivot) 業務主要 entity 從表 A 改成表 B Dual-write 寫入時同時寫舊欄位 + 新欄位,回滾安全 Partial cut-over 分階段切換,read 跟 write 不同步切 Hard cut-over(stop-the-world) 一次切完,downtime 短但 risk 大 Backfill 歷史資料補齊新欄位的 batch update Idempotent migration 重跑無副作用,cron / retry 安全 DISTINCT ON PostgreSQL 專屬去重 syntax,搭 ORDER BY 取每組第一筆 Pseudo entity 為了統一查詢介面而建的「假」實體 Link table ORM 多對多 join 表(user_id + entity_id) 為什麼選 dual-write 而非 stop-the-world 最直接的搬家方式是「stop-the-world cut-over」:選一個維護窗口,停寫入、跑 batch script、改完所有 reference、開機。但這個 SaaS 的條件不允許: ...

症狀：資料明明在，前端就是拿不到 一個 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: ...

症狀：選完手機照片，畫面卻還是貼圖 使用者回報的步驟很簡單：點頭像 → 選「從手機圖庫」→ 選張照片 → 儲存。跳回會員中心，頭像還是原本的系統貼圖。 再點進去編輯頁，看到的又是手機照片。明明存成功了，為什麼 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 的權限沒勾。 ...

前言：一個看似簡單的需求 需求很單純：讓 Email 驗證信中的連結顯示前端網址（www.example.com），而不是後台網址（api.example.com）。這樣用戶不會看到內部系統架構。 外包商寫了這段程式碼： // ❌ 看起來合理，但完全沒效果 plugin.services.user.sendConfirmationEmail = async function(user) { // 自訂邏輯... } 部署後，Email 中的連結依然指向後台。為什麼？ 問題根源：Factory Function 陷阱 翻開 Strapi 原始碼，發現 plugin.services.user 不是一個物件，而是一個 factory function： // Strapi 內部實作（簡化版） plugin.services.user = (context) => { return { sendConfirmationEmail: async (user) => { /* 原始邏輯 */ }, // 其他方法... } } 這意味著什麼？ 每次 Strapi 需要 user service 時，它會呼叫這個 factory function 來取得一個新的 service 實例。你直接覆蓋 sendConfirmationEmail 屬性，等於在一個 function 物件上加屬性——factory 被呼叫時根本不會讀取這個屬性。 不這樣理解會怎樣？ 你會像外包商一樣，花兩天 debug 卻找不到原因，因為程式碼完全沒有報錯，只是靜靜地被忽略。 解決方案：Factory Wrapper 模式 正確的做法是包裝原本的 factory function： // ✅ Factory Wrapper 模式 const originalUserServiceFactory = plugin.services.user; plugin.services.user = (context) => { // 先取得原始 service 實例 const originalUserService = originalUserServiceFactory(context); return { ...originalUserService, // 保留所有原始方法 // 覆寫特定方法 async sendConfirmationEmail(user) { // 你的自訂邏輯 const confirmationUrl = `${FRONTEND_URL}/verifyEmail`; // ... }, }; }; 為什麼這樣有效？ ...

引言：一個技術選型的起點 2024 年 6 月，我坐在會議室裡，面對著老闆和行銷總監，準備報告我對公司新系統 CMS 的技術選型建議。這不是一個輕鬆的決定——選錯了，可能浪費數百萬的開發成本；選對了，能為公司省下可觀的人力支出。 經過數週的研究與分析，作為一個架構規劃師同時也是技術決策者，我最終選擇了 Strapi 作為我們的 Headless CMS 解決方案。這篇文章將分享我的決策過程、考量因素，以及最重要的——這個選擇如何為公司省下大筆預算。 什麼是 Headless CMS？ 在深入 Strapi 之前，先理解 Headless CMS 的核心概念。 傳統 CMS vs Headless CMS graph TB subgraph Traditional["傳統 CMS（如 WordPress）"] A[後端 + 資料庫] --> B[模板引擎] B --> C[HTML 輸出] C --> D[瀏覽器] end subgraph Headless["Headless CMS（如 Strapi）"] E[後端 + 資料庫] --> F[REST/GraphQL API] F --> G[Web App] F --> H[Mobile App] F --> I[IoT Device] F --> J[其他服務] end 傳統 CMS 將前端與後端緊密耦合，網站的外觀和內容管理綁在一起。而 Headless CMS 則專注於內容管理和 API 提供，讓前端團隊可以使用任何技術框架來消費這些 API。 ...

前言：那個令人抓狂的錯誤訊息 在開發前後端分離的 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 被視為同源，必須滿足以下三個條件： ...

前言 在開發 Strapi 後台管理系統時，我遇到一個實際的使用者體驗問題：在「已購買課程」列表中，管理員可以用「真實姓名」搜尋到用戶的購課記錄，但用「電話號碼」卻搜尋不到。這個不一致的行為讓管理員感到困惑。 本文將分享如何在 Strapi v5 中實作自訂搜尋邏輯，讓 Admin 面板支援跨關聯的多欄位搜尋。 問題場景 資料結構： purchased-course（已購買課程）：關聯到 user user（用戶）：包含 email、realName、phoneNumber、username、nickname 等欄位 問題現象： ✅ 搜尋「真實姓名」→ 可以找到對應的購課記錄 ❌ 搜尋「電話號碼」→ 找不到任何結果 為什麼會這樣？ 因為 Strapi 預設的搜尋功能只會搜尋當前 Collection 的直接欄位，不會自動搜尋關聯表（relation）的欄位。當我們在 purchased-course 列表搜尋時，Strapi 只會在 purchased-course 本身的欄位中搜尋，而不會去搜尋關聯的 user 資料。 解決方案架構 Strapi 提供了三個層級可以自訂搜尋邏輯： 1. Controller 層（API 端點） 位置： src/api/purchased-course/controllers/purchased-course.ts 用途： 處理前端透過 REST API 的搜尋請求 2. Service 層（業務邏輯） 位置： src/api/purchased-course/services/purchased-course.ts 用途： 封裝可重複使用的業務邏輯 3. Content Manager Plugin Extension（Admin 面板） 位置： src/extensions/content-manager/strapi-server.ts 用途： 最重要！ 這是讓 Admin 面板搜尋生效的關鍵 ...