如何为多个FastAPI端点定义统一的默认参数签名

我正在使用FastAPI框架，目前有20多个结构相似的端点，示例代码如下：

from fastapi import Request
from typing import Optional

@app.get("/REDS/")
def query_REDS(
    request: Request,
    lighter: Optional[bool] = False,
    darker: Optional[bool] = False,
    inverse: Optional[bool] = False,
    amount: Optional[int] = 10
):
    pass  # 业务逻辑实现

@app.get("/BLUES/")
def query_BLUES(
    request: Request,
    lighter: Optional[bool] = False,
    darker: Optional[bool] = False,
    inverse: Optional[bool] = False,
    amount: Optional[int] = 10
):
    pass  # 业务逻辑实现

@app.get("/GREENS/")
def query_GREENS(
    request: Request,
    lighter: Optional[bool] = False,
    darker: Optional[bool] = False,
    inverse: Optional[bool] = False,
    amount: Optional[int] = 10
):
    pass  # 业务逻辑实现

这些端点在Swagger UI中的展示符合预期，实际配置会通过request传入并手动解析。但每次需要更新这些端点的参数签名时，我需要在约20个不同的位置进行修改，效率极低。

我曾尝试使用Pydantic的BaseModel定义输入模型：

from pydantic import BaseModel
from fastapi import Request
from typing import Optional

class Arguments(BaseModel):
    lighter: Optional[bool] = False
    darker: Optional[bool] = False
    inverse: Optional[bool] = False
    amount: Optional[int] = 10

@app.get("/REDS/")
def query_REDS(
    request: Request,
    arguments: Arguments
):
    pass  # 业务逻辑实现

# 其他端点类似...

但这种方式并不符合我的需求：一是GET请求中使用请求体的做法不被推荐，且并非所有客户端都支持；二是在Swagger UI中的交互体验不佳。

请问是否存在一种方法，可以为多个不同的FastAPI端点定义统一的默认参数签名？

当然有完美的解决办法！FastAPI的依赖注入（Depends）就是专门用来处理这类重复参数/逻辑的场景，既能保持GET请求的规范，又能让Swagger UI正常展示，还能大幅降低维护成本。下面给你两种实用方案：

方案一：用Depends封装通用查询参数 #

这是最直接的方法，把你重复的参数逻辑打包成一个依赖函数，所有端点直接引用就行：

1. 定义依赖函数（两种风格可选） #

风格1：纯函数式（简单直接）

把通用参数都放在一个函数里，FastAPI会自动把这些参数解析为URL查询参数，还能顺便加一些统一的参数校验：

from fastapi import Depends, Request
from typing import Optional

def get_color_query_args(
    lighter: Optional[bool] = False,
    darker: Optional[bool] = False,
    inverse: Optional[bool] = False,
    amount: Optional[int] = 10
):
    # 这里可以加统一的参数校验，比如限制amount不能小于1
    if amount is not None and amount < 1:
        amount = 1
    # 返回整理后的参数，用字典或者自定义类都可以
    return {
        "lighter": lighter,
        "darker": darker,
        "inverse": inverse,
        "amount": amount
    }

风格2：结合Pydantic模型（类型安全+自动校验）

如果你喜欢用Pydantic做类型检查和验证，也可以把参数定义成模型，再用Depends包装：

from pydantic import BaseModel
from fastapi import Depends, Request, Query
from typing import Optional

class ColorQueryArgs(BaseModel):
    lighter: Optional[bool] = False
    darker: Optional[bool] = False
    inverse: Optional[bool] = False
    # 用Query给amount加验证规则，比如最小值1
    amount: Optional[int] = Query(10, ge=1)

def get_color_query_args(args: ColorQueryArgs = Depends()):
    return args

2. 在端点中引用依赖 #

现在每个端点只需要一行代码就能引入所有通用参数，不用再重复写长长的参数列表：

@app.get("/REDS/")
def query_REDS(
    request: Request,
    query_args = Depends(get_color_query_args)
):
    # 业务逻辑里直接用query_args.lighter、query_args.amount（模型风格）
    # 或者query_args["lighter"]（字典风格）
    pass

@app.get("/BLUES/")
def query_BLUES(
    request: Request,
    query_args = Depends(get_color_query_args)
):
    pass

# 其他20个端点都这么写就行

为什么这个方案好用？ #

• 完全符合GET规范：所有参数都是URL查询参数，没有请求体的问题，任何客户端都能正常调用。
• Swagger体验和原来一样：FastAPI会自动把依赖里的参数渲染到Swagger UI，和你手动写参数的展示效果完全一致，支持直接在界面上测试。
• 维护成本极低：以后要改参数（比如加个saturation参数、调整默认值），只需要修改get_color_query_args或者ColorQueryArgs，所有端点自动同步更新，再也不用改20遍了！

方案二：批量注册端点（适合业务逻辑高度相似的场景） #

如果你的20个端点业务逻辑也差不多，甚至可以直接批量注册，连端点函数都不用重复写：

from fastapi import FastAPI, Request, Depends

app = FastAPI()

# 先定义好通用的依赖和处理逻辑
def get_color_query_args(...):
    # 和上面一样的定义
    pass

def handle_color_request(request: Request, query_args = Depends(get_color_query_args)):
    # 从请求路径里提取颜色标识，比如"/REDS/"提取"REDS"
    color = request.url.path.strip("/").upper()
    # 这里写统一的业务逻辑，或者根据color做分支处理
    return {"color": color, "parameters": query_args}

# 循环注册所有颜色端点
for color in ["REDS", "BLUES", "GREENS", "YELLOWS", "ORANGES"]:
    app.add_api_route(f"/{color}/", handle_color_request, methods=["GET"])

这种方式直接把重复的端点函数也干掉了，适合所有端点逻辑大同小异的情况。

内容的提问来源于stack exchange，提问作者Jared DuPont