FastAPI 官方教程与用户指南：安装、运行与循序渐进学习路线全解析

2026-09-06 18:32:48作者：齐冠琰

导读：本文围绕 FastAPI 官方仓库中的《Tutorial - User Guide》（教程-用户指南，位于 docs/en/docs/tutorial/index.md）展开，它既是零基础到能独立编写 API 的分步教学主线，也是日后可随时回查速查的参考手册。读完本文你将掌握：用 uv 快速初始化项目并安装 FastAPI、三种不同力度的安装选项如何取舍、如何把教程里的示例代码复制成 main.py 并用 uv run fastapi dev 一键启动带热重载的开发服务器，以及这套教程的全章节知识地图和后续进阶路径。

这份文档是 FastAPI 官方学习体系的"总入口"

在 FastAPI 官方文档站中，导航结构把学习路径组织为一条主线：先是 features.md 的功能概览、接着是 Python 类型简介与异步概念铺垫，然后进入真正的实战主线——Tutorial - User Guide，它的入口就是本次所聚焦的 index.md（对应 mkdocs.yml 中的 tutorial/index.md 节点）。

这份总入口文档自身篇幅不长，但承担着三项关键任务：

阐明学习方式——本教程按"每节在上一节基础上逐步累进"的方式编排，同时又刻意按主题切分，使读者可以直接跳到任意章节去解决当下具体的 API 需求；
给出"可运行代码"的承诺——文档中的所有代码块都是经过真实测试的 Python 文件，可以直接复制使用；
提供统一的安装与运行入口——即用 uv 初始化项目、安装 FastAPI、以 uv run fastapi dev 运行示例的开发工作流。

换句话说，读懂这份入口文档，就等于拿到了整条官方学习路径的"操作手册"。

先确认环境：本仓库当前的 FastAPI 版本与 Python 要求

在动手之前，可以先了解当前仓库所代表的 FastAPI 版本基线（文章所述内容以该仓库为准）。在 fastapi/init.py 中声明了当前版本为 0.141.1，并从 applications.py 中导出了核心的 FastAPI 应用类。

从 pyproject.toml 可以看到，该版本要求 requires-python = ">=3.10"，即 Python 3.10 及以上版本均可安装使用；其运行时的直接依赖包括 starlette、pydantic>=2.9.0、typing-extensions、typing-inspection、annotated-doc 等。这些约束决定了下面安装步骤中 uv 会为你的项目解析出的版本范围。

安装 FastAPI：推荐使用 uv 的项目化流程

教程入口文档给出的第一步是"搭建项目并加入 FastAPI"，使用的是当前社区主流的 uv 包管理器。整体只需三条命令：

$ uv init awesome-project --bare
$ cd awesome-project
$ uv add "fastapi[standard]"

逐条解读这三条命令的作用：

uv init：创建一个新的 Python 项目；
awesome-project：在名为 awesome-project 的新目录中创建项目；
--bare：只生成最精简的 pyproject.toml，不额外生成示例 main.py、README.md 等文件——应用代码将由你在后续教程步骤中自行创建；
cd awesome-project：进入新项目目录后再执行依赖添加；
uv add "fastapi[standard]"：把 FastAPI 及其可选标准依赖一起加入项目。

关于 uv add 这条命令，文档特别解释了它的三层效果：

在项目内创建 .venv 虚拟环境；
将 FastAPI 写入 pyproject.toml 的依赖声明；
生成 uv.lock 锁文件，从而保证日后在另一台电脑上部署时能安装到完全相同版本的依赖包。

这一过程被称为对项目依赖执行 locking（锁定），uv 会在添加包时自动完成。此外，uv 会优先复用你系统上已安装的兼容 Python 版本，若没有则会自动下载一个合适的版本，无需你手动安装解释器。

如果你希望手动管理虚拟环境与依赖，也可以退回到经典流程：先自行创建并激活虚拟环境，再执行 pip install "fastapi[standard]"（官方文档建议查阅虚拟环境指南了解详细步骤）。

