首页 > 其他分享 >FastAPI 查询参数与字符串校验详解：类型、校验规则与元数据设置

FastAPI 查询参数与字符串校验详解：类型、校验规则与元数据设置

时间：2024-11-08 09:17:44浏览次数：3  
标签：None items 校验 results item 详解 FastAPI Query id

FastAPI 查询参数与字符串校验详解：类型、校验规则与元数据设置

本文详细介绍了 FastAPI 中查询参数的设置与校验方法，涵盖了可选参数、默认值、必要参数和参数列表的处理方式。通过使用 Query 类，开发者可以为查询参数添加额外的校验规则，如最小长度、最大长度、正则表达式匹配等，从而增强 API 数据的准确性。文中还讲解了如何为参数添加元数据信息，包括标题、摘要、描述等，以便在 Swagger UI 中更清晰地展示 API 信息，帮助用户构建严谨且具备良好文档支持的 API 接口。

文章目录

示例中使用的 Python 版本为 Python 3.10.15，FastAPI 版本为 0.115.4。

一 可选查询参数

from typing import Union, List

from fastapi import FastAPI, Query
from pydantic.v1 import Required

app = FastAPI()


@app.get("/items/")
async def read_items(q: Union[str, None] = None):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

在上述示例中，查询参数 q 的类型为 str，默认值为 None，因此它是可选的。可运行代码文件 chapter05.py 来启动应用：

$ uvicorn chapter05:app --reload

在 SwaggerUI 中可以查看在线文档：http://127.0.0.1:8000/docs 。

二 参数的额外校验

