大模型輔助編寫接口程式碼與接口文檔

在之前的課程中，我們學習瞭如何使用 Figma 等工具完成 UI 設計稿、如何藉助 AI 快速生成前端靜態頁面，以及如何利用 Supabase 構建資料庫並實現初步的用戶身份驗證。現在，一個自然而然的問題擺在了面前：前端頁面中那些動感十足的按鈕點擊後，究竟是如何把資料悄無聲息地存進 Supabase 的？當我們需要執行更復雜的業務邏輯（如併發支付、定時推送、資料敏感處理）時，直接讓前端連接資料庫是安全的嗎？

這就引出了現代 Web 開發架構中至關重要的一環——後端 API 接口。

相比於過去純手工敲出成百上千行的後端路由、控制器與參數校驗邏輯，如今我們完全可以藉助大模型的強大程式碼生成能力，將繁雜的基礎程式碼交由 AI 編寫。在本節課中，我們將跳出“AI 寫的又虛又泛”的怪圈，以真實的業務場景為依託，向你展示如何通過高質量的提示詞（Prompt）引導大模型寫出健壯、符合行業規範的 Node.js 後端接口，並自動完成接口文檔與測試用例的生成。

💡 前置知識
在學習本節之前，建議你先了解以下內容：
從資料庫到 Supabase - 瞭解資料庫和資料模型的概念。
Git 和 GitHub 工作流 - 熟悉如何在項目開發中進行版本控制。
什麼是終端/命令行 - 項目初始化與啟動離不開基礎的命令操作。

你將學到

什麼是 API 接口：理解前後端通信的橋樑與 RESTful 設計規範。
大模型賦能服務構建：如何通過結構化的 Prompt 讓 AI 幫你搭建 Node.js + Express 基礎工程。
接口邏輯開發：引導大模型生成包含嚴謹業務校驗、對接 Supabase 資料庫的 CRUD（增刪改查）接口。
自動化接口文檔：讓大模型根據程式碼逆向生成跨團隊協作標配的 OpenAPI/Swagger 文檔。
測試與聯調閉環：利用大模型生成 Postman 測試合集與 Jest 單元測試用例，為程式碼質量兜底。

1. 為什麼我們需要 API 接口？

在傳統的理解中，前端是“看得到的部分”，資料庫是“存東西的倉庫”。但這中間缺少了一個調度員。如果你把整個應用想象成一家餐廳：

前端（客戶端） 是餐廳的菜單和點餐桌，客人在這裡瀏覽菜品並提出需求。
資料庫（Supabase 等） 是餐廳的後廚倉庫，裡面存放著所有的食材和賬本。
後端 API 接口 就是餐廳的服務員。客人不能直接衝進後廚拿食材（不僅混亂，而且容易引發安全問題），而是需要把“點單訴求”（HTTP Request）告訴服務員。服務員進行核對（參數校驗、權限鑑權）後，去後廚調取對應的內容，再將“做好的菜”（HTTP Response，通常是 JSON 格式的資料）端回給客人。

通過 API 接口，我們實現了明確的前後端分離：前端只關心頁面如何渲染，後端只專注於業務邏輯、資料處理與安全防護。

2. 項目架構設計與初始化

一個結構清晰的項目骨架，是大模型能寫出好程式碼的先決條件。我們在讓 AI 寫程式碼前，自己心裡必須對工程結構有個底。

2.1 常見的 API 工程結構

即使是使用大模型生成程式碼，我們也絕不能把所有程式碼都塞進一個 server.js 文件中。一個易於維護的 Node.js 後端架構通常如下所示：

text

my-api-project/
├── .env                  # 敏感環境變量（如 API Keys、資料庫連接串）
├── server.js             # 項目入口（服務器啟動、全局中間件註冊）
├── package.json          # 依賴管理文件
├── src/
│   ├── routes/           # 路由層：定義 URL 路徑與請求方法
│   ├── controllers/      # 控制器層：處理業務請求參數，調用服務並返回響應
│   ├── services/         # 服務層：封裝資料庫交互和核心業務邏輯
│   └── middlewares/      # 中間件：登錄鑑權、錯誤全局捕獲
└── docs/                 # API 文檔存放目錄

2.2 藉助 AI 完成工程初始化

與其手動 npm init 並一個個安裝依賴，不如直接將上述規範以 Prompt 的形式餵給大模型：

🗣️ 給大模型的提示詞（Prompt 示例）： "幫我搭建一個 Node.js 後端項目，要能連接 Supabase 資料庫，結構清晰一點，方便以後維護。"

運行 AI 返回的程式碼後，你就能在 localhost:3000 獲得一個具備企業級雛形的後端應用了。

3. 核心實戰：大模型輔助接口開發

這是本章節最核心的部分。大模型寫出的程式碼往往容易存在“邏輯漏洞”或“表面敷衍”，原因在於開發者給的上下文不足。大模型不怕需求複雜，最怕需求模糊。

以我們在資料庫章節中提到的 menu_items (菜單表) 的新增接口為例，看如何寫出一份高質量的 Prompt。

3.1 賦予大模型完整上下文

在請求 AI 寫接口之前，一定要提供資料庫字段定義（Schema）和具體的約束條件。

🗣️ 高質量提示詞（Prompt）模板： "幫我寫一個新增菜單的接口，菜單有商品名、價格、分類（漢堡、小食、飲料）、是否上架這幾個資訊。商品名和價格必須填，價格不能是負數。用戶輸入不對的時候要提示錯誤。"

