2025-05-28 情境式的比喻來解釋 POST /api/chat 這個 API 怎麼用

發表於 分類於 閱讀次數：
2025-05-28 情境式的比喻來解釋 POST /api/chat 這個 API 怎麼用

2025-05-28 情境式的比喻來解釋 POST /api/chat 這個 API 怎麼用

很好 👍 我用一個「情境式」的比喻來解釋 POST /api/chat 這個 API 怎麼用。

1. API 路徑

  • 你的 server（gateway.mjs）啟動後會跑在某個網址，例如：

    1
    http://localhost:4000

  • POST /api/chat 就是：

    1
    http://localhost:4000/api/chat

2. 這個 API 的用途

它是一個「轉接站」，前端（或你自己用 curl / Postman 測試）可以呼叫這個 API，告訴它：

  • 我要用哪個 AI（provider，例如 openai 或 deepseek）
  • 我要傳送什麼對話（messages，像是使用者說的話）

API 收到後會：

  1. 判斷你要的是哪個 provider（openai 或 deepseek）。
  2. 把你的對話轉交給對應的 AI。
  3. 把 AI 回覆再轉交回來給你。

如果你沒填 API key，它會用 mock（模擬回覆） 給你假資料，方便測試。

3. Request Body 說明

1
2
3
4
{
  "provider": "openai",
  "messages": [{ "role": "user", "content": "hello" }]
}

  • provider: 指定要呼叫哪個 AI

    • openai → 會走 OpenAI API
    • deepseek → 會走 DeepSeek API
    • 如果沒寫，預設是 openai

  • messages: 對話內容

    • 這是 ChatGPT 風格的格式，包含多個訊息。

    • 每個訊息有：

      • role: 誰在說話（user=使用者, assistant=AI, system=系統指令）
      • content: 實際的文字內容

例如：

1
2
3
4
5
6
7
{
  "provider": "openai",
  "messages": [
    { "role": "system", "content": "你是一個很有禮貌的客服" },
    { "role": "user", "content": "你好，可以幫我查詢訂單嗎？" }
  ]
}

4. 測試方式（情境）

假設我在本機跑起來，你可以用 curl 測試：

1
2
3
4
5
6
curl -X POST http://localhost:4000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "messages": [{ "role": "user", "content": "hello" }]
  }'

回傳（如果沒 API key）會像這樣：

1
2
3
4
{
  "provider": "openai",
  "text": "[mock openai] 這是模擬回覆"
}

👉 重點總結：

  • /api/chat 就是「前端問 AI 的唯一入口」。
  • 你在 body 裡面指定 要用哪個 AI（provider）和 對話內容（messages）。
  • 它會幫你轉接給 OpenAI 或 DeepSeek，沒 key 就回 mock。

要不要我幫你寫一個 實際 Postman 測試範例（含畫面流程），讓你可以直接看結果？
好 👍 那我就用 Postman 測試 /api/chat 的完整流程來給你一個「情境式操作」範例。

🎯 前置條件

  1. 你已經在 mcp-gateway 目錄下建立好 gateway.mjs。

  2. 已經裝好 express / dotenv（你剛剛有做）。

  3. .env 裡面先不用放 API key（這樣會回 mock 回覆）。

  4. 啟動 server：

    1
    node gateway.mjs

    你應該會看到：

    1
    MCP gateway listening on 4000

🛠️ Postman 測試步驟

1. 開啟 Postman

  • 新增一個 Request
  • 選擇 POST

2. 設定 URL

在 URL 欄位輸入：

1
http://localhost:4000/api/chat

3. 設定 Header

在 Headers 分頁新增一筆：

1
2
Key: Content-Type
Value: application/json

4. 設定 Body

切換到 Body → raw → JSON，輸入：

1
2
3
4
{
  "provider": "openai",
  "messages": [{ "role": "user", "content": "hello" }]
}

5. 點擊 Send

如果你的 .env 沒有設定 API key，會回：

1
2
3
4
{
  "provider": "openai",
  "text": "[mock openai] 這是模擬回覆"
}

如果你有填 API key，會回傳真正的 OpenAI 回覆（例如 GPT 回應一段文字）。

📌 重點

  • http://localhost:4000/api/chat = 你的 API Gateway 入口。
  • Body 的 provider 決定用哪個 AI。
  • messages 是對話訊息（照 ChatGPT API 格式）。
  • 沒有 API key → 回 mock（方便測試）。

要不要我幫你整理一張 Postman 測試畫面示意圖（標出 URL、Headers、Body）？這樣你照著操作就不會錯。