三种安装粒度：standard / 精简 / 无云端 CLI

入口文档专门用一个折叠区块介绍了 FastAPI 的安装选项，三者差异如下：

安装命令	含义与适用场景
`uv add "fastapi[standard]"`	默认推荐。安装 FastAPI 附带一批默认标准可选依赖，其中包含 `fastapi-cloud-cli`，可用于将应用一键部署到 FastAPI Cloud
`uv add fastapi`	最精简安装，不包含任何标准可选依赖
`uv add "fastapi[standard-no-fastapi-cloud-cli]"`	安装全部标准依赖，但排除 `fastapi-cloud-cli`

为什么"standard"与"精简"的差异值得关注？结合本仓库 pyproject.toml 中 standard 依赖组的实际声明，可以看到这套"标准依赖"实际上是把日常开发的高频配套一次性装齐：

fastapi-cli[standard]：提供 fastapi dev、fastapi run 等命令行工具；
httpx：供 FastAPI 自带的测试客户端（TestClient）使用；
jinja2：支持模板渲染；
python-multipart：支持表单（Form）与文件上传（File）解析；
email-validator：用于校验 email 字段；
uvicorn[standard]：生产可用的 ASGI 服务器（含 uvloop 加速）；
pydantic-settings 与 pydantic-extra-types：补充配置管理与额外 Pydantic 数据类型；
以及 fastar 等底层支持组件。

尤其要注意的是：fastapi 命令行工具本身实现在独立的 fastapi-cli 包中。仓库内的 fastapi/cli.py 清晰地揭示了这一点——它尝试 from fastapi_cli.cli import main，若导入失败则会打印提示"请安装 fastapi[standard]"并抛出错误。因此，若你只装了裸的 fastapi 而想使用 fastapi dev 命令，就会遇到这个引导信息，这就是入口文档建议你安装 fastapi[standard] 的底层原因。

创建第一个可运行文件 main.py

安装完成后，教程要求把示例代码复制保存为 main.py。仓库中真实的示例源码位于 docs_src/first_steps/tutorial001_py310.py，内容是 FastAPI 最精简的"Hello World"应用：

from fastapi import FastAPI

app = FastAPI()


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

这段代码虽短，却完整包含了一个 FastAPI 应用的四个基本要素，后续整个教程都会围绕它们层层展开：

from fastapi import FastAPI：导入 FastAPI 类；
app = FastAPI()：创建 FastAPI 实例，作为整个 API 的交互主入口；
@app.get("/")：路径操作装饰器（path operation decorator），声明下面的函数负责处理 GET / 请求；
async def root() 及其返回值：路径操作函数，FastAPI 收到匹配请求时会调用它，并把返回的字典自动序列化为 JSON 响应。

在入口文档对应的 first-steps.md 中会对这四个要素逐一定义：URL 中从第一个 / 开始的部分称为 路径（path），HTTP 的 GET/POST/PUT/DELETE 等方法在 OpenAPI 术语中称为 操作（operation），二者组合起来就是"路径操作"。FastAPI 不会限制你为某个 HTTP 方法赋予何种语义，常见的 POST 建数据、GET 读数据、PUT 更新、DELETE 删除只是通用约定而非强制约束。

教程承诺"所有代码块都是真实测试过的 Python 文件"，这一点在仓库中可以实证：tests/test_tutorial/ 目录下为教程的几乎每一个主题都建立了同名测试目录（如 test_first_steps/、test_path_params/、test_dependencies/ 等），docs_src/ 中的示例代码正是这些测试的运行对象。

用 uv run fastapi dev 启动开发服务器

将上述代码保存为 main.py 后，在项目根目录执行：

$ uv run fastapi dev

首次启动时控制台会输出一段详细日志，逐行理解它有助于排查问题：

