tiangolo.fastapi

python asyncio api async fastapi framework json json-schema openapi openapi3 pydantic python-types python3 redoc rest starlette swagger swagger-ui uvicorn web

22 KiB

Raw Blame History

FastAPI 框架，高性能、易学习、快速编码、生产就绪

文档: https://fastapi.tiangolo.com

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

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

核心特性：

快速：非常高的性能，可与 NodeJS 和 Go 媲美（得益于 Starlette 和 Pydantic）。Python 最快的框架之一。
编码高效：开发特性的速度提升约 200% 到 300%。*
更少 Bug：减少约 40% 的人为（开发者）错误。*
直观：出色的编辑器支持。随处可见的代码补全。更少的调试时间。
简单：设计为易于使用和学习。花更少时间阅读文档。
精简：最小化代码重复。每个参数声明即包含多个功能。更少的 Bug。
健壮：生成生产就绪的代码。带有自动交互式文档。
基于标准：基于（并完全兼容）API 的开放标准：OpenAPI（以前称为 Swagger）和 JSON Schema。

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

赞助商

Keystone 赞助商

Gold 赞助商

Silver 赞助商

其他赞助商

业界评价

"[...] 我最近大量使用 FastAPI。[...] 我实际上打算把它用在我们 Microsoft 所有团队的 机器学习服务 上。其中一些正在集成到 Windows 核心产品和一些 Office 产品中。"

Kabir Khan - Microsoft (ref)

"我们采用 FastAPI 库来启动一个 REST 服务器，用于查询 预测结果。[为 Ludwig]"

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

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

Kevin Glisson, Marc Vilanova, Forest Monsen - Netflix (ref)

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

Deon Pillsbury - Cisco (ref)

FastAPI Conf

FastAPI Conf '26 将于 2026 年 10 月 28 日 在荷兰阿姆斯特丹举行。关于 FastAPI 的一切，从源头出发。🎤

FastAPI 微纪录片

2025 年底发布的 FastAPI 微纪录片，可在线观看：

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 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: str | None = None):
    return {"item_id": item_id, "q": q}

或使用 async def...

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

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: str | None = None):
    return {"item_id": item_id, "q": q}

注意：

如果你不确定，请查看文档中关于 async 和 await 的快速入门章节。

运行

使用以下命令启动服务器：

$ fastapi dev

 ╭────────── 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 命令...

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 提供）：

备选 API 文档

现在访问 http://127.0.0.1:8000/redoc。

你将看到备选的自动生成文档（由 ReDoc 提供）：

进阶示例

现在修改 main.py 文件，接收来自 PUT 请求的请求体。

使用标准 Python 类型声明请求体，感谢 Pydantic。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: float
    is_offer: bool | None = None


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


@app.get("/items/{item_id}")
def read_item(item_id: int, q: 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 文档将自动更新，包含新的请求体：

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

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

备选 API 文档升级

现在访问 http://127.0.0.1:8000/redoc。

备选文档也会反映新的查询参数和请求体：

总结

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

你使用的是标准的现代 Python 类型。

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

就是标准的 Python。

例如，对于 int：

item_id: int

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

item: Item

...仅通过这个声明，你就获得了：

编辑器支持，包括：
- 代码补全。
- 类型检查。
数据验证：
- 数据无效时自动给出清晰的错误提示。
- 即使对深层嵌套的 JSON 对象也能进行验证。
输入数据的转换：从网络数据到 Python 数据类型。读取来源包括：
- JSON。
- 路径参数。
- 查询参数。
- Cookies。
- 请求头。
- 表单。
- 文件。
输出数据的转换：从 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 请求中的请求体一样）。
对于 PUT 请求到 /items/{item_id}，将请求体读取为 JSON：
- 检查它是否有必需的属性 name，应为 str 类型。
- 检查它是否有必需的属性 price，应为 float 类型。
- 检查它是否有可选属性 is_offer，如果存在则应为 bool 类型。
- 所有这些同样适用于深层嵌套的 JSON 对象。
自动进行 JSON 的序列化和反序列化。
使用 OpenAPI 记录一切，可用于：
- 交互式文档系统。
- 多种语言的自动客户端代码生成系统。
直接提供 2 个交互式文档 Web 界面。

我们只是浅尝辄止，但你已经了解了它的工作方式。

尝试修改这行：

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

...从：

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

...改为：

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

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

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

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

从其他不同位置声明参数，如：请求头、Cookies、表单字段和文件。
如何设置验证约束，如 maximum_length 或 regex。
一个非常强大且易用的 依赖注入 系统。
安全与认证，包括 OAuth2 配合 JWT tokens 和 HTTP Basic 认证。
更高级（但同样简单）的声明深层嵌套 JSON 模型的技术（感谢 Pydantic）。
与 Strawberry 和其他库的 GraphQL 集成。
许多额外特性（感谢 Starlette），如：
- WebSockets
- 基于 HTTPX 和 pytest 的极其简单的测试
- CORS
- Cookie Sessions
- ...更多。

部署你的应用（可选）

你可以选择将 FastAPI 应用部署到 FastAPI Cloud，如果还没有的话赶紧加入等待列表。🚀

如果你已经有一个 FastAPI Cloud 账号（我们从等待列表中邀请你了 😉），你可以用一条命令部署你的应用。

$ fastapi deploy

Deploying to FastAPI Cloud...

✅ Deployment successful!

🐔 准备好鸡！你的应用已就绪：https://myapp.fastapicloud.dev

就这些！现在你可以通过该 URL 访问你的应用了。✨

关于 FastAPI Cloud

FastAPI Cloud 由 FastAPI 的原作者和团队打造。

它简化了以最小工作量构建、部署和访问 API 的过程。

它将 FastAPI 构建应用的开发者体验同样带到了将它们部署到云端的环节。🎉

FastAPI Cloud 是 FastAPI 及周边 开源项目的主要赞助商和资金来源。✨

部署到其他云服务商

FastAPI 是开源的，基于标准。你可以将 FastAPI 应用部署到你选择的任何云服务商。

按照你所用云服务商的指南来部署 FastAPI 应用。🤓

性能

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

了解更多，请参阅 Benchmarks 章节。

依赖

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 许可证条款授权。

22 KiB Raw Blame History

赞助商