FastAPI¶

FastAPI 框架，高性能，易于学习，快速编码，随时可用于生产

源代码: https://github.com/fastapi/fastapi

📖 文档导读

欢迎来到 FastAPI 中文文档！本文档将帮助您快速掌握这个强大的 Python Web 框架。

👥 适合人群: Python 开发者、API 设计师、后端工程师

⏱️ 阅读时间: 完整阅读约 8-12 小时，快速入门约 30 分钟

🛣️ 推荐路径: 起步指南 → 教程 → 高级指南

FastAPI 是一个现代、快速（高性能）的 Web 框架，基于标准 Python 类型提示，用于构建 Python API。

主要特性：

快速：极高的性能，与 NodeJS 和 Go 相当（得益于 Starlette 和 Pydantic）。现有最快的 Python 框架之一。
快速编码：功能开发速度提高 200% 到 300%。*
更少错误：减少约 40% 的人为（开发者）错误。*
直观：优秀的编辑器支持。到处都有代码补全。调试时间更短。
简单：设计易于使用和学习。阅读文档时间更短。
简洁：最小化代码重复。每个参数声明的多个功能。更少错误。
健壮：获得生产就绪的代码。自动交互式文档。
基于标准：基于（并完全兼容）API 开放标准：OpenAPI（以前称为 Swagger）和 JSON Schema。

* 基于内部开发团队构建生产应用程序的测试估计。

赞助商¶

其他赞助商

意见¶

"[...] 我最近大量使用 FastAPI。[...] 我实际上计划将它用于我在 Microsoft 团队的所有 ML 服务。其中一些正在集成到核心 Windows 产品和一些 Office 产品中。"

Kabir Khan - Microsoft (参考)

"我们采用了 FastAPI 库来生成一个 REST 服务器，可以查询以获得预测结果。[用于 Ludwig]"

Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (参考)

"Netflix 很高兴地宣布开源发布我们的危机管理编排框架：Dispatch！[使用 FastAPI 构建]"

Kevin Glisson, Marc Vilanova, Forest Monsen - Netflix (参考)

"我对 FastAPI 感到非常兴奋。它太有趣了！"

Brian Okken - Python Bytes 播客主持人 (参考)

"老实说，你构建的东西看起来非常坚固和精致。在很多方面，这就是我希望 Hug 成为的样子——看到有人构建出这样的东西真的很鼓舞人心。"

Timothy Crosley - Hug 创作者 (参考)

"如果你想学习一个用于构建 REST API 的现代框架，请查看 FastAPI [...] 它快速、易于使用且易于学习 [...]"

"我们已经将我们的 API 转换为 FastAPI [...] 我想你会喜欢它的 [...]"

Ines Montani - Matthew Honnibal - Explosion AI 创始人 - spaCy 创作者 (参考) - (参考)

"如果有人想构建生产级 Python API，我强烈推荐 FastAPI。它设计精美、易于使用且高度可扩展，已成为我们 API 优先开发策略的关键组件，并推动了许多自动化和服务，如我们的虚拟 TAC 工程师。"

Deon Pillsbury - Cisco (参考)

Typer，CLI 的 FastAPI¶

如果你正在构建一个在终端中使用的 CLI 应用程序而不是 Web API，请查看 Typer。

Typer 是 FastAPI 的小兄弟。它的目标是成为 CLI 的 FastAPI。⌨️ 🚀

要求¶

FastAPI 站在巨人的肩膀上：

Starlette 用于 Web 部分。
Pydantic 用于数据部分。

安装¶

创建并激活虚拟环境，然后安装 FastAPI：

$ pip install "fastapi[standard]"

---> 100%

注意：确保将 "fastapi[standard]" 放在引号中，以确保它在所有终端中都能正常工作。

示例¶

创建它¶

创建一个 main.py 文件：

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"Hello": "World"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: Union[str, None] = None):
    return {"item_id": item_id, "q": q}

或者使用 async def...

如果你的代码使用 async / await，请使用 async def：

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def read_root():
    return {"Hello": "World"}


@app.get("/items/{item_id}")
async def read_item(item_id: int, q: Union[str, None] = None):
    return {"item_id": item_id, "q": q}

注意：

