应将路径参数声明为str并在函数体内手动尝试UUID转换，因为FastAPI不支持Union[str, UUID]对路径参数的多类型解析，直接使用会导致ValidationError且无fallback机制。
路径参数里直接写 Union[str, UUID] 会报错
FastAPI 默认用 Pydantic 解析路径参数，而 UUID 类型校验器对非标准格式（比如纯数字或带短横线但长度不对的字符串）会直接抛 ValidationError，且不会 fallback 到 str。你写 Union[str, UUID] 看似合理，但 FastAPI 不会按顺序尝试解析——它只认第一个能“严格匹配”的类型，或者直接失败。
用 str 接收再手动转换最稳妥
把路径参数声明为 str，在函数体内自己判断是否为合法 UUID，再分支处理。这是最可控、最易调试的方式：
from uuid import UUID from fastapi import HTTPException@app.get("/items/{item_id}") def get_item(item_id: str): try: uuid_obj = UUID(item_id)
是合法 UUID，走 UUID 分支
return {"type": "uuid", "id": str(uuid_obj)} except ValueError: # 不是 UUID，当普通字符串处理 return {"type": "str", "id": item_id}
- 避免了 FastAPI 自动转换的黑盒行为
- 能精确控制错误响应（比如要不要 404 还是 422）
- 兼容任意字符串输入，包括空串、中文、含斜杠等（只要路径本身没被路由引擎截断）
别用 Path(..., convert=True) 或自定义 Field
有人试过给 Path 加 convert=True 或套一层 Field(default=..., validate...)，但这些方式：
- 不改变 FastAPI 对路径参数的类型优先级逻辑
- 无法让
Union在路径参数中真正“多选一”解析 - 容易触发
TypeError: cannot use Union in Path parameter或静默转成str后丢失原始意图
如果必须用类型提示表达“可能是 UUID”，就用 Optional[UUID] + 额外 str 参数
极少数场景需要强类型提示（比如 OpenAPI 文档里显示两种可能），可以拆成两个参数，靠默认值和文档说明引导：
@app.get("/items/{item_id}")
def get_item(
item_id: str,
uuid_hint: Optional[UUID] = None, # 仅用于文档示意，实际不用
):
# 仍以 item_id 字符串为准做判断
注意：这个 uuid_hint 不参与路由匹配，只是 OpenAPI schema 里多一个字段说明。真实逻辑还是得回到第一种 str + 手动 UUID() 尝试的方式。
真正麻烦的不是怎么写，而是得想清楚：这个“混合 ID”语义到底由谁负责解释——是客户端传前就约定好格式，还是服务端无条件接受并分发？后者更常见，也更该由你亲手用 try/except ValueError 控制。
