FastAPI 路径参数与查询参数

FastAPI 路径参数 与 查询参数

1. 基本概念

路径参数

• 定义方式:在路径字符串中用 {} 包裹
• 是 URL 路径的一部分,用于标识"具体访问的资源"
• 语义上通常表示资源的唯一标识符(REST 风格)
• 必填,路径中少了这一段,路由直接匹配不上(404)
• 不能设置默认值

查询参数

• 定义方式:出现在 URL 的 ? 之后,以 key=value 形式书写,多个参数用 & 分隔
• 语义上通常表示"过滤条件/可选配置",不是资源的核心标识
• 可以设置默认值,从而变为可选参数
• FastAPI 判断规则:函数参数如果没有出现在路径的 {} 里,且类型是基本类型(str/int/float/bool等),会自动被识别为查询参数

2. 对比表

维度	路径参数	查询参数
声明位置	路径字符串中的 {}	函数签名中,不在 {} 声明
URL 表现形式	/infer_stream/camellia_det	?source=xxx&conf=0.4
是否必填	必填	可选(设默认值)或必填(不设默认值)
语义定位	资源的唯一标识("访问哪个具体资源")	附加参数/过滤条件("怎么处理这个资源")
能否设默认值	不能	能
典型用途	/users/{user_id}、/models/{model_name}	?page=1&limit=20、?conf=0.25

3. 与请求体参数(Body)的区别

FastAPI 还有第三种常见参数来源:请求体(通常用于 POST/PUT),三者对比:

参数类型	出现位置	典型请求方式	优点	缺点
路径参数	URL路径 /xxx/{id}	任意方法	语义清晰,RESTful	只能是简单类型,不适合复杂结构
查询参数	URL ?key=value	常用于GET	简单直观,浏览器可直接构造链接	明文暴露在URL/日志中,不适合传敏感信息;不适合复杂/嵌套结构
请求体(Body)	HTTP请求正文	常用于POST/PUT	支持复杂JSON结构,不出现在URL/日志里	GET请求不建议带body(部分客户端/代理不支持)

4. 实践中的选型经验

• 资源标识 → 放路径参数:比如 model_name、user_id、session_id,这些是"你要操作哪个具体对象",天然适合放进路径
• 简单的可选配置 → 放查询参数:比如分页 page/limit,过滤条件 status=active,GET 请求场景下用查询参数最自然
• 复杂结构 / 敏感信息 → 放请求体:比如包含嵌套字段的配置对象,或者像地址、密钥这种不希望出现在 URL/日志中的信息,应该用 POST + Body,不要塞进查询参数

5. 安全性提醒

查询参数会明文出现在:

• 服务器访问日志(access log)
• 浏览器历史记录
• 部分代理/CDN的缓存日志
• Referer 请求头(如果页面内有外链)

因此不要把敏感信息(密码、token、内网地址+认证信息等)放在查询参数里,应改用请求体 + POST,并配合身份验证机制。