基于Pydantic封装的通用模型在API请求验证中的应用

4,410 阅读4分钟

引言

Pydantic 是一个用于数据验证和解析的流行库,经常被用于 FastAPI 和其他现代 Python 项目中。在处理 API 请求时,我们经常需要对请求参数进行有效性检查,例如日期范围、分页和排序等。在本文中,我们将介绍如何在 Pydantic 中使用 Mixin 和组合模式来实现这些功能,并讨论它们的优缺点。

通用model

首先,我们定义了以下几个基础的 Pydantic 模型:

  1. DateModel:用于表示日期范围,包含开始日期和结束日期。
  2. OrderModel:用于表示排序参数,包含排序字段和排序方式(升序或降序)。
  3. PageModel:用于表示分页参数,包含页码和每页数量。
#!/usr/bin/python3
# -*- coding: utf-8 -*-
# @author: hui
# @Desc: { 通用的一些Pydantic模型 }
# @Date: 2023/03/30 11:57
from pydantic import BaseModel, Field, validator
from typing import Optional
from datetime import date


class DateModel(BaseModel):
    """日期模型"""

    start_date: Optional[date] = Field(None, description="开始日期")
    end_date: Optional[date] = Field(None, description="结束日期")

    @validator("end_date", always=True)
    def validate_end_date(cls, end_date, values):
        start_date = values.get("start_date")
        if all([start_date, end_date]) and end_date < start_date:
            raise ValueError("结束日期必须大于等于开始日期")
        return end_date


class OrderModel(BaseModel):
    """排序模型"""

    order_by: Optional[str] = Field(None, description="排序字段,逗号分隔")
    order_mode: Optional[str] = Field(None, description="排序方式,逗号分隔,asc升序desc降序")

    @validator("order_by", "order_mode", always=True)
    def split_comma_separated_string(cls, value):
        if value:
            return value.split(",")
        return value

    @validator("order_mode", always=True)
    def check_length(cls, order_mode, values):
        order_by = values.get("order_by")
        if order_by and order_mode and len(order_by) != len(order_mode):
            raise ValueError("order_by and order_mode must have the same length")
        return order_mode


class PageModel(BaseModel):
    """分页模型"""

    page: Optional[int] = Field(default=1, ge=1, description="页码")
    page_size: Optional[int] = Field(default=10, le=1000, description="每页数量, 默认10,最大1000")

接下来,我们通过混入(Mixin)和组合两种不同的方式将这些基础模型应用到一个实际的 API 请求中。

Mixin 模式

DateOrderModelMixin 类通过多重继承的方式继承了 DateModel 和 OrderModel。这种方式的优点是简单易懂,可以实现代码重用。然而,它也可能导致类层次结构变得复杂,尤其是当有多个 Mixin 之间存在依赖关系时。

class DateOrderModelMixin(DateModel, OrderModel):
    """日期与排序模型Mixin"""
    pass

组合模式

PageOrderModel 类通过组合的方式将 OrderModel 和 PageModel 作为它的属性。在初始化方法中,我们将请求参数映射到这两个模型,并调用基类的初始化方法。

组合模式的优点是代码结构更清晰,易于维护和扩展。但是,它可能需要编写更多的代码来将功能委托给组合的组件。

class PageOrderModel(BaseModel):
    """分页排序模型"""

    order_model: OrderModel = Field(OrderModel(), description="排序模型")
    page_model: PageModel = Field(PageModel(), description="分页模型")
    
    def __init__(self, **data):
        if "order_model" in data and "page_model" in data:
            order_model = data.pop("order_model", None)
            page_model = data.pop("page_model", None)
        else:
            # 用于直接平铺的字典入参
            order_params = {
                "order_by": data.pop("order_by", None),
                "order_mode": data.pop("order_mode", None),
            }
            page_params = {
                "page": data.pop("page", None),
                "page_size": data.pop("page_size", None),
            }
            order_model = OrderModel(**order_params)
            page_model = PageModel(**page_params)
        super().__init__(order_model=order_model, page_model=page_model, **data)
        
page_order = PageOrderModel(
    order_model=OrderModel(order_by="field1,field2", order_mode="asc,desc"),
    page_model=PageModel(page=1, page_size=10)
)

