【Python】FastAPI：快速上手

FastAPI 是一个现代的、快速的、高性能的 Python Web 框架，用于构建 API。它基于 Python 3.6+ 和标准的 ASGI（Asynchronous Server Gateway Interface）协议，主要用于创建高效且可维护的 API 服务。

FastAPI 简介

FastAPI 是一个用于构建 API 的 Web 框架，具有以下特点：

• 高性能：与 Node.js 和 Go 等现代语言的框架性能相当。
• 类型提示：利用 Python 的类型提示功能自动进行数据验证和序列化。
• 自动生成文档：自动生成 OpenAPI 和 JSON Schema 文档，支持 Swagger UI 和 ReDoc 界面。
• 异步编程：支持 async 和 await，适用于高并发请求。

安装 FastAPI 和 Uvicorn

在开始之前，你需要安装 FastAPI 和一个 ASGI 服务器。推荐使用 Uvicorn，它是一个轻量级的 ASGI 服务器，适用于开发和生产环境。

pip install fastapi
pip install uvicorn

创建基本应用程序

创建一个简单的 FastAPI 应用程序，包括以下步骤：

1. 导入 FastAPI：from fastapi import FastAPI。
2. 创建 FastAPI 实例：app = FastAPI()，这是应用程序的核心对象。
3. 定义路由：使用 @app.get("/") 装饰器定义一个处理根路径的异步请求的端点。

from fastapi import FastAPI  # FastAPI 是一个为你的 API 提供了所有功能的 Python 类。

# 创建应用程序实例，app 是应用程序的名称
app = FastAPI()  # 这个实例将是创建你所有 API 的主要交互对象。

# 定义一个根路由，处理根路径的异步请求
@app.get("/")
async def root():
    return {"message": "Hello world"}

• FastAPI 类：提供了创建和管理 API 端点的功能。
• @app.get("/")：装饰器用于定义处理 HTTP GET 请求的路由。

运行服务器

使用 Uvicorn 运行 FastAPI 应用程序：

uvicorn main:app --reload

• main：是 Python 文件的名称（不包括 .py 后缀）。
• app：是 FastAPI 实例的名称。
• --reload：启用代码重载功能，在开发过程中可以实时查看修改效果。

在终端中，你会看到如下输出，表明服务器正在运行：

INFO: Will watch for changes in these directories: [...]
INFO: Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
INFO: Started reloader process [...]
INFO: Started server process [...]
INFO: Waiting for application startup.
INFO: Application startup complete.

直接在代码中运行

你也可以在 Python 文件中直接运行 FastAPI 应用程序。以下是示例代码：

import uvicorn
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello world"}

if __name__ == '__main__':
    # 直接在代码中运行 Uvicorn 服务器
    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

• uvicorn.run()：直接在代码中启动 Uvicorn 服务器。
• host="0.0.0.0"：使应用可以在所有网络接口上访问。
• port=8000：指定监听的端口。
• reload=True：启用自动重载功能，适合开发环境。

访问 API

启动服务器后，打开浏览器并访问 http://127.0.0.1:8000，你将看到：

{"message": "Hello world"}

• http://127.0.0.1:8000：访问根路径的 API 端点，返回 JSON 格式的响应。

接口文档

FastAPI 提供了自动生成的交互式 API 文档，这使得开发和测试 API 变得更加方便和直观。以下是详细介绍 FastAPI 接口文档及其使用方法，包括如何查看和交互式测试 API。

访问交互式 API 文档

当你启动 FastAPI 应用程序后，可以通过以下 URL 访问自动生成的 API 文档：

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

这两个文档界面都可以帮助你快速了解和测试 API，但它们的展示方式和功能略有不同。

Swagger UI 文档

访问文档：

在浏览器中输入 http://127.0.0.1:8000/docs，你将看到 Swagger UI 界面。

使用方法：

• 查看 API 端点: Swagger UI 自动列出所有的 API 端点，包括 GET、POST 等请求方法。你可以清楚地看到每个端点的描述、请求方法、路径以及可能的响应状态码。

• 参数描述: 每个端点旁边会显示它接受的参数，包括路径参数、查询参数和请求体（如果适用）。这些参数的说明帮助你快速理解如何正确地使用每个 API 端点。

• “试一试”功能:

  1. 点击某个 API 端点旁边的 “Try it out” 按钮。
  2. 填写必要的参数和请求体数据。
  3. 点击 “Execute” 按钮。

• 查看响应: 执行请求后，Swagger UI 会显示请求的响应，包括状态码、响应体及时间等信息。这可以帮助你检查 API 的实际行为和响应格式。

ReDoc 文档

访问文档：

在浏览器中输入 http://127.0.0.1:8000/redoc，你将看到 ReDoc 界面。

功能特点：

• 文档结构: ReDoc 提供了一个结构化的文档视图，左侧有目录栏，可以更方便地浏览不同的 API 端点。目录栏使得文档内容层次分明，便于查找。

• 详细参数说明: 每个 API 端点及其参数都有详细说明，适合需要深入了解 API 设计的开发者。它展示了参数的数据类型、是否必需、默认值等信息。

• 响应示例: ReDoc 也会显示各个端点的响应示例，包括成功和错误的响应格式。这帮助开发者预期 API 调用的结果。

自动更新

当你在 FastAPI 应用中添加或修改 API 端点，例如新增参数或改变请求体，Swagger UI 和 ReDoc 文档会自动更新。这意味着你不需要重新生成文档或手动修改文档内容，从而提高了开发效率和文档的一致性。