Searching for package file structure... / Importing from ...：CLI 会从含 __init__.py 的目录结构中自动探测并导入你的应用模块；
module 🐍 main.py / code Importing the FastAPI app object from the module with the following code: from main import app：说明它识别出的导入串是 main:app，即从 main.py 中导入名为 app 的对象；
server Server started at http://127.0.0.1:8000：本机服务地址，浏览器打开即可看到 {"message": "Hello World"} 的 JSON 响应；
server Documentation at http://127.0.0.1:8000/docs：自动生成的交互式 API 文档地址；
Running in development mode, for production use: fastapi run：开发模式提示；
Will watch for changes in these directories、Started reloader process ... using WatchFiles：说明当前处于热重载（auto-reload）状态，修改代码后服务器会自动重启。

其中 Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) 这一行标示了应用在本机实际监听的地址。

entrypoint 的自定义方式（进阶提示）

值得提前了解的是：fastapi 命令默认从 main.py 中找 app 对象。如果你的应用不在标准位置，可以在项目根目录的 pyproject.toml 里显式声明入口：

[tool.fastapi]
entrypoint = "main:app"

也可以给命令直接传文件路径或 --entrypoint 参数，例如 uv run fastapi dev main.py 或 uv run fastapi dev --entrypoint main:app。若你的代码按包组织（如放在 backend/main.py），entrypoint 需写成 backend.main:app。入口文档建议优先使用 pyproject.toml 中的 entrypoint 声明，因为这样其他工具（如 VS Code 扩展）也能自动定位到应用对象。这些细节的完整示例可在 first-steps.md 中查阅。

推荐的学习方式：动手编辑、本地运行

入口文档特别强调：强烈建议你把代码亲自抄写或复制下来，编辑后在本机运行。只有在编辑器中真实运行起来，才能直观体会到 FastAPI 的核心开发体验——需要手写的样板代码极少、全程的类型检查、自动补全等。这种"边读边跑"的方式也是理解后续每一章节的最有效手段。

由于本教程按主题独立切分，你可以按两种方式使用它：

顺序阅读：每一节在上节基础上逐步累进，适合从零系统学习；
按需跳读：遇到具体 API 需求时，直接跳到对应主题章节。

教程全章节知识地图

结合 mkdocs.yml 的导航结构，这条教程主线的完整章节组织如下，可以作为你的阅读或速查索引：

阶段	章节（仓库路径，均在 docs/en/docs/tutorial/ 下）	覆盖主题
起步	first-steps.md	第一个 API、路径操作、OpenAPI 原理
参数	path-params.md、query-params.md、query-params-str-validations.md、path-params-numeric-validations.md、query-param-models.md、cookie-params.md、header-params.md、cookie-param-models.md、header-param-models.md	路径参数、查询参数、Cookie、Header 及其校验与模型化
请求体	body.md、body-multiple-params.md、body-fields.md、body-nested-models.md、schema-extra-example.md、extra-data-types.md、body-updates.md	Pydantic 模型、嵌套模型、示例声明、附加数据类型
响应	response-model.md、extra-models.md、response-status-code.md	响应模型过滤、状态码
表单与文件	request-forms.md、request-form-models.md、request-files.md、request-forms-and-files.md	Form、文件上传
错误与配置	handling-errors.md、path-operation-configuration.md、encoder.md	异常处理、路径操作元数据、JSON 编码
依赖注入	dependencies/index.md 及其下 classes-as-dependencies、sub-dependencies、dependencies-in-path-operation-decorators、global-dependencies、dependencies-with-yield 等	依赖注入体系
安全	security/index.md 及其下 first-steps、get-current-user、simple-oauth2、oauth2-jwt	安全与认证
工程化	middleware.md、cors.md、sql-databases.md、bigger-applications.md、testing.md、debugging.md、metadata.md	中间件、CORS、数据库、多文件应用、测试调试、OpenAPI 元数据
进阶场景	background-tasks.md、static-files.md、frontend.md、server-sent-events.md、stream-json-lines.md	后台任务、静态文件、前端、SSE、流式 JSON