在 Python Web 开发领域，FastAPI 已成为近年来增长最快的框架之一。截至 2025 年，其 GitHub Star 数已超过 80k。
FastAPI 凭借类型提示驱动、自动生成文档、异步高性能三大核心特性，迅速成为构建 REST API 和微服务的首选框架。而这一切的起点，就是 路由（Routing） 。
本文将从路由的基本概念讲起，逐步深入到模块化路由设计，最后探讨 FastAPI 在实际项目中的典型应用场景。
一、什么是路由？
简单来说，路由就是“URL 地址”和“处理函数”之间的对应关系。
当用户访问 http://localhost:8000/users/123 时，FastAPI 需要知道应该调用哪个函数来处理这个请求；当访问 http://localhost:8000/products/456 时，又应该调用另一个函数。这个映射关系，就是路由。
在 FastAPI 中，路由是通过装饰器（Decorator） 来定义的。FastAPI 提供了 @app.get()、@app.post()、@app.put()、@app.delete() 等装饰器，分别对应不同的 HTTP 方法。
二、FastAPI 基本路由的三种参数类型
在 FastAPI 的路由处理中，请求参数主要分为三类：
1. 路径参数（Path Parameters）
路径参数位于 URL 路径中，用于指向唯一的、特定的资源。
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: str):
return {"item_id": item_id}
当访问 http://localhost:8000/items/123 时，item_id 会自动绑定为 "123"。
FastAPI 还支持使用 Path 函数对路径参数进行额外校验：
from fastapi import FastAPI, Path
app = FastAPI()
@app.get("/book/{id}")
async def get_book(
id: int = Path(…, ge=1, le=100, description="书籍ID，取值在1-100之间")
):
return {"id": id, "title": f"这是第{id}本书"}
2. 查询参数（Query Parameters）
查询参数位于 URL 的 ? 之后，用于对资源集合进行过滤、排序、分页等操作。
@app.get("/items/")
async def list_items(skip: int = 0, limit: int = 10):
return {"skip": skip, "limit": limit}
访问 /items/?skip=5&limit=20 时，skip=5、limit=20 会自动传入函数。
3. 请求体（Request Body）
请求体位于 HTTP 请求的消息体中，用于创建或更新资源时携带大量数据（通常为 JSON 格式）。
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
@app.post("/items/")
async def create_item(item: Item):
return {"item_name": item.name, "price": item.price}
FastAPI 会基于 Pydantic 模型自动完成请求体的校验、序列化和文档生成。
三、模块化路由：APIRouter 的工程化实践
当项目规模扩大，把所有路由写在 main.py 一个文件里会导致代码臃肿、难以维护。例如一个电商系统可能有用户、商品、订单、购物车等多个模块，全部塞进一个文件可能达到几千行代码。
FastAPI 提供了 APIRouter 来解决这个问题。APIRouter 是一个轻量级的路由容器，允许开发者将相关功能的路由逻辑封装在独立模块中，再通过主应用统一挂载。
1. 创建独立路由模块
# routers/users.py
from fastapi import APIRouter
router = APIRouter(
prefix="/users", # 统一路径前缀
tags=["用户管理"] # Swagger 文档分组标签
)
@router.get("/all")
async def get_all_users():
return [{"id": 1, "name": "张三"}, {"id": 2, "name": "李四"}]
@router.get("/{user_id}")
async def get_user(user_id: int):
return {"id": user_id, "name": f"用户{user_id}"}
# routers/products.py
from fastapi import APIRouter
router = APIRouter(prefix="/products", tags=["商品管理"])
@router.get("/all")
async def get_all_products():
return [{"id": 1, "name": "手机"}, {"id": 2, "name": "电脑"}]
2. 在主应用中挂载路由模块
# main.py
from fastapi import FastAPI
from routers import users, products
app = FastAPI(title="我的API项目")
app.include_router(users.router)
app.include_router(products.router)
3. 模块化带来的工程优势
采用 APIRouter 架构后，可以获得以下优势：
逻辑隔离：每个模块独立一个文件，职责清晰
团队协作：不同团队可独立开发各自模块，避免代码冲突
依赖注入优化：支持模块级依赖管理，减少重复声明
便于版本控制：可通过 prefix 轻松实现 API 版本管理，如 /v1/products 与 /v2/products 并行维护
热更新支持：模块级路由可独立更新，无需重启整个服务
某电商项目实践数据显示，采用 APIRouter 架构后，代码重构时间从平均 8.2 小时/次降至 2.1 小时。
四、自动生成 API 文档
FastAPI 最具生产力的特性之一是自动生成 API 文档。无需额外编写文档，启动服务后即可访问：
/docs：Swagger UI 交互式文档，支持在线调试
/redoc：ReDoc 风格的 API 文档
uvicorn main:app –reload
# 访问 http://127.0.0.1:8000/docs
五、FastAPI 的典型应用场景
FastAPI 凭借高性能（可媲美 Node.js/Go）、原生异步支持和自动文档等特性，在以下场景中展现出独特优势：
1. 机器学习模型服务（AI/ML API 部署）
FastAPI 被广泛用于在生产环境中部署机器学习模型。它能与 TensorFlow、PyTorch、Hugging Face 等库良好集成，支持异步推理管道，实现最大吞吐量。
典型案例：
将 scikit-learn 模型封装为 Web 服务，接收外部请求并返回预测结果
基于 FastAPI 将 LoRA 微调后的大模型暴露为标准 API 接口
金融数据预测项目中，利用 FastAPI 处理大量并发请求，确保高流量下仍能提供实时价格信息
2. 大模型与 AI Agent 应用
FastAPI 已成为构建 LLM 应用后端的事实标准。无论是 RAG（检索增强生成）系统、AI Agent 还是智能客服，FastAPI 的异步路由都能实现从 HTTP 请求到模型推理的全链路非阻塞通信。
典型案例：
基于 FastAPI + Azure OpenAI + Azure AI Search 构建 RAG 应用
FastAPI + LangChain 构建智能招聘系统
企业售后客服 Agent，集成 RAG、Function Calling、Redis 和向量数据库
3. 微服务架构
FastAPI 天生适合微服务架构，在实现模块化部署和独立扩展方面表现优异。
典型场景：
高并发 API 服务：如支付网关、用户认证中台
数据密集型应用：如日志分析、实时推荐系统
API 网关：处理请求路由、负载均衡和认证鉴权
某金融风控系统采用 FastAPI 后，API 响应时间从 300ms 降至 80ms，代码量减少 40%。
4. 实时应用与 WebSocket
FastAPI 原生支持 WebSocket，其异步模型使得单个 worker 可以处理数千个并发 WebSocket 连接。
典型场景：
在线客服系统
即时聊天应用
实时数据仪表板（结合 MongoDB Change Streams 推送实时更新）
协作工具中的实时交流模块
5. 物联网（IoT）与边缘计算
FastAPI 的轻量级和异步特性使其成为 IoT 网关和边缘计算的理想选择。
典型场景：
工业物联网网关，管理多台 MQTT 设备并提供 HTTP 接口
实时环境监测系统，高频传感器数据采集与告警
医疗 IoT 设备集成，通过 BLE 通信提供 REST API 服务
离线救灾协调系统，在 Raspberry Pi 上运行 FastAPI 提供 WiFi 热点服务
6. 企业级后台管理系统
FastAPI 被广泛用于构建企业级后端管理系统，结合分层架构实现高性能、强安全性和易维护性。
典型场景：
电商平台后台（商品管理、订单管理、用户管理、数据分析）
企业工商信息大数据查询系统
RBAC 权限管理系统
多租户 SaaS 平台
