FastAPI查询参数和字符串校验

news2025/1/18 11:47:50

在FastAPI中，你可以为参数声明额外的信息和校验。这对于查询参数来说尤其有用，因为它们通常用于过滤或排序结果。本教程将引导你如何使用Query对象来添加这些额外的校验。

导入所需库

首先，你需要导入FastAPI以及Query对象：

from fastapi import FastAPI, Query

初始化应用

创建一个FastAPI实例：

app = FastAPI()

定义带有Query参数的路由

现在让我们定义一个简单的路由，它有一个名为status的查询参数。这个参数是一个字符串，用于指定返回的结果状态。我们将使用Query对象来指定一些额外的校验条件。

@app.get("/employees/")
async def read_employees(status: str = Query(default=None, max_length=10)):
    results = {"employees": [{"employee_id": "1", "name": "John Doe"}, {"employee_id": "2", "name": "Jane Smith"}]}
    if status:
        results.update({"status": status})
    return results

在这个例子中，我们设置了max_length参数为10，这意味着status参数的值不能超过10个字符。

添加更多校验

除了max_length之外，你还可以添加其他校验条件，比如min_length、regex等。下面是一个例子：

@app.get("/employees/")
async def read_employees(
    status: str = Query(default=None, min_length=3, max_length=10, regex="^[a-zA-Z_]+$")
):
    results = {"employees": [{"employee_id": "1", "name": "John Doe"}, {"employee_id": "2", "name": "Jane Smith"}]}
    if status:
        results.update({"status": status})
    return results

在这个例子中，我们添加了min_length参数，确保status参数至少有3个字符。同时，我们还添加了一个正则表达式"^[a-zA-Z_]+$"，表示status参数只能包含字母和下划线，正则表达式，几乎是我最常使用的参数验证方式，因为它实在是太强大了，有了它，几乎可以不使用其他的了，当然，需要去数据库查询再作出判断的除外，但是去数据库查询之前，一般都可以使用正则表达式进行初步的验证，这是我通常在实际开发中所使用的。

默认值和必需参数

如果你想要设置一个默认值，可以像这样使用default参数：

@app.get("/employees/")
async def read_employees(
    status: str = Query(default="active", min_length=3, max_length=10, regex="^[a-zA-Z_]+$")
):
    results = {"employees": [{"employee_id": "1", "name": "John Doe"}, {"employee_id": "2", "name": "Jane Smith"}]}
    if status:
        results.update({"status": status})
    return results

打开自动化测试文档可以看到，status参数并没有红色的*，表示它并不是必须的
在这里插入图片描述

在这个例子中，如果用户没有提供status参数，那么它的默认值将是"active"。

声明必需参数

如果你想让某个参数成为必需参数，只需不提供默认值即可。例如：

@app.get("/employees/")
async def read_employees(
    status: str = Query(min_length=3, max_length=10, regex="^[a-zA-Z_]+$")
):
    results = {"employees": [{"employee_id": "1", "name": "John Doe"}, {"employee_id": "2", "name": "Jane Smith"}]}
    if status:
        results.update({"status": status})
    return results

在这个例子中，status参数是必需的，因为没有提供默认值。
官方文档中，还有声明为...的方式来表示是必须参数，如下面的示例代码

from typing import Union

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
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

虽然可以是None，但是default中的...表示它仍然是必填参数，我们打开自动化文档测试工具就可以很明显的看到这一点
在这里插入图片描述
如果你觉得...不好理解或者很别扭，你可以用Required代替它，因为python号称最接近自然语言的编程语言，我们为什么不让程序更好懂呢。直接写成Required不是所有人都懂吗，干嘛弄成…呢，还以为是省略号呢？记住，我们写的代码别人一看就能懂，那才是牛人，而不是故意装大牛，故意让人看不懂。