第 11 章 數據分析儀表板

42. 設計資料庫 schema

什麼時候用你要開始存資料了，需要先規劃資料長什麼樣、有哪些欄位？

我要設計〔專案，例如：一個線上課程平臺〕，需要儲存這些東西：〔例如：學員、課程、報名紀錄〕。請幫我設計資料庫結構（schema）：每一種資料該有哪些欄位、各是什麼型態、彼此之間怎麼關聯（例如一個學員可以報名多門課）。請用白話解釋你的設計，並提醒我有沒有漏掉常見會用到的欄位。

資料結構是地基，蓋歪了以後很難改。花時間跟 AI 對這一步，並主動問「我以後想加 X 功能，現在的設計擋不擋得住」。

43. 請 AI 幫我寫資料查詢

什麼時候用你想從資料裡撈出特定的結果，但不知道查詢語法怎麼寫？

我的資料表〔表名與欄位說明〕。我想查出「〔用白話描述你要什麼，例如：這個月報名人數最多的前五門課，含各自的報名人數〕」。請幫我寫出這段查詢，並逐句用白話解釋它在做什麼，讓我看得懂、以後能自己微調。如果有更有效率的寫法也請告訴我。

查詢用白話描述你要的結果最好，別自己猜語法。重點是請 AI 逐句解釋，這樣你會慢慢看懂，而不是永遠只能複製貼上。

44. 建立一個 API 端點

什麼時候用你要讓前端畫面能跟後端要資料或送資料，需要一個溝通的接口。

請幫我建立一個 API 端點（endpoint），功能是「〔做什麼，例如：接收前端送來的報名資料，存進資料庫，回傳成功或失敗〕」。請說明這個端點的網址、該用哪種請求方式、前端要送什麼格式的資料、會收到什麼回應。並幫我加上基本的錯誤處理（例如資料不完整時回傳清楚的錯誤訊息）。

把 API 想成點餐窗口：前端遞單子（送資料）進去，後端把菜（回應）端出來。講清楚送什麼、回什麼，這個窗口就打通了。

45. 描述第三方 API 串接需求

什麼時候用你想接一個現成的外部服務（地圖、簡訊或 AI 等），但不知道怎麼開始。

我想在我的專案裡串接〔某個外部服務，例如：把地址轉成地圖座標的服務〕。請先幫我規劃：這類服務常見的選擇有哪些、串接大致要哪些步驟、我需要去申請什麼、免費額度大概到哪、要注意什麼限制。金鑰我會自己申請保管，你在程式裡需要用到的地方請留〔佔位符〕並註明。

串接外部服務前，先問免費額度到哪、超過會怎樣？很多新手不小心接了會計費的服務，用一用才發現帳單來了。

46. 建立環境變數與金鑰觀念

什麼時候用你手上有 API 金鑰、密碼這類機密，想知道該怎麼安全地放。

我有一些機密資訊（例如 API 金鑰、資料庫密碼）需要在程式裡使用，但我知道不能直接寫死在程式碼裡。請用零基礎能懂的方式教我：什麼是環境變數（environment variable）、為什麼機密要放在這裡、我該怎麼設定、以及要怎麼確保它不會不小心被上傳到公開的地方。請幫我把專案設定成正確的做法。

金鑰寫死在程式碼裡、又推上公開的地方，是新手最貴的一課（可能被盜刷）。務必一開始就把環境變數＋不上傳機密這件事做對。

47. 加上後端資料驗證

什麼時候用你想確保存進資料庫的資料是乾淨、合法的，不被亂七八糟的輸入污染。

前端表單雖然有做檢查，但我知道不能只信任前端。請幫我在後端（收到資料、存進資料庫之前）也加一層驗證：檢查〔必填欄位有沒有缺、格式對不對、數字有沒有在合理範圍、有沒有奇怪的內容〕。驗證不過就擋下來、回傳清楚的錯誤，不要讓髒資料進到資料庫。

請謹記這句話：「永遠不要只相信前端的檢查。」前端驗證是為了體驗，後端驗證才是真正的防線，因為前端的檢查是能被繞過的。

48. 加上快取讓速度變快

什麼時候用某些資料每次都重算或重抓很慢，你想把結果暫存起來加速。

我的〔某個功能，例如：首頁的熱門文章排行〕每次載入都要重新計算，有點慢。這份資料其實不用即時、每〔10 分鐘〕更新一次就好。請幫我加上快取（cache）：把結果暫存起來，時間內直接用暫存的，時間到了再重算。請用白話解釋你的做法，並提醒我快取可能帶來的副作用（例如資料會有點延遲）。

快取是用一點點資料新鮮度，換很多速度。先確認這份資料晚幾分鐘更新有沒有關係，如果沒關係的才適合快取，會即時變動的資料別亂快取。

49. 建立一個排程任務

什麼時候用你想讓某件事在固定時間自動執行，不用你手動去按。

我想讓〔某件事，例如：每天早上 9 點自動寄出前一天的報名統計信〕自動定時執行。請幫我規劃這個排程任務（scheduled task）：該用什麼方式設定、要執行什麼、失敗了怎麼辦（例如要不要重試、要不要通知我）。請用零基礎能懂的方式解釋，並提醒我測試時該怎麼確認它真的有照時間跑。

排程任務最怕你以為它有跑，其實默默失敗了。一定要問 AI 失敗時怎麼通知我，別讓它在背後無聲無息地掛掉。

50. 規劃一次資料遷移

什麼時候用你要改資料結構、或把資料搬到新地方，怕把現有資料搞壞。