如果你不知道，请查看文档中关于 async 和 await 的 "急于求成？" 部分。

运行它¶

使用以下命令运行服务器：

$ fastapi dev main.py

 ╭────────── FastAPI CLI - Development mode ───────────╮
 │                                                     │
 │  Serving at: http://127.0.0.1:8000                  │
 │                                                     │
 │  API docs: http://127.0.0.1:8000/docs               │
 │                                                     │
 │  Running in development mode, for production use:   │
 │                                                     │
 │  fastapi run                                        │
 │                                                     │
 ╰─────────────────────────────────────────────────────╯

INFO:     Will watch for changes in these directories: ['/home/user/code/awesomeapp']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [2248755] using WatchFiles
INFO:     Started server process [2248757]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

关于命令 fastapi dev main.py...

命令 fastapi dev 读取你的 main.py 文件，检测其中的 FastAPI 应用程序，并使用 Uvicorn 启动服务器。

默认情况下，fastapi dev 将为本地开发启用自动重载。

你可以在 FastAPI CLI 文档中了解更多。

检查它¶

在浏览器中打开 http://127.0.0.1:8000/items/5?q=somequery。

你将看到 JSON 响应：

{"item_id": 5, "q": "somequery"}

你已经创建了一个 API，它：

在_路径_ / 和 /items/{item_id} 上接收 HTTP 请求。
两个_路径_都接受 GET 操作（也称为 HTTP 方法）。
路径 /items/{item_id} 有一个_路径参数_ item_id，应该是一个 int。
路径 /items/{item_id} 有一个可选的 str 查询参数 q。

交互式 API 文档¶

现在转到 http://127.0.0.1:8000/docs。

你将看到自动交互式 API 文档（由 Swagger UI 提供）：

Swagger UI

替代 API 文档¶

现在，转到 http://127.0.0.1:8000/redoc。

你将看到替代的自动文档（由 ReDoc 提供）：

ReDoc

示例升级¶

现在修改 main.py 文件以从 PUT 请求接收主体。

多亏了 Pydantic，使用标准 Python 类型声明主体。

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: float
    is_offer: Union[bool, None] = None


@app.get("/")
def read_root():
    return {"Hello": "World"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: Union[str, None] = None):
    return {"item_id": item_id, "q": q}


@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
    return {"item_name": item.name, "item_id": item_id}

fastapi dev 服务器应该自动重载。

交互式 API 文档升级¶

现在转到 http://127.0.0.1:8000/docs。

交互式 API 文档将自动更新，包括新的主体：

Swagger UI

点击"Try it out"按钮，它允许你填写参数并直接与 API 交互：

Swagger UI interaction

然后点击"Execute"按钮，用户界面将与你的 API 通信，发送参数，获取结果并在屏幕上显示：

Swagger UI interaction

替代 API 文档升级¶

现在，转到 http://127.0.0.1:8000/redoc。

替代文档也将反映新的查询参数和主体：

ReDoc

总结¶

总的来说，你只需要将参数、主体等的类型声明一次作为函数参数。

你使用标准的现代 Python 类型来做到这一点。

你不必学习新的语法、特定库的方法或类等。

只需要标准的 Python。

例如，对于 int：

item_id: int

或者对于更复杂的 Item 模型：

item: Item

...通过这一个声明，你就能获得：

编辑器支持，包括：
- 代码补全。
- 类型检查。
数据验证：
- 当数据无效时自动和清晰的错误。
- 甚至对深度嵌套的 JSON 对象进行验证。
输入数据的转换：从网络到 Python 数据和类型。读取来自：
- JSON。
- 路径参数。
- 查询参数。
- Cookie。
- 头部。
- 表单。
- 文件。
输出数据的转换：从 Python 数据和类型转换为网络数据（如 JSON）：
- 转换 Python 类型（str、int、float、bool、list 等）。
- datetime 对象。
- UUID 对象。
- 数据库模型。
- ...以及更多。
自动交互式 API 文档，包括 2 个替代用户界面：
- Swagger UI。
- ReDoc。

回到之前的代码示例，FastAPI 将：

