RESTful 伺服器之搭建

Table of contents

背景

架設 RESTful API 伺服器需的步驟

  1. 選擇 Web 框架： 首先，選擇一個適合你的程式語言的 Web 框架。常見的選擇包括：

    • Python： 使用 Flask、Django REST framework、FastAPI 等。
    • Node.js： 使用 Express、Koa、Restify 等。
    • Ruby： 使用 Ruby on Rails。
    • Java： 使用 Spring Boot、Dropwizard 等。
    • Go： 使用 Gin、Echo 等。

    選擇框架時，考慮到你的需求、熟悉度和框架的特性。

  2. 安裝框架： 安裝你選擇的框架。通常，可以使用 package manager 如 pip（Python）、npm（Node.js）、gem（Ruby）或者 maven/gradle（Java）進行安裝。

  3. 設定路由（路徑映射）： 定義 API 的路由和端點。這些路由將決定 API 的 URL 結構和各種端點可以提供的服務。

  4. 實現業務邏輯： 在每個端點中實現相應的業務邏輯。這可能包括資料庫查詢、檔案操作、驗證、授權等。

  5. 處理請求和回應： 使用框架提供的工具處理請求（request）和回應（response）。這可能包括解析請求、驗證用戶、記錄日誌等。

  6. 實現 RESTful 準則： 遵循 RESTful API 的設計準則，包括使用合適的 HTTP 方法（GET、POST、PUT、DELETE 等）、使用資源 URI、使用適當的狀態碼、實現 HATEOAS（Hypermedia As The Engine Of Application State）等。

  7. 實現認證和授權： 根據你的需求實現 API 的認證和授權機制。這可以包括使用 API 金鑰、OAuth、JWT 等方法。

  8. 測試 API： 進行單元測試和端對端測試，以確保 API 的正確運作。

  9. 文件化 API： 提供清晰且易於理解的 API 文件，以方便其他開發者使用你的 API。這可以使用 Swagger、OpenAPI 等工具來生成 API 文件。

  10. 部署伺服器： 最後，將你的 API 部署到伺服器上。這可以使用雲服務（AWS、Google Cloud、Azure）、自有伺服器或容器技術（Docker、Kubernetes）等方式進行。

以上是一個簡要的流程，實際上可能還需要根據你的特定需求和技術堆疊進行調整。

框架比較

比較 Python、Node.js、Java、Go 和 Ruby 這五種編程語言在 API 伺服器框架方面的應用場域、傳遞訊息的複雜度和遠端算力：

  1. 應用場域：

    • Python：
      • 適用場域： Python 適用於各種應用場景，特別是在科學計算、數據分析、機器學習和 Web 開發等領域廣受歡迎。
    • Node.js：
      • 適用場域： Node.js 適用於構建高效的非同步 I/O 應用，特別是適用於實時應用程式和單頁應用（SPA）的後端。
    • Java：
      • 適用場域： Java 適用於大型企業應用程式、分布式系統、後端服務、Android 開發等，具有豐富的生態系統和企業級支持。
    • Go：
      • 適用場域： Go 適用於構建高性能和併發性能的應用，特別適用於微服務、容器化應用和系統級編程。
    • Ruby：
      • 適用場域： Ruby 適用於 Web 開發，特別是 Ruby on Rails 框架在構建快速原型和開發 MVC 應用方面非常流行。

  2. 傳遞訊息的複雜度：

    • Python：
      • 傳遞訊息複雜度： Python 擁有簡潔易讀的語法，傳遞訊息的複雜度通常較低，尤其在使用框架如 Flask 或 FastAPI 時。
    • Node.js：
      • 傳遞訊息複雜度： Node.js 非同步特性使其在處理大量並發請求時表現優越，但某些開發者可能需要習慣事件驅動的程式風格。
    • Java：
      • 傳遞訊息複雜度： Java 的豐富生態系統和靜態類型語言特性有助於管理較大的程式碼庫，但可能會增加開發的初始複雜度。
    • Go：
      • 傳遞訊息複雜度： Go 設計簡單，語言特性有助於管理並發和簡化代碼，傳遞訊息的複雜度相對較低。
    • Ruby：
      • 傳遞訊息複雜度： Ruby 的語法簡潔，但在處理大量並發時可能需要注意性能。

  3. 遠端算力：

    • Python：
      • 遠端算力： Python 在科學計算和機器學習方面表現優異，但相對於一些原生編譯語言，性能可能較低。
    • Node.js：
      • 遠端算力： Node.js 的非同步 I/O 特性使其在處理大量並發請求時表現優越，但在 CPU 密集型任務上性能可能受限。
    • Java：
      • 遠端算力： Java 的虛擬機（JVM）具有良好的性能，適用於處理大量並發和較大規模的計算。
    • Go：
      • 遠端算力： Go 的設計重點之一是性能，特別適用於需要高效處理的並發工作。
    • Ruby：
      • 遠端算力： Ruby 的性能可能不如一些原生編譯語言，在某些場景下可能不適用於大規模計算。

