FastAPI 框架入门与原理：从安装、第一个 API 到自动文档的完整实战-开发者社区

FastAPI 框架入门与原理：从安装、第一个 API 到自动文档的完整实战

【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi

FastAPI 是基于标准 Python 类型提示构建的现代高性能 Web API 框架，它借助 Starlette 处理 Web 层、Pydantic 处理数据层，让开发者“声明一次类型，即得校验、转换与自动交互文档”的能力。本文以官方文档主页 docs/en/docs/index.md 为主线，覆盖安装配置、最小可运行示例、开发服务器与部署流程，并结合当前仓库源码（版本 0.141.1）说明其依赖结构、CLI 实现与自动文档机制，读完你可以独立搭建、运行并扩展一个生产可用的 Python API 服务。

FastAPI 是什么：核心特性与定位

FastAPI 是一个现代化的、高速（高性能）的 Web 框架，用于使用 Python 构建 API，其核心基础是标准的 Python 类型提示。官方文档中列出的关键特性如下：

快（Fast）：极高的性能，可与 NodeJS 和 Go 相比（得益于 Starlette 和 Pydantic）。在独立的 TechEmpower 基准测试中，FastAPI 属于最快的 Python 框架之一（详见下文“性能”一节）；
编码快（Fast to code）：据官方说明，可让功能开发速度提升约 200% 到 300%（该数据来自官方内部开发团队构建生产应用时的估算）；
少出 Bug（Fewer bugs）：可减少约 40% 由人为（开发者）导致的错误（同样是官方内部估算）；
直觉（Intuitive）：优秀的编辑器支持，处处有自动补全（Completion），减少调试时间；
简单（Easy）：设计为易于使用和上手，减少阅读文档的时间；
精简（Short）：最小化代码重复，每个参数声明同时提供多项功能，从而减少 Bug；
健壮（Robust）：直接获得生产级代码，并自带自动交互文档；
基于标准（Standards-based）：基于（并完全兼容）API 开放标准 OpenAPI（原 Swagger）和 JSON Schema。

从源码结构看，FastAPI 的“标准兼容”并非口号：fastapi包的主入口类直接继承自 Starlette 的Starlette，见 fastapi/applications.py 中的class FastAPI(Starlette)，同时通过 fastapi/init.py 一次性导出FastAPI、APIRouter、Depends、Query、Path、Body、File、Form、Header、Cookie、Security、HTTPException、BackgroundTasks、UploadFile、WebSocket等全部公开 API，构成一个高度统一的类型提示驱动 API。

技术基座：站在巨人的肩膀上

官方文档明确说明，FastAPI 建立在两个“巨人”之上：

Starlette 负责 Web 部分（ASGI 应用框架）；
Pydantic 负责数据部分（数据校验与序列化）。

当前仓库的 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；
Python 版本要求：requires-python = ">=3.10"，分类器声明支持 3.10 至 3.14；
许可协议：MIT（见 LICENSE）。

这三层工具的关系在 docs/en/docs/benchmarks.md 中有一个清晰的层次描述：Uvicorn 是 ASGI 服务器，Starlette 是 Web 微框架（使用 Uvicorn 运行），FastAPI 则是构建在 Starlette 之上的 API 微框架，额外提供数据校验、序列化与自动文档。由于 FastAPI 使用了 Starlette，它不可能比 Starlette 更快，但其“免费”带来的校验、序列化与文档能力，通常正是应用中代码量最大的部分。

安装：fastapi[standard] 可选依赖组

官方推荐先安装uv，然后在项目中添加 FastAPI：

$ uv add "fastapi[standard]"

注意：务必将"fastapi[standard]"放在引号中，以确保在所有终端下都能正确解析。如果你更习惯使用pip，则应在虚拟环境中安装fastapi[standard]，替代步骤见 docs/en/docs/tutorial/ 下的安装指南。

standard 依赖组里到底装了什么

uv add "fastapi[standard]"会安装standard这组可选依赖。对照 pyproject.toml 中[project.optional-dependencies]的standard段，其实际包含：