我需要〔要做的變更，例如：在現有的客戶資料表新增一個來源管道欄位，並把舊資料的這個欄位預設為「其他」〕。這裡面已經有正在使用的真實資料，我很怕改壞。請幫我規劃一個安全的資料遷移（migration）步驟：先做什麼、怎麼備份、怎麼驗證改完後資料沒問題、萬一出錯怎麼還原。

動到真實資料前，第一件事永遠是先備份。就像遊戲打魔王前先存檔，出事了才有回頭路。務必請 AI 把備份和還原步驟寫進去。寫程式遇到出錯，不是你笨，是全世界工程師的日常。真正的差別在於會不會求救：把問題描述清楚的人，AI 三兩下就幫他解決；描述得含糊的人，來回半天還在鬼打牆。這一關教你怎麼把卡關的情況講到 AI 一聽就懂，就像你去看醫生，症狀說得愈準，愈快對症下藥。

connection refused / could not connect to database

你會在哪看到程式啟動或第一次要存取資料時，說連不上資料庫。

白話意思你的程式去敲資料庫的門，結果沒人應門，可能是地址錯了，或倉庫根本沒開。

• 資料庫沒啟動。
• 連線字串（地址、帳號密碼或埠號）有誤。
• 網路或防火牆擋住。

我的程式出現 `connection refused`，連不上資料庫。請帶我逐項排查：資料庫服務有沒有在跑、連線設定（主機、埠號、帳號、密碼、資料庫名稱）對不對、是不是被防火牆擋。我用的資料庫是〔資料庫種類，例如 PostgreSQL、MySQL 或 Supabase〕。

先確認資料庫本身有沒有在運作？本機的資料庫常常只是忘了啟動，雲端的則要確認連線字串一字不差。

migration failed（資料表建置/更新失敗）

你會在哪看到執行資料庫的 migration（把資料表結構的變更套用上去）時失敗。

白話意思你想重新裝潢倉庫的格局，但施工到一半撞到問題，改不下去。

• 新的結構跟已有資料衝突（例如要加一個「不能為空」的欄位，但舊資料是空的）。
• migration 檔本身有錯。
• 之前跑到一半的 migration 卡住了。

我跑資料庫 migration 時失敗，訊息如下。請幫我看懂它卡在哪一步、為什麼，最安全的處理方式是什麼（尤其我不想弄丟現有資料）。訊息：〔貼上整段〕。我用〔資料庫或工具名〕。

涉及 migration 一定要小心，動到的是真實資料。跟 AI 強調「我不想弄丟資料」，請它先解釋清楚再動手，重要資料先備份。

schema 不一致（drift，程式跟資料庫對不上）

你會在哪看到程式抓資料時說某個欄位不存在，或型別對不上，但你覺得明明有。

白話意思程式手上那張倉庫平面圖，跟倉庫的實際格局長得不一樣了，兩邊沒對齊。

• 改了程式的資料結構定義，但沒同步更新資料庫。
• 本機跟線上的資料庫結構不一致。

我遇到程式跟資料庫對不上的問題（它說某欄位不存在／型別不符，但我以為改過了）。請幫我判斷是不是「我改了定義但沒同步到資料庫」，並帶我確認兩邊目前的實際結構、怎麼把它們對齊。我用〔工具名，例如 Prisma、Drizzle、Supabase〕。

這種「明明改了卻沒生效」的問題，先分清楚你改的是程式裡的定義，還是資料庫的實際結構？兩者要同步，光改一邊不夠。

syntax error at or near "xxx"（SQL 語法錯誤）

你會在哪看到執行一段資料庫查詢（SQL）時，說語法有錯。

白話意思你給倉庫管理員的指令，文法寫錯了，它看不懂。

• 少了逗號、括號或引號。
• 用了資料庫的保留字當欄位名。
• 不同資料庫的語法有細微差異。

我執行這段 SQL 時出現 `syntax error at or near ``"``〔它指的那個字〕``"`。請幫我找出文法錯在哪、改好給我。我用的資料庫是〔種類〕。這是我的 SQL：〔貼上整段查詢〕。

不同資料庫的 SQL 有小差異。一定要跟 AI 講清楚你用哪一種（PostgreSQL、MySQL、SQLite...），它才能給對版本的寫法。

foreign key constraint 或 unique constraint 衝突

你會在哪看到新增或刪除資料時被擋，說違反外鍵或唯一鍵限制。

白話意思倉庫有規矩。唯一鍵是說這個值不能重複（例如同一個 E-mail 不能註冊兩次）；外鍵是說這筆資料牽連著別筆資料，不能亂刪亂加。

• 想存入一個已經存在的、不該重複的值。
• 想刪掉一筆還被其他資料引用著的資料。
• 想引用一筆根本不存在的關聯資料。

我在〔新增／刪除〕資料時出現 `〔``unique``／``foreign`` key``〕`` constraint` 衝突。請用白話解釋這條規矩在保護什麼，並幫我判斷正確的做法是什麼（例如是不是該先檢查有沒有重複、或先處理關聯的資料）。完整訊息：〔貼上〕。

這類錯誤其實是資料庫在幫你把關，避免髒資料。別想著硬繞過限制，先問 AI這條規矩想擋的是什麼，順著它做才安全。這一區是這份手冊最想補給你的部分。前面八區都在講程式的錯，但當你用 Claude Code、Codex 或 Antigravity 這類會自己動手做事的 AI 工具時，卡關的常常是 AI 這個夥伴本身：它改壞了、它鑽牛角尖、它說謊或是連不上。這些書裡不會教，但你天天會遇到。這一區教你怎麼管理你的 AI 夥伴。