Python: 创建 REST API

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

👋 欢迎查阅 Stackhero 文档！

Stackhero 提供即开即用的 Python 云服务 方案，助您高效简化部署流程：

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

节省时间，简化工作流程：通过 Stackhero 的 Python 云主机，您的代码最快只需 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、获取其凭据并更改其配置