FastAPI路径参数正则约束必须写在路由字符串的{param:regex}中，而非Path()的regex参数；例如"/items/{item_id:\d{3,6}}"有效，而Path(..., regex=r"\d{3,6}")对路径参数无效。
FastAPI 路径参数怎么加正则约束
FastAPI 原生支持在路径参数中嵌入正则表达式，不需要额外写验证逻辑或中间件。关键是在 {param_name:regex} 语法里直接写正则，而不是靠 Path(..., regex=...) —— 后者只对查询参数或请求体字段有效，对路径参数无效。
路径参数正则必须写在路由字符串里
这是最容易踩的坑：Path 的 regex 参数对路径参数完全不起作用。FastAPI 解析路径时，只认 URL 模板里的内联正则。比如想限制 item_id 只能是 3~6 位数字：
@app.get("/items/{item_id:\d{3,6}}")
def read_item(item_id: str):
return {"item_id": item_id}
注意：\d{3,6} 是写在 {item_id:...} 冒号后面的部分，不是传给 Path() 的参数。如果写成这样就无效：
@app.get("/items/{item_id}")
def read_item(item_id: str = Path(..., regex=r"\d{3,6}")): # ❌ 不会校验路径匹配
正则里要小心转义和特殊字符
URL 路径中斜杠 /、点 .、括号等有特殊含义，写正则时得双重转义（Python 字符串 + FastAPI 路由解析）：
- 匹配带下划线的用户名：
{username:[a-zA-Z0-9_]+}，不用双反斜杠 - 匹配含点的域名片段（如
api.example.com）：{domain:[a-zA-Z0-9.-]+}，点在字符组里不需转义 - 想匹配字面量
{或}？不行 —— 这些是 FastAPI 路由语法定界符，无法出现在正则中 - 避免用
.*开头，否则可能吞掉后续路径段，比如{path:.+}/detail会破坏路由结构
多个路径参数正则可以共存，但顺序和贪婪性要留意
多个带正则的参数可以一起用，FastAPI 会按顺序尝试匹配。例如：
@app.get("/files/{year:\d{4}}/{month:\d{2}}/{name:[a-z]+\.txt}")
def get_file(year: int, month: int, name: str):
...
这里要注意：
-
year和month的正则必须严格匹配长度，否则可能被后一个参数“抢走”字符 - 如果
name正则太宽泛（比如用.*），month就可能匹配失败，因为路径分割依赖正则边界 - 所有路径参数正则最终都编译为 Python 的
re.Pattern，所以支持^和$，但没必要加 —— FastAPI 自动锚定整个路径段
真正难调的不是写法，而是当正则和实际 URL 边界不一致时，FastAPI 直接返回 404，连错误提示都不告诉你哪段正则没命中。
