FastAPI带参路由指定响应媒体类型失效 返回application/json问题

这个现象和路由是否带参没有直接关联，核心是未做类型、来源注解的裸参数会触发FastAPI的自动参数校验逻辑：

• 你在/a、/b路由中声明的a、b参数没有指定参数类型，也没有用Query/Body/File等声明参数来源，FastAPI会默认将其识别为必传查询参数
• 当你发起请求时没有携带对应参数，请求根本不会进入你写的路由函数逻辑，会被FastAPI的前置校验层直接拦截，返回422参数校验错误响应，这个响应用的是你全局配置的ORJSONResponse，媒体类型自然是application/json
• 无参的/working路由不存在参数校验环节，请求能正常进入路由逻辑，你直接返回了构造好的StreamingResponse实例，因此能正常返回image/jpeg类型的图片流

你可以手动给/a接口发带a参数的请求（比如POST /a?a=test），就会发现请求能正常返回图片，和/working表现一致。

另外你写的/b路由还有个逻辑问题：直接返回路径字符串不会被自动识别为文件路径，即使参数校验通过，也不会正常返回图片，需要显式构造FileResponse实例返回。

1. 所有路由入参必须显式声明类型和参数来源，避免非预期的校验拦截：
   • 必传参数要明确标注来源，可选参数要设置默认值
   • 如果你不需要FastAPI自动做参数校验，可以直接将入参类型标注为Request，从请求对象中自行提取参数
2. 返回文件/流类响应时，建议直接显式构造对应Response实例返回，不要依赖response_class自动包装，避免配置不生效。

修复后的可运行代码示例：

from io import BytesIO
from fastapi import FastAPI, Request
from fastapi.responses import ORJSONResponse, StreamingResponse, FileResponse


app = FastAPI(default_response_class=ORJSONResponse)


@app.post("/working", response_class=FileResponse)
async def send_w():
    with open("/tmp/test/b.jpg", "rb") as f:
        image = BytesIO(f.read())
    image.seek(0)
    return StreamingResponse(image, media_type="image/jpeg")


# 示例1：声明a为可选查询参数，不传也不会触发422错误
@app.post("/a", response_class=FileResponse)
async def send_a(a: str | None = None):
    with open("/tmp/test/b.jpg", "rb") as f:
        image = BytesIO(f.read())
    image.seek(0)
    return StreamingResponse(image, media_type="image/jpeg")


# 示例2：直接接收Request对象，完全自行处理参数，无自动校验
@app.post("/a-no-validate", response_class=FileResponse)
async def send_a_no_validate(request: Request):
    # 如需取参数可自行从request对象提取：a = request.query_params.get("a")
    with open("/tmp/test/b.jpg", "rb") as f:
        image = BytesIO(f.read())
    image.seek(0)
    return StreamingResponse(image, media_type="image/jpeg")


# 修复/b路由的逻辑问题，显式返回FileResponse实例
@app.post("/b", response_class=FileResponse)
async def send_b(b: str | None = None):
    return FileResponse("/tmp/test/b.jpg", media_type="image/jpeg")

路由上的response_class配置仅在路由函数返回普通Python对象（非Response实例）时才会生效，用来将返回值序列化包装为对应类型的响应；如果你直接返回StreamingResponse/FileResponse等Response实例，会直接使用该实例的媒体类型、内容配置，不受response_class参数影响。

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