class-validator para TypeScript: guia completo com exemplos

Introdução ao class-validator

\n\n

class-validator é uma biblioteca poderosa e popular para validação de dados em TypeScript e JavaScript, construída com base em decoradores. Ela permite descrever declarativamente as regras de validação diretamente dentro das classes, usando anotações. Isso torna o código limpo, legível e fácil de manter.

\n\n

A biblioteca é especialmente útil no desenvolvimento de aplicações server-side (por exemplo, em NestJS ou Express), onde é necessário verificar requisições de entrada, dados de formulários, configurações e quaisquer outras estruturas de dados. Em vez de escrever longas cadeias de if-else, você simplesmente adiciona decoradores às propriedades da classe.

\n\n

Por que usar class-validator?

\n\n

\n
• Declaratividade: As regras de validação são definidas junto aos dados, melhorando a legibilidade.
\n
• Conjunto poderoso de validadores: Inclui dezenas de decoradores embutidos para verificar strings, números, datas, arrays, objetos aninhados e muito mais.
\n
• Validadores personalizados: Permite criar facilmente suas próprias regras.
\n
• Integração com TypeScript: Suporte total a tipos e decoradores.
\n
• Validação assíncrona: Suporta verificações que exigem operações assíncronas (por exemplo, verificação de unicidade no banco de dados).
\n

\n\n

Instalação

\n\n

Para usar class-validator, você precisará do Node.js e npm/yarn. Instale a biblioteca e as dependências necessárias:

\n\n

npm install class-validator class-transformer reflect-metadata

\n\n

Ou via yarn:

\n\n

yarn add class-validator class-transformer reflect-metadata

\n\n

Importante: A biblioteca reflect-metadata é obrigatória para o funcionamento dos decoradores. Certifique-se de que ela está importada no seu arquivo principal (por exemplo, index.ts ou main.ts):

\n\n

import 'reflect-metadata';

\n\n

Além disso, certifique-se de que as seguintes configurações estão habilitadas no seu tsconfig.json:

\n\n

{\n  "compilerOptions": {\n    "experimentalDecorators": true,\n    "emitDecoratorMetadata": true\n  }\n}

\n\n

Início rápido

\n\n

Vamos criar um modelo de usuário simples e validá-lo.

\n\n

import 'reflect-metadata';\nimport { validate, IsString, IsEmail, MinLength } from 'class-validator';\nimport { plainToClass } from 'class-transformer';\n\nclass User {\n    @IsString()\n    @MinLength(3, { message: 'O nome deve conter no mínimo 3 caracteres' })\n    name: string;\n\n    @IsEmail({}, { message: 'Email inválido' })\n    email: string;\n\n    constructor(name: string, email: string) {\n        this.name = name;\n        this.email = email;\n    }\n}\n\nasync function main() {\n    // Criando um objeto com dados inválidos\n    const userData = { name: 'Jo', email: 'not-an-email' };\n    \n    // Convertendo um objeto simples em uma instância da classe\n    const user = plainToClass(User, userData);\n    \n    // Validando\n    const errors = await validate(user);\n    \n    if (errors.length > 0) {\n        console.log('Erros de validação:', errors);\n        errors.forEach(error => {\n            console.log(`Campo: ${error.property}`);\n            for (const constraint in error.constraints) {\n                console.log(`  - ${error.constraints[constraint]}`);\n            }\n        });\n    } else {\n        console.log('Validação bem-sucedida!');\n    }\n}\n\nmain();\n// Saída:\n// Erros de validação: [...]\n// Campo: name\n//   - O nome deve conter no mínimo 3 caracteres\n// Campo: email\n//   - Email inválido

\n\n

Principais métodos e decoradores

\n\n

1. @IsString()

\n

O que faz: Verifica se o valor é uma string.

\n

Parâmetros: Aceita um objeto opcional com opções de validação (por exemplo, { message: '...' }).

\n<