Visão Geral dos Campos de Modelo no Django ORM

No Django ORM, definir os campos corretos para seus modelos é fundamental. Cada campo corresponde a uma coluna no banco de dados e possui tipos específicos e parâmetros de configuração.

Tipos de Campos Disponíveis

Abaixo estão listados os principais tipos de campo fornecidos pelo Django:

• Campos Numéricos:
  • AutoField: Um campo de auto-incremento para chaves primárias. Se não for declarado explicitamente, o Django cria automaticamente um campo id deste tipo.
  • IntegerField: Armazena números inteiros dentro de um intervalo padrão.
  • BigIntegerField: Para números inteiros de grande porte.
  • SmallIntegerField: Para números inteiros pequenos.
  • PositiveIntegerField: Inteiros positivos (incluidno zero).
  • FloatField: Para números de ponto flutuante.
  • DecimalField: Para números decimais com precisão exata. Requer os parâmetros max_digits e decimal_places.
• Campos de Texto:
  • CharField: Uma string de tamanho fixo. O parâmetro max_length é obrigatório.
  • TextField: Para strings de texto longo, sem limite de tamanho pré-definido.
  • SlugField: Um campo de texto otimizado para URLs, permitindo letras, números, hífens e sublinhados.
  • EmailField, URLField, IPAddressField: Variações de CharField com validação formatada.
• Campos de Data e Hora:
  • DateField: Armazena uma data (ano, mês, dia).
  • DateTimeField: Armazena data e hora.
  • TimeField: Armazena apenas a hora.
  • DurationField: Representa um intervalo de tempo.
• Campos de Arquivo e Caminho:
  • FileField: Salva um caminho para um arquivo enviado. Use o parâmetro upload_to.
  • ImageField: Uma extensão de FileField para imagens.
  • FilePathField: Oferece uma lista de arquivos de um diretório específico no servidor.
• Outros Campos:
  • BooleanField e NullBooleanField: Para valores booleanos.
  • UUIDField: Para armazenar identificadores universalmente únicos.
  • BinaryField: Para dados binários brutos.

Exemplo Prático de Modelo

from django.db import models
from django.core import validators

class Produto(models.Model):
    # Um campo CharField para o nome, com validação de tamanho.
    nome = models.CharField(
        max_length=100,
        verbose_name="Nome do Produto"
    )
    
    # Um campo de preço com precisão decimal.
    preco = models.DecimalField(
        max_digits=10,
        decimal_places=2
    )
    
    # Um campo de estoque usando IntegerField com validação personalizada.
    quantidade_estoque = models.PositiveIntegerField(
        default=0,
        validators=[validators.MinValueValidator(0)]
    )
    
    # Campo de texto longo para a descrição.
    descricao = models.TextField(blank=True)
    
    # Campo booleano para indicar se o produto está ativo.
    esta_ativo = models.BooleanField(default=True)
    
    # Data de criação, preenchida automaticamente ao criar o registro.
    data_criacao = models.DateTimeField(auto_now_add=True)
    
    # Campo de escolha para a categoria do produto.
    CATEGORIA_CHOICES = [
        ('EL', 'Eletrônico'),
        ('VE', 'Vestuário'),
        ('AL', 'Alimento'),
    ]
    categoria = models.CharField(
        max_length=2,
        choices=CATEGORIA_CHOICES,
        default='EL'
    )

    class Meta:
        db_table = 'produtos'  # Define um nome personalizado para a tabela no banco de dados.

Parâmetros de Configuração dos Campos

Os campos do modelo aceitam diversos parâmetros que definem seu comportamento e restrições.

Parâmetros Essenciais

• null: Se True, o Django armazenará valores vazios como NULL no banco de dados. Padrão é False.
• blank: Se True, o campo é permitido em formulários. Diferente de null, é uma validação no nível da aplicação.
• default: O valor padrão para o campo. Pode ser um valor ou um objeto callable.
• primary_key: Se True, este campo é a chave primária do modelo.
• unique: Se True, este campo deve ser único em toda a tabela.
• db_index: Se True, um índice de banco de dados será criado para este campo.
• choices: Uma sequência de tuplas de 2 elementos, usada para populas caixas de seleção no Admin e formulários.

Parâmetros Específicos do Django Admin

Estes parâmetros afetam principalmente a interface do Django Admin.

class Livro(models.Model):
    titulo = models.CharField(
        max_length=200,
        verbose_name="Título",  # Rótulo exibido no Admin.
        help_text="Insira o título completo do livro."  # Texto de ajuda.
    )
    autor = models.CharField(max_length=100, editable=False)  # Campo não editável no Admin.
    # ... outros campos

Validação e Tratamento de Erros

O Django permite a validação robusta dos dados dos modelos.

Validadores Personalizados

Use a lista validators para adicionar lógica de validação customizada.

from django.core.validators import RegexValidator, ValidationError

class Cliente(models.Model):
    # Validação com expressão regular para um código de cliente.
    codigo = models.CharField(
        max_length=10,
        unique=True,
        validators=[
            RegexValidator(
                regex=r'^CLI-\d{5}$',
                message="O código deve estar no formato 'CLI-XXXXX'.",
                code='codigo_invalido'
            )
        ]
    )
    
    # Validação customizada no método 'clean'.
    def clean(self):
        super().clean()
        # Exemplo: Validar que o primeiro caractere do nome seja maiúsculo.
        if self.nome and not self.nome[0].isupper():
            raise ValidationError({'nome': "O nome deve começar com uma letra maiúscula."})

Você também pode entegrar validações no Django Admin criando uma classe ModelForm personalizada.

# admin.py
from django.contrib import admin
from .models import Cliente
from django import forms

class ClienteAdminForm(forms.ModelForm):
    class Meta:
        model = Cliente
        fields = '__all__'
        error_messages = {
            'codigo': {
                'unique': "Já existe um cliente com este código."
            }
        }

class ClienteAdmin(admin.ModelAdmin):
    form = ClienteAdminForm

admin.site.register(Cliente, ClienteAdmin)

Campos Personalizados

É possível criar tipos de campos customizados herdando de campos existentes.

# Cria um campo que gera um código automático no formato "PROD-00001".
class CodigoAutoField(models.CharField):
    def __init__(self, *args, **kwargs):
        kwargs.setdefault('max_length', 20)
        kwargs.setdefault('editable', False)
        kwargs.setdefault('unique', True)
        super().__init__(*args, **kwargs)

    def pre_save(self, model_instance, add):
        if add:
            # Lógica para gerar o próximo código sequencial.
            ultimo = model_instance.__class__.objects.all().order_by('-id').first()
            proximo_num = 1 if not ultimo else ultimo.id + 1
            valor = f"PROD-{proximo_num:05d}"
            setattr(model_instance, self.attname, valor)
            return valor
        return super().pre_save(model_instance, add)

# Uso no modelo
class ItemEstoque(models.Model):
    codigo = CodigoAutoField()
    descricao = models.CharField(max_length=255)

Considerações Importantes

Lembre-se de que as validações definidas no modelo (validators, full_clean()) são aplicadas ao salvar via ORM com full_clean() ou ao usar formulários do Django. Operações diretas no banco de dados (raw SQL, bulk_create com ignore_conflicts) ignorarão essas validações. Para garantir a integridade, utilize restrições no nível do banco de dados (Meta.constraints).