FastAPI 官方入门详解：从安装、示例 API 到自动文档与性能基准

FastAPI 是官方文档首页（docs/de/docs/index.md）所定义的"现代、高速（高性能）Python Web 框架"，其核心思路是用标准 Python 类型注解声明参数、请求体和返回值，从而同时获得数据校验、类型转换、编辑器智能提示和自动交互文档。本篇基于仓库中的官方首页文档展开，并结合 pyproject.toml、fastapi/applications.py、fastapi/cli.py 等源码逐条印证：读完你可以独立完成"安装 → 创建示例 API → 启动开发服务器 → 验证 JSON 响应 → 使用 Swagger UI/ReDoc 交互调试 → 升级带 Pydantic 请求体的版本 → 部署"的完整闭环。

FastAPI 是什么：核心特性一览

官方首页对 FastAPI 的定位是：基于标准 Python 类型提示（type hints）构建 API 的现代、快速 Web 框架。其关键特性包括：

• 快速（Schnell）：非常高的运行性能，与 NodeJS、Go 处于同一梯队（得益于 Starlette 和 Pydantic），是可用 Python 框架中最快的之一（见"性能"一节）。
• 开发速度快：官方内部开发团队估算，开发功能的速度可提升约 200%～300%，人为（开发者）导致的错误可减少约 40%。注意原文标注：这是基于内部团队生产应用测试的估算值，而非独立基准。
• 直观：出色的编辑器支持，处处可用代码补全（Auto-Complete / IntelliSense），减少调试时间。
• 简单：设计为易学易用，减少查阅文档的时间。
• 简短：最小化代码重复，单个参数声明即可带出多项能力，减少 Bug。
• 健壮：直接产出生产级代码，附带自动交互式文档。
• 基于标准：完全兼容 OpenAPI（原 Swagger）与 JSON Schema 两大开放标准。

从源码结构看，框架本体入口 fastapi/init.py 中当前版本为 0.141.1，并对外导出 FastAPI、APIRouter、HTTPException、Depends、Query、Body、Form、File、UploadFile、BackgroundTasks、WebSocket 等最常用的 API 面——也就是说，首页文档中承诺的"路径参数、查询参数、请求体、文件上传、依赖注入、后台任务、WebSocket"这些能力，都是包级公开接口，而非隐藏机制。

技术底座：Starlette 与 Pydantic

首页"要求"一节明确写道：FastAPI 站在巨人的肩膀上——

• Starlette：承担所有 Web 层能力（ASGI 应用、路由、中间件、WebSocket 等）；
• Pydantic：承担所有数据层能力（类型校验、序列化、嵌套模型）。

这一点在 fastapi/applications.py 中可以直接验证：class FastAPI(Starlette) 直接继承 Starlette 的应用类，并在构造函数中内置 OpenAPI 文档生成（get_swagger_ui_html、get_redoc_html、get_openapi）与请求校验异常处理器。pyproject.toml 中声明的硬性依赖与版本下限为：

依赖	版本约束（pyproject.toml）	作用
starlette	>=0.46.0	Web 层（ASGI）框架
pydantic	>=2.9.0	数据校验与序列化（v2）
typing-extensions	>=4.8.0	类型系统扩展
typing-inspection	>=0.4.2	运行时类型注解检查
annotated-doc	>=0.0.2	为参数提供文档说明（Doc）

同时 pyproject.toml 声明 requires-python = ">=3.10"，分类器中标注支持 Python 3.10～3.14，并声明 Framework :: AsyncIO——即示例中 async def 路径的一等支持。

安装：fastapi[standard] 与依赖组

官方首页推荐的安装方式是先安装 uv，再执行：

$ uv add "fastapi[standard]"

官方特别提醒："fastapi[standard]" 务必加引号，否则在 Windows 等终端中会被当作重定向。若偏好 pip，则在虚拟环境中安装 fastapi[standard]，替代步骤见文档站教程中的"安装 FastAPI"章节（仓库中对应 docs_src/first_steps/tutorial001_py310.py 所服务的 tutorial 安装小节）。

standard 可选依赖组到底装了什么

首页列出了 standard 组的内容，pyproject.toml 的 [project.optional-dependencies].standard 给出了精确清单，可以按"谁在用"归类：

Pydantic 使用

• email-validator（>=2.0.0）：EmailStr 等邮箱字段校验。

Starlette 使用

• httpx（>=0.23.0,<1.0.0）：使用 TestClient 做应用测试时必需；
• jinja2（>=3.1.5）：使用默认模板配置（fastapi.templating.Jinja2Templates）时必需；
• python-multipart（>=0.0.18）：用 request.form() 解析表单时必需。

FastAPI 使用

