ANTIGRAVITY 全端網頁開發實戰系列（階段 4 / 6）

STAGE 04 ｜ BACKEND API & DATABASE

後端 API 與資料庫：
給《今天學AI》裝上大腦與報名記憶庫

搞懂「餐廳外場、傳菜口 API 與廚房資料庫」的運作邏輯，讓 Antigravity 幫我們建立報名資料表與後端路由，真正記錄每一筆學員報名。

核心概念

API (GET / POST / DELETE) 與 JSON

實作目標

/api/registrations 報名讀寫系統

授課教師

方正璽

PART 01 ｜後端心智模型

一張圖秒懂全端架構：外場、傳菜口與廚房冰箱

Full-Stack Analogy

01 ｜前端 Frontend（餐廳外場）

學員看得到的報名表單

跑在學員的手機或電腦瀏覽器裡
負責展示漂亮的《今天學AI》文章與表單輸入框
基於安全，外場客人絕對不能自己走進廚房開冰箱！

02 ｜ API 介面（傳菜口點菜單）

唯一合法的溝通窗口

前端填好報名表後，把點菜單遞進傳菜口（/api/registrations）
負責檢查：「姓名有沒有填？這個 Email 是不是已經報過名了？」

03 ｜資料庫 Database（廚房冰箱）

永久保存資料的金庫

跑在後台伺服器上，外人看不到
當 API 檢查通過後，把學員報名資料正式寫入資料表，斷電重開也不會消失！

PART 01 ｜ API 基礎語彙

跟 AI 討論後端時，你只需要認識這 3 個英文單字

HTTP Methods

同樣是同一個網址 /api/registrations，根據你貼上的「動作標籤」不同，廚房就會做不同的事：

METHOD 01 ｜ POST（新增）

「我要送出一筆新報名！」

當學員在首頁填完表單按下「確認送出」時，前端會發送 POST 請求，把學員資料塞進資料庫。

METHOD 02 ｜ GET（讀取）

「請把報名名單拿給我看！」

當老師打開 /admin 後台頁面時，網頁會發送 GET 請求，向後端索取目前所有報名學員清單。

METHOD 03 ｜ DELETE（刪除）

「請刪除這筆測試報名！」

當老師在後台點擊某筆資料旁邊的「刪除」按鈕時，會發送 DELETE 請求，將該筆紀錄從資料庫移除。

PART 01 ｜資料格式

什麼是 JSON？前後端傳遞點菜單的「標準格式」

JSON Format

WHY JSON?

人類跟程式都能一眼看懂的清單

全名是 JavaScript Object Notation
用大括號 { } 包住一筆資料
每一行都是 "欄位名稱": "內容" 的配對
未來看 AI 測試後端或除錯時，只要看懂右邊這張卡片就夠了！

一筆《今天學AI》報名資料的 JSON 長相
{
  "id": "reg_20261107_001",
  "name": "林雅婷",
  "email": "yating@university.edu.tw",
  "session": "場次 A：AI Agent 工作流入門",
  "role": "大學助理教授",
  "question": "想了解如何把課程講義自動轉成互動網頁",
  "createdAt": "2026-11-07T18:30:00Z"
}

PART 02 ｜ DATABASE SCHEMA & MCP

設計報名資料表與儲存架構：
從本機練習到雲端資料庫

規劃《今天學AI》的 7 個核心資料欄位，並了解如何透過 Antigravity 的 MCP 與 Plugins 連接各類資料庫。

PART 02 ｜資料表設計

設計資料庫的第一步：定義資料表欄位（Schema）

Database Schema

就像開 Google 表單收集報名一樣，我們要先跟 AI 約定好每一筆報名要存哪些欄位：

欄位英文名	欄位中文說明	資料型態	後端檢查規則（Validation）
id	報名唯一編號	字串（主鍵）	由系統自動生成（避免兩個人同名同姓搞混）
name	學員姓名	文字字串	必填，不可為空白
email	電子信箱	文字字串	必填，需包含 @，且同一場次不可重複報名
session	報名場次	文字字串	必填（場次 A ／場次 B ／兩場皆報名）
role ／ question	職稱與課前提問	文字字串	選填，讓老師課前了解學員背景與痛點
createdAt	報名時間戳記	ISO 日期字串	由後端伺服器自動蓋上當下時間

PART 02 ｜儲存策略與外掛

