Django 结合 Pydantic 实现 JSONField 强类型校验教程_阿奇CMS

在 Django 开发中，`JSONField` 以其灵活性被广泛用于存储非结构化数据（如接口请求参数、配置信息等），但原生 `JSONField` 缺乏强类型校验，容易导致数据格式混乱、业务逻辑异常。而 Pydantic 作为 Python 生态中最流行的数据校验库，能通过强类型定义、自动校验和结构化转换，解决 JSON 数据的规范性问题。

## 一、教程简介
在 Django 开发中，`JSONField` 以其灵活性被广泛用于存储非结构化数据（如接口请求参数、配置信息等），但原生 `JSONField` 缺乏强类型校验，容易导致数据格式混乱、业务逻辑异常。而 Pydantic 作为 Python 生态中最流行的数据校验库，能通过强类型定义、自动校验和结构化转换，解决 JSON 数据的规范性问题。

本教程将通过「基础方案」和「进阶方案」两种实践路径，带你掌握 Django 与 Pydantic 的结合方式，让 `JSONField` 兼具灵活性与强类型安全性。教程内容贴合实际业务场景（如 OpenAI 转发平台的请求参数存储），代码可直接复用。

## 二、前置准备
### 1. 环境依赖
确保已安装以下依赖（推荐最新稳定版）：
```bash
# Django 框架（3.2+ 版本兼容 JSONField）
pip install django>=3.2
# Pydantic（v2 版本语法更简洁，推荐使用）
pip install pydantic>=2.0
```

### 2. 项目初始化（可选）
若从零开始，执行以下命令创建 Django 项目和应用：
```bash
# 创建项目
django-admin startproject django_pydantic_demo
cd django_pydantic_demo
# 创建应用
python manage.py startapp api
```
在 `settings.py` 中注册应用：
```python
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # 注册自定义应用
    'api',
]
```

## 三、基础方案：手动结合 Pydantic 校验（入门友好）
基础方案通过「Django 模型存储 + Pydantic 手动校验」的方式，实现 JSON 数据的结构化管理，适合中小项目或快速迭代场景，低侵入、易维护。

### 1. 步骤 1：定义 Django 模型（JSONField 存储）
在应用的 `models.py` 中定义包含 `JSONField` 的模型，用于存储非结构化数据（以 OpenAI 请求参数存储为例）：
```python
# api/models.py
from django.db import models

class OpenAIRequest(models.Model):
    """
    OpenAI 转发请求记录表
    用于存储接口请求参数、响应结果等非结构化数据
    """
    # 原生 JSONField，负责数据存储
    request_params = models.JSONField(
        verbose_name="请求参数",
        blank=True,
        default=dict,  # 默认空字典，避免 None 引发的问题
        help_text="存储 OpenAI 接口的请求参数，如 model、messages 等"
    )
    response_result = models.JSONField(
        verbose_name="响应结果",
        blank=True,
        default=dict
    )
    created_at = models.DateTimeField(verbose_name="创建时间", auto_now_add=True)

class Meta:
        db_table = "openai_request_record"
        verbose_name = "OpenAI 请求记录"
        verbose_name_plural = verbose_name

def __str__(self):
        return f"请求记录（ID：{self.id}）"
```

