DEV Community

Lucas Pereira de Souza
Lucas Pereira de Souza

Posted on

Design de schema GraphQL

#design #api #architecture #graphql

logotech

## Boas Práticas de Nomenclatura, Separação de Tipos e Inputs, e Versionamento de Schema: Um Guia Prático

A qualidade do código é fundamental para o sucesso de qualquer projeto de software. Um código limpo, legível e fácil de manter não apenas acelera o desenvolvimento, mas também reduz significativamente os custos a longo prazo. Neste artigo, exploraremos três áreas cruciais para alcançar esse objetivo: boas práticas de nomenclatura, separação de tipos e inputs, e versionamento de schema.

1. Boas Práticas de Nomenclatura: A Chave da Clareza

A nomenclatura é a arte de dar nomes significativos a variáveis, funções, classes e outros elementos do seu código. Nomes bem escolhidos tornam o código mais fácil de entender e manter, reduzindo a necessidade de comentários excessivos.

Dicas Essenciais:

  • Seja Descritivo: Use nomes que expliquem claramente o propósito do elemento. Evite abreviações e jargões desnecessários.
  • Consistência: Adote um padrão de nomenclatura consistente em todo o projeto. Isso facilita a leitura e compreensão do código. (Ex: camelCase para variáveis, PascalCase para classes).
  • Evite Nomes Genéricos: Evite nomes como data, value ou temp. Seja específico e use nomes que reflitam o significado real.
  • Use Verbos para Funções: Nomes de funções devem descrever o que a função faz (Ex: calcularImposto, obterUsuario).
  • Nomes de Variáveis Booleanas: Use nomes que indiquem claramente o estado booleano (Ex: isAtivo, podeEnviar).

Exemplo:

Ruim:

x = get_d()
if x > 10:
    print(\"OK\")
Enter fullscreen mode Exit fullscreen mode

Bom:

valor_total = obter_desconto()
if valor_total > 10:
    print(\"Desconto aplicado\")
Enter fullscreen mode Exit fullscreen mode

2. Separação de Tipos e Inputs: Blindando seu Código

A separação de tipos e inputs é uma prática essencial para garantir a segurança e a robustez do seu código. Ao definir claramente os tipos de dados esperados e validar os inputs, você evita erros inesperados e comportamentos indesejados.

Benefícios:

  • Prevenção de Erros: Detecta erros de tipo em tempo de desenvolvimento, evitando que se propaguem para o tempo de execução.
  • Melhoria da Legibilidade: Torna o código mais fácil de entender, pois deixa claro quais tipos de dados são esperados.
  • Validação de Dados: Garante que os inputs recebidos estejam dentro dos limites esperados, prevenindo ataques e outros problemas de segurança.

Implementação:

  • Tipagem Estática: Utilize linguagens com tipagem estática (como Java, C#, TypeScript) para definir explicitamente os tipos de dados.
  • Validação de Dados: Valide os inputs em todas as fronteiras do seu sistema (ex: API, interface do usuário). Utilize bibliotecas de validação (como pydantic em Python) para simplificar esse processo.
  • Interfaces e Contratos: Defina interfaces ou contratos claros para as interações entre diferentes partes do seu sistema. Isso ajuda a garantir que os dados sejam passados corretamente.

Exemplo (Python com pydantic):

from pydantic import BaseModel, validator

class Usuario(BaseModel):
    nome: str
    idade: int
    email: str

    @validator('idade')
    def idade_valida(cls, idade):
        if idade < 0:
            raise ValueError('Idade deve ser um número positivo')
        return idade

usuario = Usuario(nome=\"João\", idade=30, email=\"joao@email.com\")
print(usuario)
Enter fullscreen mode Exit fullscreen mode

3. Versionamento de Schema: Evolução Controlada dos Dados

O versionamento de schema é fundamental para garantir a compatibilidade e a continuidade do seu sistema ao longo do tempo. Quando seus dados evoluem, você precisa de um mecanismo para gerenciar essas mudanças sem quebrar a compatibilidade com versões anteriores do seu código.

Por que Versionar?

  • Evolução Natural: Os dados mudam com o tempo. Novas informações são adicionadas, campos são renomeados, tipos são alterados.
  • Manutenção da Compatibilidade: Permite que versões antigas do seu software continuem funcionando, mesmo com mudanças nos dados.
  • Facilidade de Implantação: Permite implantar novas versões do seu código sem interrupções.

Estratégias de Versionamento:

  • Versionamento Semântico: Utilize o versionamento semântico (SemVer) para identificar as mudanças nas suas APIs e schemas.
  • Novos Campos: Adicione novos campos com valores padrão para manter a compatibilidade.
  • Campos Opcionais: Torne campos opcionais para evitar quebras em versões anteriores.
  • Deprecated: Marque campos antigos como \"deprecated\" e forneça um período de transição antes de removê-los completamente.
  • Ferramentas: Utilize ferramentas como Alembic (Python) ou bibliotecas específicas para seu banco de dados para gerenciar as migrações do schema.

Exemplo (Conceitual):

Versão 1:

{
  \"id\": 123,
  \"nome\": \"Produto A\",
  \"preco\": 10.00
}
Enter fullscreen mode Exit fullscreen mode

Versão 2 (Adicionando um campo):

{
  \"id\": 123,
  \"nome\": \"Produto A\",
  \"preco\": 10.00,
  \"descricao\": \"Produto de alta qualidade"
}
Enter fullscreen mode Exit fullscreen mode

Conclusão:

Implementar boas práticas de nomenclatura, separação de tipos e inputs, e versionamento de schema é um investimento valioso para a qualidade do seu código. Ao seguir essas diretrizes, você construirá sistemas mais robustos, legíveis e fáceis de manter, economizando tempo e recursos a longo prazo. Adote essas práticas em seus projetos e colha os benefícios de um código de alta qualidade!

Top comments (0)