1. 十分钟能学到什么先明确 FastAPI 的定位如果你刚接触 Python Web 开发或者从 Flask、Django 过来想找个更现代、性能更好的框架来写 API那 FastAPI 绝对是现在最值得花十分钟试试的那个。它不是什么“玩具”而是一个能直接用在生产环境、文档自动生成、类型提示支持极好的现代框架。这十分钟我们不搞虚的目标就一个让你在自己的电脑上从零跑起来一个能处理 GET 和 POST 请求的 FastAPI 应用并且亲眼看到它自动生成的交互式 API 文档。你会清楚知道它和 Flask 写起来哪里不一样为什么都说它快以及后续深入学习该往哪个方向走。很多人被“高性能”、“异步”这些词吓住觉得入门门槛高。其实完全相反FastAPI 的入门简单程度可能超乎你想象核心代码比 Flask 还少。它的“快”不仅指运行速度更指开发效率——你写代码时就有类型检查和自动补全写完文档自动就有了调试接口再也不用到处找文档或手写测试用例。所以别管那些复杂的配置和部署我们先聚焦在最核心的体验上安装、启动、定义接口、看文档。这是判断一个框架是否“友好”最直接的方式。2. 动手之前确认你的“起跑线”环境开始写代码前花一分钟确认环境能避免 80% 的“为什么我的跑不起来”问题。FastAPI 对 Python 版本有要求这是第一个关键点。Python 版本是门槛FastAPI 严重依赖 Python 的类型提示Type Hints这是它实现自动校验、自动文档的核心。因此你需要Python 3.7 或更高版本。在终端输入python --version或python3 --version确认一下。如果版本低于 3.7先去升级 Python这是硬性前提没有商量余地。虚拟环境是“安全区”强烈建议使用虚拟环境。这不是 FastAPI 的要求而是 Python 项目的通用最佳实践。它能把你这个项目的依赖比如 FastAPI 本身、服务器和系统全局的 Python 包隔离开避免版本冲突。# 创建虚拟环境名字叫 venv 或者 .venv 都行 python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate激活后你的命令行提示符前通常会显示(venv)表示你已经在虚拟环境里了。两个核心依赖框架与服务器FastAPI 是一个框架它本身不直接处理网络请求。我们需要一个 ASGI 服务器来运行它。这就是 Uvicorn一个轻量级、高性能的 ASGI 服务器用纯 Python 编写是 FastAPI 官方推荐的默认选择。 安装命令非常简单pip install fastapi uvicorn[standard]注意uvicorn[standard]里的[standard]这表示安装 Uvicorn 的“标准”版本它会额外带上一些高性能的依赖如httptools,uvloop在支持的操作系统上能获得更好的性能。如果安装失败可以先尝试pip install uvicorn。至此你的“起跑线”就画好了Python 3.7一个激活的虚拟环境以及安装好的 fastapi 和 uvicorn。3. 第一个应用从“Hello World”到自动文档现在我们开始写代码。创建一个新文件比如叫main.py。别被“项目结构”吓到我们就从一个文件开始。3.1 最小可运行应用在main.py里输入以下代码from fastapi import FastAPI app FastAPI() app.get(/) def read_root(): return {Hello: World}四行代码一个完整的 API 就完成了。from fastapi import FastAPI: 导入框架。app FastAPI(): 创建应用实例。这个app对象是你整个应用的核心。app.get(“/“): 这是一个路径操作装饰器。它告诉 FastAPI当用户通过 HTTP GET 方法访问根路径/时就执行下面这个函数。def read_root(): …:路径操作函数。它直接返回一个 Python 字典FastAPI 会自动将其转换为 JSON 格式响应。3.2 启动服务器并访问保存文件在终端确保在虚拟环境下运行uvicorn main:app --reload这个命令需要解释一下main: 指你的 Python 文件main.py去掉.py后缀。app: 指在main.py文件中创建的FastAPI实例对象的名字即app FastAPI()里的app。--reload: 让服务器在代码更改后自动重启。仅在开发时使用生产环境必须去掉。看到类似Uvicorn running on http://127.0.0.1:8000的输出就说明服务器启动成功了。现在打开浏览器访问http://127.0.0.1:8000。你会看到{“Hello”: “World”}这个 JSON 响应。你的第一个 API 接口已经工作了。3.3 体验“王牌功能”交互式 API 文档这才是 FastAPI 十分钟入门最该看的亮点。访问以下两个地址http://127.0.0.1:8000/docs这是自动生成的 Swagger UI 交互式文档。你会看到一个非常漂亮的页面里面列出了你的/接口GET 方法。你可以直接点击 “Try it out”然后 “Execute”在页面上就完成了对接口的测试。无需 Postman 或 curl 命令。http://127.0.0.1:8000/redoc这是 ReDoc 生成的另一种风格的 API 文档更侧重于阅读。为什么这个功能至关重要对于后端开发者你再也不用手动维护一份可能过时的 API 文档。对于前端或测试同学他们可以自己打开/docs页面查看接口定义、数据类型并直接进行测试。这极大地减少了沟通成本是 FastAPI 提升团队协作效率的核心卖点。4. 进阶一步处理路径参数、查询参数和 POST 请求只会返回 “Hello World” 显然不够。我们快速增加几个最常用的功能感受一下 FastAPI 的简洁。4.1 路径参数修改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): return {item_id: item_id}注意read_item函数参数item_id: int。这里使用了类型提示int。FastAPI 会从 URL 路径中获取item_id例如/items/123。自动尝试将其转换为整数。如果用户传入“foo”这种无法转换为整数的字符串FastAPI 会自动返回一个清晰的422 错误并告诉你期望收到一个整数。这就是基于类型提示的自动数据验证。启动服务器如果已启动由于--reload会自动重启访问http://127.0.0.1:8000/items/123返回{“item_id”: 123}。访问http://127.0.0.1:8000/items/foo你会看到一个结构化的错误响应。4.2 查询参数查询参数就是 URL 中?后面的部分如?skip10limit20。在 FastAPI 中只需将非路径参数的函数参数定义为查询参数。from fastapi import FastAPI from typing import Optional app FastAPI() # ... 之前的代码 ... app.get(“/items/“) def read_items(skip: int 0, limit: int 10, q: Optional[str] None): # 模拟从数据库取数据 fake_items [{item_name: Foo}, {item_name: Bar}, {item_name: Baz}] results fake_items[skip : skip limit] if q: results [item for item in results if q.lower() in item[“item_name”].lower()] return {“results”: results, “query”: q}skip: int 0: 定义了查询参数skip类型是int默认值是0。如果请求中不传skip它就等于 0。limit: int 10: 同理。q: Optional[str] None: 定义了可选的查询参数q类型是可选字符串默认None。Optional需要从typing模块导入。访问http://127.0.0.1:8000/items/?skip1limit1qbar试试看。再打开/docs页面你会发现这个接口的文档已经自动更新清晰地列出了这三个查询参数及其类型和默认值。4.3 处理 POST 请求与请求体POST 请求通常用于创建数据数据放在请求体Body中通常是 JSON 格式。FastAPI 通过 Pydantic 模型来优雅地处理它。首先需要安装 Pydantic安装fastapi时通常已包含但明确一下pip install pydantic然后修改main.pyfrom fastapi import FastAPI from pydantic import BaseModel from typing import Optional app FastAPI() # 定义数据模型 class Item(BaseModel): name: str description: Optional[str] None price: float tax: Optional[float] None app.post(“/items/“) def create_item(item: Item): # 直接使用 item 对象它已经是一个验证过的 Pydantic 模型实例 item_dict item.dict() if item.tax: price_with_tax item.price item.tax item_dict.update({“price_with_tax”: price_with_tax}) return item_dictclass Item(BaseModel):定义了一个 Pydantic 模型。它清晰地描述了期望接收的数据结构必须有name(字符串) 和price(浮点数)description和tax是可选的。def create_item(item: Item):在路径操作函数中将参数item的类型声明为Item模型。FastAPI 会自动从请求体中读取 JSON。转换为相应的类型字符串转字符串数字转浮点数。进行数据验证检查必需字段是否存在类型是否正确。如果无效同样返回 422 错误。将验证后的数据提供给item参数。现在打开/docs页面找到POST /items/接口。点击 “Try it out”在 Request body 里输入{ “name”: “Foo”, “price”: 50.5, “description”: “A very nice item”, “tax”: 10.5 }点击 “Execute”你会看到返回了完整的 item 数据并自动计算了price_with_tax。如果你尝试发送一个缺少name字段或price是字符串的 JSON会立刻在文档页面上看到验证错误。5. 十分钟后的方向部署、异步与项目结构十分钟到了你的本地开发环境里应该已经有了一个能处理 GET/POST、带路径和查询参数、有自动验证和交互文档的 API。这已经覆盖了 80% 的日常 API 开发场景。接下来你可能会问1. 怎么部署到服务器你已经在用 Uvicorn 了。在生产环境去掉--reload并使用更多配置。例如使用多个工作进程处理请求uvicorn main:app --host 0.0.0.0 --port 80 --workers 4--host 0.0.0.0: 监听所有网络接口。--workers 4: 启动 4 个工作进程根据 CPU 核心数调整。对于 CPU 密集型或同步代码增加 workers 能提升并发。但注意如果你的代码是纯异步的见下一点并且 IO 操作很多少量 workers 甚至 1 个也可能足够因为异步本身就能处理大量并发连接。更常见的生产部署方式是搭配 Gunicorn一个 WSGI/ASGI 服务器管理器来管理 Uvicorn 工作进程或者使用 Docker 容器化部署。2. 异步async/await是必须的吗不是必须但强烈推荐。FastAPI 支持异步这是它高性能的重要原因之一。如果你的操作是 I/O 密集型的如读写数据库、调用外部 API、读写文件使用async def可以极大提升并发能力。app.get(“/async-demo”) async def read_async_data(): # 模拟一个耗时的 I/O 操作 await asyncio.sleep(1) return {“message”: “Data fetched”}使用async def时函数内部可以使用await调用其他异步函数。如果你的函数内部没有await表达式直接使用普通def也可以。但为了保持一致性和未来扩展对于 I/O 操作建议从一开始就养成使用async def的习惯。3. 项目结构怎么组织当你的应用超过一个文件时就需要考虑结构。一个常见的简单结构是your_project/ ├── app/ │ ├── __init__.py │ ├── main.py # 原来的 main.py现在可能只保留 FastAPI app 创建和路由汇总 │ ├── api/ │ │ ├── __init__.py │ │ ├── endpoints/ │ │ │ ├── __init__.py │ │ │ ├── items.py # 与 items 相关的路由 │ │ │ └── users.py # 与 users 相关的路由 │ │ └── deps.py # 依赖项如数据库会话 │ ├── core/ │ │ ├── config.py # 配置 │ │ └── security.py # 安全相关 │ ├── models/ │ │ └── schemas.py # Pydantic 模型 │ └── db/ │ └── session.py # 数据库连接 └── requirements.txt在app/main.py中你会导入各个模块的路由器APIRouter并将其包含到主app中。这样可以将不同功能模块解耦。4. 遇到常见错误怎么办422 Unprocessable Entity: 这是你未来最常见的错误。它意味着请求数据验证失败。第一时间去/docs页面确认接口期望的数据格式然后对比你发送的数据。99% 的情况是字段名拼错、类型不对比如字符串传了数字、或缺少了必需的字段。ImportError或ModuleNotFoundError: 检查虚拟环境是否激活依赖是否安装正确。运行pip list确认fastapi和uvicorn是否存在。地址已被占用 (Address already in use)默认端口 8000 被其他程序占用。使用--port 8001指定另一个端口。代码修改后服务器没重启检查启动命令是否包含--reload。如果没有需要手动停止并重启 Uvicorn。这十分钟的快速入门目的是让你用最小的代价感受到 FastAPI 的核心优势开发体验的流畅度。它通过 Python 类型提示把数据验证、序列化、文档生成这些繁琐工作自动化了。接下来你可以根据自己的需求深入探索数据库集成如 SQLAlchemy、Tortoise-ORM、身份认证OAuth2、JWT、中间件、后台任务等特性。记住官方文档https://fastapi.tiangolo.com/写得极其出色是你最好的进阶指南。 FastAPI十分钟快速入门：从零构建Python Web API与自动文档
1. 十分钟能学到什么先明确 FastAPI 的定位如果你刚接触 Python Web 开发或者从 Flask、Django 过来想找个更现代、性能更好的框架来写 API那 FastAPI 绝对是现在最值得花十分钟试试的那个。它不是什么“玩具”而是一个能直接用在生产环境、文档自动生成、类型提示支持极好的现代框架。这十分钟我们不搞虚的目标就一个让你在自己的电脑上从零跑起来一个能处理 GET 和 POST 请求的 FastAPI 应用并且亲眼看到它自动生成的交互式 API 文档。你会清楚知道它和 Flask 写起来哪里不一样为什么都说它快以及后续深入学习该往哪个方向走。很多人被“高性能”、“异步”这些词吓住觉得入门门槛高。其实完全相反FastAPI 的入门简单程度可能超乎你想象核心代码比 Flask 还少。它的“快”不仅指运行速度更指开发效率——你写代码时就有类型检查和自动补全写完文档自动就有了调试接口再也不用到处找文档或手写测试用例。所以别管那些复杂的配置和部署我们先聚焦在最核心的体验上安装、启动、定义接口、看文档。这是判断一个框架是否“友好”最直接的方式。2. 动手之前确认你的“起跑线”环境开始写代码前花一分钟确认环境能避免 80% 的“为什么我的跑不起来”问题。FastAPI 对 Python 版本有要求这是第一个关键点。Python 版本是门槛FastAPI 严重依赖 Python 的类型提示Type Hints这是它实现自动校验、自动文档的核心。因此你需要Python 3.7 或更高版本。在终端输入python --version或python3 --version确认一下。如果版本低于 3.7先去升级 Python这是硬性前提没有商量余地。虚拟环境是“安全区”强烈建议使用虚拟环境。这不是 FastAPI 的要求而是 Python 项目的通用最佳实践。它能把你这个项目的依赖比如 FastAPI 本身、服务器和系统全局的 Python 包隔离开避免版本冲突。# 创建虚拟环境名字叫 venv 或者 .venv 都行 python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate激活后你的命令行提示符前通常会显示(venv)表示你已经在虚拟环境里了。两个核心依赖框架与服务器FastAPI 是一个框架它本身不直接处理网络请求。我们需要一个 ASGI 服务器来运行它。这就是 Uvicorn一个轻量级、高性能的 ASGI 服务器用纯 Python 编写是 FastAPI 官方推荐的默认选择。 安装命令非常简单pip install fastapi uvicorn[standard]注意uvicorn[standard]里的[standard]这表示安装 Uvicorn 的“标准”版本它会额外带上一些高性能的依赖如httptools,uvloop在支持的操作系统上能获得更好的性能。如果安装失败可以先尝试pip install uvicorn。至此你的“起跑线”就画好了Python 3.7一个激活的虚拟环境以及安装好的 fastapi 和 uvicorn。3. 第一个应用从“Hello World”到自动文档现在我们开始写代码。创建一个新文件比如叫main.py。别被“项目结构”吓到我们就从一个文件开始。3.1 最小可运行应用在main.py里输入以下代码from fastapi import FastAPI app FastAPI() app.get(/) def read_root(): return {Hello: World}四行代码一个完整的 API 就完成了。from fastapi import FastAPI: 导入框架。app FastAPI(): 创建应用实例。这个app对象是你整个应用的核心。app.get(“/“): 这是一个路径操作装饰器。它告诉 FastAPI当用户通过 HTTP GET 方法访问根路径/时就执行下面这个函数。def read_root(): …:路径操作函数。它直接返回一个 Python 字典FastAPI 会自动将其转换为 JSON 格式响应。3.2 启动服务器并访问保存文件在终端确保在虚拟环境下运行uvicorn main:app --reload这个命令需要解释一下main: 指你的 Python 文件main.py去掉.py后缀。app: 指在main.py文件中创建的FastAPI实例对象的名字即app FastAPI()里的app。--reload: 让服务器在代码更改后自动重启。仅在开发时使用生产环境必须去掉。看到类似Uvicorn running on http://127.0.0.1:8000的输出就说明服务器启动成功了。现在打开浏览器访问http://127.0.0.1:8000。你会看到{“Hello”: “World”}这个 JSON 响应。你的第一个 API 接口已经工作了。3.3 体验“王牌功能”交互式 API 文档这才是 FastAPI 十分钟入门最该看的亮点。访问以下两个地址http://127.0.0.1:8000/docs这是自动生成的 Swagger UI 交互式文档。你会看到一个非常漂亮的页面里面列出了你的/接口GET 方法。你可以直接点击 “Try it out”然后 “Execute”在页面上就完成了对接口的测试。无需 Postman 或 curl 命令。http://127.0.0.1:8000/redoc这是 ReDoc 生成的另一种风格的 API 文档更侧重于阅读。为什么这个功能至关重要对于后端开发者你再也不用手动维护一份可能过时的 API 文档。对于前端或测试同学他们可以自己打开/docs页面查看接口定义、数据类型并直接进行测试。这极大地减少了沟通成本是 FastAPI 提升团队协作效率的核心卖点。4. 进阶一步处理路径参数、查询参数和 POST 请求只会返回 “Hello World” 显然不够。我们快速增加几个最常用的功能感受一下 FastAPI 的简洁。4.1 路径参数修改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): return {item_id: item_id}注意read_item函数参数item_id: int。这里使用了类型提示int。FastAPI 会从 URL 路径中获取item_id例如/items/123。自动尝试将其转换为整数。如果用户传入“foo”这种无法转换为整数的字符串FastAPI 会自动返回一个清晰的422 错误并告诉你期望收到一个整数。这就是基于类型提示的自动数据验证。启动服务器如果已启动由于--reload会自动重启访问http://127.0.0.1:8000/items/123返回{“item_id”: 123}。访问http://127.0.0.1:8000/items/foo你会看到一个结构化的错误响应。4.2 查询参数查询参数就是 URL 中?后面的部分如?skip10limit20。在 FastAPI 中只需将非路径参数的函数参数定义为查询参数。from fastapi import FastAPI from typing import Optional app FastAPI() # ... 之前的代码 ... app.get(“/items/“) def read_items(skip: int 0, limit: int 10, q: Optional[str] None): # 模拟从数据库取数据 fake_items [{item_name: Foo}, {item_name: Bar}, {item_name: Baz}] results fake_items[skip : skip limit] if q: results [item for item in results if q.lower() in item[“item_name”].lower()] return {“results”: results, “query”: q}skip: int 0: 定义了查询参数skip类型是int默认值是0。如果请求中不传skip它就等于 0。limit: int 10: 同理。q: Optional[str] None: 定义了可选的查询参数q类型是可选字符串默认None。Optional需要从typing模块导入。访问http://127.0.0.1:8000/items/?skip1limit1qbar试试看。再打开/docs页面你会发现这个接口的文档已经自动更新清晰地列出了这三个查询参数及其类型和默认值。4.3 处理 POST 请求与请求体POST 请求通常用于创建数据数据放在请求体Body中通常是 JSON 格式。FastAPI 通过 Pydantic 模型来优雅地处理它。首先需要安装 Pydantic安装fastapi时通常已包含但明确一下pip install pydantic然后修改main.pyfrom fastapi import FastAPI from pydantic import BaseModel from typing import Optional app FastAPI() # 定义数据模型 class Item(BaseModel): name: str description: Optional[str] None price: float tax: Optional[float] None app.post(“/items/“) def create_item(item: Item): # 直接使用 item 对象它已经是一个验证过的 Pydantic 模型实例 item_dict item.dict() if item.tax: price_with_tax item.price item.tax item_dict.update({“price_with_tax”: price_with_tax}) return item_dictclass Item(BaseModel):定义了一个 Pydantic 模型。它清晰地描述了期望接收的数据结构必须有name(字符串) 和price(浮点数)description和tax是可选的。def create_item(item: Item):在路径操作函数中将参数item的类型声明为Item模型。FastAPI 会自动从请求体中读取 JSON。转换为相应的类型字符串转字符串数字转浮点数。进行数据验证检查必需字段是否存在类型是否正确。如果无效同样返回 422 错误。将验证后的数据提供给item参数。现在打开/docs页面找到POST /items/接口。点击 “Try it out”在 Request body 里输入{ “name”: “Foo”, “price”: 50.5, “description”: “A very nice item”, “tax”: 10.5 }点击 “Execute”你会看到返回了完整的 item 数据并自动计算了price_with_tax。如果你尝试发送一个缺少name字段或price是字符串的 JSON会立刻在文档页面上看到验证错误。5. 十分钟后的方向部署、异步与项目结构十分钟到了你的本地开发环境里应该已经有了一个能处理 GET/POST、带路径和查询参数、有自动验证和交互文档的 API。这已经覆盖了 80% 的日常 API 开发场景。接下来你可能会问1. 怎么部署到服务器你已经在用 Uvicorn 了。在生产环境去掉--reload并使用更多配置。例如使用多个工作进程处理请求uvicorn main:app --host 0.0.0.0 --port 80 --workers 4--host 0.0.0.0: 监听所有网络接口。--workers 4: 启动 4 个工作进程根据 CPU 核心数调整。对于 CPU 密集型或同步代码增加 workers 能提升并发。但注意如果你的代码是纯异步的见下一点并且 IO 操作很多少量 workers 甚至 1 个也可能足够因为异步本身就能处理大量并发连接。更常见的生产部署方式是搭配 Gunicorn一个 WSGI/ASGI 服务器管理器来管理 Uvicorn 工作进程或者使用 Docker 容器化部署。2. 异步async/await是必须的吗不是必须但强烈推荐。FastAPI 支持异步这是它高性能的重要原因之一。如果你的操作是 I/O 密集型的如读写数据库、调用外部 API、读写文件使用async def可以极大提升并发能力。app.get(“/async-demo”) async def read_async_data(): # 模拟一个耗时的 I/O 操作 await asyncio.sleep(1) return {“message”: “Data fetched”}使用async def时函数内部可以使用await调用其他异步函数。如果你的函数内部没有await表达式直接使用普通def也可以。但为了保持一致性和未来扩展对于 I/O 操作建议从一开始就养成使用async def的习惯。3. 项目结构怎么组织当你的应用超过一个文件时就需要考虑结构。一个常见的简单结构是your_project/ ├── app/ │ ├── __init__.py │ ├── main.py # 原来的 main.py现在可能只保留 FastAPI app 创建和路由汇总 │ ├── api/ │ │ ├── __init__.py │ │ ├── endpoints/ │ │ │ ├── __init__.py │ │ │ ├── items.py # 与 items 相关的路由 │ │ │ └── users.py # 与 users 相关的路由 │ │ └── deps.py # 依赖项如数据库会话 │ ├── core/ │ │ ├── config.py # 配置 │ │ └── security.py # 安全相关 │ ├── models/ │ │ └── schemas.py # Pydantic 模型 │ └── db/ │ └── session.py # 数据库连接 └── requirements.txt在app/main.py中你会导入各个模块的路由器APIRouter并将其包含到主app中。这样可以将不同功能模块解耦。4. 遇到常见错误怎么办422 Unprocessable Entity: 这是你未来最常见的错误。它意味着请求数据验证失败。第一时间去/docs页面确认接口期望的数据格式然后对比你发送的数据。99% 的情况是字段名拼错、类型不对比如字符串传了数字、或缺少了必需的字段。ImportError或ModuleNotFoundError: 检查虚拟环境是否激活依赖是否安装正确。运行pip list确认fastapi和uvicorn是否存在。地址已被占用 (Address already in use)默认端口 8000 被其他程序占用。使用--port 8001指定另一个端口。代码修改后服务器没重启检查启动命令是否包含--reload。如果没有需要手动停止并重启 Uvicorn。这十分钟的快速入门目的是让你用最小的代价感受到 FastAPI 的核心优势开发体验的流畅度。它通过 Python 类型提示把数据验证、序列化、文档生成这些繁琐工作自动化了。接下来你可以根据自己的需求深入探索数据库集成如 SQLAlchemy、Tortoise-ORM、身份认证OAuth2、JWT、中间件、后台任务等特性。记住官方文档https://fastapi.tiangolo.com/写得极其出色是你最好的进阶指南。