### 2. 步骤 2：定义 Pydantic 模型（强类型校验）
在应用中创建 `schemas.py` 文件，定义与业务对应的 Pydantic 模型，实现 JSON 数据的强类型校验和结构化：
```python
# api/schemas.py
from pydantic import BaseModel, EmailStr, field_validator, ValidationError
from typing import Optional, List, Dict
import re

# 1. 定义子模型（OpenAI 消息格式）
class OpenAIMessage(BaseModel):
    role: str  # 消息角色：user/assistant/system
    content: str  # 消息内容

@field_validator("role")
    def validate_role(cls, value):
        """校验消息角色合法性"""
        valid_roles = ["user", "assistant", "system"]
        if value not in valid_roles:
            raise ValueError(f"消息角色必须是 {valid_roles} 中的一种")
        return value

# 2. 定义核心请求参数模型
class OpenAIRequestParams(BaseModel):
    model: str  # 模型名称，如 gpt-3.5-turbo
    messages: List[OpenAIMessage]  # 对话消息列表
    stream: Optional[bool] = False  # 是否流式输出
    temperature: Optional[float] = 1.0  # 温度系数
    customer_email: Optional[EmailStr] = None  # 客户邮箱（自动校验格式）
    customer_phone: Optional[str] = None  # 客户手机号（自定义校验）

# 手机号格式校验（国内 11 位手机号）
    @field_validator("customer_phone", mode="after")
    def validate_phone(cls, value):
        if value is not None:
            phone_pattern = re.compile(r"^1[3-9]\d{9}$")
            if not phone_pattern.match(value):
                raise ValueError("手机号格式错误，请输入国内11位手机号（如：13800138000）")
        return value

# 空字符串转 None（兼容前端传参）
    @field_validator("customer_email", "customer_phone", mode="before")
    def empty_str_to_none(cls, value):
        return None if value == "" else value
```

### 3. 步骤 3：数据存入/取出的校验与转换
在视图或服务层，通过 Pydantic 模型对 `JSONField` 数据进行校验和转换，确保数据合法性。

#### （1）存入数据：先校验再存储
```python
# api/services.py（推荐使用服务层封装业务逻辑）
from .models import OpenAIRequest
from .schemas import OpenAIRequestParams
from pydantic import ValidationError

def create_openai_request(params: dict):
    """创建 OpenAI 请求记录（先校验再存储）"""
    try:
        # 1. Pydantic 校验参数合法性
        validated_params = OpenAIRequestParams(**params)
        # 2. 转换为字典存入 JSONField
        request_record = OpenAIRequest.objects.create(
            request_params=validated_params.model_dump()  # Pydantic 实例 → 字典
        )
        return request_record
    except ValidationError as e:
        # 捕获校验错误，返回标准化提示
        error_msg = f"参数校验失败：{e.errors()}"
        raise ValueError(error_msg)
```

#### （2）取出数据：转换为 Pydantic 实例（结构化）
```python
def get_openai_request(request_id: int) -> OpenAIRequestParams:
    """获取请求记录，并转换为 Pydantic 实例"""
    request_record = OpenAIRequest.objects.get(id=request_id)
    # 将 JSONField 的字典解析为 Pydantic 实例，方便结构化调用
    return OpenAIRequestParams(**request_record.request_params)
```

#### （3）测试基础方案
```python
# 测试合法参数
valid_params = {
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": True,
    "customer_email": "test@example.com",
    "customer_phone": "13800138000"
}
create_openai_request(valid_params)  # 成功存入

# 测试非法参数（邮箱格式错误）
invalid_params = {
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "你好"}],
    "customer_email": "test.example.com"  # 非法邮箱
}
try:
    create_openai_request(invalid_params)
except ValueError as e:
    print(e)  # 输出：参数校验失败：[{'type': 'value_error', 'loc': ('customer_email',), ...}]
```

## 四、进阶方案：自定义 PydanticJSONField（自动校验）
进阶方案通过自定义 Django 字段，实现「存入/取出 JSONField 时自动触发 Pydantic 校验」，无需手动调用 Pydantic 模型，适合大型项目或需要批量复用的场景，减少重复代码。

