FastAPI 入门实战指南：uv 环境搭建、fastapi dev 启动与进阶学习路线

本指南对应仓库中 FastAPI「Tutoriel - Guide utilisateur（入门教程）」的导读与总纲，系统讲解从零开始使用 FastAPI 的完整路径：先用 uv 创建项目并安装 fastapi[standard]，再通过 fastapi dev 启动开发服务器，最后说明如何按教程目录循序渐进掌握全部主要功能，以及何时转入高级用户指南（Advanced User Guide）。读完本文，你将掌握一套可复现的 FastAPI 项目初始化流程、开发服务器运行机制，以及围绕本仓库教程体系自学的导航方法。

教程（Tutoriel - Guide utilisateur）是什么

原文档 docs/fr/docs/tutorial/index.md 是整个「入门教程」栏目的入口与总索引，对应英文版位于 docs/en/docs/tutorial/index.md，两套目录结构完全一致。它本身并不讲解某一个具体 API 特性，而是交代了三条最重要的学习纪律：

1. 逐步递进：每个章节都建立在前一章的基础上，知识点层层叠加，避免一次引入过多概念。
2. 按需跳读：章节按主题彼此隔离，当你只需要解决某个具体问题（例如表单校验、依赖注入）时，可以直奔对应小节，不必从头读到尾。
3. 可作后续参考：教程被设计成一本可随时回查的速查手册，需要时可精确找回你想要的用法。

教程还刻意与「高级用户指南」做了分工：仅凭入门教程你就能构建一个完整应用，高级指南只是在此之上补充更多可选特性与配置。

运行示例代码：一切代码块都可复制可运行

教程中出现的每一个代码块都是真实的、经过测试的 Python 文件，可直接复制使用，这也是仓库采用「示例代码即源码」的组织方式——所有教程片段都维护在 docs_src 目录下，例如最经典的第一段示例 docs_src/first_steps/tutorial001_py310.py：

from fastapi import FastAPI

app = FastAPI()


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

想运行某个示例时，把代码保存为 main.py，然后在项目内执行：

$ uv run fastapi dev

  FastAPI  Starting development server 🚀

             Searching for package file structure from directories
             with __init__.py files
             Importing from /home/user/code/awesomeapp

   module   🐍 main.py

     code   Importing the FastAPI app object from the module with
             the following code:

             from main import app

      app   Using import string: main:app

   server   Server started at http://127.0.0.1:8000
   server   Documentation at http://127.0.0.1:8000/docs

      tip   Running in development mode, for production use:
             fastapi run

             Logs:

     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 [383138] using WatchFiles
     INFO   Started server process [383153]
     INFO   Waiting for application startup.
     INFO   Application startup complete.

这段启动日志包含了理解 fastapi dev 的几条关键信息：

• CLI 会自动发现应用对象：它在带有 __init__.py 的目录结构中搜索模块，并默认按 from main import app 导入 FastAPI 应用实例（导入字符串 main:app）。
• 服务默认监听 http://127.0.0.1:8000，交互式 API 文档自动托管在 http://127.0.0.1:8000/docs。
• 底部提示已明确区分环境：开发模式运行 fastapi dev，生产环境请改用 fastapi run。
• 日志显示启用了基于 WatchFiles 的 reloader（自动重载）进程与独立的 server 进程，说明修改代码后服务器会自动重启。

fastapi 命令的底层来源

fastapi 命令并非 FastAPI 核心包自带的可执行逻辑，而是通过可选依赖注入的。查看入口实现 fastapi/cli.py 可以看到：

try:
    from fastapi_cli.cli import main as cli_main
except ImportError:  # pragma: no cover
    cli_main = None

def main() -> None:
    if not cli_main:
        message = 'To use the fastapi command, please install "fastapi[standard]":\n\n\tpip install "fastapi[standard]"\n'
        print(message)
        raise RuntimeError(message)
    cli_main()

即：只有安装 fastapi[standard]（其中包含 fastapi-cli）后 fastapi 命令才可用，否则会给出明确的安装提示。同时在 pyproject.toml 中注册了命令入口 fastapi = "fastapi.cli:main"，而 fastapi/main.py 让 python -m fastapi 也可以等价触发同一入口。关于 fastapi dev / fastapi run 的完整行为差异，可进一步阅读仓库内的 docs/fr/docs/fastapi-cli.md（英文版见 docs/en/docs/fastapi-cli.md）。

