Django Ninja查询参数验证终极指南：范围检查与格式验证详解

Django Ninja查询参数验证终极指南：范围检查与格式验证详解

【免费下载链接】django-ninja 💨 Fast, Async-ready, Openapi, type hints based framework for building APIs 项目地址: https://gitcode.com/gh_mirrors/dj/django-ninja

Django Ninja 是一个基于类型提示的快速API框架，它为查询参数验证提供了强大的支持。通过类型注解和Pydantic模型，开发者可以轻松实现参数的范围检查和格式验证，确保API接口的健壮性和安全性。💪

什么是查询参数验证？

查询参数验证是确保API接收到的查询参数符合预期格式和范围的重要机制。在Django Ninja中，查询参数验证通过Python类型提示和Pydantic字段验证器实现。

基础验证类型

1. 数值范围验证

Django Ninja支持对数值参数进行范围检查，确保参数值在合理范围内：

from ninja import NinjaAPI

api = NinjaAPI()

@api.get("/products")
def list_products(request, price_min: int = 0, price_max: int = 10000):
    # price_min 和 price_max 自动验证为整数
    # 默认值确保参数始终有效
    return {"message": f"查询价格范围 {price_min} - {price_max}"}

2. 字符串格式验证

对于字符串参数，可以使用正则表达式或枚举进行格式验证：

from enum import Enum
from ninja import NinjaAPI

class StatusEnum(Enum):
    ACTIVE = "active"
    INACTIVE = "inactive"

api = NinjaAPI()

@api.get("/users")
def list_users(request, status: StatusEnum, email: str = None):
    # status 必须是 "active" 或 "inactive"
    # email 可选，但必须符合邮箱格式
    return {"status": status.value}

使用Schema进行高级验证

Django Ninja支持使用Pydantic Schema封装复杂的查询参数：

from pydantic import Field, validator
from ninja import Query, Schema

class ProductFilters(Schema):
    limit: int = Field(10, ge=1, le=100)  # 1-100范围
    offset: int = Field(0, ge=0)  # 必须大于等于0
    category: str = Field(None, min_length=1, max_length=50)
    price_range: str = Field(None, regex=r'^\d+-\d+$')
    
    @validator('price_range')
    def validate_price_range(cls, v):
        if v:
            min_price, max_price = map(int, v.split('-'))
            if min_price > max_price:
                raise ValueError('最小价格不能大于最大价格')
        return v

@api.get("/products")
def list_products(request, filters: Query[ProductFilters]):
    return {"filters": filters.dict()}

实际应用场景

分页参数验证

class PaginationParams(Schema):
    page: int = Field(1, ge=1, description="页码")
    page_size: int = Field(20, ge=1, le=100, description="每页数量")

搜索过滤验证

class SearchFilters(Schema):
    query: str = Field(..., min_length=1, max_length=100)
    sort_by: str = Field("created_at", regex=r'^(created_at|price|name)$')

验证错误处理

Django Ninja自动处理验证错误，返回清晰的错误信息：

{
  "detail": [
    {
      "loc": ["query", "filters", "limit"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.not_le"
    }
  ]
}

最佳实践建议

1. 始终使用类型注解 - 即使参数有默认值
2. 合理设置范围限制 - 避免过大或过小的取值范围
3. 提供清晰的错误信息 - 帮助前端开发者快速定位问题
4. 使用Schema封装复杂逻辑 - 提高代码可维护性

Django Ninja的查询参数验证机制让API开发变得更加安全和高效。通过合理的验证规则设置，可以有效防止恶意请求和数据异常，提升整个系统的稳定性。🚀

通过本文的介绍，相信您已经掌握了Django Ninja查询参数验证的核心技巧。开始使用这些验证功能，让您的API更加健壮可靠！

【免费下载链接】django-ninja 💨 Fast, Async-ready, Openapi, type hints based framework for building APIs 项目地址: https://gitcode.com/gh_mirrors/dj/django-ninja