Python: 建立 REST API

如何使用 Flask 建立 REST API

👋 歡迎來到 Stackhero 文檔！

Stackhero 提供一個即用型的 Python 雲端 解決方案，帶來多項好處，包括：

  • 只需一個簡單的 git push，即可在幾秒鐘內部署您的應用程式。
  • 使用您自己的域名，並享受 HTTPS 證書的自動配置以增強安全性。
  • 享受自動備份、一鍵更新，以及簡單、透明且可預測的定價，讓您安心無憂。
  • 得益於專用的私人 VM，獲得最佳的性能和強大的安全性。

節省時間並簡化您的生活：只需 5 分鐘即可嘗試 Stackhero 的 Python 雲端託管 解決方案！

這份文件是關於如何在 Python 中建立 REST API 的初學者指南。

在這個例子中，我們使用 Flask，一個輕量且易於使用的微框架，讓您能快速建立網頁應用程式。

先決條件

在開始之前，請確保您的電腦已安裝以下工具：

  1. Python
  2. pip
  3. git
  4. asdf

如果您的開發環境尚未設置，請參考 Development platform 指南以獲取詳細說明。或者，您可以使用線上 Code-Hero 平台。Code-Hero 提供線上 IDE 和終端機，所有必要工具都已預先安裝，讓您可以立即開始編碼而無需安裝。

Python REST API 在 Code-Hero 中運行，可直接從瀏覽器訪問Python REST API 在 Code-Hero 中運行，可直接從瀏覽器訪問

建立新專案

第一步是建立一個新的專案目錄。在本指南中，我們將其命名為 myRestApi：

mkdir myRestApi
cd myRestApi

接下來，使用 asdf 設定 Python 版本為最新版本，並初始化 Git 儲存庫：

asdf install python latest \
  && asdf local python latest

echo "__pycache__/" >> .gitignore

git init
git add -A .
git commit -m "First commit"

安裝 Flask 依賴

在這個例子中，我們只需要一個依賴：Flask。

Flask 是一個輕量的網頁框架，能夠快速開發網頁應用程式。它設計簡單易用，讓開發者能快速建立和部署網頁服務。內建的路由、模板和 HTTP 請求處理支持，使 Flask 成為建立 REST API 的絕佳選擇。

使用 pip 安裝 Flask（和 python-dotenv）：

pip install Flask python-dotenv

我們在這裡安裝了 Flask 和 python-dotenv 模組。您將很快看到我們為何使用 python-dotenv（提示：用於管理環境變數）。

安裝後，將套件版本凍結到 requirements.txt 文件中：

pip freeze > requirements.txt

凍結您的依賴確保您的生產伺服器或同事使用與您相同的版本。幾秒鐘的工作可以避免許多未來的麻煩。

使用 Flask 實現 REST API

現在，讓我們進入程式碼！

建立一個名為 app.py 的文件，並插入以下程式碼：

import os
from dotenv import load_dotenv
from flask import Flask, jsonify, request

# 當不在生產環境時，從 .env 文件加載環境變數
if os.environ.get('ENV') != 'production':
    load_dotenv()

# 建立 Flask 應用程式
app = Flask(__name__)

# 範例數據集
tasks = [
    {
        'id': 1,
        'title': '買雜貨',
        'description': '牛奶、奶酪、披薩、水果',
        'done': False
    },
    {
        'id': 2,
        'title': '學習 Python',
        'description': '學習 Python 程式設計基礎',
        'done': False
    }
]

# 路由 '/api/tasks' (GET) 列出所有任務
@app.route('/api/tasks', methods=['GET'])
def get_tasks():
    return jsonify({'tasks': tasks})

# 路由 '/api/tasks/<task_id>' (GET) 根據 ID 獲取特定任務
@app.route('/api/tasks/<int:task_id>', methods=['GET'])
def get_task(task_id):
    task = [task for task in tasks if task['id'] == task_id]
    if len(task) == 0:
        return jsonify({'error': '任務未找到'}), 404
    return jsonify({'task': task[0]})

