什么是 REST API？

• API（應用程序編程接口）是軟件組件之間的橋梁，允許不同部分的系統進行通信和交互。
• REST 代表“表述性狀態轉移”（Representational State Transfer），是一種設計 API 的風格，用于通過網絡在分布式應用程序之間進行通信。
• REST API 廣泛應用于各種規模的軟件系統中，從簡單的 Web 或移動應用程序到復雜的分布式微服務架構。
• REST 通信是同步的，通常用于需要快速響應的場景，例如在用戶界面中顯示數據。
• 在某些情況下，異步架構可能更適合，例如數據需要分發到多個服務或數據處理耗時較長時。
• REST 的數據交換是語言無關的，這使其能夠與多種軟件系統兼容。通常，僅需基本的 HTTP 和數據序列化功能即可實現。

REST API 的構建塊

1. 服務器與客戶端：通信發生在提供 REST API 的服務器和與之交互的客戶端之間。
2. HTTP 協議：雖然 REST 不強制使用 HTTP，但 HTTP 是最常用的底層協議，因此通常需要一個 HTTP 服務器。
3. 資源與操作：REST API 的核心是資源，資源通過 HTTP 方法 和 URL 路徑 來描述操作。
4. 數據序列化：REST 是為網絡通信設計的，因此需要對數據進行序列化。最常用的格式是 JSON，因為它簡單且易于閱讀。

示例：Todo 列表 API

為了更好地說明，我們將實現一個用 Golang 編寫的簡單 REST API。我們的資源是 Todo 項目，它描述了一項任務，可以標記為已完成或未完成。

API 端點設計

1. 獲取所有 Todo 項目：

   • 請求：GET /Todo/all
   • 操作：只讀操作，不會修改服務器端狀態。

2. 添加新的 Todo 項目：

   • 請求：POST /Todo
   • 操作：通過 HTTP 請求體傳輸新的 Todo 項目，創建一個新的資源。

3. 操作特定的 Todo 項目：

   • 獲取特定項目：GET /Todo/{index}，只讀操作。
   • 更新特定項目：PUT /Todo/{index}，通過 HTTP 請求體傳輸更新的 Todo 項目，替換現有資源。PUT 操作是冪等的。
   • 刪除特定項目：DELETE /Todo/{index}，刪除指定資源。

Golang 中的實現

啟動 HTTP 服務器

在 Golang 中啟動一個 HTTP 服務器非常簡單。以下是一個定義簡單端點 /hello 的示例：

package main

import (
    "fmt"
    "net/http"
)func main() {
    http.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "Hello, World!")
    })
    http.ListenAndServe(":8080", nil)
}

運行程序后，可以通過瀏覽器或 [curl](http://m.dlbhg.com/wiki/what-are-curl-url-uri/) 查詢 /hello 端點。

請求處理

為了更靈活地處理請求，可以使用 Golang 的 ServeMux 類型。ServeMux 是一個多路復用器，通過 URL 路徑和 HTTP 方法將請求分派到具體的處理邏輯中。

數據模型

以下是一個簡單的 Todo 數據模型示例：

type Todo struct {
    Title     string json:"title"
    Completed bool   json:"completed"
}

需要注意的是，只有導出的字段（以大寫字母開頭）才能被序列化為 JSON 或從 JSON 反序列化。

讀寫 JSON 數據

Golang 提供了標準庫函數 json.Marshal 和 json.Unmarshal 來處理 JSON 數據。例如：

• 將 Go 類型寫入 HTTP 響應：

todos := []Todo{{Title: "Learn Go", Completed: false}}
jsonData, _ := json.Marshal(todos)
w.Write(jsonData)

• 從請求體中讀取 JSON 數據：

var todo Todo
json.NewDecoder(r.Body).Decode(&todo)

URL 參數與查詢參數

• URL 參數：通過路徑參數（如 /Todo/{index}）獲取特定資源。
• 查詢參數：通過 GET /Todo/all?complete=false 只返回未完成的任務。

狀態代碼與錯誤處理

為客戶端提供有意義的狀態代碼和錯誤消息是 REST API 的重要部分。例如：

• 設置狀態代碼 201 Created：

w.WriteHeader(http.StatusCreated)

• 返回錯誤狀態和消息：

http.Error(w, "Invalid data", http.StatusBadRequest)

總結

通過以上構建塊，我們在 Golang 中實現了一個簡單但功能強大的 REST API。整個過程完全基于標準庫，無需第三方依賴。Golang 提供了直觀且高效的工具來構建 REST API，這在許多其他語言中可能更為復雜。

REST API 的核心概念已經在本文中詳細討論。如果您對完整的源代碼（包括自動化測試）感興趣，可以參考相關代碼倉庫。

原文鏈接: https://bastian-isensee.com/post/29-rest-api-go/

<ol id="wktfk"></ol>