验证 GET 和 PUT 请求的路径中是否有 item_id。
验证 GET 和 PUT 请求的 item_id 是否为 int 类型。
- 如果不是，客户端将看到有用、清晰的错误。
检查 GET 请求是否有名为 q 的可选查询参数（如 http://127.0.0.1:8000/items/foo?q=somequery）。
- 由于 q 参数用 = None 声明，它是可选的。
- 没有 None，它将是必需的（就像使用 PUT 的主体情况一样）。
对于到 /items/{item_id} 的 PUT 请求，将主体读取为 JSON：
- 检查它是否有一个名为 name 的必需属性，该属性应该是 str。
- 检查它是否有一个名为 price 的必需属性，该属性必须是 float。
- 检查它是否有一个名为 is_offer 的可选属性，如果存在，该属性应该是 bool。
- 所有这些对于深度嵌套的 JSON 对象也同样有效。
自动从 JSON 转换和转换为 JSON。
使用 OpenAPI 记录所有内容，可用于：
- 交互式文档系统。
- 多种语言的自动客户端代码生成系统。
直接提供 2 个交互式文档 Web 界面。

我们只是触及了表面，但你已经了解了它是如何工作的。

尝试更改这一行：

    return {"item_name": item.name, "item_id": item_id}

...从：

        ... "item_name": item.name ...

...到：

        ... "item_price": item.price ...

...看看你的编辑器如何自动补全属性并知道它们的类型：

editor support

要获得包含更多功能的更完整示例，请参阅教程 - 用户指南。

剧透警告：教程 - 用户指南包括：

从其他不同地方声明参数，如：头部、cookie、表单字段和文件。
如何设置验证约束，如 maximum_length 或 regex。
一个非常强大且易于使用的依赖注入系统。
安全和身份验证，包括对带有 JWT 令牌和 HTTP Basic 身份验证的 OAuth2 的支持。
声明深度嵌套 JSON 模型的更高级（但同样简单）技术（得益于 Pydantic）。
与 Strawberry 和其他库的 GraphQL 集成。
许多额外功能（得益于 Starlette），如：
- WebSocket
- 基于 HTTPX 和 pytest 的极其简单的测试
- CORS
- Cookie 会话
- ...以及更多。

性能¶

独立的 TechEmpower 基准测试显示，在 Uvicorn 下运行的 FastAPI 应用程序是可用的最快 Python 框架之一，仅次于 Starlette 和 Uvicorn 本身（FastAPI 内部使用）。(*)

要了解更多信息，请参阅基准测试部分。

依赖项¶

FastAPI 依赖于 Pydantic 和 Starlette。

`standard` 依赖项¶

当你使用 pip install "fastapi[standard]" 安装 FastAPI 时，它附带了 standard 可选依赖项组：

Pydantic 使用的：

email-validator - 用于电子邮件验证。

Starlette 使用的：

httpx - 如果你想使用 TestClient，则需要。
jinja2 - 如果你想使用默认模板配置，则需要。
python-multipart - 如果你想支持表单"解析"，与 request.form() 一起使用，则需要。

FastAPI 使用的：

uvicorn - 用于加载和服务你的应用程序的服务器。这包括 uvicorn[standard]，其中包括高性能服务所需的一些依赖项（例如 uvloop）。
fastapi-cli[standard] - 提供 fastapi 命令。
- 这包括 fastapi-cloud-cli，它允许你将 FastAPI 应用程序部署到 FastAPI Cloud。

不使用 `standard` 依赖项¶

如果你不想包含 standard 可选依赖项，可以使用 pip install fastapi 而不是 pip install "fastapi[standard]" 来安装。

不使用 `fastapi-cloud-cli`¶

如果你想使用标准依赖项安装 FastAPI 但不使用 fastapi-cloud-cli，可以使用 pip install "fastapi[standard-no-fastapi-cloud-cli]" 来安装。

额外的可选依赖项¶

你可能想要安装一些额外的依赖项。

额外的可选 Pydantic 依赖项：

pydantic-settings - 用于设置管理。
pydantic-extra-types - 用于与 Pydantic 一起使用的额外类型。

额外的可选 FastAPI 依赖项：

orjson - 如果你想使用 ORJSONResponse，则需要。
ujson - 如果你想使用 UJSONResponse，则需要。

许可证¶

该项目根据 MIT 许可证的条款进行许可。