### 1. 步骤 1：自定义 PydanticJSONField
在应用中创建 `fields.py` 文件，定义继承自 Django `JSONField` 的自定义字段，内置 Pydantic 校验逻辑：
```python
# api/fields.py
from django.db import models
from pydantic import BaseModel, ValidationError

class PydanticJSONField(models.JSONField):
    """
    自定义 JSONField，支持绑定 Pydantic 模型实现自动校验/转换
    核心功能：存入时校验数据格式，取出时转换为 Pydantic 实例
    """
    def __init__(self, pydantic_model: type[BaseModel], *args, **kwargs):
        # 绑定对应的 Pydantic 模型
        self.pydantic_model = pydantic_model
        super().__init__(*args, **kwargs)

def to_python(self, value):
        """
        从前端接收数据或从数据库读取数据时，转换为 Pydantic 实例
        :param value: 原始数据（字典/JSON 字符串）
        """
        # 先调用父类方法，将数据库的 JSON 转为 Python 字典
        value = super().to_python(value)
        if value is None:
            return None
        # 转换为 Pydantic 实例，触发校验
        try:
            return self.pydantic_model(**value)
        except ValidationError as e:
            raise ValidationError(f"数据格式不符合要求：{e.errors()}")

def from_db_value(self, value, expression, connection):
        """从数据库读取值时，自动转换为 Pydantic 实例"""
        value = super().from_db_value(value, expression, connection)
        if value is None:
            return None
        return self.pydantic_model(**value)

def get_prep_value(self, value):
        """存入数据库前，将 Pydantic 实例转为字典"""
        if isinstance(value, BaseModel):
            # Pydantic 实例 → 字典（自动忽略未定义字段）
            return value.model_dump()
        elif isinstance(value, dict):
            # 字典先校验，再存入
            self.pydantic_model(**value)
            return value
        return super().get_prep_value(value)

def value_to_string(self, obj):
        """Django Admin 等场景下的字符串转换"""
        value = self.value_from_object(obj)
        if isinstance(value, BaseModel):
            return value.model_dump_json()  # 转为 JSON 字符串
        return super().value_to_string(obj)
```

### 2. 步骤 2：在 Django 模型中使用自定义字段
修改 `models.py`，将原生 `JSONField` 替换为自定义的 `PydanticJSONField`，并绑定对应的 Pydantic 模型：
```python
# api/models.py
from django.db import models
from .fields import PydanticJSONField
from .schemas import OpenAIRequestParams

class OpenAIRequestAdvanced(models.Model):
    """
    进阶版 OpenAI 请求记录表（使用自定义 PydanticJSONField）
    """
    # 绑定 Pydantic 模型，自动校验/转换
    request_params = PydanticJSONField(
        pydantic_model=OpenAIRequestParams,
        verbose_name="请求参数",
        blank=True,
        default=dict,
        help_text="自动校验参数格式，不符合要求会抛出错误"
    )
    created_at = models.DateTimeField(verbose_name="创建时间", auto_now_add=True)

class Meta:
        db_table = "openai_request_advanced"
        verbose_name = "进阶版 OpenAI 请求记录"
        verbose_name_plural = verbose_name

def __str__(self):
        return f"进阶请求记录（ID：{self.id}）"
```

### 3. 步骤 3：测试进阶方案（自动校验）
使用自定义字段后，存入/取出数据时会自动触发 Pydantic 校验和转换，无需手动调用：
```python
# 测试存入数据（自动校验）
valid_params = {
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": True
}
# 自动校验并存储
request_record = OpenAIRequestAdvanced.objects.create(request_params=valid_params)

# 测试取出数据（自动转为 Pydantic 实例）
request = OpenAIRequestAdvanced.objects.get(id=request_record.id)
print(type(request.request_params))  # <class 'api.schemas.OpenAIRequestParams'>
print(request.request_params.model)  # gpt-3.5-turbo
print(request.request_params.stream)  # True

# 测试存入非法数据（自动报错）
invalid_params = {
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "invalid_role", "content": "你好"}],  # 非法角色
    "customer_phone": "123456"  # 非法手机号
}
try:
    OpenAIRequestAdvanced.objects.create(request_params=invalid_params)
except ValidationError as e:
    print(e)  # 输出：数据格式不符合要求：[{'type': 'value_error', 'loc': ('messages', 0, 'role'), ...}]
```

