FastAPI中Path参数正则约束需写在路径字符串中，格式为{param_name:regex}，如@app.get("/item/{item_id:\d+}")；正则在路由匹配阶段生效，不满足则直接404，且不可含捕获组。
FastAPI 中 Path 参数如何用正则表达式约束路径段
FastAPI 原生支持在 Path 参数中嵌入正则表达式，但不是靠 Python 的 re 模块手动校验，而是通过路径参数的「类型注解 + 正则语法」直接定义规则。关键在于：正则写在路径字符串里，不是写在函数参数的 regex=... 里。
路径正则必须写在路由装饰器的路径字符串中
错误做法是试图在 Path(...) 里传正则对象或字符串——FastAPI 不识别这种用法。正确方式是把正则写进路径模板，用 {param_name:regex} 格式：
@app.get("/item/{item_id:\d+}")
def read_item(item_id: int):
return {"item_id": item_id}
-
\d+是正则表达式，匹配一个或多个数字；整个{item_id:\d+}表示该路径段只接受纯数字 - 注意：
item_id的类型注解仍需写（如int），FastAPI 会先按正则匹配路径，再尝试类型转换 - 如果请求是
/item/abc，直接返回 404（不进函数）；如果是/item/123，才调用函数并转成int - 正则中不能有捕获组
()，否则报错；只支持基本语法，如[a-z]、\w+、[0-9]{4}
常见正则写法与对应场景
实际开发中高频用到的几种模式：
- 纯字母 ID：
/user/{username:[a-zA-Z]+}—— 避免数字开头或混入符号 - 带分隔符的版本号：
/api/v{version:[0-9]\.[0-9]}→ 匹配v1.2，但不匹配v10.20 - 十六进制哈希：
/file/{sha256:[a-f0-9]{64}}—— 精确 64 位小写 hex - 可选前缀的路径：
/docs/{section:(?:api|user|admin)?}—— 注意非捕获组(?:...)写法，避免括号被误解析
正则不生效？检查这三点
正则没起作用，大概率是以下原因：
- 路径字符串里漏了冒号，比如写成
{item_id\d+}（缺:）→ FastAPI 当作普通字符串字面量处理 - 正则里用了未转义的特殊字符，如点号
.没写成\.→ 导致匹配行为异常 - 路径段被其他更宽泛的路由覆盖，例如
/item/{item_id}和/item/{item_id:\d+}同时存在，前者会优先匹配所有输入，后者永远不触发
正则限制发生在路由匹配阶段，早于依赖注入和参数校验，所以它既是安全边界，也是性能开关——写得太松会导致无效请求穿透到后续逻辑。
