FastAPI 三种传参方式详解路径参数、查询参数与请求体参数路径参数Path Parameters路径参数是 URL 路径中的动态可变部分格式为/路由/{参数名}用于标识具体的资源如物品 ID、用户 ID。例如/books/{book_id}表示要查询特定 ID 的书籍信息。基础用法app.get(/users/{username}, summary字符串路径参数) def read_user(username: str): # str 类型注解可省略默认按字符串处理 return {username: username}使用装饰器app.get定义路由路径接口函数必须声明与路径参数同名的形参。高级校验Path 类当参数需要复杂校验时可导入Path类进行更精细的规则配置from fastapi import Path app.get(/items/{item_id}) def read_item( # Path 类参数ge(≥)、le(≤)、gt()、lt()、title、description 等 item_id: int Path( ge1, # 必须大于等于 1 le100, # 必须小于等于 100 title物品ID, # 参数标题显示在文档中 description物品的唯一标识范围 1-100, # 参数描述 aliasitem-id # 参数别名文档中显示的名称 ) ): return {item_id: item_id}通过Path类可实现按业务场景进行校验具体参数可查阅 FastAPI 源码。查询参数Query Parameters查询参数是 URL 中?后面的键值对组合格式为key1value1key2value2用于对资源进行筛选、分页、排序等辅助操作。例如/items?skip0limit10skip跳过条数、limit查询条数是查询参数/users?name张三age20name姓名、age年龄是查询参数高级校验Query 类查询参数同样支持类似Path的校验方式使用前需导入Queryfrom fastapi import Query通过Query类可实现对查询参数的多规则校验# Query 类型注解基础示例 from fastapi import FastAPI, Query import uvicorn app FastAPI(titleQuery 注解教程, version1.0.0) Query 注解限制 limit ≥ 1 且 ≤ 50添加详细描述 app.get(/items/advanced/, summaryQuery 注解基础示例) def read_items_advanced( # 核心语法参数名: 类型 Query(默认值, 校验规则/元数据) skip: int Query(0, ge0, description跳过条数不能为负数), limit: int Query(10, ge1, le50, description查询条数1-50 条) ): Query 注解分页接口 :param skip: 跳过条数≥0 :param limit: 查询条数1-50 :return: 分页结果 fake_items [{item_id: i, name: f物品{i}} for i in range(skip, skip limit)] return { code: 200, skip: skip, limit: limit, data: fake_items } if name main: uvicorn.run(main:app, host127.0.0.1, port8000, reloadTrue)请求体参数Request Body请求体参数用于传递大量、复杂、结构化的数据如 JSON、表单数据常用于 POST 或 PUT 请求。定义HTTP 请求的正文部分专门用于传递大量、复杂、结构化数据。核心场景创建资源如用户注册、更新资源如修改商品信息需要传递完整的资源数据。优势数据容量大、格式灵活支持 JSON / 表单 / 文件、传输安全配合 HTTPS。关键前提请求体与 HTTP 方法请求体通常与非查询类HTTP 方法配合使用符合 RESTful 规范POST创建资源如用户注册、新增商品→ 必用请求体PUT全量更新资源如修改商品所有信息→ 必用请求体PATCH部分更新资源如修改商品价格→ 常用请求体GET查询资源 → 禁止使用请求体不符合 HTTP 规范实现步骤1. 安装 Pydantic 依赖pip install pydantic2. 导入 BaseModel 和 Fieldfrom pydantic import BaseModel, Field3. 定义 Pydantic 模型例如定义一个用户登录接口的模型包含用户名和密码的校验规则from pydantic import BaseModel, Field class Login(BaseModel): username: str Field( ..., min_length3, max_length50, description用户名长度需在 3-50 字符之间, examplejohndoe ) password: str Field( ..., min_length6, description密码长度至少 6 位 )4. 在路由中使用模型from fastapi import APIRouter from app.models.user import User from app.schemas import Login router APIRouter(prefix/users, tags[用户管理]) router.post(/login) async def login(login: Login): user await User.get_or_none(usernamelogin.username, passwordlogin.password) if user is None: return {code: 400, message: 用户不存在} return {message: fHello {login.username}}5. 在交互式文档中测试接口启动服务后访问http://127.0.0.1:8000/docs即可在 FastAPI 自带的交互式文档页面测试接口。返回code: 200状态码和Hello admin即表示登录成功。
FastAPI 三种传参方式详解路径参数、查询参数与请求体参数路径参数Path Parameters路径参数是 URL 路径中的动态可变部分格式为/路由/{参数名}用于标识具体的资源如物品 ID、用户 ID。例如/books/{book_id}表示要查询特定 ID 的书籍信息。基础用法app.get(/users/{username}, summary字符串路径参数) def read_user(username: str): # str 类型注解可省略默认按字符串处理 return {username: username}使用装饰器app.get定义路由路径接口函数必须声明与路径参数同名的形参。高级校验Path 类当参数需要复杂校验时可导入Path类进行更精细的规则配置from fastapi import Path app.get(/items/{item_id}) def read_item( # Path 类参数ge(≥)、le(≤)、gt()、lt()、title、description 等 item_id: int Path( ge1, # 必须大于等于 1 le100, # 必须小于等于 100 title物品ID, # 参数标题显示在文档中 description物品的唯一标识范围 1-100, # 参数描述 aliasitem-id # 参数别名文档中显示的名称 ) ): return {item_id: item_id}通过Path类可实现按业务场景进行校验具体参数可查阅 FastAPI 源码。查询参数Query Parameters查询参数是 URL 中?后面的键值对组合格式为key1value1key2value2用于对资源进行筛选、分页、排序等辅助操作。例如/items?skip0limit10skip跳过条数、limit查询条数是查询参数/users?name张三age20name姓名、age年龄是查询参数高级校验Query 类查询参数同样支持类似Path的校验方式使用前需导入Queryfrom fastapi import Query通过Query类可实现对查询参数的多规则校验# Query 类型注解基础示例 from fastapi import FastAPI, Query import uvicorn app FastAPI(titleQuery 注解教程, version1.0.0) Query 注解限制 limit ≥ 1 且 ≤ 50添加详细描述 app.get(/items/advanced/, summaryQuery 注解基础示例) def read_items_advanced( # 核心语法参数名: 类型 Query(默认值, 校验规则/元数据) skip: int Query(0, ge0, description跳过条数不能为负数), limit: int Query(10, ge1, le50, description查询条数1-50 条) ): Query 注解分页接口 :param skip: 跳过条数≥0 :param limit: 查询条数1-50 :return: 分页结果 fake_items [{item_id: i, name: f物品{i}} for i in range(skip, skip limit)] return { code: 200, skip: skip, limit: limit, data: fake_items } if name main: uvicorn.run(main:app, host127.0.0.1, port8000, reloadTrue)请求体参数Request Body请求体参数用于传递大量、复杂、结构化的数据如 JSON、表单数据常用于 POST 或 PUT 请求。定义HTTP 请求的正文部分专门用于传递大量、复杂、结构化数据。核心场景创建资源如用户注册、更新资源如修改商品信息需要传递完整的资源数据。优势数据容量大、格式灵活支持 JSON / 表单 / 文件、传输安全配合 HTTPS。关键前提请求体与 HTTP 方法请求体通常与非查询类HTTP 方法配合使用符合 RESTful 规范POST创建资源如用户注册、新增商品→ 必用请求体PUT全量更新资源如修改商品所有信息→ 必用请求体PATCH部分更新资源如修改商品价格→ 常用请求体GET查询资源 → 禁止使用请求体不符合 HTTP 规范实现步骤1. 安装 Pydantic 依赖pip install pydantic2. 导入 BaseModel 和 Fieldfrom pydantic import BaseModel, Field3. 定义 Pydantic 模型例如定义一个用户登录接口的模型包含用户名和密码的校验规则from pydantic import BaseModel, Field class Login(BaseModel): username: str Field( ..., min_length3, max_length50, description用户名长度需在 3-50 字符之间, examplejohndoe ) password: str Field( ..., min_length6, description密码长度至少 6 位 )4. 在路由中使用模型from fastapi import APIRouter from app.models.user import User from app.schemas import Login router APIRouter(prefix/users, tags[用户管理]) router.post(/login) async def login(login: Login): user await User.get_or_none(usernamelogin.username, passwordlogin.password) if user is None: return {code: 400, message: 用户不存在} return {message: fHello {login.username}}5. 在交互式文档中测试接口启动服务后访问http://127.0.0.1:8000/docs即可在 FastAPI 自带的交互式文档页面测试接口。返回code: 200状态码和Hello admin即表示登录成功。
