Python: 创建 REST API

如何使用 Flask 创建 REST API

👋 欢迎来到 Stackhero 文档！

Stackhero 提供现成的 Python 云 解决方案，具有众多优势，包括：

  • 通过简单的 git push 在几秒钟内 部署您的应用程序。
  • 使用您自己的域名，并享受 HTTPS 证书的自动配置以增强安全性。
  • 享受 自动备份、一键更新，以及简单、透明和可预测的定价带来的安心。
  • 通过私有和专用的 VM获得最佳的性能和强大的安全性。

节省时间并简化您的生活：尝试 Stackhero 的 Python 云托管 解决方案只需 5 分钟！

本文档是一个关于在 Python 中创建 REST API 的入门指南。

在这个例子中，我们使用 Flask，一个轻量且易于使用的微框架，可以让您快速创建 Web 应用程序。

前提条件

在开始之前，请确保您的计算机配备以下工具：

  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 是一个轻量级的 Web 框架，可以快速开发 Web 应用程序。它设计简单易用，使开发者能够快速构建和部署 Web 服务。内置的路由、模板和 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 文件仅用于开发环境。对于 staging 或生产，请在 Stackhero 仪表板的 Python 服务配置中设置环境变量。

为生产部署准备 Python 和 Flask

虽然本指南使用 Flask 的内置开发服务器，但对于生产环境，使用生产就绪的 WSGI 服务器（如 Gunicorn）是必不可少的。请按照以下步骤操作：

  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）
  • 在私有和专用的 VM 上运行，以实现最大安全性
  • 支持 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 代码的步骤