Day 6 | 🗣️ 溝通的語言：API, Restful SOAP Websocket,JSON/XML

17th鐵人賽

ChrisYen8341_V

2025-08-11 19:53:15

198 瀏覽

分享至

Day 6 | 🗣️ 溝通的語言：API, Restful SOAP Websocket,JSON/XML

嗨，各位鐵人夥伴！ 👋

這是一篇專為新手設計的文章。如果你是經驗豐富的開發者，可以考慮跳過，或將它分享給需要入門指引的新人，有效節省您寶貴的指導時間！ 😉

本文將用最淺顯易懂的方式，解釋 API 的真正含義，並釐清業界口語中的「API」與其學術定義的區別。此外，我們還會探討常見的 Restful API，並簡要介紹 SOAP 和 WebSocket。當然，過程中也少不了常用的資料格式，如 JSON 與 XML。

此文由本人花數小時撰寫，融合了業界經驗分享，AI僅用輔助與美化文章內容，你看到不懂的地方可以搭配AI查詢關鍵字，希望你會喜歡

🤔 API：大家說的都不太一樣？

首先，讓我們先看看維基百科對 API (Application Programming Interface) 的定義：

An API is a computing interface that defines interactions between multiple software intermediaries. It consists of a set of definitions, protocols, and tools for building application software.

簡單來說，API 的標準定義非常廣泛。但在日常工作會議中，我們口中的「API」通常會根據上下文，簡化為特定類型的 API。

當討論涉及 Web 應用程式架構時，業界口語中的 API，絕大多數指的是 Web API 或 HTTP API。

用最通俗的話來解釋這種 API 就是：

一套系統提供好的方法，讓其他程式能透過 HTTP 協定來呼叫它，以執行特定商業邏輯（如：新增、查詢、修改、刪除資料等）。

請注意，API 是設計給程式呼叫的，而不是給使用者直接操作。這裡的「程式」包含但不限於：

其他後端系統
前端瀏覽器
桌面應用軟體
您自己撰寫的任何程式碼

常見範例：

系統間串接：您負責的系統 A 需要發送簡訊。公司的簡訊系統 B 提供了一個「發送簡訊的 API」。這意味著您的系統 A 可以透過 HTTP Request 呼叫系統 B 的 API，系統 B 收到請求後會執行發送簡訊的動作，並回傳一個 Response 告知您發送是否成功。
前端獲取資料：當使用者在瀏覽器上操作時，瀏覽器本身就是一個「程式」。在前後端分離的架構下 (Client-Side Rendering)，瀏覽器會直接呼叫後端 API 來獲取或提交資料，例如載入文章列表、新增、編輯或刪除一篇文章。

重點：API 不僅僅是為了「要資料」。它是一種互動，只要雙方定義好溝通方式，它就能幫您執行新增、修改、刪除資料，或觸發發送簡訊等特定行為。

廣義的 API

回到維基百科的定義，許多人第一次看到 "Interface" (介面) 這個詞可能會感到困惑。

讓我們先關注這句話的核心：defines interactions between multiple software intermediaries。白話來說，它定義了多個軟體之間如何協作的標準。這裡的 "software" 涵蓋了許多層級，所以才會說標準的API定義很廣：

應用程式層級：您的訂單系統與物流系統之間的溝通。
程式語言層級：Java 程式碼呼叫 System.out.println()。
作業系統層級：您的應用程式呼叫 Windows 的功能來讀寫檔案。

這些 API 就像一個操作「介面」，它定義了您該如何使用它（傳什麼參數），並隱藏了底層複雜的實作細節，讓開發變得更簡單。

📋 常見的傳遞資料格式

在系統溝通時，我們需要一個共通的「語言」，也就是資料格式。最常見的是 JSON 和 XML。

JSON (JavaScript Object Notation)

{
  "orderId": "ORD123456",
  "customer": {
    "name": "陳大明",
    "email": "david.chen@example.com"
  },
  "items": [
    {
      "productId": "PROD001",
      "productName": "筆記型電腦",
      "quantity": 1,
      "price": 25000.0
    },
    {
      "productId": "PROD002",
      "productName": "無線滑鼠",
      "quantity": 2,
      "price": 800.0
    }
  ],
  "totalAmount": 26600.0,
  "status": "已出貨",
  "orderDate": "2025-08-11T19:30:00Z"
}

XML (eXtensible Markup Language)

<order>
    <orderId>ORD123456</orderId>
    <customer>
        <name>陳大明</name>
        <email>david.chen@example.com</email>
    </customer>
    <items>
        <item>
            <productId>PROD001</productId>
            <productName>筆記型電腦</productName>
            <quantity>1</quantity>
            <price>25000.00</price>
        </item>
        <item>
            <productId>PROD002</productId>
            <productName>無線滑鼠</productName>
            <quantity>2</quantity>
            <price>800.00</price>
        </item>
    </items>
    <totalAmount>26600.00</totalAmount>
    <status>已出貨</status>
    <orderDate>2025-08-11T19:30:00Z</orderDate>
</order>

講完格式之後，我們就來看常見的 API 架構或風格或協定囉