Pydantic 侧
- email-validator >=2.0.0：用于邮箱字段校验；
- pydantic-settings >=2.0.0：用于配置管理（Settings）；
- pydantic-extra-types >=2.0.0：扩展的 Pydantic 数据类型；
Starlette 侧
- httpx >=0.23.0,<1.0.0：使用TestClient测试客户端所必需；
- jinja2 >=3.1.5：使用默认模板配置所必需；
- python-multipart >=0.0.18：支持request.form()表单解析所必需；
FastAPI 侧
- uvicorn[standard] >=0.12.0：加载并服务你应用的服务器，其中uvicorn[standard]附带uvloop等高性能运行时所需依赖；
- fastapi-cli[standard] >=0.0.32：提供fastapi命令行，其中包含fastapi-cloud-cli，可将应用部署到 FastAPI Cloud；
- fastar >=0.9.0：仓库当前版本额外引入的依赖（官方文档未逐一列举，以 pyproject.toml 为准）。

裁剪安装：两种变体

不带 standard 依赖：只需uv add fastapi，此时只有 Starlette 与 Pydantic 等基础依赖；
不带 fastapi-cloud-cli：使用uv add "fastapi[standard-no-fastapi-cloud-cli]"，可安装完整 standard 组但排除云部署 CLI。对应 pyproject.toml 中的standard-no-fastapi-cloud-cli可选依赖组。

其他可选依赖

根据项目需要可额外安装：

pydantic-settings：配置管理（已含于 standard 组）；
pydantic-extra-types：扩展数据类型（已含于 standard 组）；
orjson：使用ORJSONResponse时需要；
ujson：使用UJSONResponse时需要。

第一个 API：main.py

创建文件

创建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，请将def换成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 def，可参考文档中 docs/en/docs/async.md 的 “In a hurry?” 小节。

这个例子已经实现了什么

上面几行代码创建的 API：

在路径/和/items/{item_id}上接收 HTTP 请求；
两条路径都接受GET操作（即 HTTP 方法）；
路径/items/{item_id}有一个必须是int类型的路径参数item_id；
路径/items/{item_id}还有一个可选的str类型查询参数q。

其中“可选/必填”的语义完全由标准 Python 类型声明决定：q: str | None = None中的= None默认值使其变为可选参数；若无None则参数为必填（如同后文PUT请求中的 Body）。这一点在 fastapi/applications.py 的路由与参数处理代码中可以看到统一实现：路径操作函数签名中的类型注解被 FastAPI 解析为校验与文档元数据。

示例代码在仓库中的对应关系

官方文档示例的完整可运行版本位于 docs_src/first_steps/tutorial001_py310.py，并有配套测试 tests/test_tutorial/test_first_steps/test_tutorial001_tutorial002_tutorial003.py 使用TestClient对上述端点的响应进行回归验证——这保证了文档示例与实现持续一致。

运行服务器：fastapi dev

在main.py所在目录执行：

$ 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 监控文件变更）。生产环境则改用fastapi run。更多参数（例如显式指定入口uv run fastapi dev --entrypoint main:app）见 docs/en/docs/fastapi-cli.md。

从源码看，fastapi命令的入口由 pyproject.toml 中的[project.scripts]声明（fastapi = "fastapi.cli:main"），其实现 fastapi/cli.py 会尝试从fastapi_cli包加载真正的 CLI：如果未安装fastapi[standard]（缺少fastapi-cli），运行fastapi命令会直接提示安装"fastapi[standard]"。

验证接口与自动交互文档

查看 JSON 响应

在浏览器打开http://127.0.0.1:8000/items/5?q=somequery，你会看到 JSON 响应：

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

Swagger UI（/docs）

打开http://127.0.0.1:8000/docs，会看到由 Swagger UI 提供的自动交互 API 文档（即前文摘要后第一张截图所示界面）。

ReDoc（/redoc）

打开http://127.0.0.1:8000/redoc，可以看到由 ReDoc 提供的另一种自动文档样式（即摘要后第二张截图所示界面）。

从 fastapi/applications.py 的导入可以看到，这两套文档页分别由get_swagger_ui_html、get_redoc_html及 OAuth2 重定向页函数生成，且 OpenAPI Schema 由get_openapi构建。文档说明中特别指出：自动文档不会给运行中的应用增加开销，因为它是在启动时生成的。

进阶示例：声明 Body 与 Pydantic 模型

现在修改main.py，让 API 接收PUT请求的 Body。借助 Pydantic，用标准 Python 类型声明 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服务器会自动重新加载。此时：