@app.get("/items02/")
async def read_items(q: Union[str, None] = Query(default=None, max_length=50)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

给查询参数 q 增加约束条件，该参数 max_length=50 即不能超过50个字符的长度：Query(default=None, max_length=50)。 Query 用作查询参数的默认值，使用 Query(default=None) 替换默认值 None。参数 q 为可选参数。

q: Union[str, None] = Query(default=None)

等同于：

q: str = None

完整的校验参数：

q: Union[str, None] = Query(default=None, max_length=50)

超过 50 字符长度，返回 422 错误码，错误信息如下：

{
  "detail": [
    {
      "type": "string_too_long",
      "loc": [
        "query",
        "q"
      ],
      "msg": "String should have at most 50 characters",
      "input": "超过50字符长的字符串",
      "ctx": {
        "max_length": 50
      }
    }
  ]
}

三 添加 min_length 校验

@app.get("/items03/")
async def read_items(
        q: Union[str, None] = Query(default=None, min_length=3, max_length=50),
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

四 添加正则表达式校验

@app.get("/items04/")
async def read_items(
        q: Union[str, None] = Query(
            default=None, min_length=3, max_length=50, pattern="^fixedquery$"
        ),
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

正则表达式 pattern="^fixedquery$" 用于限制 q 的值必须严格为 "fixedquery"。这里的 ^ 和 $ 是正则表达式的锚点，分别表示字符串的开始和结束，确保除了 "fixedquery" 之外不接受任何其他字符。

五 添加默认值

可以向 Query 的第一个参数传入默认值，并将查询参数 q的元数据 min_length 设置为 3，默认值为 fixedquery，例如：

@app.get("/items05/")
async def read_items(q: str = Query(default="fixedquery", min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

使用 Query 中的 default 设置默认值为 fixedquery ，具有默认值还会使该参数成为可选参数。

六 声明为必要参数

q 参数不声明任何默认值则它成为必要参数，例如：

q: str
1 使用 Query 声明

使用 Query 声明一个必要参数：

@app.get("/items06/")
async def read_items(q: str = Query(min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results
2 使用 (…) 声明

显式的将默认参数的默认值设为 ... ：

@app.get("/items07/")
async def read_items(q: str = Query(default=..., min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

“...” 是一个特殊的单独值，它是 Python 的一部分，被称为 Ellipsis(省略号)，FastAPI 会识别此查询参数是必要的。

3 使用None声明

声明None是一个有效的类型，并仍然使用default=...，这时查询参数仍然是一个必要参数：

@app.get("/items08/")
async def read_items(q: Union[str, None] = Query(default=..., min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Pydantic 文档中有关必要可选字段的信息。不习惯使用 ... ，也可以从 Pydantic 导入并使用 Required：

@app.get("/items09/")
async def read_items(q: str = Query(default=Required, min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

一般情况下如果参数必须，那么省略 default 参数就好了。

七 查询参数列表 / 多个值

1 无默认值

使用 Query 显式地定义查询参数时，它可以接收多个值。

@app.get("/items10/")
async def read_items(q: Union[List[str], None] = Query(default=None)):
    query_items = {"q": q}
    return query_items

在路径操作函数的函数参数q中，通过Python list形式接收查询参数q的多个值。当HTTP请求中查询参数q出现多次时，该参数会以列表形式传入。输入如下网址：

http://localhost:8000/items10/?q=foo&q=bar

注：要声明类型为 list 的查询参数，如前例所示，你需要显式使用 Query；否则，系统会将该参数解释为请求体。

2 有默认值
@app.get("/items11/")
async def read_items(q: List[str] = Query(default=["foo", "bar"])):
    query_items = {"q": q}
    return query_items

如果访问：

http://localhost:8000/items11/

响应会返回默认值。

3 使用 list 简写

使用 list 代替 List [str]：

@app.get("/items12/")
async def read_items(q: list = Query(default=[])):
    query_items = {"q": q}
    return query_items

注：在这种情况下，FastAPI 不会验证列表内容，例如，使用 List[str] 时不会检查列表中的元素是否为字符串。

八 声明更多元数据

@app.get("/items13/")
async def read_items(
        q: Union[str, None] = Query(
            default=None,
            alias="item-query",
            summary="API 的简短摘要",
            title="API 的标题",
            description="API 的简短描述",
            min_length=3,
            max_length=50,
            pattern="^fixedquery$",
            deprecated=True,
        ),
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

参数列表

参数类型描述
titlestrAPI 的标题。
summarystrAPI 的简短摘要。 自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。.
descriptionstrAPI 的简短描述。可以使用Markdown。
aliasstr参数别名，该别名将用于在 URL 中查找查询参数值。
deprecatedstrdeprecated=True 弃用参数，保留一段时间后弃用。

Swagger UI 文档展示

在这里插入图片描述

如图所示，元数据加载的信息较少，说明当前版本的 FastAPI 对 OpenAPI 的支持还不够完善。

九 完整代码示例

from typing import Union, List

from fastapi import FastAPI, Query
from pydantic.v1 import Required

app = FastAPI()


@app.get("/items/")
async def read_items(q: Union[str, None] = None):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results


@app.get("/items02/")
async def read_items(q: Union[str, None] = Query(default=None, max_length=50)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results


@app.get("/items03/")
async def read_items(
        q: Union[str, None] = Query(default=None, min_length=3, max_length=50),
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results


@app.get("/items04/")
async def read_items(
        q: Union[str, None] = Query(
            default=None, min_length=3, max_length=50, pattern="^fixedquery$"
        ),
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results


@app.get("/items05/")
async def read_items(q: str = Query(default="fixedquery", min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results


@app.get("/items06/")
async def read_items(q: str = Query(min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results


@app.get("/items07/")
async def read_items(q: str = Query(default=..., min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results


@app.get("/items08/")
async def read_items(q: Union[str, None] = Query(default=..., min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results


@app.get("/items09/")
async def read_items(q: str = Query(default=Required, min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results


@app.get("/items10/")
async def read_items(q: Union[List[str], None] = Query(default=None)):
    query_items = {"q": q}
    return query_items


@app.get("/items11/")
async def read_items(q: List[str] = Query(default=["foo", "bar"])):
    query_items = {"q": q}
    return query_items


@app.get("/items12/")
async def read_items(q: list = Query(default=[])):
    query_items = {"q": q}
    return query_items


@app.get("/items13/")
async def read_items(
        q: Union[str, None] = Query(
            default=None,
            alias="item-query",
            summary="API 的简短摘要",
            title="API 的标题",
            description="API 的简短描述",
            min_length=3,
            max_length=50,
            pattern="^fixedquery$",
            deprecated=True,
        ),
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

十 源码地址

详情见：GitHub FastApiProj

引用： FastAPI 文档

标签：None,items,校验,results,item,详解,FastAPI,Query,id
From： https://blog.csdn.net/u014394049/article/details/143597748

相关文章

  • glibc 内存分配与释放机制详解
    作者：来自vivo互联网存储团队-WangYuzhi本文以一次线上故障为基础介绍了使用glibc进行内存管理可能碰到问题，进而对库中内存分配与释放机制进行分析，最后提供了相应问题的解决方案。一、引言内存对象的分配与释放一直是后端开发人员代码设计中需要考虑的问题，考虑不周极易......
  • 【命令操作】Linux三剑客之sed详解 _ 统信 _ 麒麟 _ 方德
    原文链接：【命令操作】Linux三剑客之sed详解|统信|麒麟|方德Hello，大家好啊！今天带来一篇关于Linux三剑客之sed命令详解的文章。sed是一款功能强大的流编辑器，它可以在命令行中快速处理文本，支持替换、插入、删除等操作，特别适合用于处理大型文件或批量文本处理任务。本文......
  • MySQL索引详解
    MySQL索引详解索引介绍索引是一种用于快速查询和检索数据的数据结构，其本质可以看成是一种排序好的数据结构。索引的作用就相当于书的目录。打个比方:我们在查字典的时候，如果没有目录，那我们就只能一页一页的去找我们需要查的那个字，速度很慢。如果有目录了，我们只需要先去目录里......
  • HC-SR04超声波传感器详解（STM32）
    HC-SR04是一款广泛使用的超声波传感器，它通过发射和接收超声波来测量距离。本文将详细介绍HC-SR04的工作原理、引脚描述、STM32的接线方式以及如何通过STM32控制HC-SR04来测量距离。一、HC-SR04传感器介绍HC-SR04超声波传感器的主要参数如下：工作电压：DC5V工作电流：3.3mA工......
  • 阅文批示与资产管理系统数据库设计详解
    阅文批示与资产管理系统数据库设计详解项目背景：为了提升文件处理及资产管理的效率，该系统设计了完善的数据库结构，以满足不同角色的需求。通过记录文件的审批、传阅、资产交易等过程，实现了文件和资产的全生命周期管理。数据库表结构概述系统数据库包含用户、文件、资产、通知等多......
  • Oracle OCP认证考试考点详解082系列14
    题记：本系列主要讲解OracleOCP认证考试考点（题目），适用于19C/21C,跟着学OCP考试必过。66.第66题：题目解析及答案：关于撤销（UNDO）和撤销表空间（UNDOTABLESPACE），以下哪两个陈述是正确的？A.一个撤销表空间可能仅由一个实例所拥有。B.撤销段由SYSBACKUP所拥有。C.撤销段由......
  • 大数据学习笔记 第5天 ZooKeeper 3.6.3安装部署 CAP原则 Paxos算法 ZAB协议详解
    ZooKeeper3.6.3重点CAP原则Paxos算法存储模型和监听机制一、集群与分布式集群：将一个任务部署在多个服务器，每个服务器都能独立完成该任务。分布式：将一个任务拆分成若干个子任务，由若干个服务器分别完成这些子任务，每个服务器只能完成某个特定的子任务。从概念上就可......
  • 操作符详解（上）
    1.操作符的分类 2.移位操作符3.位操作符4.单目操作符5.逗号表达式6.下标访问，函数调用操作符7.结构体成员访问操作符                  一.操作符的分类  二.移位操作符2.1 左移操作符（<<）移位规则：左边抛弃，右边补0如上......
  • Day31--构造器详解
    Day31--构造器详解使用new关键字创建对象。使用new关键字创建的时候，除了分配内存空间之外，还会给创建好的对象进行默认的初始化以及对类中构造器的调用。类中的构造器也称为构造方法，是在进行创建对象的时候必须要调用的。并且构造器有以下两个特点：必须和类的名字相同；\2.......
  • TCP Fast Open 详解
    TCPFastOpen详解TCPFastOpen（TFO）是对传输控制协议（TCP）的一种扩展，用于加快两个端点之间连续TCP连接的打开速度。以下是关于TCPFASTOPEN的详细介绍：产生背景和目的：在传统的TCP三次握手过程中，建立连接需要一个完整的往返时间（RoundTripTime，RTT），这对于一些对延迟敏感......

赞助商

阅读排行

网站主页关于我们联系我们网站地图

本网站内容转载自其他媒体，侵权联系[admin##ips99.com]。

Copyright © 2020-2023 IPS99 版权所有 IPS99