FastAPI 路由模块化与 APIRouter 入门教程

欢迎来到Web开发的世界！

如果你刚学完Python基础，但对Web开发一窍不通，别担心！FastAPI是一个超级适合初学者的Python Web框架，它能让你快速体验到创建网站的乐趣。今天，我们要探索一个很酷的功能：路由模块化，以及它的好帮手 APIRouter。

什么是路由？先来个生活类比

想象一下，你开了一家咖啡馆。顾客通过不同的门（比如前门、后门）进入，去不同的区域（比如吧台、座位区）。在Web开发中，路由就像是咖啡馆的入口和内部路径，它告诉用户（比如浏览器）当访问特定网址（如 /menu）时，应该展示什么内容。

• 简单例子：在FastAPI中，定义一个路由就像告诉程序：“嘿，如果有人访问 /hello，就回复‘你好！’”。

为什么需要模块化？就像整理房间

如果你的咖啡馆只有一个大房间，所有东西都堆在一起，管理和找东西会很难。同样，在Web应用中，如果所有路由都写在一个文件里，代码会变得很长、很乱。模块化就是把相关路由分组到不同的“房间”里，比如把用户相关路由放一个文件，商品相关放另一个。这样做的好处是：

• 易于管理：代码更清晰，不容易出错。
• 便于团队合作：不同开发者可以负责不同模块。
• 快速上手：你只需要关注一个模块，不用被整个项目吓到。

认识 APIRouter：你的模块化小助手

在FastAPI中，APIRouter 是专门用来创建路由模块的工具。你可以把它想象成一个小型FastAPI应用，但它不会自己运行，需要被添加到主应用中。

安装FastAPI（如果还没安装）

在开始前，确保你已经安装了FastAPI和Uvicorn（一个ASGI服务器，用来运行应用）。打开终端，运行：

pip install fastapi uvicorn

动手实践：创建你的第一个模块化路由

让我们从零开始，一步步创建一个小项目，模拟一个简单的博客应用。

步骤1：导入所需模块

创建一个新文件夹，比如 fastapi_tutorial，在里面新建一个Python文件，命名为 main.py。然后，我们导入必要的模块：

# main.py
from fastapi import FastAPI
from fastapi import APIRouter  # 导入APIRouter

步骤2：创建APIRouter实例

在 main.py 中，添加以下代码：

# 创建一个名为user_router的APIRouter实例，用于用户相关路由
user_router = APIRouter()

# 创建一个名为post_router的APIRouter实例，用于博客文章相关路由
post_router = APIRouter()

步骤3：在路由器上定义路由

现在，我们在每个路由器上添加一些简单的路由。先来一个“成功时刻”——定义第一个路由并看到它工作！

# 在user_router上定义一个路由：访问 /users 返回用户列表
@user_router.get("/users")
async def get_users():
    return [{"id": 1, "name": "小明"}, {"id": 2, "name": "小红"}]

# 在post_router上定义一个路由：访问 /posts 返回文章列表
@post_router.get("/posts")
async def get_posts():
    return [{"id": 1, "title": "我的第一篇博客"}, {"id": 2, "title": "FastAPI教程"}]

步骤4：创建主FastAPI应用并包含路由器

我们需要一个主应用来“组装”这些路由器。添加以下代码到 main.py：

# 创建FastAPI应用实例
app = FastAPI(title="我的博客应用")

# 将路由器包含到主应用中，并指定前缀（可选，让路由更清晰）
app.include_router(user_router, prefix="/api/users", tags=["用户管理"])
app.include_router(post_router, prefix="/api/posts", tags=["博客文章"])

• 前缀：比如 /api/users/users 会变成 /api/users（这里例子中，前缀是 /api/users，路由是 /users，所以总路径是 /api/users/users，但实际上路由是 /users，所以总路径是 /api/users/users 是错误的。让我修正一下：在 user_router 上定义的路由是 /users，当使用 prefix="/api/users" 时，总路径会变成 /api/users/users。为了更直观，我们可以调整前缀或路由。假设我们想让 /api/users 访问用户列表，那么可以设置 prefix="/api"，然后路由是 /users。为了简单，让我们调整一下。

修正后的步骤：

在 main.py 中：

# 导入模块
from fastapi import FastAPI, APIRouter

# 创建路由器
user_router = APIRouter(prefix="/users", tags=["用户管理"])
post_router = APIRouter(prefix="/posts", tags=["博客文章"])

# 定义路由
@user_router.get("/")
async def get_users():
    return [{"id": 1, "name": "小明"}, {"id": 2, "name": "小红"}]

@post_router.get("/")
async def get_posts():
    return [{"id": 1, "title": "我的第一篇博客"}, {"id": 2, "title": "FastAPI教程"}]

# 创建主应用
app = FastAPI(title="我的博客应用")

# 包含路由器，并指定总前缀
app.include_router(user_router, prefix="/api")
app.include_router(post_router, prefix="/api")

这样，访问 /api/users/ 会返回用户列表，访问 /api/posts/ 会返回文章列表。更清晰！

步骤5：运行应用并体验成功时刻

保存 main.py 文件。在终端中，导航到你的项目文件夹，运行：

uvicorn main:app --reload

• main:app 表示从 main.py 文件导入 app 实例。
• --reload 开启热重载，这样你修改代码后会自动重启服务器。

现在，打开浏览器，访问 http://127.0.0.1:8000/api/users/，你应该能看到JSON格式的用户列表！再试试 http://127.0.0.1:8000/api/posts/。太棒了！你的第一个模块化Web应用跑起来了！

模块化的好处：实际例子

假设你的博客应用要添加评论功能，你只需创建另一个路由器，比如 comment_router，定义评论相关路由，然后包含到主应用中。代码保持整洁，易于扩展。

# 新建一个文件 comments.py，或直接在main.py中添加
comment_router = APIRouter(prefix="/comments", tags=["评论管理"])

@comment_router.get("/")
async def get_comments():
    return [{"id": 1, "text": "好文章！"}, {"id": 2, "text": "学习了！"}]

# 在主应用中包含
app.include_router(comment_router, prefix="/api")

然后重启服务器（如果是热重载，它会自动更新），访问 http://127.0.0.1:8000/api/comments/，看看新功能！

总结与下一步

恭喜你！你已经学会了：

• 路由是什么：Web应用的入口点。
• 为什么模块化：让代码更有组织，像整理房间一样。
• 如何使用APIRouter：导入、创建实例、定义路由、包含到主应用。

记住，实践是最好的老师。试着创建更多路由模块，比如登录、注册功能，或者整合数据库（这可能是进阶话题）。FastAPI文档很友好，随时查阅！

小挑战：创建一个新路由器 auth_router，定义一个路由 /login，返回一个简单的登录消息。然后包含到你的应用中，看看它如何工作！

如果你遇到问题，别担心——Web开发路上，每个错误都是学习的机会。加油，继续探索吧！