# 路由 '/api/tasks' (POST) 創建新任務
@app.route('/api/tasks', methods=['POST'])
def create_task():
    if not request.json or 'title' not in request.json:
        return jsonify({'error': '標題是必需的'}), 400
    task = {
        'id': tasks[-1]['id'] + 1,
        'title': request.json['title'],
        'description': request.json.get('description', ""),
        'done': False
    }
    tasks.append(task)
    return jsonify({'task': task}), 201

# 啟動 API 伺服器
if __name__ == '__main__':
    if os.environ.get('ENV') == 'production':
        app.run()
    else:
        app.run(host='0.0.0.0', port=8080, debug=True)

要啟動伺服器，請運行：

python app.py

使用 host='0.0.0.0' 選項，您也可以在使用 Code-Hero 時通過瀏覽器訪問您的 API。只需導航到 http://<XXXXXX>.stackhero-network.com:8080/api/tasks，將 <XXXXXX> 替換為您的 Code-Hero 網域。

測試您的 REST API

伺服器運行後，您可以使用 cURL 與其互動。以下是一些範例：

  • 檢索所有任務：

    curl -s http://localhost:8080/api/tasks
{
  "tasks": [
    {
      "description": "牛奶、奶酪、披薩、水果",
      "done": false,
      "id": 1,
      "title": "買雜貨"
    },
    {
      "description": "學習 Python 程式設計基礎",
      "done": false,
      "id": 2,
      "title": "學習 Python"
    }
  ]
}

  • 檢索 ID 為 2 的任務：

    curl -s http://localhost:8080/api/tasks/2
{
  "task": {
    "description": "學習 Python 程式設計基礎",
    "done": false,
    "id": 2,
    "title": "學習 Python"
  }
}

  • 創建新任務：

    curl -s -X POST -H "Content-Type: application/json" \
-d '{"title": "新任務", "description": "使用 cURL 創建"}' \
http://localhost:8080/api/tasks
{
  "task": {
    "description": "使用 cURL 創建",
    "done": false,
    "id": 3,
    "title": "新任務"
  }
}

提示：將輸出導入 jq 以美化 JSON。例如，curl -s http://localhost:8080/api/tasks/2 | jq 會產生更易讀的結果。

使用 Flask 的 Python REST API 範例，運行於 Stackhero Code-Hero，伺服器 (1) 和使用 cURL 的客戶端 (2)使用 Flask 的 Python REST API 範例，運行於 Stackhero Code-Hero，伺服器 (1) 和使用 cURL 的客戶端 (2)

處理環境變數

環境變數對於保護敏感信息（如資料庫憑證或 API 密鑰）至關重要。使用環境變數有兩個主要好處：

  1. 您的機密不會存儲在 Git 儲存庫中，確保未經授權的人即使獲得您的源代碼也無法訪問您的敏感數據。
  2. 您可以為不同的環境使用不同的憑證（例如，生產與開發）。

為了管理環境變數，我們使用 python-dotenv 模組。首先，如果尚未安裝，請安裝它：

pip install python-dotenv
pip freeze > requirements.txt

接下來，在專案根目錄創建 .env 文件，並添加您的開發環境變數。例如：

ENV="development"
DATABASE_PASSWORD="secretPassword"
THIRD_API_PRIVATE_KEY="secretKey"

最後，將 .env 文件添加到 .gitignore 以保持安全：

echo ".env" >> .gitignore

要在 Python 中訪問這些環境變數，只需使用 os.environ.get()：

import os

print(os.environ.get('ENV'))

.env 文件僅用於開發環境。對於測試或生產，請在 Stackhero 儀表板中的 Python 服務配置中設置環境變數。

為生產部署準備 Python 和 Flask

