FastAPI 基本路由：从零开始构建你的第一个 API 接口
在现代 Web 开发中，后端服务的构建效率和稳定性越来越受到重视。FastAPI 作为一个基于 Python 的现代 Web 框架，凭借其高性能、自动生成文档和强大的类型提示支持，迅速成为许多开发者构建 RESTful API 的首选工具。而掌握 FastAPI 基本路由，是开启 FastAPI 之旅的第一步。
想象一下，你正在搭建一座城市交通网络。API 路由就像城市中的道路规划，每一个 URL 路径（如 /users、/products）都是通往不同功能区域的入口。FastAPI 通过清晰的路由机制，让你能精准地将请求导向对应的处理函数，实现“按路走人”的高效运作。
本文将带你一步步理解 FastAPI 基本路由 的核心概念，通过实际代码示例，从最简单的路径定义到参数处理，手把手带你构建一个完整的 API 接口系统。
安装与环境准备
在开始之前，你需要确保本地环境已安装 Python 3.7 或更高版本。推荐使用虚拟环境来隔离项目依赖，避免冲突。
打开终端，执行以下命令安装 FastAPI 及其依赖的 ASGI 服务器（如 Uvicorn）：
pip install fastapi uvicorn
安装完成后，你可以通过以下命令验证是否安装成功：
python -c "from fastapi import FastAPI; print(FastAPI())"
如果输出类似 <FastAPI> 的对象，说明安装成功。
创建第一个 FastAPI 应用
现在我们来创建一个最简单的 FastAPI 应用，它将返回一个欢迎消息。
新建一个文件，命名为 main.py，并输入以下代码：
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
# 返回一个字典，FastAPI 会自动将其序列化为 JSON 格式
return {"message": "欢迎来到 FastAPI 的世界！"}
代码详解
from fastapi import FastAPI：导入 FastAPI 框架的核心类。app = FastAPI()：创建一个 FastAPI 应用实例，后续所有路由都将绑定到这个实例上。@app.get("/")：这是一个装饰器，用来定义一个 HTTP GET 请求的路由。/表示根路径。def read_root():：这是一个普通的 Python 函数，当请求匹配该路径时，自动调用。return {"message": "欢迎来到 FastAPI 的世界！"}：返回一个字典，FastAPI 会自动将其转换为 JSON 响应。
启动服务：
uvicorn main:app --reload
main:app：表示模块名（main.py）和应用对象名（app）。--reload：开启热重载，代码修改后自动重启服务，开发时非常实用。
访问浏览器，打开 http://127.0.0.1:8000，你将看到：
{"message": "欢迎来到 FastAPI 的世界！"}
这就是你的第一个 FastAPI 接口，简洁而强大。
路由路径参数详解
在实际项目中，我们通常需要根据路径中的动态部分来获取数据。比如 /users/123 中的 123 是用户 ID。FastAPI 支持路径参数（Path Parameters），让你轻松提取这些信息。
示例：获取用户信息
修改 main.py 文件，添加一个获取用户详情的路由：
from fastapi import FastAPI, Path
app = FastAPI()
@app.get("/users/{user_id}")
def get_user(user_id: int = Path(..., description="用户的唯一标识 ID")):
# user_id 是路径中的参数，FastAPI 会自动解析并类型检查
# Path(...) 表示该参数是必填的
# description 用于生成 API 文档的说明
return {"user_id": user_id, "name": f"用户 {user_id}"}
代码说明
@app.get("/users/{user_id}")：{user_id}是一个路径参数占位符，匹配任意数字或字符串。user_id: int：声明参数类型为整数，FastAPI 会自动验证输入是否为合法整数。Path(..., description=...)：Path是 FastAPI 提供的类型提示工具，用于定义路径参数的元信息。...表示必填，description用于文档生成。
测试：访问 http://127.0.0.1:8000/users/101，返回：
{"user_id": 101, "name": "用户 101"}
如果访问 http://127.0.0.1:8000/users/abc，FastAPI 会立即返回错误提示，因为 abc 不是整数，无需手动写判断逻辑。
查询参数与请求体处理
除了路径参数，我们还经常需要通过查询字符串（Query String）或请求体（Request Body）传递数据。FastAPI 通过类型提示和依赖注入，让这些操作变得极其简单。
查询参数示例
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items")
def get_items(q: str = Query(None, min_length=1, max_length=50, description="搜索关键词")):
# q 是查询参数，如 ?q=apple
# Query(None) 表示该参数可选
# min_length 和 max_length 用于验证输入长度
return {"search": q}
访问：http://127.0.0.1:8000/items?q=苹果
返回：
{"search": "苹果"}
请求体示例（POST 请求）
from fastapi import FastAPI, Body
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
price: float
description: str = None
@app.post("/items")
def create_item(item: Item = Body(..., embed=True)):
# item 是一个 Item 实例，FastAPI 会自动解析 JSON 并验证字段
# embed=True 表示将数据嵌套在 JSON 对象中
return {"item": item.dict()}
发送 POST 请求（使用 curl）：
curl -X POST http://127.0.0.1:8000/items \
-H "Content-Type: application/json" \
-d '{"name": "笔记本电脑", "price": 5999.0, "description": "高性能轻薄本"}'
返回：
{"item": {"name": "笔记本电脑", "price": 5999.0, "description": "高性能轻薄本"}}
路由分组与模块化设计
随着项目规模扩大，将所有路由写在一个文件中会变得难以维护。FastAPI 支持路由分组，通过 APIRouter 实现模块化设计。
创建独立的路由模块
新建文件 routers/users.py：
from fastapi import APIRouter
router = APIRouter()
@router.get("/users")
def list_users():
return {"users": ["张三", "李四", "王五"]}
@router.get("/users/{user_id}")
def get_user(user_id: int):
return {"user_id": user_id, "name": f"用户 {user_id}"}
在主应用中注册路由
修改 main.py：
from fastapi import FastAPI
from routers.users import router
app = FastAPI()
app.include_router(router, prefix="/api/v1")
现在访问 http://127.0.0.1:8000/api/v1/users，即可获取用户列表。
自动文档生成：Swagger UI 与 ReDoc
FastAPI 最大的亮点之一是自动为你的 API 生成交互式文档。你无需手动编写文档，只需写代码，文档自动生成。
启动服务后，访问：
http://127.0.0.1:8000/docs：自动生成的 Swagger UI 文档，支持直接测试接口。http://127.0.0.1:8000/redoc：ReDoc 风格的文档页面，更简洁美观。
这些文档会自动包含你定义的路径参数、查询参数、请求体结构和返回示例，极大提升开发协作效率。
总结：掌握 FastAPI 基本路由，开启高效开发之路
通过本文，你已经掌握了 FastAPI 基本路由 的核心能力：路径定义、路径参数、查询参数、请求体处理、模块化路由以及自动文档生成。这些功能共同构成了一个强大而灵活的 API 开发基础。
FastAPI 不仅让你写代码更简单，还通过类型提示和自动验证，提前发现潜在错误，减少运行时异常。它的设计理念是“少写代码，多做事情”，非常适合构建高可用、高效率的后端服务。
无论你是初学者还是有经验的开发者，只要掌握了这些基础，就能快速上手构建真实项目。接下来，你可以尝试集成数据库、添加认证机制、部署到服务器，逐步打造完整的应用系统。
记住：一个清晰的路由设计，是优秀 API 的起点。从今天开始，用 FastAPI 基本路由，为你的项目打下坚实基础。