>>>out
order_model=OrderModel(order_by=['field1', 'field2'], order_mode=['asc', 'desc'])
page_model=PageModel(page=1, page_size=10)

req_params = {
    "order_by": "field1,field2",
    "order_mode": "asc,desc",
    "page": 1,
    "page_size": 10
}

req_model = PageOrderModel(**req_params)

>>>out
order_model=OrderModel(order_by=['field1', 'field2'], order_mode=['asc', 'desc'])
page_model=PageModel(page=1, page_size=10)

再来几个业务逻辑模型继承 DateOrderModelMixin 和 PageOrderModel 然后模拟一些请求参数去验证

让我们创建两个业务逻辑模型,一个用于查询商品信息,另一个用于查询订单信息。这两个模型分别继承 DateOrderModelMixin 和 PageOrderModel

from pydantic import BaseModel, Field
from typing import Optional

class ProductQueryModel(DateOrderModelMixin):
    product_category: Optional[str] = Field(None, description="商品类别")


class OrderQueryModel(PageOrderModel):
    customer_id: Optional[int] = Field(None, description="客户ID")


# 使用 ProductQueryModel 进行参数验证
product_query_params = {
    "start_date": "2023-04-01",
    "end_date": "2023-04-30",
    "order_by": "price",
    "order_mode": "desc",
    "product_category": "Electronics"
}

product_query = ProductQueryModel(**product_query_params)

>>>out
order_by=['price'] order_mode=['desc'] start_date=datetime.date(2023, 4, 1) end_date=datetime.date(2023, 4, 30) product_category='Electronics'


# 使用 OrderQueryModel 进行参数验证
order_query_params = {
    "start_date": "2023-04-01",
    "end_date": "2023-04-30",
    "order_by": "order_date",
    "order_mode": "asc",
    "page": 1,
    "page_size": 20,
    "customer_id": 12345
}

order_query = OrderQueryModel(**order_query_params)

>>>out
order_model=OrderModel(order_by=['order_date'], order_mode=['asc']) page_model=PageModel(page=1, page_size=20) customer_id=12345

这里的 ProductQueryModel 和 OrderQueryModel 分别用于处理商品查询和订单查询的请求参数。ProductQueryModel 继承自 DateOrderModelMixin,因此它具有日期范围和排序功能。OrderQueryModel 则继承自 PageOrderModel,具有分页和排序功能。

通过这两个模型,我们可以轻松地验证和解析传入的请求参数。在上面的示例代码中,我们分别创建了 product_query_params 和 order_query_params 字典来模拟请求参数,并使用 ProductQueryModel 和 OrderQueryModel 进行验证。可以看到,这两个模型成功解析了请求参数,并对日期范围、排序和分页进行了验证。

结论

在处理Pydantic模型时,根据具体的业务场景和需求来选择组合或Mixin模式。

Mixin模式适用于简单的继承关系,代码简洁易懂;组合模式适用于复杂的类关系,提供更好的灵活性和扩展性。在实际项目中,可以根据需求灵活选择这两种模式,或者根据情况将它们结合使用。

在实践中,如果需要将多个通用功能混合到一个业务逻辑模型中,Mixin模式可能是一个更好的选择,因为它可以让我们轻松地将这些功能组合在一起。然而,当我们需要对这些功能进行更精细的控制,或者在多个业务逻辑模型之间共享某些功能时,组合模式可能会更合适。

总之,在处理Pydantic模型时,我们应根据项目的实际需求和场景来权衡这两种模式的优缺点,从而做出合适的选择。这里的入参校验感觉使用多继承会更简单点,但到一些复杂的业务逻辑处理时可以使用组合模式,来做到更好的维护与扩展。

由于 GET 请求的入参不太好定义数据结构,减少的代码冗余就想到了多继承来组合属性和方法,如果使用 POST 请求传递 json 数据入参就可以更好设计参数结构,这时使用组合的方式hui更好。

杂谈

go的结构体嵌套就有点像组合

type Address struct {
    Street string
    City   string
    State  string
    Zip    string
}

type Person struct {
    Name    string
    Age     int
    Address Address
}

通过结构体的组合,可以方便地组合多个不同的数据结构,构建出更加复杂的结构体。这种组合方式可以让代码更加灵活和可维护,同时也可以提高代码的可读性和可重用性。

本文正在参加「金石计划」