亲自运行比阅读更重要

原文档特别强调：强烈建议你亲手编写或复制代码、编辑并本地运行。把示例放进编辑器才能真正体会到 FastAPI 的价值——需要写的代码极少、全程有类型检查（type checks）、自动补全（autocompletion）等开发体验。也就是说，教程不是让你“看懂”，而是让你“跑通”。

安装 FastAPI：推荐用 uv 管理项目

第一步是搭建项目环境并加入 FastAPI。安装好 uv 之后，按以下三步创建项目并安装依赖：

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

---> 100%

这三条命令各司其职，逐条拆解：

命令	作用
uv init	创建一个新的 Python 项目
uv init awesome-project	在名为 awesome-project 的新目录中创建项目
uv init --bare	只生成最小化的 pyproject.toml，不生成示例 main.py、README.md 等文件，应用文件由你自己在后续步骤中创建
cd awesome-project	在添加 FastAPI 之前进入新项目目录
uv add "fastapi[standard]"	解析并安装 FastAPI 及其兼容依赖，自动创建 .venv 虚拟环境

uv add 完成三件事：

1. 在 .venv 中创建项目的虚拟环境（无需手工 python -m venv 或手动激活）；
2. 把 FastAPI 写入 pyproject.toml 的依赖声明；
3. 生成/更新 uv.lock 锁文件。

其中 uv.lock 记录了各依赖的精确版本，使得之后在另一台机器或部署环境安装时能得到完全一致的包版本，这个动作被称为“锁定（lock）依赖”，由 uv 在添加包时自动完成。本仓库根目录下的 uv.lock 与 pyproject.toml 正是这种工作流的一个真实范例。此外，如果系统里没有兼容版本的 Python，uv 会自动使用已安装的兼容版本，必要时还会自行下载一份。

uv init 之后配合 uv run fastapi dev 使用：uv run 会在项目的 .venv 环境中执行命令，因此无需手动激活虚拟环境。关于虚拟环境的原理与更多做法（如 python -m venv + pip 的替代流程），参考仓库文档 docs/fr/docs/virtual-environments.md。

三种安装方式：standard、精简与剔除云端 CLI

uv add 时通过不同的 extra 选择不同的依赖组合，这是本仓库在 pyproject.toml 中用 [project.optional-dependencies] 定义的三档配置：

1. 标准安装（推荐）：uv add "fastapi[standard]"

包含默认的标准可选依赖。查看仓库的 pyproject.toml 中 standard 组的实际内容，它聚合了：

• fastapi-cli[standard]：提供 fastapi 命令（即 fastapi dev / fastapi run）；
• uvicorn[standard]：生产级 ASGI 服务器（带 uvloop 加速）；
• httpx：供 TestClient 测试客户端使用；
• jinja2：HTML 模板渲染（对应 docs/fr/docs/tutorial/static-files.md 等章节）；
• python-multipart：表单与文件上传解析（对应 request forms/files 系列章节）；
• email-validator：邮箱字段校验；
• pydantic-settings、pydantic-extra-types：设置管理与额外的 Pydantic 数据类型；
• 另外还连带 fastapi-cloud-cli，可用于将应用部署到 FastAPI Cloud。

由于 standard 已覆盖教程绝大多数场景所需的配套库，原文档将它作为默认推荐项。

2. 极简安装：uv add fastapi

如果完全不需要这些可选依赖，直接 uv add fastapi 即可，只装入 FastAPI 核心及其必需的五个依赖（见 pyproject.toml 的 dependencies：starlette、pydantic、typing-extensions、typing-inspection、annotated-doc）。代价是：不带 fastapi 命令，也无法使用需要 python-multipart 等的表单功能，除非后续按需补装。

3. 标准依赖但不要云 CLI：uv add "fastapi[standard-no-fastapi-cloud-cli]"

