Skip to content

路由

4.1 URL介绍

URL（Uniform Resource Locator，统一资源定位符）是互联网上用来标识和定位某个资源（网页、图片、文件、API 等）的地址，简单来说就是用户请求的网址。

用户通过URL网址找到对应后端服务，进而执行对应的后端业务逻辑。

一个完整的URL地址格式如下:

1
http://IP或域名:端口号/请求路径?参数

例如：

1
http://127.0.0.1:8000/hello/python
  • http://
    • 代表请求协议（Scheme）
    • 在浏览器中通常会省略
  • 127.0.0.1
    • 后端服务器在网络上的地址。
    • 可以是域名(如 www.heima.cn)，也可以是 IP 地址（如 192.168.1.1）
  • :8000
    • 指定服务的端口
    • 端口号的范围从0到65535，可以由后端自己指定
  • /hello/python
    • 代表请求路径
    • 在后端代码中，通过匹配不同路径来执行不同函数的逻辑，也就是路由匹配

4.2 路由介绍

Web 路由（Web Routing） 指的是 把用户请求的 URL 映射到后端对应的处理逻辑（函数/方法/控制器） 的过程。 换句话说：当用户访问 http://127.0.0.1:8000/hello/python 时，框架通过 路由规则 判断应该调用哪个函数来处理这个请求。

FastAPI的路由定义基于 Python 的装饰器模式，使用 @app.get(), @app.post() 等装饰器将 HTTP 方法与特定的路径操作函数关联起来。

书写格式:

1
@app.get("路径")

不同的 HTTP 方法被赋予特定的语义。

  • GET 方法用于请求数据的检索 @app.get()；
  • POST 方法则用于提交新数据，通常是为了创建新的资源 @app.post() ；
  • PUT、DELETE 和 PATCH 则分别用于资源的完全替换、删除或部分更新 @app.put()。

在设计 API 时，必须考虑请求体的传输，请求体主要用于那些需要向服务器发送数据的操作。

HTTP 方法与典型路由行为

HTTP 方法 典型用途 是否支持请求体 Request Body
GET 检索资源 否
POST 创建新资源 是 (常见)
PUT 替换更新资源 是
DELETE 删除资源 否

4.3 路由编写

编写一个的路由，实现自己的业务

1
2
3
@app.get("/heima")
async def func():
    return {"message": "heima1"}

image-20250920204649529

image-20251011120044088

注意：每次增加修改python代码后需要重启服务!!!

4.4 APIRouter 模块化路由

在FastAPI中组织路由，通常有两种主流方式：

  1. 直接在主应用实例上定义路由，适合简单场景,如4.3中的方式；

  2. 使用 APIRouter 模块化地组织路由，这在大型项目中更高效。下面这个表格汇总了它们的主要特点和适用场景：

特性 直接应用路由 APIRouter 模块化路由
适用场景 简单应用，路由数量少 中大型项目，需要分模块
代码结构 所有路由集中在主文件 路由按模块拆分，结构清晰
可维护性 低，不易维护 高，易于维护和扩展
团队协作 差，容易产生冲突 好，不同开发者负责不同模块
前缀/Tags 需手动为每个路由添加 可在路由器级别统一设置 prefix 和 tags

当项目规模增长时，强烈建议使用 APIRouter 将路由分模块管理。核心步骤是创建路由实例、定义路由，最后在主应用中挂载。

使用方法：

  1. 创建 APIRouter 实例 在模块（例如 routers/users.py）中导入 APIRouter 并创建实例。你可以配置：

    • prefix：为该模块下所有路由添加统一路径前缀，如 prefix="/users"。
    • tags：在自动生成的 API 文档中对接口进行分组。
    1
2
3
4
5
6
7
    from fastapi import APIRouter

# 创建路由实例
router = APIRouter(
    prefix="/users",
    tags=["users"],
)

  2. 定义路由 使用 @router.get("/") 这样的装饰器定义路径操作。

    1
2
3
4
5
    # 定义路由处理函数
@router.get("/")
async def get_users():

    return {"message": "获取所有用户"}

  3. 在主应用中挂载路由 在主应用（如 main.py）中，使用 app.include_router() 方法将各个模块的路由器导入并包含进

    1
2
3
4
    from fastapi import FastAPI
from routers import users
app = FastAPI()
app.include_router(users.router)

image-20251011185959398

image-20251011190323971