資料要存哪裡？本機輕量儲存 vs. 雲端資料庫外掛

Storage Options

OPTION A ｜零門檻教學首選（本階段採用）

混合式儲存（本地檔案＋雲端記憶體備援）

本機開發時：自動讀寫專案內的 data/registrations.json 或 SQLite，直接點開檔案就能看到學員名單！
免綁信用卡、零外部帳號設定：全班同學不需要去申請複雜的資料庫帳號就能 100% 跑通 CRUD 流程
同時支援 Vercel 雲端環境自動切換，確保部署上線後可直接展示互動

OPTION B ｜進階正式營運（搭配 MCP / Plugins）

Vercel Storage（Neon Postgres / Supabase）

當網站正式對外長期收單時，可在 Antigravity 啟用 Vercel Plugin 或 vercel-storage 技能
只要對 AI 說：「請幫我透過 Vercel Marketplace 連結 Neon Postgres 資料庫」，AI 就會透過 MCP 工具自動拉取連線金鑰並建好資料表！

PART 02 ｜路由規則

在 Next.js 裡，後端 API 程式寫在哪個資料夾？

API Route Convention

Next.js 前後端檔案對照
src/
├── app/
│   ├── page.tsx                  # 網址：/ (網站首頁畫面)
│   ├── admin/
│   │   └── page.tsx              # 網址：/admin (教師後台畫面)
│   └── api/
│       └── registrations/
│           └── route.ts          # ★ 網址：/api/registrations (後端 API)
└── lib/
    └── db.ts                     # ★ 負責讀寫資料庫的工具模組

MAGIC CONVENTION

檔名叫 page.tsx 是畫面；叫 route.ts 是 API！

Next.js 的規則非常直覺：資料夾名稱就是網址路徑
放在 app/api/registrations/route.ts 的程式碼，永遠只會在伺服器後台執行，學員的瀏覽器絕對看不到裡面的原始碼，非常安全！

PART 03 ｜ HANDS-ON BACKEND IMPLEMENTATION

動手打造後端廚房：
建立報名資料庫與 API 路由

用三個清晰的步驟，請 Antigravity 幫我們完成資料庫模組、防重複報名檢查，以及終端機自動化測試。

PART 03 ｜動手實作（1 / 3）

實作任務一：建立報名資料讀寫模組與 3 筆示範名單

Hands-on 01

請點擊下方按鈕複製 Prompt，讓 AI 為我們打造穩健的資料儲存層：

PROMPT 01 ｜建立 src/lib/registrations-db.ts 與初始資料

「我們現在進入『階段四：後端 API 與資料庫』。請幫我建立報名資料儲存模組 src/lib/registrations-db.ts 與初始資料檔 data/registrations.json：
1. 定義包含 id, name, email, session, role, question, createdAt 的資料結構。
2. 預先放入 3 筆逼真的示範學員報名資料。
3. 實作讀取名單、新增報名、依 id 刪除報名的函式（本機直接讀寫 JSON 檔，雲端環境自動相容記憶體暫存，確保未來部署 Vercel 零報錯）。」

PART 03 ｜動手實作（2 / 3）

實作任務二：建立 /api/registrations 後端 API 路由

Hands-on 02

PROMPT 02 ｜建立 GET、POST（含防重複報名）與 DELETE API

「請幫我建立後端 API 路由 src/app/api/registrations/route.ts：
1. GET：回傳目前所有報名名單與各場次人數統計。
2. POST：接收新報名，檢查姓名、Email、場次必填，並防止同一個 Email 重複報名同一場次（若重複回傳繁體中文提示）。
3. DELETE：支援透過 ?id=xxx 刪除指定的報名紀錄。」

教學亮點：注意我們在 Prompt 裡要求了「防止同一個 Email 重複報名同一場次」——這就是典型的「後端商業邏輯（Business Logic）」，只有掌握資料庫的後端廚房才能做到！

PART 03 ｜驗收常識

廚房回傳的「數字暗號」：秒懂 4 個常見 HTTP 狀態碼

Status Codes

200 OK ／ 201 Created

綠燈：任務圓滿成功！

200 代表成功讀取名單；201 代表成功新增一筆報名資料進資料庫。

400 Bad Request

黃燈：點菜單沒填好

例如學員忘記填姓名，或 Email 少打了 @，被後端退件重填。

409 Conflict

黃燈：資料重複衝突

