企业官网建设流程全解析

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( ge=1, # 必须大于等于 1 le=100, # 必须小于等于 100 title="物品ID", # 参数标题（显示在文档中） description="物品的唯一标识，范围 1-100", # 参数描述 alias="item-id" # 参数别名（文档中显示的名称） ) ): return {"item_id": item_id}

通过Path类可实现按业务场景进行校验，具体参数可查阅 FastAPI 源码。

查询参数（Query Parameters）

查询参数是 URL 中?后面的键值对组合，格式为key1=value1&key2=value2，用于对资源进行筛选、分页、排序等辅助操作。

例如：

• /items?skip=0&limit=10：skip（跳过条数）、limit（查询条数）是查询参数
• /users?name=张三&age=20：name（姓名）、age（年龄）是查询参数

高级校验：Query 类

查询参数同样支持类似Path的校验方式，使用前需导入Query：

from fastapi import Query

通过Query类可实现对查询参数的多规则校验：

# ====================== Query 类型注解基础示例 ====================== from fastapi import FastAPI, Query import uvicorn app = FastAPI(title="Query 注解教程", version="1.0.0") Query 注解：限制 limit ≥ 1 且 ≤ 50，添加详细描述 @app.get("/items/advanced/", summary="Query 注解基础示例") def read_items_advanced( # 核心语法：参数名: 类型 = Query(默认值, 校验规则/元数据) skip: int = Query(0, ge=0, description="跳过条数，不能为负数"), limit: int = Query(10, ge=1, le=50, 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", host="127.0.0.1", port=8000, reload=True)

请求体参数（Request Body）

请求体参数用于传递大量、复杂、结构化的数据（如 JSON、表单数据），常用于 POST 或 PUT 请求。

• 定义：HTTP 请求的正文部分，专门用于传递大量、复杂、结构化数据。
• 核心场景：创建资源（如用户注册）、更新资源（如修改商品信息），需要传递完整的资源数据。
• 优势：数据容量大、格式灵活（支持 JSON / 表单 / 文件）、传输安全（配合 HTTPS）。

关键前提：请求体与 HTTP 方法

请求体通常与非查询类HTTP 方法配合使用（符合 RESTful 规范）：

• POST：创建资源（如用户注册、新增商品）→ 必用请求体
• PUT：全量更新资源（如修改商品所有信息）→ 必用请求体
• PATCH：部分更新资源（如修改商品价格）→ 常用请求体
• GET：查询资源 → 禁止使用请求体（不符合 HTTP 规范）

实现步骤

1. 安装 Pydantic 依赖

pip install pydantic

2. 导入 BaseModel 和 Field

from pydantic import BaseModel, Field

3. 定义 Pydantic 模型

例如，定义一个用户登录接口的模型，包含用户名和密码的校验规则：

from pydantic import BaseModel, Field class Login(BaseModel): username: str = Field( ..., min_length=3, max_length=50, description="用户名长度需在 3-50 字符之间", example="johndoe" ) password: str = Field( ..., min_length=6, 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(username=login.username, password=login.password) if user is None: return {"code": 400, "message": "用户不存在"} return {"message": f"Hello {login.username}"}

5. 在交互式文档中测试接口

启动服务后，访问http://127.0.0.1:8000/docs即可在 FastAPI 自带的交互式文档页面测试接口。

返回code: 200状态码和"Hello admin"即表示登录成功。