O jsonfield é um campo de modelo reutilizável para Django, projetado para armazenar dados JSON validados, gerenciando automaticamente a serialização e desserialização entre o aplicativo e o banco de dados. Ao integrar jsonfield.JSONField em seus modelos Django, você pode atender eficientemente à necessidade de armazenar dados não estruturados, adicionando uma camada de flexibilidade ao gerenciamento de dados em seus projetos.

Instalação Rápida

Para começar a usar o jsonfield, instale-o facilmente através do pip:

pip install jsonfield

Após a instalação, você estará pronto para importar e utilizar o tipo de campo JSONField em seus projetos Django.

Uso Básico

Integrar o jsonfield em modelos Django é direto. Importe JSONField do módulo jsonfield e defina o campo em seu modelo:

from django.db import models
from jsonfield import JSONField

class MeuModelo(models.Model):
   dados = JSONField()  # Define um campo para armazenar dados não estruturados em formato JSON

Com esta definição, o Django cuidará da conversão entre os dados JSON e o banco de dados. Você poderá interagir com este campo de forma semelhante a um dicionário Python comum.

Consultas e Filtragem

Embora o jsonfield seja primariamente para armazenamento, ele suporta operações básicas de consulta. Tenha em mente que os dados são armazenados como strings JSON serializadas; testes completos são recomendados antes de aplicar consultas complexas:

# Consulta por correspondência exata
MeuModelo.objects.filter(dados__exact='{"chave": "valor"}')

# Consulta usando expressão regular
MeuModelo.objects.filter(dados__regex=r'"nome": ".*Joao.*"')

Consultas JSON mais elaboradas podem exigir a combinação com outras funcionalidades de consulta do Django ou a implementação de métodos de consulta personalizados.

Configurações Avançadas

O jsonfield oferece opções de configuração para personalizar o comportamento de serialização e desserialização de JSON:

Preservando a Ordem das Chaves

Por padrão, a desserialização JSON em Python resulta em dicionários que não mantêm a ordem das chaves. Para preservar essa ordem, utilize OrderedDict:

import collections
from jsonfield import JSONField

class MeuModelo(models.Model):
   dados_ordenados = JSONField(load_kwargs={'object_pairs_hook': collections.OrderedDict})

Codificadores Personalizados

É possível especificar um codificador JSON personalizado através do parâmetro dump_kwargs para lidar com tipos de dados específicos:

from jsonfield import JSONField
from meuapp.codificadores import CodificadorCustomizado

class MeuModelo(models.Model):
   dados_customizados = JSONField(dump_kwargs={'cls': CodificadorCustomizado})

Tratamento de Valores Nulos

O parâmetro null no jsonfield dita como os valores nulos são armazenados, com comportamento distinto dos campos padrão do Django:

• null=True: O valor nulo não é serializado e é armazenado diretamente como NULL no banco de dados.
• null=False: O valor nulo é serializado e armazenado como a string "null".

A consulta por valores nulos varia conforme a configuração:

# Funciona para ambas as configurações de null
MeuModelo.objects.filter(dados=None)

# Funciona especificamente quando null=True
MeuModelo.objects.filter(dados__isnull=True)

Para evitar o armazenamento de nulos, utilize validadores em vez de depender apenas do parâmetro null.

Outros Tipos de Campo Disponíveis

Além do JSONField padrão, o pacote oferece:

JSONCharField

Este campo herda de models.CharField do Django e é ideal para armazenar pequenas quantidades de dados JSON:

from jsonfield import JSONCharField

class MeuModelo(models.Model):
   json_curto = JSONCharField(max_length=255)  # Campo JSON com limite de comprimento

Migração para o JSONField Nativo do Django

Versões do Django a partir da 3.1 incluem um JSONField nativo com suporte para múltiplos backends de banco de dados. Para migrar:

1. Substitua jsonfield.JSONField por models.JSONField.
2. Execute python manage.py makemigrations para gerar os arquivos de migração.
3. Execute python manage.py migrate para aplicar as alterações.

Se encontrar problemas na migração direta, considere a criação de migrações de dados para converter os dados manualmente. O repositório do projeto inclui um diretório migration-example com exemplos.

Executando Testes

O projeto jsonfield possui um conjunto completo de testes que podem ser executados facilmente com o tox:

pip install tox  # Instala o tox
tox  # Executa todos os testes
tox -e py313-django52  # Executa testes para um ambiente específico