這個 Email 已經報名過同一場工作坊了，後端貼心攔截避免重複扣名額。

500 Internal Server Error

紅燈：後端廚房失火了

後端程式碼有 Bug 或資料庫連不上。看到 500 時直接把紅字丟給 AI 修即可！

PART 03 ｜動手實作（3 / 3）

實作任務三：不用等前端接好，請 AI 直接測試後端 API！

Hands-on 03

專業工程師寫完後端，一定會先測試廚房能不能正常出菜。我們直接請 Antigravity 幫我們測：

PROMPT 03 ｜請 AI 自動發送請求測試 GET 與 POST 功能

「請幫我在終端機測試剛剛寫好的 /api/registrations 是否運作正常：
1. 發送 GET 確認能讀出預設的 3 筆名單。
2. 發送一筆 POST 測試報名，確認回傳 201 新增成功。
3. 用相同信箱再送一次 POST，確認防重複機制有成功攔截（回傳 409）。
4. 測試後把該筆測試資料刪除，並向我回報三項測試結果。」

PART 03 ｜親眼驗證

你也可以自己打開瀏覽器，親眼看看 API 吐出來的資料！

Browser Check

TRY IT IN BROWSER

在網址列輸入：
http://localhost:3000/api/registrations

在瀏覽器網址列輸入網址按 Enter，其實就是發送一個 GET 請求！
你會親眼看到瀏覽器畫面上印出結構清楚的 JSON 報名名單與統計數字
點開左側檔案樹的 data/registrations.json，也能看到真實存在硬碟裡的資料檔！

瀏覽器看到的 API 回應畫面
{
  "summary": {
    "total": 3,
    "bySession": {
      "場次 A：AI Agent 工作流入門": 2,
      "場次 B：全端網站實戰班": 1
    }
  },
  "registrations": [
    {
      "id": "reg_01",
      "name": "陳建宏",
      "email": "chen@ntu.edu.tw",
      "session": "場次 A：AI Agent 工作流入門"
    }
  ]
}

WRAP UP & NEXT STAGE

階段四總結與下一階段預告

Summary

CHECK 01 ｜後端觀念

秒懂 API 與 JSON

理解外場（前端）、傳菜口（API GET/POST/DELETE）與廚房冰箱（資料庫）的分工。

CHECK 02 ｜資料庫建立

報名資料表正式運作

完成 registrations.json 讀寫模組與雲端無伺服器相容設計。

CHECK 03 ｜商業邏輯

防重複報名驗證通過

由 AI 完成終端機自動化 API 測試，確認 201 新增與 409 防重複攔截皆正常。

NEXT STAGE PREVIEW ｜階段五預告

階段五：前後端串接、教師管理後台（/admin）與教練式除錯

外場跟廚房都建好了，只差把兩邊的電線接起來！下一階段我們將打通首頁報名表單、打造專屬老師查看與匯出名單的 /admin 後台，並教你遇到 Bug 時如何派 Subagents 與 /browser 自動抓蟲！

後端 API 與資料庫：給《今天學AI》裝上大腦與報名記憶庫

學員看得到的報名表單

唯一合法的溝通窗口

永久保存資料的金庫

「我要送出一筆新報名！」

「請把報名名單拿給我看！」

「請刪除這筆測試報名！」

人類跟程式都能一眼看懂的清單

設計報名資料表與儲存架構：從本機練習到雲端資料庫

混合式儲存（本地檔案 ＋ 雲端記憶體備援）

Vercel Storage（Neon Postgres / Supabase）

檔名叫 page.tsx 是畫面；叫 route.ts 是 API！

動手打造後端廚房：建立報名資料庫與 API 路由

綠燈：任務圓滿成功！

黃燈：點菜單沒填好

黃燈：資料重複衝突

紅燈：後端廚房失火了

在網址列輸入：http://localhost:3000/api/registrations

秒懂 API 與 JSON

報名資料表正式運作

防重複報名驗證通過

階段五：前後端串接、教師管理後台（/admin）與教練式除錯

後端 API 與資料庫：
給《今天學AI》裝上大腦與報名記憶庫

設計報名資料表與儲存架構：
從本機練習到雲端資料庫

混合式儲存（本地檔案＋雲端記憶體備援）

動手打造後端廚房：
建立報名資料庫與 API 路由

在網址列輸入：
http://localhost:3000/api/registrations