FastAPI 路径参数完全指南：类型转换、校验与路由匹配

FastAPI 路径参数定义与类型控制

路径操作装饰器中花括号包裹的变量即为路径参数。FastAPI 会自动从请求 URL 中提取对应值，并注入到同名函数参数中。默认情况下，未声明类型的路径参数会被视为 str 类型。

from fastapi import FastAPI
app = FastAPI()

@app.get("/hello/{name}")
def say_hello(name: str):
    return {"message": f"Hello {name}"}

运行后访问 http://127.0.0.1:8001/hello/xiaoming，接口返回：

{"message":"Hello xiaoming"}

通过函数参数声明类型实现自动转换与校验

在为函数参数添加类型注解后，FastAPI 会自动尝试将 URL 中的字符串转换为目标类型。转换失败时返回标准的 422 验证错误，清晰提示数据类型不符。

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

访问 http://127.0.0.1:8001/items/11 时，服务端自动完成转换并返回整数：{"item_id":11}。若访问 /items/xiaoming，则会收到包含 type_error.integer 的详细错误信息。

在装饰器中直接声明路径类型

也可以在路由装饰器的路径模板中直接指定类型，例如 {item_id:int}。这种方式要求 URL 片段必须严格匹配该类型格式。若不匹配且无其他兼容路由，服务器将返回 404 Not Found，而非 422 验证错误。这是因为 FastAPI 将其视为不同的路由模式进行匹配。

路由优先级与参数匹配顺序

FastAPI 采用自上而下的顺序遍历路由装饰器进行匹配。当存在多个相似路径时，先定义的装饰器拥有更高优先级。调整声明顺序可改变最终触发的业务逻辑。

@app.get("/items/{item_id}")
def read_item(item_id):
    return {"item_id": item_id}

@app.get("/items/{item_id:int}")
def read_item_int(item_id):
    return {"item_id_int": item_id}

上述代码中，数字请求会优先命中第一个宽泛的 str 路由。若希望精确匹配数字走专用逻辑，只需将带 :int 的装饰器置于前面即可。实际开发中建议将精确路由放在通用路由之前，避免隐性拦截。

路径参数校验规则与元数据声明

对于需要约束取值范围的路径参数，可通过导入 Path 类进行精细化校验。它支持数值区间限制、字符串长度过滤以及正则表达式匹配。

from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int = Path(gt=0, le=100)):
    return {"item_id": item_id}

示例中限制了 item_id 必须在 (0, 100] 范围内。正常访问 /items/11 返回结果；访问 /items/101 则触发 value_error.number.not_le 验证异常。常用校验参数包括：gt（大于）、ge（大于等于）、lt（小于）、le（小于等于）、min_length、max_length 及 pattern（正则）。

通过向 Path 传递元数据关键字，可大幅提升接口文档的可读性。设置 description 与 example 后，FastAPI 会自动将其渲染至交互式文档中，便于上下游对接查阅。

@app.get("/items/{item_id}")
def read_item(item_id: int = Path(description="商品唯一标识ID，范围大于0且不超过100", gt=0, le=100)):
    return {"item_id": item_id}

开发注意事项与常见问题排查

• 404 与 422 的区别：装饰器写死类型导致 URL 模式不匹配时返回 404；函数参数类型注解转换失败或 Path 校验不通过时返回 422。排查时应优先检查路由声明写法与入参格式。
• 参数命名一致性：URL 模板中的变量名必须与函数形参名完全一致，否则无法完成自动绑定。
• 复杂场景处理：路径参数仅适用于少量关键标识符。若需传递大量结构化数据，建议结合表单或请求体（Request Body），并使用 Pydantic 模型进行统一验证。

以上就是 FastAPI 路径参数的详细内容，更多关于 FastAPI 路径参数使用的资料请关注本站其它相关文章！