打开http://127.0.0.1:8000/docs，交互文档自动更新，包含新的 Body 定义；
点击 “Try it out” 按钮，即可填写参数并直接对 API 发起请求；
点击 “Execute”，界面会与你的 API 通信、发送参数、取回结果并在屏幕上展示（见前文 “Swagger UI Try it out 交互界面” 截图）；
打开http://127.0.0.1:8000/redoc，替代文档同样会反映新的查询参数与 Body。

回顾：一次类型声明换来的能力

总结一下，你只需一次用标准的现代 Python 类型声明参数、Body 等（不需要学习新语法或特定库的方法），例如int：

item_id: int

或更复杂的Item模型：

item: Item

这一个声明同时带来：

编辑器支持：自动补全、类型检查；
数据校验：数据无效时自动产生清晰的错误，且对深度嵌套的 JSON 对象同样有效；
输入数据转换：将来自网络的数据读取并转换为 Python 数据类型，来源包括 JSON、路径参数、查询参数、Cookie、请求头、表单、文件；
输出数据转换：将 Python 数据类型转换为网络数据（JSON），支持str、int、float、bool、list等基础类型、datetime对象、UUID对象、数据库模型等；
自动交互 API 文档：包含 Swagger UI 与 ReDoc 两套界面。

对应前文示例，FastAPI 具体会：

校验GET和PUT请求路径中存在item_id；
校验item_id是int类型，否则客户端会看到有用的、清晰的错误；
检查GET请求是否存在可选查询参数q（如http://127.0.0.1:8000/items/foo?q=somequery）——因为声明了= None所以可选，否则必填（如同PUT的 Body）；
对PUT /items/{item_id}，以 JSON 读取 Body，并校验：必填的name（str）、必填的price（float）、可选的is_offer（若存在必须是bool）；对深度嵌套 JSON 同样适用；
自动完成 JSON 的双向转换；
用 OpenAPI 文档化一切，可用于交互式文档系统、面向多种语言的自动客户端代码生成系统，并直接提供两套交互文档 Web 界面。

关于编辑器的自动补全体验：把update_item的返回从"item_name": item.name改为"item_price": item.price，即可看到编辑器自动补全模型属性并知晓其类型——这正是“类型提示驱动开发”的日常收益。

更完整的示例与进阶特性（参见 docs/en/docs/tutorial/ 教程）包括：

从请求头、Cookie、表单字段、文件等更多位置声明参数；
设置校验约束，如maximum_length或正则；
强大而易用的**依赖注入（Dependency Injection）**系统；
安全与认证，包括OAuth2 + JWT 令牌和HTTP Basic认证；
借助 Pydantic 声明深度嵌套 JSON 模型的进阶技巧；
与 Strawberry 等库的GraphQL集成；
更多来自 Starlette 的能力：WebSockets、基于 HTTPX 与pytest的轻松测试、CORS、Cookie Sessions等。

部署你的应用（可选）

FastAPI Cloud 一键部署

可以任选一条命令将应用部署到 FastAPI Cloud：

$ 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 的作者与团队构建，将“构建 API 的开发体验”延伸到了“部署到云”的环节，同时也是FastAPI and friends开源项目的主要赞助商与资金来源。

部署到其他云服务商

FastAPI 是开源且基于标准的，你可以把应用部署到任何云服务商——按所选云厂商的指南部署即可。

性能

独立的 TechEmpower 基准测试表明，运行在 Uvicorn 之下的FastAPI应用属于最快的 Python 框架之一，仅次于其内部使用的 Starlette 与 Uvicorn 本身（*）。理解这类基准时应注意工具层次：Uvicorn 是 ASGI 服务器，Starlette 是微框架，FastAPI 在其之上增加了 API 构建所需的数据校验、序列化与文档；不直接使用 FastAPI 时，这些能力仍需在应用代码中自行实现，最终应用往往有相同甚至更多的开销。更详细的基准解读见 docs/en/docs/benchmarks.md。

许可

本项目基于 MIT 许可发布，详见 LICENSE。

（）“提升 200%~300%”“减少 40% 错误”等数据为 FastAPI 官方基于内部开发团队生产实践给出的估算，引用时请注明来源口径；版本相关事实（0.141.1、Python >= 3.10、starlette >= 0.46.0、pydantic >= 2.9.0）以当前仓库 pyproject.toml 与 fastapi/init.py 为准。

【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考