FastAPI中GET请求接收URL作为路径参数出现404的解决方法

问题原因 #

你遇到的404是因为FastAPI默认的路径参数{image_name}只会匹配到第一个斜杠（/）之前的内容。当传入包含//的完整图片URL时，即便URL被编码，路由匹配逻辑仍会把https%3A当作image_name的内容，剩余部分被识别为新的路径段，导致找不到对应路由，最终返回404。

方案一：使用通配符路径参数 #

如果坚持用路径参数传递，可修改路由定义，让image_name能捕获包含斜杠的完整路径。FastAPI支持{参数名:path}的语法实现这一点：

from fastapi import FastAPI

app = FastAPI()

@app.get("/v1/image/{image_name:path}")
async def image_resize(image_name: str):
    # image_name会自动完成URL解码，直接得到原始图片URL
    image_file_name = image_name.split("/")[-1]
    return {"image_url": image_name, "file_name": image_file_name}

这种写法会让image_name捕获/v1/image/之后的所有内容（包括斜杠），无需手动处理%3A或%2F这类编码字符。

方案二：使用查询参数（更推荐） #

将完整URL作为路径参数不符合RESTful设计规范，路径参数更适合标识资源唯一标识，而查询参数才是传递外部资源地址的合理选择。这种方式实现更简单，还能避免路径匹配的各类问题：

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/v1/image/")
async def image_resize(image_url: str = Query(...)):
    image_file_name = image_url.split("/")[-1]
    return {"image_url": image_url, "file_name": image_file_name}

请求URL格式改为：
http://localhost:8000/v1/image/?image_url=https://www.freeimages.com/photo/circulate-abstract-1562332.jpg

该方案的优势：

• 无需处理特殊路由匹配规则，兼容性更强
• 其他API调用时逻辑更直观，明确这是参数而非资源路径的一部分
• 规避URL编码带来的潜在异常

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