總的來說，每種語言都有其優勢和適用場景，取決於具體的應用需求和開發團隊的經驗。

Terminology

FastAPI

FastAPI 是一個基於 Python 的現代、快速（fast）、Web 框架，設計用於構建 API。以下是一些 FastAPI 的主要特點和資訊：

  1. 基於標準的 Python 類型提示：
    • FastAPI 使用 Python 3.7+ 的標準類型提示（Type Hints），這使得代碼更易於理解，並且提供了更好的自動化文檔生成。
  2. 自動生成 API 文件：
    • FastAPI 支援自動生成交互式 API 文檔（Swagger 和 ReDoc），這使得開發者能夠輕鬆理解 API 的端點、輸入數據、輸出數據以及如何使用 API。
  3. 高性能：
    • FastAPI 通過使用 Starlette 框架以及 Pydantic 库等進行底層優化，以實現高性能的異步（async）處理。
  4. 支援 OAuth 和 JWT：
    • 提供了易於使用的 OAuth2 和 JWT 認證方案，方便實現身份驗證和授權。
  5. 依賴注入：
    • FastAPI 具有先進的依賴注入系統，方便管理應用程式中的依賴關係。
  6. 支援 WebSockets：
    • 可以處理 WebSockets 連接，這使得 FastAPI 不僅適用於傳統的 HTTP API，還適用於實時應用程式。
  7. 支援 GraphQL：
    • 提供與 GraphQL 的集成，方便構建更靈活和高效的 API。
  8. 易於測試：
    • FastAPI 具有易於測試的設計，支援標準的測試框架。
  9. 生態系統整合：
    • FastAPI 與大量現有的 Python 生態系統整合，包括 ASGI 伺服器（如 Uvicorn 和 Hypercorn）、數據庫引擎（如 SQLAlchemy 和 Tortoise-ORM）等。
  10. 自動化的 OpenAPI 和 JSON Schema 生成：
    • FastAPI 可以自動生成 OpenAPI 文檔和 JSON Schema，提供詳細的 API 描述和驗證。

FastAPI 是一個現代且強大的 Web 框架，特別適用於構建高效、易於維護和自動文檔化的 API。

API金鑰

API 金鑰（API Key）是一種用於識別和驗證 API 使用者身份的機制。這是在許多 API 中常見的安全措施之一，以確保只有經過授權的應用程式或使用者可以訪問特定的 API 資源。以下是一些 API 金鑰的相關資訊：

  1. 用途：
    • 身份識別： API 金鑰充當識別 API 使用者身份的唯一標識。
    • 授權： 通常與 API 金鑰相關聯的是特定的權限，以限制應用程式對 API 資源的訪問。
  2. 如何使用：
    • 傳遞於請求中： 通常，API 金鑰是通過將其包含在 API 請求的標頭中或作為參數的一部分來傳遞的。例如：
      GET /api/resource
