ORM

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

問題現象：登入成功卻被拒於門外 最近在 Staging 環境遇到一個詭異的問題：使用者登入成功，拿到了有效的 JWT Token，但存取任何需要認證的 API 都回傳 401 Unauthorized。 # 登入成功，拿到 token POST /api/auth/local → 200 OK { "jwt": "eyJhbGc...xxxxx...your-jwt-token", "user": { "id": 1001, "email": "user@example.com" } } # 但存取個人資料失敗 GET /api/users/me → 401 Unauthorized Token 驗證通過、使用者存在、帳號未被封鎖。問題到底在哪？ 根本原因：遺失的 Link Table 經過一番追查，發現問題出在資料庫同步時漏掉了關聯表（Link Table）。 什麼是 Link Table？ 在關聯式資料庫中，多對多關係需要透過中間表來建立。這個中間表就是 Link Table（也稱為 Junction Table、Join Table、或 Pivot Table）。 使用者與角色的關係： 一個使用者可以有多個角色（User → Roles） 一個角色可以分配給多個使用者（Role → Users） 這是典型的多對多關係 各種 ORM 的 Link Table 命名 不同框架的 Link Table 命名慣例不同，但概念完全相同： ORM/Framework Link Table 範例 備註 Django user_groups, user_permissions 使用 _ 連接 Laravel role_user, permission_role 字母順序排列 TypeORM user_roles_role 較長的命名 Prisma _UserToRole 以 _ 開頭 Sequelize UserRoles 駝峰命名 問題的本質：資料不完整 當我們同步資料庫時，通常會注意主要的資料表： ...