• uvicorn[standard]（>=0.12.0）：加载并运行你的应用的 ASGI 服务器，[standard] 额外引入 uvloop 等高并发部署所需组件；
• fastapi-cli[standard]（>=0.0.32）：提供 fastapi 命令行；其中包含 fastapi-cloud-cli，用于把应用部署到 FastAPI Cloud。

Pydantic 生态的额外可选件（同样在 standard 组内）

• pydantic-settings（>=2.0.0）：配置管理；
• pydantic-extra-types（>=2.0.0）：Pydantic 的附加数据类型。

此外 standard 组还包含 fastar（>=0.9.0），用于文件上传相关的性能优化（源码清单中可见，文档首页未单独展开）。

三种安装形态

首页还给出两个变体，与 pyproject.toml 中的可选依赖组一一对应：

1. 不含 standard：uv add fastapi——只安装核心硬依赖（上表五项），适合自管服务器/测试客户端的场景；
2. 不含 fastapi-cloud-cli：uv add "fastapi[standard-no-fastapi-cloud-cli]"——保留其余标准依赖，但剔除云部署 CLI，对应 standard-no-fastapi-cloud-cli 依赖组（fastapi-cli[standard-no-fastapi-cloud-cli]）；
3. 完整版 all：额外引入 itsdangerous（Starlette SessionMiddleware 用）与 pyyaml（Starlette 的 schema 生成用），适合需要 Starlette 完整能力的场景。

关于 CLI 的可用性有一个源码级细节：fastapi/cli.py 会尝试从 fastapi_cli.cli 导入真正的命令行入口；若未安装 fastapi[standard]，则打印提示并抛出 RuntimeError，要求执行 pip install "fastapi[standard]"。这解释了为什么 fastapi dev/fastapi deploy 等命令必须搭配 standard 组使用。

示例 API：最小可运行程序

创建 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}

这个文件对应的可运行源码就在仓库中：docs_src/first_steps/tutorial001_py310.py（该版本使用 async def 与 {"message": "Hello World"} 响应）。

异步写法：如果你的代码使用 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/applications.py 的依赖注入体系可以推断：同步函数会被放到线程池中执行，异步函数则在事件循环中执行，两种写法都能正确工作，关键取决于你的 I/O 库是否支持 await。

启动开发服务器

$ uv run 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 的行为在首页有明确说明：它自动读取当前目录的 main.py，识别其中的 FastAPI 应用实例，然后用 Uvicorn 启动服务器；默认开启 WatchFiles 文件监听自动重载（对应上面日志中的 reloader 进程），方便本地开发。生产环境则使用 fastapi run。

验证请求

打开浏览器访问 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} 含可选的字符串查询参数 q。

仓库的测试套件对这类示例应用有直接覆盖：tests/test_tutorial/test_first_steps/test_tutorial001_tutorial002_tutorial003.py 用 TestClient 断言 GET / 返回 200 与 {"message": "Hello World"}、GET /nonexistent 返回 404 与 {"detail": "Not Found"}——后者也顺带印证了"路径参数缺失/类型不符时客户端能看到清晰错误"这一特性在异常处理器中的实现路径。

自动交互文档：Swagger UI 与 ReDoc

启动后无需任何额外配置，访问两个地址即可：

1. http://127.0.0.1:8000/docs——Swagger UI 提供的自动交互文档：

2. http://127.0.0.1:8000/redoc——ReDoc 提供的替代版自动文档：

从源码看，这两套文档页面由 fastapi/applications.py 引入的 get_swagger_ui_html、get_redoc_html 与 OAuth2 重定向页 get_swagger_ui_oauth2_redirect_html 生成，底层数据则是 get_openapi 产出的 OpenAPI Schema（当前测试快照显示生成的是 OpenAPI 3.1.0，见上文测试文件）。测试文件中的 test_openapi_schema 断言 /openapi.json 返回 3.1.0 规范、含 paths./get 与 operationId: root__get——这正是两份文档 UI 的数据源。

示例升级：引入 Pydantic 请求体

在 main.py 中加入 PUT 请求体处理，用 Pydantic 声明 Body：

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 会自动重载该改动。回到 /docs：

• 交互文档自动出现新的 PUT 接口与 Body 结构：

• 点击 Try it out，即可在页面内填写参数并直接调用 API：

• 点击 Execute 后，UI 与后端通信、发送参数、接收结果并展示在页面上。

/redoc 替代文档同样会反映新的查询参数与 Body。

一次类型声明带来的能力（官方总结）

首页"Zusammenfassung（小结）"一节是全文的骨架性总结：你只需用标准 Python 类型把参数/请求体声明一次，无需学习框架私有语法、方法或类。一次声明即可得到：