Headers:
  Authorization: API_KEY
  3. 生成方式：
    • 手動創建： 由 API 提供者手動創建和分配給開發者或應用程式。
    • 自動生成： 由 API 提供者提供的一種機制，可能在開發者控制台上或在應用程式註冊流程中生成。
  4. 保密性：
    • 保密性要求： API 金鑰通常需要保持機密，應盡量避免在公共地方公開。
    • 加密和傳輸： 在使用 HTTPS 等安全通信協議的情況下，API 金鑰可以透過加密的方式傳輸，提高安全性。
  5. 採用最佳實踐：
    • 定期複製和重新生成： 定期更換 API 金鑰以增加安全性。
    • 限制訪問： 將 API 金鑰與特定 IP 地址、應用程式或用戶相關聯，以減少濫用風險。

API 金鑰是一種有效的安全機制，但同時也需要遵循最佳實踐以確保安全性和防止濫用。

OAuth

OAuth（Open Authorization）是一種授權標準，用於委託第三方應用程式獲取訪問用戶資源的權限，而無需將用戶的密碼傳遞給該應用程式。OAuth 的目標是在保護用戶資料的同時，使得用戶能夠授權其他應用程式訪問其受保護的資源。

OAuth 主要涉及以下幾個主要角色：

  1. 用戶（Resource Owner）： 擁有資源的實體，通常是用戶。

  2. 客戶端（Client）： 需要訪問用戶資源的應用程式。

  3. 授權服務（Authorization Server）： 負責驗證用戶並發放訪問令牌的伺服器。

  4. 資源服務（Resource Server）： 存儲和提供用戶資源的伺服器。

  5. 授權令牌（Access Token）： 由授權服務授予客戶端的令牌，用於訪問資源服務。

OAuth 的主要流程如下：

  1. 註冊應用程式： 客戶端向授權服務註冊，獲得客戶端識別和密碼。

  2. 取得授權碼： 用戶將授權授予客戶端，客戶端使用授權碼向授權服務請求取得授權令牌。

  3. 取得令牌： 授權服務驗證客戶端，並向客戶端發放授權令牌。

  4. 訪問資源： 客戶端使用授權令牌向資源服務請求訪問用戶資源。

OAuth 提供了多種授權流程，包括授權碼流程（Authorization Code Flow）、隱式流程（Implicit Flow）、密碼流程（Password Credentials Flow）等，以應對不同的應用場景。這種標準的設計有助於確保安全性、隱私性和互操作性。

JWT

JWT（JSON Web Token）是一種開放標準（RFC 7519），定義了一種緊湊且自包含的方法，用於在各方之間安全地傳輸資訊作為 JSON 對象。JWT 可以使用 HMAC 算法或使用 RSA 或 ECDSA 的公開/私有金鑰對進行簽署，以驗證傳送者的身份並確保資訊的完整性。

JWT 由三個部分組成：

  1. Header（標頭）： 通常包含兩部分，類型（”typ”）和簽署算法（”alg”）。通常以 Base64 編碼為 JSON 字符串。

  2. Payload（有效載荷）： 包含一個或多個聲明（claim），每個聲明表示一個有關實體（通常是用戶）和有關主題（通常是客戶端）的資訊。可以包含預定義的聲明，也可以包含自定義的聲明。也是以 Base64 編碼的 JSON 字符串。

  3. Signature（簽署）： 使用密碼或私有金鑰進行簽署，以確保在傳輸過程中未被篡改。簽署的部分是前兩部分的編碼結果和一個秘密（HMAC）或私有金鑰的結果。

JWT 的使用場景包括身份驗證和資訊傳輸。當用戶成功登錄後，伺服器可以生成一個 JWT，並將其發送給客戶端。客戶端將 JWT 存儲，並在後續的請求中將其包含在標頭中。伺服器使用先前共享的密鑰驗證 JWT 的簽名，並可以使用有效載荷中的信息驗證用戶身份。

JWT 具有簡單、輕量和自包含的特性，使其在分散式系統和前後端分離的應用中廣泛應用。