FastAPI 入门实战教程从环境搭建到运行第一个 API 应用【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapiFastAPI的《Tutorial - User Guide》官方教程-用户指南是一份循序渐进的入门地图它覆盖 FastAPI 绝大多数核心功能每章在前一章基础上逐步深入同时每个主题又相互独立方便你按需直达。本文以该教程入口docs/es/docs/tutorial/index.md为主线完整讲解运行示例代码、安装 FastAPI、配置可选依赖、安装官方 AI Agent 技能的每个环节并结合本仓库的源码pyproject.toml、fastapi/cli.py、测试用例等揭示背后的实现细节让你能立刻跑通第一个可交互、带自动文档的 API 应用。教程整体设计既可顺序学习也可按需查询这份指南的核心组织原则有两个逐层递进每个章节都建立在前一章的基础概念之上从第一个应用一路深入到请求参数、请求体、响应模型、依赖注入、安全认证与测试等主题主题独立章节按知识点拆分你可以跳过已掌握的部分直接跳到当前要解决的问题例如只想知道如何处理文件上传就直奔request-files。正因如此这份文档不仅是一条学习路径更被设计成一份日后可随时回来查阅的工具性参考。在本仓库中教程正文分散在 docs/es/docs/tutorial/ 目录下的一个个 Markdown 文件中如 first-steps.md、body.md、query-params.md、dependencies/ 等每个文件对应一个独立的知识点。运行示例代码用fastapi dev一键启动教程中的所有代码块都不是贴出来好看的片段而是经过测试、可直接复制运行的 Python 文件。在本仓库中这些示例的真实源码位于 docs_src/ 目录——例如经典的第一个 Hello World 示例就是 docs_src/first_steps/tutorial001_py310.pyfrom fastapi import FastAPI app FastAPI() app.get(/) async def root(): return {message: Hello World}要在本地运行任意一个示例只需把代码保存为main.py然后在项目目录执行uv run fastapi dev$ uv run fastapi dev 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 INFO Will watch for changes in these directories: [/home/user/code/awesomeapp] INFO Uvicorn running on http://127.0.0.1:8000 (Press CTRLC 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专为开发环境设计它会以main:app的导入字符串定位应用对象自动开启文件监听与热重载日志中的 reloader 进程由 WatchFiles 驱动并在终端里给出开发服务器地址http://127.0.0.1:8000交互式文档默认可用浏览器打开http://127.0.0.1:8000/docs即可看到自动生成的 Swagger UI生产部署命令不同日志末尾明确提示 Running in development mode, for production use:fastapi run即上线时应改用fastapi run。fastapi命令与源码的对应关系fastapi dev/fastapi run这套命令并非内置于核心包而是由独立的fastapi-cli提供本仓库通过 pyproject 做了两处接线在 pyproject.toml 的[project.scripts]中注册了命令行入口fastapi fastapi.cli:mainfastapi/main.py 内同样调用fastapi.cli的main()因此也支持python -m fastapi dev这种启动方式。真正的实现位于 fastapi/cli.py它尝试从fastapi_cli导入命令入口如果环境中没有安装fastapi-cli则会打印提示并抛出异常——提示语正是To use the fastapi command, please install fastapi[standard]:pip install fastapi[standard]这段逻辑也有对应的自动化测试覆盖见 tests/test_fastapi_cli.py其中test_fastapi_cli用python -m fastapi dev传入一个不存在的文件断言进程返回码为 1 且输出包含 Path does not existtest_fastapi_cli_not_installed则模拟fastapi-cli缺失的场景断言出现 To use the fastapi command, please install 的报错。由此可以得出一个实用结论想使用fastapi命令必须安装fastapi[standard]这个 extra或其替代 extra否则命令不可用。教程代码全部来自真实测试文件文档强调所有代码块都是经过测试的 Python 文件这一点仓库可以印证docs_src 下的每个示例目录例如first_steps/、body/、query_params/都配套存放了可执行的 Python 源码而 tests/test_tutorial/ 目录中对应着大量针对这些示例的测试确保文档示例与实际行为一致。这意味你在教程里看到的每段代码都可以放心复制。强烈建议亲手敲一遍代码官方指南强烈建议你把代码写下来或复制到本地动手编辑并运行。原因在于只有在你的编辑器如 VS Code、PyCharm中打开 FastAPI 项目才能真正体会到它的价值——得益于类型注解驱动设计编辑器会实时给出类型检查、自动补全、参数提示以及基于你声明的 Pydantic 模型推断出的补全能力让你直观看到原来实现同样功能只需这么少的代码。安装 FastAPI使用uv初始化项目在动手写代码前第一步是初始化项目环境并加入 FastAPI 依赖。快速安装路径先安装uvAstral 出品的 Python 包与项目管理工具依次执行以下命令创建项目并添加 FastAPI$ 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 及其标准可选依赖写入项目依赖。依赖管理做了什么.venv、pyproject.toml 与 uv.lock执行uv add后uv 会替你完成三件事在.venv下创建项目专属的虚拟环境把 FastAPI 写入pyproject.toml的依赖列表生成uv.lock锁文件。锁文件的意义在于锁定依赖原文称之为 dependency lockinguv 会为 FastAPI 以及它依赖的每个包挑选相互兼容的精确版本并把确切版本记录到uv.lock中。这样无论换一台电脑还是日后部署上线都能安装到完全一致的包版本避免本地能跑、线上跑不起来的经典问题。当你每次新增或升级依赖时uv 都会自动更新锁文件。Python 解释器从哪来uv 会优先使用系统里已安装的、与项目要求兼容的 Python 版本如果找不到合适的解释器它会自动下载一个——这意味着你甚至不必预先手动安装 Python。FastAPI 的安装选项与可选依赖当你在不同场景下安装 FastAPI 时可选依赖extras的取舍很重要。参考本仓库 pyproject.toml 的[project.optional-dependencies]定义可以精确回答每种装法到底装了什么fastapi[standard]标准安装官方推荐uv add fastapi[standard]会带来一组开箱即用的标准可选依赖除了让fastapi命令可用的fastapi-cli[standard]之外还包括依据 pyproject 中的列表uvicorn[standard]生产级 ASGI 服务器带 uvloop 加速本地开发服务器由它承载httpx为 TestClient 测试客户端提供底层支持jinja2HTML 模板渲染python-multipart处理表单Form与文件上传email-validator用于校验 Email 字符串字段pydantic-settings应用配置/设置管理pydantic-extra-types额外的 Pydantic 数据类型。该 extra 还默认包含fastapi-cloud-cli用于向 FastAPI Cloud 平台执行部署。如果你不需要这些可选依赖可以退而求其次安装最精简的内核uv add fastapi——此时只有核心框架本身fastapi命令和 uvicorn 服务器等都不会附带。fastapi[standard-no-fastapi-cloud-cli]标准依赖但不带云 CLI若你希望保留上述全部标准依赖唯独不想要fastapi-cloud-cli官方提供了专门的 extrauv add fastapi[standard-no-fastapi-cloud-cli]从仓库的 pyproject.toml 可见它与其他标准安装共享 httpx、jinja2、python-multipart、email-validator、uvicorn[standard]、pydantic-settings、pydantic-extra-types 等依赖只把云部署 CLI 排除在外。用pip安装如果你更习惯手动管理虚拟环境与依赖也可以创建并激活虚拟环境后用 pip 安装等价的版本pip install fastapi[standard]pip 与 uv 在此场景下的区别主要在于pip 不会像 uv 那样自动生成.venv、同步pyproject.toml并维护锁文件虚拟环境的创建与激活需要你手动完成。运行环境验证你的第一个请求安装完成并写好main.py后用uv run fastapi dev启动即可在浏览器中访问http://127.0.0.1:8000返回{message: Hello World}JSON 响应http://127.0.0.1:8000/docsSwagger UI 交互式 API 文档可以直接在线调用接口http://127.0.0.1:8000/redocReDoc 风格的可读性文档。这也对应了本仓库示例 docs_src/first_steps/tutorial001_py310.py 的行为它仅用app.get(/)声明了一个异步根路由并返回字典FastAPI 便会自动完成 JSON 序列化与 OpenAPI 文档生成——这正是教程强调代码极少、编辑器体验极佳的第一手体验。官方 AI Agent 技能让编程助手懂你的 FastAPI 版本教程还特别介绍了一项较新的能力——FastAPI 官方 AI 编程 Agent 技能AI Agent Skills。它的设计要点随包发布、版本一致该技能被打包在 FastAPI 发行版中其指导内容始终与你项目里安装的 FastAPI 版本保持对齐升级 FastAPI 时技能也会同步更新避免 AI 助手用过时的旧知识给你写出不兼容代码安装方式项目安装好 FastAPI 后用 Library Skills 工具安装即可uvx library-skills其中uvx是uv tool run的别名它会在一个临时、隔离的环境里运行 Library Skills而 Library Skills 会扫描你当前项目里已安装的包据此把匹配的 FastAPI 技能安装到项目中。兼容面广该技能兼容 Codex、Claude Code、Cursor、GitHub Copilot、Gemini CLI、Pi、OpenCode 以及大多数主流编程 Agent。若使用 Claude Code在询问安装位置时请选择.claude/skills目录。值得注意的是仓库根目录同样存放了一份给翻译/文档 AI 使用的通用提示词 scripts/general-llm-prompt.md 及各语言的 llm-prompt.md说明该仓库在 AI 辅助写作与翻译流程上已有成熟实践而为 AI 编程 Agent 提供随版本更新的官方技能正是 FastAPI 面向 AI 时代开发者体验的延续。教程之后进阶用户指南Advanced User Guide完成这份《Tutorial - User Guide》之后官方还提供一份《Advanced User Guide》进阶用户指南它建立在教程的同一套概念之上教你更多额外的高级功能二者的关系是顺序进阶建议先通读 Tutorial再进入 Advanced教程本身被设计成仅靠它就能构建一个完整应用当应用逐步长大、出现特定需求时再按需从进阶指南中取用补充技巧进行扩展。换句话说入门阶段你可以心无旁骛地跟完教程主线把扩展路径留给日后按需探索。教程章节导航可参考的下一步结合 docs/es/docs/tutorial/ 目录内容一个典型的推进顺序可以是这样第一个应用first-steps.md——创建FastAPI()实例、声明路径操作与交互式文档路径参数path-params.md、数值校验见 path-params-numeric-validations.md查询参数query-params.md 与字符串校验 query-params-str-validations.md请求体body.md、字段与嵌套模型分别见 body-fields.md、body-nested-models.md响应建模response-model.md、状态码 response-status-code.md表单与文件request-forms.md、request-files.md依赖注入与安全dependencies/、security/ 子目录中的系列章节中间件、后台任务与大型应用middleware.md、background-tasks.md、bigger-applications.md错误处理与调试handling-errors.md、debugging.md测试testing.md——用 TestClient 编写接口测试示例与测试的对应关系可参考仓库 tests/test_tutorial/。小结从写一个最小应用到配置标准依赖、锁定版本、让 AI Agent 协作、规划进阶路径这份 FastAPI 官方入门指南为你规划了一条低门槛、可增量扩展的学习曲线。实践时请记住三条主线用uv init --bare干净起步、用uv add fastapi[standard]一次装齐开发所需的服务器与工具链、用uv run fastapi dev立即获得热重载与交互式文档的开发体验待到上线部署再切换到fastapi run即可。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考