当前位置：首页 > news >正文

【FastAPI】请求参数全解析：路径参数、查询参数、请求体参数详解 + 原生注解 vs 函数类型注解

news 2026/6/11 1:56:31

《FastAPI 请求参数全解析：路径参数、查询参数、请求体参数详解 + 原生注解 vs 函数类型注解（附完整代码 + 易错点）》

文章前言

在 FastAPI 开发中，正确使用路径参数、查询参数、请求体参数是构建高效、安全、可维护 API 的基础。
很多开发者容易混淆“原生注解”与“函数类型注解”的使用方式，导致422 错误、API 文档缺失、类型不校验等问题。

本文通过代码实操 + 详细注释 + 知识点总结 + 易错点警示，带你系统掌握：

路径参数：Path(...)用法
查询参数：Query(...)用法
请求体参数：BaseModel + Field(...)用法
每个参数的完整函数类型注解写法（如path(...),field(...)等）

一、基础路由

1. 原生注解

@app.get("/")asyncdefroot():return{"message":"Hello World888"}@app.get("/hello")asyncdefhello():return{"msg":"你好 FastAPI"}@app.get("/user/hello")asyncdefhello_user():return{"msg":"我正在学习 FastAPI..."}

知识点

@app.get("/")：定义 GET 请求路径
async def：异步函数，支持高并发
返回dict，FastAPI 自动转为 JSON

易错点

不能返回str或int，必须返回dict或list
不能用print()输出，应使用logging

2. 函数的类型注解（无`-> dict`，仅保留函数结构）

@app.get("/")asyncdefroot():return{"message":"Hello World888"}@app.get("/hello")asyncdefhello():return{"msg":"你好 FastAPI"}@app.get("/user/hello")asyncdefhello_user():return{"msg":"我正在学习 FastAPI..."}

此部分不添加-> dict，与原生注解一致，保持简洁
FastAPI 通过返回值自动推断类型，无需显式声明

知识点

async def不需要->返回类型，FastAPI 自动识别
无需-> dict，代码更简洁，更符合实际开发习惯

易错点

返回None会导致500错误 → 应返回空字典{}或{"msg": ""}
若 IDE 报错，可开启pydantic-settings+type-checking插件

二、路径参数

1. 原生注解

@app.get("/book1/{id}")asyncdefget_book_by_id(id:int):return{"id":id,"title":f"这是第{id}本书"}@app.get("/square/{num}")asyncdefsquare(num:int):return{"输入数字":num,"平方结果":num**2}

知识点

{id}：路径变量，自动绑定为函数参数
id: int：原生类型，自动转换为整数
无需手动解析，自动完成

易错点

参数名写错（如id1）会导致路径不匹配
不写类型 →id: Any，无校验、无 Swagger 表单

2. 函数的类型注解（结合`Path(...)`，无`-> dict`）

@app.get("/book2/{id}")asyncdefget_book_with_validation(id:int=Path(...,gt=0,le=100,description="书籍ID必须是 1~100 之间的整数")):return{"id":id,"title":f"这是第{id}本书"}@app.get("/author/{name}")asyncdefget_name(name:str=Path(...,min_length=5,max_length=10,description="作者名称")):return{"作者":name}

知识点

Path(...)：显式声明路径参数，支持校验
gt=0, le=100：数值范围校验，不满足返回 422
min_length,max_length：字符串长度控制
description：显示在 Swagger 文档中
不写-> dict，保持代码简洁

易错点

Path(...)要写在右端，如int = Path(...)，不是id: Path(...)否则语法错误
max_length=10, min_length=5写成max_length=10,min_length=5→ 缺少逗号报错
Path(..., ...)中永远不要混用Field(...)，Path不支持Field

三、查询参数

1. 原生注解

@app.get("/news/news_list")asyncdefget_news_list(page:int=1,size:int=10):return{"page":page,"size":size}

知识点

page: int = 1：默认值，可选参数
查询字符串拼接：?page=1&size=10
自动类型转换（如字符串转整数）

易错点

不设默认值 → 参数必填，用户不传会报错
用int = 1而不用Query→ 无校验、无文档

2. 函数的类型注解（结合`Query(...)`，无`-> dict`）

@app.get("/news1/news_list")asyncdefget_news_list(page:int=Query(1,lt=100,description="页码"),size:int=Query(10,ge=5,le=50,description="每页数量")):return{"page":page,"size":size}@app.get("/book/book_list")asyncdefget_book_list(category:str=Query("python",min_length=5,max_length=255,description="图书分类"),price:int=Query(50,ge=50,le=100,description="图书价格")):return{"图书分类":category,"图书价格":price}

知识点

Query(...)：显式定义查询参数，支持校验与文档描述
lt=100：小于 100，ge=5：大于等于 5
description：生成 Swagger 表单说明
不写-> dict，FastAPI 自动识别返回类型

易错点

Query(10, ge=5, le=50)会冲突（10 满足ge=5但不满足le=50）→ 不违规但会报错文本
Query("python", max_length=255)可以，但Query("python", min_length=5)时需确保值 ≥5 字符
Query(...)不能写在dict外部，必须作为参数默认值

四、请求体参数

1. 原生注解（使用`BaseModel`）

classUser(BaseModel):username:strpassword:str@app.post("/user/register")asyncdefregister(user:User):return{"username":user.username,"password":user.password}

知识点

BaseModel：定义请求体数据结构
user: User：FastAPI 自动解析application/json请求体
字段未加Field(...)= 必填（...自动添加）

易错点

BaseModel类重复定义 → 报错
请求体格式错误（如"username": 123）→ 返回422，提示字段类型错误

2. 函数的类型注解（结合`Field(...)`，无`-> dict`）

classEmployee(BaseModel):name:str=Field(...,min_length=2,max_length=10,description="员工姓名")age:int=Field(...,ge=18,le=60,description="员工年龄")salary:float=Field(...,gt=5000,lt=10000,description="员工薪资")@app.post("/employee")asyncdefsearch_employee(employee:Employee):return{"name":employee.name,"age":employee.age,"salary":employee.salary}classBook(BaseModel):name:str=Field(...,min_length=5,max_length=255,description="图书名称")price:int=Field(...,ge=50,le=100,description="图书价格")category:str=Field(...,min_length=5,max_length=255,description="图书分类")author:str=Field(...,min_length=5,max_length=255,description="图书作者")publish_date:str=Field(...,min_length=5,max_length=255,description="图书出版日期")publish_house:str=Field("黑马出版社",min_length=5,max_length=255,description="图书出版社")@app.post("/book")asyncdefsearch_book(book:Book):return{"name":book.name,"price":book.price,"category":book.category,"author":book.author,"publish_date":book.publish_date,"publish_house":book.publish_house}