快速入门：安装与环境搭建
准备工作与虚拟环境
在开始使用 FastAPI 构建高性能 API 之前，建议使用一个隔离的 虚拟环境，以便集中管理依赖并避免版本冲突。虚拟环境有助于可重复部署，尤其在团队协作和持续集成场景下更为关键。
确保你使用的 Python 版本支持现代特性，通常推荐 Python 3.9 及以上，以充分利用类型提示和异步特性带来的性能收益。
常见的准备步骤包括创建、激活虚拟环境以及安装必要的包。下面是一个完整的命令集合，适用于大多数开发场景：
# Linux / macOS
python -m venv venv
source venv/bin/activate# Windows
python -m venv venv
venv\Scripts\activate# 安装 FastAPI 与异步服务器
pip install fastapi uvicorn
安装完成后，你就具备了开发 FastAPI 应用的基本环境，接下来可以开始编写你的第一个 API。
第一步：创建最简单的 FastAPI 应用
编写一个 Hello API
在一个新的文件中（如 app.py），创建一个 FastAPI 实例并暴露一个路由，返回一个简单的 JSON 响应。这是理解路由、请求和响应的基础入口点，也是后续逐步扩展的起点。
注意：FastAPI 的核心优势在于异步支持与自动生成文档，你也可以使用同步函数来实现简单接口。下面给出最小示例，帮助你快速上手。
from fastapi import FastAPIapp = FastAPI()@app.get("/")
def read_root():return {"message": "Hello, FastAPI!"}
启动应用后，FastAPI 会为你的服务自动生成交互式文档，方便你在浏览器中试验接口。常见的访问地址包括 http://127.0.0.1:8000/docs（Swagger UI）以及 http://127.0.0.1:8000/redoc。
uvicorn app:app --reload --port 8000数据模型与验证
Pydantic 数据模型
FastAPI 与 Pydantic 的结合让请求体数据具备强类型和校验能力。通过定义数据模型，API 会自动进行数据验证并返回清晰的错误信息，提升了开发效率与接口可靠性。
下面展示一个带字段校验的物品模型示例，包含名称、价格和库存状态三个字段：
from pydantic import BaseModelclass Item(BaseModel):name: strprice: floatin_stock: bool = True
将该模型应用到 POST 请求中，FastAPI 会自动将请求体解析为 Item 实例并执行校验；无效数据将返回 422 Unprocessable Entity 错误，帮助前端快速定位问题。
from fastapi import FastAPI
from pydantic import BaseModelapp = FastAPI()class Item(BaseModel):name: strprice: floatin_stock: bool = True@app.post("/items/")
def create_item(item: Item):return item
路由、请求体、路径参数与响应
路由与路径参数
通过 路由装饰器，你可以将函数绑定到不同的路径和 HTTP 方法，路径参数是设计清晰 API 的关键。合理的路径可以帮助开发者快速理解资源层级。
下面示例演示了带路径参数和查询参数的路由，以及如何返回结构化的响应：
from fastapi import FastAPI
from pydantic import BaseModel
from typing import Optionalapp = FastAPI()class Item(BaseModel):name: strprice: floatin_stock: bool = True@app.get("/items/{item_id}")
def read_item(item_id: int, q: Optional[str] = None):return {"item_id": item_id, "q": q}
你还可以通过请求体来接收更复杂的数据对象，如上面的 Item 模型，请求体的校验逻辑与返回结构将自动推断，确保前后端数据一致性。
@app.post("/items/")
def create_item(item: Item):return {"received": item}
依赖注入、中间件与文档化
依赖注入与中间件
FastAPI 的依赖注入（Depends）机制用于在路由之间复用公共逻辑，如鉴权、参数处理和数据库会话等，提升代码可维护性与测试性。
下面的示例展示如何把通用参数作为依赖项，在不同路由中共享同一组查询参数：
from fastapi import Depends, FastAPIapp = FastAPI()def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):return {"q": q, "skip": skip, "limit": limit}@app.get("/items/")
def read_items(commons: dict = Depends(common_parameters)):return commons
此外，中间件可用于在请求和响应之间执行自定义逻辑，例如添加自定义头部、日志记录或跨域处理。通过 FastAPI 的装饰器或 Starlette 的中间件接口，你可以灵活扩展功能。
from starlette.middleware.base import BaseHTTPMiddleware
from fastapi import FastAPI, Requestapp = FastAPI()@app.middleware("http")
async def add_header(request: Request, call_next):response = await call_next(request)response.headers["X-Custom-Header"] = "Powered by FastAPI"return response
通过上述机制，OpenAPI 文档也会自动更新，帮助你在开发、测试、部署各阶段快速可视化 API 结构，无需额外文档工作。
部署与性能优化
生产部署要点
FastAPI 的高性能来自于以下核心要素：异步 I/O、强类型提示、以及与现代 Python 生态的良好协作。要在生产环境获得最佳性能，通常将 ASGI 服务器组合用于部署，例如 Uvicorn 与 Gunicorn 的组合。
在正式上线前，请确保关闭调试模式、优化日志输出、并合理配置工作进程数以充分利用多核 CPU。下面给出常见的生产部署命令：
# 使用 Gunicorn 搭配 UvicornWorker
gunicorn -k uvicorn.workers.UvicornWorker -w 4 -t 120 main:app
如果是在本地快速迭代开发，可以继续使用 uvicorn --reload，这样每次修改代码都会自动重载，提升开发效率。
uvicorn main:app --reloadFastAPI 的自动文档能力在生产环境也非常有用——你可以直接通过文档界面向团队展示 API 结构，帮助缩短沟通成本，提升交付透明度，文档站点随代码变动而自动更新。