🎨 Restful API：一種設計風格而非硬性規範

這是一個經常引起混淆的概念，即使是一些初階工程師也可能一知半解。

維基百科將 REST (Representational State Transfer) 定義為一種軟體架構風格 (software architectural style)。

關鍵在於，它是一種風格，而不是像法律一樣的硬性規範。這意味著它沒有任何強制性。

正因如此，業界在實踐上可能不完全符合其理論，但通常會遵循以下幾個核心原則：

使用 HTTP 協定：所有通訊都基於 HTTP。
使用 JSON 格式傳遞資料：雖然 RESTful 並未強制規定，但 JSON 已成為事實上的標準。
以「資源」為中心的 URL：URL 代表的是「名詞」(資源)，而不是「動詞」(操作)。
- 例如：https://example.com/orders、https://example.com/posts
使用 HTTP 方法 (Method) 表達操作：
- GET：讀取資源。
- POST：新增資源。
- PUT / PATCH：更新資源。
- DELETE：刪除資源。
範例：
- GET /orders：取得所有訂單。
- GET /orders/{orderId}：取得特定 ID 的訂單。
- POST /orders：新增一筆訂單 (資料放在 Request Body)。
- PUT /orders/{orderId}：修改特定 ID 的訂單 (資料放在 Request Body)。
- DELETE /orders/{orderId}：刪除特定 ID 的訂單 (通常是軟刪除)。
無狀態 (Stateless)：這是 RESTful 的一個重要特性。為了理解它，我們得先了解其相反的概念——有狀態 (Stateful)，而這通常與 Session 機制緊密相關。

讓我們先深入探討 Session 的運作機制：

在傳統的單體式架構中，當一個請求 (Request) 送達主機，後端程式可以在該主機的記憶體 (Memory) 中建立一個 Session 物件。這個物件可以儲存任何資訊（例如使用者登入狀態），並擁有一個獨一無二的 Session ID。

當伺服器回應 (Response) 時，會要求瀏覽器將這個 Session ID 儲存在 Cookie 中。

根據 Cookie 的特性，瀏覽器之後的每一個請求都會自動帶上這個 Session ID。

如此一來，後端伺服器便能透過 Session ID，在主機記憶體中找回先前儲存的資訊，並根據這些資訊執行不同的處理。

聽起來還是有點複雜嗎？我們用「使用者認證」來舉例就清楚了：
1. 使用者使用帳號密碼登入。
2. 後端驗證成功後，將使用者資料（如姓名、ID）存入 Session 物件，並將 Session ID 透過 Cookie 交給瀏覽器。
3. 當使用者訪問網站的其他頁面時，瀏覽器會自動帶上存有 Session ID 的 Cookie。
4. 後端檢查到 Session ID，從記憶體中找到對應的 Session 物件，確認此使用者為已登入狀態，於是直接顯示頁面，無需再次驗證。
您發現問題了嗎？

後續請求的處理方式，依賴於前一個請求在伺服器上儲存的狀態（Session 物件）。這種設計就是有狀態 (Stateful)。

而 RESTful 強調的 無狀態 (Stateless)，正是為了解決這種對伺服器狀態的依賴性，讓每個請求都變得獨立、自我包含，進而帶來易於水平擴展等架構上的好處。

Restful API 的好處

可預期性：當團隊遵循 RESTful 風格時，即使不看文件，開發者也能從 URL 和 HTTP 方法大致猜到 API 的功能，大幅提升協作效率。
靈活性：因為是「風格」而非「規範」，它提供了設計上的彈性，不會過於死板。
主流與生態系：作為當前主流，它擁有豐富的工具支援，例如用於產生 API 文件的 OpenAPI (Swagger)。

🧼 SOAP：嚴謹的傳輸協定

SOAP (Simple Object Access Protocol) 是另一種 API 設計風格，重點如下：

嚴謹的協定：與 RESTful 的「風格」不同，SOAP 是一個嚴格的協定 (Protocol)。
基於 XML：資料交換格式主要是 XML。
WSDL 規格書：通常會搭配一個稱為 WSDL (Web Services Description Language) 的嚴謹規格文件，詳細定義了請求、回應的結構與可用操作。
應用場景：常見於需要高度嚴謹和安全性的系統，例如金融、電信或跨國交易 (如 SWIFT)。

⚡ WebSocket：實現即時雙向通訊

WebSocket 與前兩者不同，它解決的是即時通訊的需求。

持續性連線：傳統 HTTP 是「請求-回應」模式，必須由客戶端發起請求。WebSocket 則在客戶端與伺服器之間建立一條持續性的雙向連線。
伺服器主動推播：最大的特點是伺服器可以主動發送訊息給客戶端，無需等待客戶端請求。
應用場景：
- 即時通訊軟體：如 LINE, Messenger。
- 線上遊戲：即時同步玩家狀態。
- 金融報價：股票、外匯等價格的即時更新。
與 RESTful 互補：WebSocket 和 RESTful API 並非競爭關係，而是互補的。一套現代化的系統常會結合兩者，用 RESTful 處理常規的資料操作，用 WebSocket 處理即時訊息推播。