雖然本指南使用 Flask 的內建開發伺服器，但在生產環境中，使用像 Gunicorn 這樣的生產就緒 WSGI 伺服器是必須的。請按照以下步驟操作：

  1. 安裝 Gunicorn：

    pip install gunicorn
pip freeze > requirements.txt

  2. 使用 app:app 參數啟動您的應用程式（其中第一個 app 是文件名，第二個 app 是 Flask 實例）：

    ENV=production gunicorn app:app \
  --error-logfile - \
  -b 0.0.0.0:8080

  3. 創建一個 Makefile 以簡化開發和生產模式之間的切換：

    .DEFAULT_GOAL := dev

# 默認情況下，Stackhero for Python 執行 "run" 規則。我們將其覆蓋為執行 'prod' 規則。
run: prod

prod:
 	ENV=production gunicorn app:app \
 	  --error-logfile - \
 	  -b 0.0.0.0:8080

dev:
 	python app.py

您可以使用 make dev（或簡單地 make）在開發模式下運行伺服器，並使用 make prod 在生產模式下運行。

將您的 Python 代碼部署到生產環境

部署您的 Python 專案最簡單的方法是使用 Stackhero Python 雲端託管服務。主要功能包括：

  • 使用簡單的 git push 進行部署
  • 可自定義域名，並自動管理 TLS 證書（HTTPS）
  • 在專用的虛擬機上運行，提供最大安全性
  • 支持 HTTP/2、TLS 1.3（HTTPS）、WebSockets、GZIP 和 Brotli 壓縮、ETag 和 TCP/UDP 端口訪問

配置 "Stackhero for Python" 服務

要將代碼部署到 Stackhero，請按照以下步驟操作：

  1. 使用以下命令檢索您的公鑰：

    cat ~/.ssh/id_*.pub

  2. 在 Stackhero 儀表板中，轉到您的 "Stackhero for Python" 服務並點擊 "Configure" 按鈕。

  3. 從第一步中複製公鑰並將其粘貼到 "SSH public keys" 或 "Key" 欄位中。

  4. 點擊頁面底部的 "Validate" 按鈕以驗證配置。

"Stackhero for Python" 公鑰配置"Stackhero for Python" 公鑰配置

沒有 SSH 密鑰？運行以下命令創建它們：

ssh-keygen -t ed25519

最後，配置您的儲存庫以部署到 Stackhero。在您的專案文件夾中，使用 Stackhero 服務中提供的命令添加 Git 遠端（將 <XXXXXX> 替換為您的服務域名）：

git remote add stackhero ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

Git 遠端命令Git 遠端命令

部署到生產環境

一旦一切配置完成，使用以下命令將您的代碼部署到生產環境：

git push stackhero main

確保在將代碼推送到生產環境之前添加並提交您的更改。在 Stackhero Code-Hero 中，您可以使用命令面板快速提交更改（在 Windows/Linux 上按 Ctrl+Shift+P 或在 macOS 上按 Cmd+Shift+P 並輸入 Git: Commit）。

部署後，訪問您的 API URL https://<XXXXXX>.stackhero-network.com/api/tasks（將 <XXXXXX> 替換為您的服務域名）以查看您的 Flask API 運行情況。

結論

通過遵循本指南，您現在了解如何使用 Flask 建立 REST API。憑藉這些知識，您可以自信地開發和擴展您的 RESTful 應用程式，並將其與各種前端和後端服務集成。

Python 的其他文章

  1. 開發平台
    為您準備一個愉快且高效的開發平台
  2. 學習 Python
    全面的 Python 指南
  3. 部署到生產環境
    如何在數分鐘內將您的 Python 程式碼部署到生產環境
  4. 使用 GitHub Actions 進行部署
    如何利用 GitHub Actions 部署您的 Python 程式碼
  5. 進階用法
    深入了解 Python 部署
  6. 疑難排解
    您的 Python 服務遇到問題？解決方案可能就在這裡！
  7. 簡介
    在 Stackhero 上部署您的 Python 代碼的步驟