新手必看：FastAPI 参数接收的正确姿势（路径 / 查询 / 请求体全解析）

继上一篇《FastAPI 零基础入门从安装到快速搭建 Web 接口》之后本篇聚焦 FastAPI 最核心的参数接收能力 —— 路径参数、查询参数、请求体用(大白话 实操代码 可视化测试)的方式拆解新手跟着敲代码就能懂掌握后就能实现真正的 “数据交互型接口”。前言上一篇我们学会了搭建基础接口和四种请求方法但实际开发中接口不可能只返回固定数据比如根据用户 ID 查信息、分页查询列表、提交用户注册信息… 这些都需要前端给后端传数据而 FastAPI 接收前端数据的核心方式就是路径参数、查询参数、请求体这也是新手从 “写死数据” 到 “动态交互” 的关键一步。前置准备确保你已经完成安装 FastAPI 和 uvicornpip install fastapi uvicorn熟悉基础的 FastAPI 项目结构和启动方式保留上一篇的 main.py 文件本篇代码都基于这个文件迭代。1 路径参数从URL路径中取数据1.1.什么是路径参数简单来说把参数直接写在接口URL的路径里比如想根据用户ID查询信息接口地址设计成/user/1(1就是用户ID),这个1就是路径参数。核心场景查询 / 操作指定唯一资源如用户 ID、商品 ID、文章 ID。1.2.基础实操获取单个用户ID打开main.py编写如下代码fromfastapiimportFastAPIimportuvicorn appFastAPI()# 路径参数核心语法app.get(/路径/{参数名})app.get(/user/{user_id},summary根据用户ID查询用户信息)defget_user_by_id(user_id:int):# 这里指定类型intFastAPI会自动校验# 模拟根据ID查数据实际开发中可对接数据库return{code:200,msg:查询成功,data:{user_id:user_id,# 直接使用路径参数username:f用户{user_id},age:18user_id%10# 简单动态生成年龄}}if__name____main__:uvicorn.run(main:app,host127.0.0.1,port8000,reloadTrue)1.3.测试与关键知识点第一步启动服务点击 PyCharm 运行按钮启动 main.py确保服务正常。第二步访问接口打开浏览器访问http://127.0.0.1:8000/user/5返回结果如下新手必看知识点类型注解的作用如果访问http://127.0.0.1:8000/user/abc传字符串FastAPI 会自动返回 422 错误无需手动写校验代码参数名要一致装饰器里的{user_id}必须和函数参数user_id同名支持多种类型除了 int还支持 str、float、bool 等比如/article/{article_title:str}。2 查询参数URL中后面的键值对2.1.什么是查询参数简单说在 URL 末尾用?参数名值的形式传参多个参数用分隔比如/goods?page1size10page 是页码size 是每页条数。核心场景筛选、分页、模糊查询如列表分页、多条件筛选商品2.2. 基础实操商品列表分页查询代码如下fromfastapiimportFastAPIimportuvicorn appFastAPI()# 查询参数无需在路径中写函数直接接收参数即可app.get(/goods,summary商品列表分页查询)defget_goods_list(page:int1,# 默认值如果前端不传默认查第1页size:int10# 默认值如果前端不传默认每页10条):# 模拟分页数据实际开发中根据page和size查数据库goods[]foriinrange(size):goods.append({goods_id:(page-1)*sizei1,goods_name:f商品{(page-1)*sizei1},price:99.9i})return{code:200,msg:查询成功,data:{page:page,size:size,total:100,# 模拟总条数goods_list:goods}}if__name____main__:uvicorn.run(main:app,host127.0.0.1,port8000,reloadTrue)2.3.测试与关键知识不传参数访问http://127.0.0.1:8000/goods默认使用page1size10传参数访问http://127.0.0.1:8000/goods?page2size5返回第 2 页、每页 5 条数据返回结果如图新手必看知识点查询参数无需在路径中定义函数参数直接写FastAPI 会自动从 URL 的?后解析默认值的作用前端不传参时使用默认值避免报错混合使用路径参数和查询参数可以一起用比如/user/{user_id}/orders?page1size10根据用户 ID 查订单同时分页。3 请求体POST/PUT 请求传“大量数据”3.1.什么是请求体简单说前端把复杂数据如注册信息、表单数据放在请求的 “正文” 里传参而不是 URL 里URL 传参有长度限制。核心场景提交 / 更新大量数据如用户注册、提交表单、上传复杂 JSON。⚠️ 注意GET 请求不支持请求体只能用 POST/PUT 等方法。3.2.基础实操用户注册POST请求请求体第一步导入 Pydantic 模型FastAPI 的 “数据校验神器”FastAPI 用 Pydantic 的BaseModel定义请求体的格式自动校验数据类型和必填项新手不用手动写校验逻辑。第二步编写注册接口代码在 main.py 中新增如下代码fromfastapiimportFastAPIimportuvicornfrompydanticimportBaseModel# 导入Pydantic模型appFastAPI()# 定义请求体模型用户注册数据格式classUserRegister(BaseModel):username:str# 必填项用户名字符串password:str# 必填项密码字符串age:int18# 可选项年龄默认18email:str# 可选项邮箱可传None# POST请求请求体用户注册app.post(/user/register,summary用户注册)defuser_register(user_info:UserRegister):# 接收请求体类型为自定义的UserRegister# 模拟注册逻辑实际开发中可写入数据库return{code:200,msg:注册成功,data:{username:user_info.username,age:user_info.age,email:user_info.emailifuser_info.emailelse未填写}}if__name____main__:uvicorn.run(main:app,host127.0.0.1,port8000,reloadTrue)3.3.测试请求体请求体无法直接在浏览器访问推荐用 FastAPI 自带的交互式文档测试启动服务后访问http://127.0.0.1:8000/docs自动生成的 Swagger 文档找到/user/register接口点击「Try it out」编辑请求体 JSON按模型格式填示例点击 Execute就能看到返回结果新手必看知识点Pydantic 模型的作用自动校验比如 age 传字符串会报错username 不传会提示必填自动解析把前端传的 JSON 自动转成 Python 对象直接用user_info.username取值可选项定义age: int 18默认值、email: str | None None可传 None请求体只支持 POST/PUT 等GET 请求不能用因为 GET 请求没有 “正文”。4 三者对比一张表看懂用法场景类型传参位置核心场景请求方法支持示例路径参数URL 路径中/user/{id})唯一资源查询 / 操作ID所有方法/user/1、/goods/100查询参数URL 末尾?page1size10筛选、分页、简单条件查询所有方法GET 常用/goods?page2size5请求体请求正文JSON提交 / 更新大量复杂数据POST/PUT/ 等注册、提交表单、修改多字段5 新手避坑指南参数名大小写敏感路径参数{user_id}和函数参数user_id必须完全一致类型注解别漏写FastAPI 靠类型注解做自动校验漏写会失去校验能力GET 请求别用请求体前端用 GET 传请求体后端收不到这是 HTTP 协议规定测试工具选对路径参数 / 查询参数用浏览器请求体用/docs或 Postman。6 进阶美化Path/Query/Field 让参数更规范这是最简单、最实用的进阶用法不用改逻辑只需要加一行代码就能让你的接口带中文注释加参数校验比如数字必须大于 0接口文档更清晰一看就懂每个参数干嘛用先安装/导入必须做fromfastapiimportFastAPI,Path,Query# 路径查询参数专用frompydanticimportBaseModel,Field# 请求体专用6.1.路径参数Path作用给路径参数加说明、限制范围app.get(/user/{user_id})defget_user(# Path给路径参数加注释 校验user_id:intPath(...,description用户ID必须大于0,ge1)):return{user_id:user_id}…代表必填ge1代表必须 ≥ 1description接口文档里会显示中文说明6.2.查询参数Query作用给查询参数加默认值、长度限制、范围限制app.get(/goods)defget_goods(page:intQuery(1,description页码,ge1),size:intQuery(10,description每页数量,le100)):return{page:page,size:size}ge1大于等于 1le100小于等于 100不传就用默认值传了自动校验6.3.请求体Field作用给请求体字段加说明、长度 / 格式校验classUserRegister(BaseModel):username:strField(...,description用户名必填)password:strField(...,description密码至少6位,min_length6)age:intField(18,description年龄默认18)app.post(/user/register)defregister(user:UserRegister):returnusermin_length6密码最少 6 位自动校验不合格直接报错三者一起用最常用实战写法app.get(/user/{user_id}/order)defget_user_order(# 路径参数user_id:intPath(...,description用户ID,ge1),# 查询参数page:intQuery(1,description页码)):return{user_id:user_id,page:page}总结本篇我们掌握了 FastAPI接收前端数据的三种核心方式以及接口参数的完整用法路径参数从 URL 路径取唯一标识用Path获取 URL 路径中的唯一标识支持校验与文档说明查询参数从 URL 末尾取筛选 / 分页条件用Query获取 URL 问号后的筛选、分页条件可设默认值与限制请求体从请求正文取复杂数据配合 Pydantic 自动校验。用BaseModel Field接收复杂 JSON 数据自动完成格式校验与字段约束。三者搭配使用就能覆盖绝大多数接口传参场景让接口更规范、更健壮、文档更清晰。新手跟着代码实操一遍并用 /docs 测试验证就能完全掌握“前端传参、后端接收”的核心逻辑。下一篇我们将继续讲解响应模型、统一异常处理、依赖注入等实战内容帮你写出生产级标准接口。