路径参数需在路由和函数签名中显式声明并匹配名称与类型，如user_id: int；查询参数须设默认值才能被正确识别，校验需用path或query类区分，重名参数会引发语法错误。
路径参数必须显式声明在路由和函数签名里
FastAPI不会自动从URL路径中提取变量，你得在 @app.get("/users/{user_id}") 的花括号里写明参数名，同时在函数参数列表里用同名变量接收。漏掉任意一处，user_id 就拿不到。
类型注解不是可选的——写 user_id: int 不仅让 FastAPI 做类型转换，还会在传入非数字（比如 /users/abc）时直接返回 422 错误，而不是等你手动 int() 报 ValueError。
常见错误现象：
- 路由写了
/items/{id}，但函数参数叫item_id→ 参数始终为None或报错 - 没加类型注解，比如
def read_item(id):→id是字符串，后续做数值比较或数据库查询容易出隐性 bug - 多个路径参数顺序错乱，比如先定义
/users/{user_id}/posts/{post_id}，却把post_id放在函数参数第一位 → 类型校验和文档生成都错位
Query 参数靠函数参数默认值触发识别
只要参数没出现在路由路径里，FastAPI 就把它当查询参数处理。但关键点在于：**必须给默认值**，否则会被当成请求体参数（Pydantic 模型），导致 GET 请求带 body 时报错或参数丢失。
比如 skip: int = 0 是标准写法；而 skip: int（无默认值）会让 FastAPI 认为这是个必填的请求体字段，哪怕你发的是 GET /items?skip=5，它也收不到。
使用场景差异：
- 分页类参数（
skip,limit）通常设默认值，避免前端不传时崩掉 - 过滤类参数（
q,status）常用Optional[str] = None表示可选 - 需要强校验时，用
Query类替代默认值，比如limit: int = Query(10, le=100)，既能设默认值，又能加范围限制
Path 和 Query 的校验逻辑不能混用
Path 类只对路径参数生效，Query 类只对查询参数生效。拿 Query 去修饰路径参数（比如 user_id: int = Query(..., ge=1)）不会报错，但校验规则实际不生效——因为 FastAPI 根本不会把路径参数交给 Query 解析器。
正确做法是：
- 路径参数校验用
Path：user_id: int = Path(..., ge=1, le=999999) - 查询参数校验用
Query：page: int = Query(1, ge=1) -
...表示“该参数必填”，但仅对Path和Query有意义；普通默认值如= 0已隐含“可选”语义
别图省事全用 Query，路径参数走 Query 校验会绕过 FastAPI 的路径匹配优先级机制，可能影响文档生成和错误提示准确性。
参数冲突时路径参数永远优先
如果路径和查询参数重名，比如路由是 /users/{id}，函数定义为 def get_user(id: int, id: str = None)，Python 本身就不允许同名参数，会直接语法报错。
更隐蔽的问题是命名冲突但类型不同，例如：
@app.get("/users/{user_id}")-
def get_user(user_id: int, user_id: str = Query(None))→ 语法错误，无法启动
所以路径参数名要和查询参数名严格区分开。实际项目中建议统一前缀，比如路径用 user_id，查询用 filter_user_id 或 q_user_id，避免混淆。
另外注意路由顺序：像 /users/me 和 /users/{user_id} 这类，/users/me 必须写在前面，否则 me 会被当成 user_id 字符串值匹配进去——这个坑不看文档很难意识到。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
