Python: 创建 REST API

使用 Python 的 Flask 构建 REST API 的分步指南

👋 欢迎来到 Stackhero 文档！

Stackhero 提供即开即用的 Python cloud 解决方案，旨在简化您的部署流程：

  • 只需简单 git push，即可在几秒钟内将您的应用部署到生产环境。
  • 支持自定义域名，自动配置 HTTPS 证书，安全连接由我们为您管理。
  • 提供自动备份、一键更新和可预测的定价，让您专注于代码开发，无需担心基础设施管理。
  • 依托专属私有基础设施，为您带来强大的性能与安全性。您的环境将被隔离并受到保护。

节省时间，简化工作流程：通过 Stackhero 的 Python cloud hosting，您的代码最快只需 5 分钟即可上线运行。

本指南将向您展示如何使用 Python 和 Flask 创建一个简单的 REST API。Flask 是一个轻量级的微框架，让您能够快速构建 Web 应用和 API。

前置条件

在开始之前，请确保您已安装以下工具：

  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 API，无需额外负担。它内置了路由、模板和 HTTP 请求处理等功能，帮助您从想法到可用 API 只需几分钟。

您可以通过 pip 安装 Flask 及 python-dotenv：

pip install Flask python-dotenv

我们引入 python-dotenv，以便安全、便捷地管理环境变量。后续步骤会用到它。

安装完成后，将依赖冻结到 requirements.txt 文件：

pip freeze > requirements.txt

冻结依赖可以确保所有人使用相同的包版本，这一步虽小，却能为您节省大量后续排查时间。

使用 Flask 实现 REST API

现在，您可以开始编写 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()

app = Flask(__name__)

# 示例任务数据
tasks = [
    {
        'id': 1,
        'title': 'Buy groceries',
        'description': 'Milk, Cheese, Pizza, Fruits',
        'done': False
    },
    {
        'id': 2,
        'title': 'Learn Python',
        'description': 'Learn Python programming basics',
        'done': False
    }
]

@app.route('/api/tasks', methods=['GET'])
def get_tasks():
    return jsonify({'tasks': tasks})

@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 not task:
        return jsonify({'error': 'Task not found'}), 404
    return jsonify({'task': task[0]})

@app.route('/api/tasks', methods=['POST'])
def create_task():
    if not request.json or 'title' not in request.json:
        return jsonify({'error': 'Title is required'}), 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

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 与 API 交互。以下是一些示例命令：

  • 获取所有任务：

    curl -s http://localhost:8080/api/tasks
# Output:
# {
#   "tasks": [
#     ...
#   ]
# }

  • 获取指定任务（ID 2）：

    curl -s http://localhost:8080/api/tasks/2
# Output:
# {
#   "task": {
#     ...
#   }
# }

  • 创建新任务：

    curl -s -X POST -H "Content-Type: application/json" \
-d '{"title": "New task", "description": "Created with cURL"}' \
http://localhost:8080/api/tasks
# Output:
# {
#   "task": {
#     ...
#   }
# }

提示：为了让输出更易读，您可以将结果通过管道传递给 jq。例如，curl -s http://localhost:8080/api/tasks/2 | jq 可以让 JSON 更清晰。

Python REST API 使用 Flask，在 Stackhero Code-Hero 上运行，1 为服务器，2 为使用 cURL 的客户端Python REST API 使用 Flask，在 Stackhero Code-Hero 上运行，1 为服务器，2 为使用 cURL 的客户端

管理环境变量

环境变量有助于保护诸如数据库凭证或 API 密钥等敏感信息。使用环境变量可以避免敏感数据出现在代码库和 Git 历史中，并便于为不同环境配置不同参数。

要管理环境变量，您可以使用 python-dotenv 模块。如果之前未安装，可以现在安装：

pip install python-dotenv
pip freeze > requirements.txt

在项目根目录下创建 .env 文件，并添加开发环境变量：

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

将 .env 添加到 .gitignore，避免其被提交到 Git：

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. 使用 Gunicorn 启动应用：

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

    这里，app:app 指的是您的文件（app.py）和 Flask 应用实例（app）。

  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 代码到生产环境

Stackhero 让云端部署变得简单且安全。您可以通过 Python cloud hosting service 部署您的 Python 项目。主要特性包括：

  • 只需一次 git push 即可部署
  • 自动 TLS（HTTPS）及可自定义域名
  • 专属基础设施保障安全
  • 支持 HTTP/2、TLS 1.3、WebSockets、GZIP & Brotli、ETag，以及 TCP/UDP 端口访问

配置 "Stackhero for Python" 服务

部署步骤如下：

  1. 获取您的 SSH 公钥：

    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 服务提供的命令，将 Git 远程仓库添加到您的项目（将 <XXXXXX> 替换为您的服务域名）：

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

Git remote 命令Git remote 命令

部署到生产环境

准备好部署时，使用以下命令推送代码：

git push stackhero main

请确保在部署前已提交您的更改。在 Stackhero Code-Hero 中，您可以使用命令面板（Ctrl+Shift+P 或 Cmd+Shift+P），输入 Git: Commit 快速提交。

部署完成后，您的 API 可通过 https://<XXXXXX>.stackhero-network.com/api/tasks 访问。将 <XXXXXX> 替换为您的服务域名，即可访问 Flask API。

总结

现在，您已经拥有一个基于 Flask 构建的可用 REST API。以此为基础，您可以轻松扩展应用、连接数据库或集成其他服务。Flask 为您提供了从原型到生产级 API 的灵活成长空间。

Python 的其他文章

  1. 开发平台
    为您的开发平台做好准备，确保顺畅高效的体验
  2. 学习 Python
    全面的 Python 指南
  3. 部署到生产环境
    如何在几分钟内将您的 Python 代码部署到生产环境
  4. 使用 GitHub Actions 部署
    如何使用 GitHub Actions 部署您的 Python 代码
  5. 高级用法
    深入了解您的 Python 部署
  6. 故障排除
    您的 Python 服务遇到问题了吗？解决方案可能就在这里！
  7. 简要说明
    在 Stackhero 上部署 Python 代码的步骤
  8. 使用 CLI 实现自动化
    通过 Stackhero CLI 以编程方式启动 Python、获取其凭证并更改其配置