standard-no-fastapi-cloud-cli 组与 standard 组几乎一致（同为 fastapi-cli、httpx、jinja2、python-multipart、email-validator、uvicorn、pydantic-settings、pydantic-extra-types），唯一区别是不包含 fastapi-cloud-cli——适合想拥有完整本地开发与运行能力、但不需要云平台 CLI 的场景。

用 pip 的替代方案

如果你更习惯手工管理虚拟环境与包，可以自行创建并激活虚拟环境后执行：

$ pip install "fastapi[standard]"

详细的虚拟环境激活与工作流讲解可阅读仓库文档 docs/fr/docs/virtual-environments.md。需要说明的是：使用 pip 方案时 fastapi 命令同样来自 fastapi-cli，机制与 uv 方案一致。

为 AI 编程智能体准备的官方 Skill

FastAPI 随包附带一个面向 AI 编码智能体（coding agents）的官方 skill。它的优势在于：skill 随 FastAPI 包一起分发，其指引始终与你项目里安装的 FastAPI 版本保持一致，升级 FastAPI 时 skill 也会同步更新，不会出现文档与版本脱节的问题。

项目安装好 FastAPI 后，通过 Library Skills 安装该 skill：

uvx library-skills

其中 uvx 是 uv tool run 的别名：它会在一个临时、隔离的环境中运行 Library Skills，同时让 Library Skills 分析你当前项目里已安装的包，从而把 FastAPI skill 装配进项目。该 skill 兼容 Codex、Claude Code、Cursor、GitHub Copilot、Gemini CLI、Pi、OpenCode 及大多数主流编码智能体。若使用 Claude Code，安装时当被询问把 skill 装到哪个目录，请选择 .claude/skills。

学完教程之后：转战高级用户指南

入门教程是主路线；在其之上，仓库还提供一份高级用户指南（Guide d'utilisation avancé / Advanced User Guide），对应 docs/fr/docs/advanced/index.md（英文版为 docs/en/docs/advanced/index.md）。

二者的衔接关系在原文档中被明确约定：

• 高级指南建立在入门教程的基础之上，复用相同概念并补充更多功能；
• 请务必先读完入门教程（也就是本栏目），再用高级指南扩展；
• 入门教程本身足以让你构建一个完整应用，之后可按需挑选高级指南中的扩展点（如自定义响应、WebSocket、流式响应、子应用、模板等，具体可浏览 docs/fr/docs/advanced 下的章节清单）。

推荐的下一步学习路径

本仓库的入门教程按主题拆分为多个文件，位于 docs/fr/docs/tutorial（英文版结构与之一致），按官方推荐顺序建议这样走：

1. 起点是「快速上手」章节 docs/fr/docs/tutorial/first-steps.md：创建第一个带路径操作（path operation）的应用，认识自动生成的 /docs 交互文档，示例代码见 docs_src/first_steps/tutorial001_py310.py；
2. 随后进入「路径参数」docs/fr/docs/tutorial/path-params.md 与「查询参数」docs/fr/docs/tutorial/query-params.md，掌握请求入参的声明方式；
3. 再到「请求体」docs/fr/docs/tutorial/body.md 与「响应模型」docs/fr/docs/tutorial/response-model.md，理解基于 Pydantic 模型的数据建模与输出过滤；
4. 接着依次消化表单与文件上传（request-forms.md、request-files.md）、错误处理（handling-errors.md）、依赖注入（dependencies 目录）、安全认证（security 目录）等章节；
5. 最后可阅读「测试」章节 docs/fr/docs/tutorial/testing.md，配合仓库 tests/test_tutorial 下的测试文件理解如何验证自己的应用。

关于本仓库作为示例的说明

值得注意的是，本仓库本身就是用 uv 管理依赖的 FastAPI 项目——根目录的 pyproject.toml 中同时存在 standard、standard-no-fastapi-cloud-cli、all 三组可选依赖定义与 uv.lock 锁文件，这正是本文介绍的安装组合的源码级依据；教程示例代码全部集中在 docs_src，被仓库测试体系自动执行，这也印证了“教程里每个代码块都是真实可运行文件”的说法。建议读者结合本仓库实际文件动手实践，将教程示例逐一复制、运行、改造，完整走一遍从 uv init 到 fastapi run 的闭环。