
FastAPI 第一步实战编写第一个路径操作、运行fastapi dev并理解自动生成的 OpenAPI 文档【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本篇指南以 FastAPI 官方教程的入门章节为骨架带你从零完成「导入FastAPI→ 创建app实例 → 用app.get(/)定义路径操作 → 运行开发服务器 → 访问自动文档与openapi.json」的完整闭环。读完你将掌握 FastAPI 最核心的最小可运行代码模型理解路径Path、操作Operation、路径操作函数与 JSON 序列化之间的内在关系并学会通过pyproject.toml、命令行参数等多种方式向fastapi命令声明应用入口为后续编写更复杂的 API 打下基础。一、最小可运行的 FastAPI 文件FastAPI 最简单的应用只有一个文件。将下面的代码保存为main.py就是一套完整可运行的 APIfrom fastapi import FastAPI app FastAPI() app.get(/) async def root(): return {message: Hello World}这一完整示例正是仓库中 docs_src/first_steps/tutorial001_py310.py 的全部内容而它的每一个部分FastAPI导入、app实例、装饰器、函数、返回值都将在后文「逐步回顾」中被逐一拆解。二、启动开发服务器在包含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 CTRLC to quit) INFO Started reloader process [383138] using WatchFiles INFO Started server process [383153] INFO Waiting for application startup. INFO Application startup complete.其中值得重点关注的几行信息import string: main:app说明fastapi命令自动从当前目录定位到了main.py并按main:app导入应用对象Server started at http://127.0.0.1:8000应用服务地址Documentation at http://127.0.0.1:8000/docs自动文档地址开发模式development mode提示当前运行的是带热重载的开发服务器生产环境应改用fastapi run。日志中还会出现这样一行它指明本地服务监听的 URLINFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRLC to quit)从仓库源码可以看到fastapi命令本身并不内置于框架核心在 fastapi/cli.py 中它通过from fastapi_cli.cli import main as cli_main引用外部fastapi-cli包若未安装会提示To use the fastapi command, please install fastapi[standard]。也就是说使用本教程的命令前需要安装带标准依赖集的版本例如pip install fastapi[standard]当前仓库的 pyproject.toml 也定义了完整依赖在仓库环境中可直接通过uv复现。三、验证接口浏览器里的 JSON 响应开发服务器启动后用浏览器打开 http://127.0.0.1:8000即可看到如下 JSON 响应{message: Hello World}返回的是纯 JSON这正是 FastAPI 的核心体验之一你只需在 Python 函数里返回普通的dictFastAPI 就会自动将其序列化为 JSON 响应。四、自动生成的交互式 API 文档交互式文档Swagger UI打开 http://127.0.0.1:8000/docs你会看到一个自动生成、可直接交互操作的 API 文档页面它由 Swagger UI 提供在这个页面里你可以直接对GET /接口发起请求、查看响应、观察请求参数结构无需任何手动维护文档的工作。替代文档ReDoc再打开 http://127.0.0.1:8000/redoc可看到另一种风格的自动文档由 ReDoc 提供两份文档都来自同一份自动生成的 schema只是渲染风格不同可互为补充。五、认识 OpenAPISchema 到底是什么FastAPI 使用OpenAPI标准为你的全部 API 自动生成一份「schema模式」上述两种文档都只是这份 schema 的可视化表现。术语拆解Schema模式对某事物的定义或描述是对数据/接口的抽象描述而不是实现它的代码API Schema由 OpenAPI 规范 定义描述你的 API 有哪些路径、路径上可能带哪些参数等。OpenAPI 规范规定了如何定义这套 schema数据 Schemaschema 一词也可指某类数据的形状shape例如一段 JSON 内容包含哪些属性、属性类型是什么等OpenAPI 与 JSON Schema 的关系OpenAPI 描述整个 API其内部又借助JSON SchemaJSON 数据模式的标准定义 API 收发数据的结构。换言之OpenAPI 是「API 的 schema」JSON Schema 是「数据的 schema」二者嵌套组合。查看原始的openapi.json如果好奇机器视角的原始 schema 长什么样直接访问 http://127.0.0.1:8000/openapi.jsonFastAPI 会为你的全部 API 自动生成一份描述用 JSON开头形如{ openapi: 3.1.0, info: { title: FastAPI, version: 0.1.0 }, paths: { /items/: { get: { responses: { 200: { description: Successful Response, content: { application/json: { ...注意title: FastAPI与version: 0.1.0如果不做任何配置这就是默认的元信息后续可以在创建FastAPI()实例或阅读 metadata 相关教程时自定义它们。这一行为在仓库测试中有精确的断言测试文件 tests/test_tutorial/test_first_steps/test_tutorial001_tutorial002_tutorial003.py 请求/openapi.json后用快照比对确认 schema 包含openapi: 3.1.0、paths下挂载GET /且响应模型为summary: Root、operationId: root__get。OpenAPI 有什么用它是内置两套交互式文档Swagger UI 与 ReDoc的数据源生态中存在大量基于 OpenAPI 的工具可以轻松接入你用 FastAPI 构建的应用它还能用于自动生成客户端代码——为与 API 通信的前端、移动端、物联网等应用批量产出调用代码。六、在pyproject.toml中声明应用入口fastapi命令需要知道去哪里找 FastAPI 应用对象。推荐的稳定做法是把它写进pyproject.toml[tool.fastapi] entrypoint main:app该entrypoint告诉fastapi命令按下面的方式导入应用from main import app如果代码被组织进子包例如目录结构为. ├── backend │ ├── main.py │ ├── __init__.py那么entrypoint要相应写成[tool.fastapi] entrypoint backend.main:app等价于from backend.main import appentrypoint的写法就是「模块路径 冒号 对象名」的 Python 导入字符串前半段backend.main对应可导入的模块路径包间用.连接后半段app是模块内暴露的 FastAPI 实例变量名。七、用路径或--entrypoint运行fastapi dev除了pyproject.toml还有两种临时指定应用的方式。方式一直接传文件路径$ uv run fastapi dev main.pyfastapi dev会根据文件内容自动推断其中定义的 FastAPI 应用对象。方式二传--entrypoint选项$ uv run fastapi dev --entrypoint main:app为什么不推荐每次都传参每次调用fastapi命令都要记住并正确传 path/entrypoint容易出错更关键的是其它工具例如 VS Code 扩展、FastAPI Cloud很可能无法感知你在命令行里临时指定的入口从而找不到应用。因此官方推荐把入口固定配置在pyproject.toml的[tool.fastapi]段落中让所有工具共享同一份声明。八、可选一键部署到 FastAPI Cloud如需快速上线体验FastAPI 官方提供了配套的 FastAPI Cloud 服务一条命令即可部署$ uv run fastapi deploy Deploying to FastAPI Cloud... ✅ Deployment successful! Ready the chicken! Your app is ready at https://myapp.fastapicloud.devCLI 会自动检测你的 FastAPI 应用并完成部署若尚未登录浏览器会自动打开以完成认证流程。部署完成后即可通过返回的 URL 访问应用。需要说明的是该步骤完全可选。FastAPI 本身是开源且基于开放标准的你可以按照任意云厂商的指南把 FastAPI 应用部署到自己选择的任何平台并不受绑定。九、逐步回顾第一个应用的六步拆解第 1 步导入FastAPIfrom fastapi import FastAPIFastAPI是提供 API 全部功能的 Python 类。技术细节从源码看FastAPI是直接继承自Starlette的类——见 fastapi/applications.py 第 42 行class FastAPI(Starlette):。这意味着 FastAPI 应用天然具备 Starlette 的全部底层能力ASGI、路由分发、中间件体系等在此之上叠加了 OpenAPI 文档生成、类型驱动的请求校验/序列化等高级功能。第 2 步创建FastAPI实例app FastAPI()这里的app变量就是FastAPI类的一个实例instance它将是你构建所有 API 时最主要的交互入口——后续所有路由、中间件、异常处理等几乎都挂载在它之上。第 3 步创建路径操作path operation路径Path「路径」指 URL 中从第一个/开始的后半部分。例如对 URLhttps://example.com/items/foo其路径是/items/foo「路径」通常也被称为「端点endpoint」或「路由route」。在设计 API 时路径是划分不同「关注点concerns」与「资源resources」的主要手段。操作Operation「操作」指 HTTP 方法中的一种常见的有POSTGETPUTDELETE以及相对少用的一些OPTIONSHEADPATCHTRACEHTTP 协议允许你用其中一种或多种方法访问同一条路径。构建 API 时通常按语义约定使用不同方法POST用于创建数据、GET用于读取数据、PUT用于更新数据、DELETE用于删除数据。在 OpenAPI 术语中每种 HTTP 方法被称为一个「operation」本系列教程也沿用这一叫法。从仓库源码可以确认FastAPI类对全部 8 种 HTTP 方法都提供了对应的装饰器方法get、put、post、delete、options、head、patch、trace均定义于 fastapi/applications.py例如get位于第 1646 行附近。定义路径操作装饰器app.get(/)app.get(/)告诉 FastAPI紧挨在它下面的那个函数负责处理发往路径/、使用get操作的请求。Python 中这种something语法被称为「装饰器decorator」它被放在函数顶部接收下面的函数并对它做某些处理。在这里装饰器向 FastAPI 登记「下面这个函数对应路径/的get操作」因此它被称为路径操作装饰器。除app.get()外同样可以使用app.post()、app.put()、app.delete()以及app.options()、app.head()、app.patch()、app.trace()。需要强调的是FastAPI不会强制某种方法必须对应某种语义上文语义只是约定俗成的指导而非约束。例如使用 GraphQL 时通常只用POST完成所有动作。第 4 步定义路径操作函数我们的路径操作函数由三要素构成路径/操作get函数装饰器app.get(/)下方紧邻的那个函数async def root(): return {message: Hello World}这是一个普通 Python 函数每当 FastAPI 收到一个对/的GET请求时它就会被调用。示例中使用的是async def异步函数如果你暂时不需要异步能力也可以把它写成普通同步函数等价示例见 docs_src/first_steps/tutorial003_py310.pyfrom fastapi import FastAPI app FastAPI() app.get(/) def root(): return {message: Hello World}关于async def与普通def的区别、以及「异步接口里到底该选哪种」可以参考 Async 相关章节的讲解。仓库测试会同时验证两种写法行为一致上述测试文件通过 pytest fixture 将tutorial001_py310与tutorial003_py310两个模块轮流载入断言对/的请求都返回200与{message: Hello World}对不存在的路径/nonexistent则返回404。第 5 步返回内容return {message: Hello World}路径操作函数可以返回多种类型dict、list、单一值如str、int等也可以返回 Pydantic 模型后续教程会展开。实际上还有大量其它对象与模型包括各类 ORM 对象都会被自动转换成 JSON——你大可以优先尝试自己惯用的类型它们很可能已被内置支持。这一「自动转 JSON」的能力正是 FastAPI「基于标准、开箱即用」的体现框架在返回阶段自动完成序列化并同步生成对应的 OpenAPI schema。第 6 步部署可选使用fastapi deploy单命令部署到 FastAPI Cloud见上文通用做法FastAPI 基于开放标准、完全开源遵循所选云厂商的部署指南即可在任何平台运行。十、本章小结回顾全篇一个 FastAPI 应用的最小闭环包含五个固定动作导入FastAPI创建app实例用app.get(/)之类的装饰器编写路径操作装饰器定义路径操作函数例如def root(): ...用fastapi dev命令运行开发服务器可选再用fastapi deploy部署。更进一步把应用的入口字符串写进pyproject.toml的[tool.fastapi] entrypoint能让fastapiCLI、编辑器扩展乃至云端工具都稳定地找到你的应用而自动生成的 Swagger UI、ReDoc 与openapi.json则让你的第一个接口从诞生起就自带完整、可交互、机器可读的 API 契约。掌握了这个骨架之后你便可以沿着教程目录继续深入路径参数、查询参数、请求体、响应模型与安全认证等能力都建立在本篇这五个步骤之上。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考