• 编辑器支持：补全、类型检查；
• 数据校验：数据非法时自动且明确的错误，深层嵌套 JSON 同样适用；
• 输入转换：从网络数据转为 Python 类型，来源覆盖 JSON、路径参数、查询参数、Cookie、请求头、表单、文件；
• 输出转换：Python 对象转 JSON 返回，支持 str/int/float/bool/list、datetime、UUID、数据库模型等；
• 自动交互文档：内置 Swagger UI 与 ReDoc 两套界面。

针对上面的代码，FastAPI 具体会做：

• 校验 GET/PUT 路径中都存在 item_id；
• 校验 item_id 是 int，否则客户端收到清晰错误；
• 检查 GET 是否有可选查询参数 q（声明为 = None 即为可选；去掉 None 则变为必填，如 PUT 的 Body）；
• 对 PUT /items/{item_id} 读取 JSON Body：必填 name: str、必填 price: float、可选 is_offer: bool（存在时必须是布尔），且深层嵌套对象同样生效；
• 自动完成 JSON 双向转换；
• 用 OpenAPI 完整记录这一切，可供交互式文档与多语言客户端代码自动生成工具消费；
• 直接提供两套交互文档 Web 界面。

最后，首页给了一个体验"类型提示价值"的小实验：把 return {"item_name": item.name, ...} 中的 item.name 改成 item.price，编辑器会自动补全 Item 的属性并知道其类型——这正是"标准 Python + Pydantic"带来 IDE 集成的直观体现。仓库中的截图 docs/en/docs/img/vscode-completion.png 对应的就是该补全效果。完整功能教程见文档站的 Tutorial（仓库中 docs_src/ 下 90 余个教程示例目录与 tests/test_tutorial/ 下的 325 个测试文件，一一对应），涵盖 Header/Cookie/表单/文件参数、maximum_length/regex 等校验约束、依赖注入、OAuth2/JWT/HTTP Basic 安全、嵌套 JSON 模型、GraphQL 集成，以及 Starlette 带来的 WebSockets、基于 httpx 与 pytest 的简单测试、CORS、Cookie 会话等。

部署：fastapi deploy 与任意云

首页将部署标记为可选步骤：

$ uv run fastapi deploy

输出示例：

Deploying to FastAPI Cloud...

✅ Deployment successful!

🐔 Ready the chicken! Your app is ready at https://myapp.fastapicloud.dev

CLI 会自动识别 FastAPI 应用并部署到 FastAPI Cloud；未登录时会打开浏览器完成认证。FastAPI Cloud 由 FastAPI 作者与团队开发，面向"创建、部署、访问 API"的最小化流程，并是 FastAPI 系列开源项目的主要资助方。文档同时强调：FastAPI 是开源且基于标准的，任何云厂商都可以部署——遵循对应云厂商的部署指南即可（生产环境建议配合 fastapi run 与 uvicorn[standard] 的高性能组件）。

性能：TechEmpower 基准的位置

首页"Performanz"一节的结论：独立 TechEmpower 基准显示，运行在 Uvicorn 下的 FastAPI 应用是最快的可用 Python 框架之一，仅排在 Starlette 与 Uvicorn 本身之后（二者即 FastAPI 内部使用的组件）。该结论附带前提：基于 TechEmpower 的 query 测试项（独立基准，随时间可能变化），且性能优势很大程度来自 Uvicorn + uvicorn[standard]（含 uvloop 等）的运行栈选择。更完整的基准讨论见文档站 Benchmarks 章节。

依赖关系总览与许可证

综合首页与 pyproject.toml：

• 核心依赖：starlette>=0.46.0、pydantic>=2.9.0、typing-extensions>=4.8.0、typing-inspection>=0.4.2、annotated-doc>=0.0.2；
• standard 组：fastapi-cli[standard]、fastar、httpx、jinja2、python-multipart、email-validator、uvicorn[standard]、pydantic-settings、pydantic-extra-types；
• 变体：standard-no-fastapi-cloud-cli（去云 CLI）、all（再加 itsdangerous、pyyaml）；
• 额外可选：orjson（使用 ORJSONResponse 时需要）、ujson（使用 UJSONResponse 时需要）——首页单列了这一节，fastapi/responses.py 中确有对应的响应类实现。

项目基于 MIT 许可证 发布（见 LICENSE 与 pyproject.toml 的 license = "MIT" 声明）。

小结

这篇官方首页文档勾勒出的 FastAPI 工作流可以浓缩为一条主线：用 uv add "fastapi[standard]" 安装 → 用标准类型注解写 main.py → fastapi dev 热重载启动 → 浏览器验证 JSON 响应 → /docs 与 /redoc 自动文档交互调试 → 用 Pydantic 模型扩展请求体 → 生产用 fastapi run/fastapi deploy 交付。仓库中 fastapi/ 包源码（applications.py 继承 Starlette、cli.py 的 CLI 回退逻辑）、docs_src/ 教程源码与 tests/ 测试用例，为文档中的每个能力点都提供了可核查的实现与验证依据。