## 五、关键注意事项
### 1. Django Admin 适配
自定义 `PydanticJSONField` 在 Django Admin 中编辑时，需确保输入的 JSON 符合 Pydantic 模型要求，否则会触发校验错误。若需更友好的编辑体验，可自定义 Admin 表单字段：
```python
# api/admin.py
from django.contrib import admin
from .models import OpenAIRequestAdvanced
from django import forms
from pydantic import ValidationError

class OpenAIRequestAdminForm(forms.ModelForm):
    class Meta:
        model = OpenAIRequestAdvanced
        fields = "__all__"

def clean_request_params(self):
        """自定义表单校验，返回更友好的错误提示"""
        data = self.cleaned_data.get("request_params")
        try:
            # 手动触发 Pydantic 校验
            OpenAIRequestParams(**data)
        except ValidationError as e:
            raise forms.ValidationError(f"参数格式错误：{e.errors()}")
        return data

@admin.register(OpenAIRequestAdvanced)
class OpenAIRequestAdvancedAdmin(admin.ModelAdmin):
    form = OpenAIRequestAdminForm
    list_display = ("id", "created_at")
```

### 2. 空值与默认值处理
- Pydantic 模型中，可选字段建议设置 `default=None`，避免 `JSONField` 存储 `None` 时触发校验错误；
- Django 模型的 `JSONField` 建议设置 `default=dict`，而非 `default=None`，减少空值判断逻辑。

### 3. 性能考量
自定义字段每次存入/取出都会触发 Pydantic 校验，对高频读写场景，可优化为「仅写入时校验」：
```python
# 优化 fields.py 中的 from_db_value 方法，仅返回字典
def from_db_value(self, value, expression, connection):
    value = super().from_db_value(value, expression, connection)
    return value  # 直接返回字典，不转换为 Pydantic 实例
```
读取时按需解析为 Pydantic 实例：
```python
request = OpenAIRequestAdvanced.objects.get(id=1)
params = OpenAIRequestParams(**request.request_params)  # 手动解析
```

### 4. 迁移兼容性
自定义 `PydanticJSONField` 本质继承自 Django `JSONField`，数据库存储格式完全一致，因此无需修改迁移文件，可直接替换原生 `JSONField`，兼容现有数据。

### 5. Pydantic 版本兼容
- Pydantic v2：使用 `model_dump()`（转为字典）、`model_dump_json()`（转为 JSON 字符串）；
- Pydantic v1：将 `model_dump()` 改为 `dict()`，`model_dump_json()` 改为 `json()` 即可。

## 六、教程总结
本教程通过两种方案实现了 Django 与 Pydantic 的结合，解决了 `JSONField` 强类型校验的问题：
1. **基础方案**：手动结合 Pydantic 校验，适合中小项目，简单易理解，无需修改 Django 原生逻辑；
2. **进阶方案**：自定义字段自动校验/转换，适合大型项目，减少重复代码，提升开发效率。

两种方案的核心逻辑都是「Django 负责存储，Pydantic 负责校验」，既保留了 `JSONField` 的灵活性，又通过强类型定义提升了数据可靠性，特别适合需要存储非结构化业务数据（如接口请求参数、配置信息）的场景。

Django 结合 Pydantic 实现 JSONField 强类型校验教程

搜索

热门推荐

最好用的vue拖拽组件vuedraggable在vue2和3下的使用

记录axios上传到阿里云OSS的两个小坑

Python使用PIL把一段文字完美像word一样排版

【开源】用于uni-app通过命令行打包自动上传到微信小程序的vite插件

Django安装百度统计referrer被禁用问题解决方案

阿奇支付接口文档

FastApi的初步推荐

阿奇WebSockets公共服务文档

FastApi用户指南

Django国际化makemessages报编码错误解决方案

标签