3.2 審查大模型生成的程式碼

大模型生成的程式碼通常會像下面這樣清晰地拆分了職責：

javascript

// services/menuService.js
const { createClient } = require('@supabase/supabase-js');
const supabase = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_KEY);

exports.createMenuItem = async (menuData) => {
    // 調用 Supabase SDK 將資料推入表內
    const { data, error } = await supabase
        .from('menu_items')
        .insert([menuData])
        .select();

    if (error) throw new Error(`資料庫插入失敗: ${error.message}`);
    return data[0];
};

你可以發現，通過這種方式生成的程式碼，不僅結構合理，而且將 Supabase 的初始化、錯誤捕獲以及異常處理都考慮在內，這與簡單要求“寫個新增接口”得到的麵條式程式碼（Spaghetti Code）有著天壤之別。

4. 解放雙手：自動生成接口文檔

對於開發團隊而言，沒有文檔的 API 就是一個盲盒。前端工程師無法猜測你需要傳入什麼參數，也不能預測會返回什麼結構。業界最通用的 API 描述規範是 OpenAPI (此前也稱 Swagger)。

過去，手寫 YAML 或者 JSON 格式的 Swagger 文檔極其痛苦且容易出錯。現在，這也成了大模型最擅長的領域。

你可以直接選中你剛才寫的 routes 和 controllers 程式碼，然後丟給大模型：

🗣️ 生成文檔的提示詞： "幫我根據上面的程式碼生成一份接口文檔，要寫清楚每個參數是什麼意思、返回什麼資料，方便前端同事對接。"

在這個過程中，你甚至可以要求 AI 補全字段的說明（Description）和 Mock 資料（如 price_cents: 1200 代表 12 美元），極大地降低了溝通成本。

5. 保駕護航：生成測試程式碼與 Postman 集合

程式碼寫好、文檔出爐，還差最後一步：驗證程式碼到底能不能跑通。

5.1 生成 Postman / Apifox 測試配置

在接口開發中，我們通常使用 Postman 這樣的可視化工具來模擬前端發送 HTTP 請求。如果不使用大模型，你需要手動填入 URL、逐個添加 Header（請求頭）以及拼接 JSON 請求體。

你只需向 AI 發送指令：

"幫我把這份接口文檔轉成 Postman 可以導入的格式，要包含正常請求和錯誤請求的例子。"

拿到 JSON 文本後，保存為 menu_api.json 並拖入 Postman，你瞬間就獲得了一套開箱即用的測試點擊面板。

5.2 編寫自動化單元測試

如果你追求更嚴謹的工程質量，可以讓大模型幫你使用 Jest 等測試框架編寫單元測試（Unit Tests），對核心業務邏輯進行邊界測試（比如傳入負數價格時，資料庫層的校驗是否生效）。

6. 後端接口必知的最佳實踐

即使有 AI 的協助，作為整個系統的“把關人”，你依然需要了解並審核以下這些核心準則：

RESTful 規範的路徑命名：
- 好的設計：GET /api/users（獲取用戶列表）、POST /api/users（創建用戶）。URL 應該代表“資源”的名詞。
- 錯誤的設計：POST /api/getUser 或 POST /api/createUser。動詞應該交由 HTTP Method (GET/POST/PUT/DELETE) 來體現。
規範的 HTTP 狀態碼：
- 200/201：請求成功 / 資源創建成功。
- 400：Bad Request，前端傳參格式錯誤、少傳了必填項。
- 401/403：Unauthorized / Forbidden，用戶未登錄或無權操作。
- 404：NotFound，資源不存在。
- 500：Server Error，後端程式碼報錯或資料庫掛了，絕對儘量避免將報錯調用棧直接暴露給前端（會有安全隱患）。
永遠不信任用戶的輸入：前端的輸入可能是偽造的，所有核心參數校驗必須在後端接口中再做一次。

7. 總結

通過本章節的學習，你實現了開發視角的真正轉變：你不再是被困在語法和標點符號中的“打字員”，而是上升成為了系統設計師和架構指揮官。你已經掌握了：

API 接口與前後端分離的核心繫統思維。
如何通過提供上下文與分層結構理念，大幅提高大模型生成服務端程式碼的質量。
把繁瑣的文檔編寫和測試用例構建，巧妙地轉化為 AI 擅長的自動化任務。
結合此前學過的 Supabase 知識，打通了從客戶端請求到底層資料庫更新的完整資料流。

💡 下一步

當你的資料流和後端服務都準備就緒後，它目前還只能在你的本地電腦上“自娛自樂”。在接下來的章節中，我們將學習如何把這套辛辛苦苦建立的服務部署（Deploy）到公網服務器上，讓你的產品能被全世界的用戶訪問。

大模型輔助編寫接口程式碼與接口文檔 ​

你將學到 ​

1. 為什麼我們需要 API 接口？ ​

2. 項目架構設計與初始化 ​

2.1 常見的 API 工程結構 ​

2.2 藉助 AI 完成工程初始化 ​

3. 核心實戰：大模型輔助接口開發 ​

3.1 賦予大模型完整上下文 ​

3.2 審查大模型生成的程式碼 ​

4. 解放雙手：自動生成接口文檔 ​

5. 保駕護航：生成測試程式碼與 Postman 集合 ​

5.1 生成 Postman / Apifox 測試配置 ​

5.2 編寫自動化單元測試 ​

6. 後端接口必知的最佳實踐 ​

7. 總結 ​