class-validator für TypeScript: Komplettguide mit Beispielen

Einführung in class-validator

class-validator ist eine leistungsstarke und beliebte Bibliothek zur Datenvalidierung in TypeScript und JavaScript, die auf Decorators basiert. Sie ermöglicht es, Validierungsregeln deklarativ direkt innerhalb von Klassen mithilfe von Annotationen zu definieren. Das macht den Code sauber, lesbar und leicht wartbar.

Die Bibliothek ist besonders nützlich bei der Entwicklung von Backend-Anwendungen (z. B. mit NestJS oder Express), wo eingehende Anfragen, Formulardaten, Konfigurationen und andere Datenstrukturen überprüft werden müssen. Anstatt lange if-else-Ketten zu schreiben, fügen Sie einfach Decorators zu den Eigenschaften Ihrer Klasse hinzu.

Warum class-validator verwenden?

• Deklarativ: Validierungsregeln werden direkt neben den Daten definiert, was die Lesbarkeit verbessert.
• Umfangreicher Validierungssatz: Enthält Dutzende integrierter Decorators zur Überprüfung von Strings, Zahlen, Datumsangaben, Arrays, verschachtelten Objekten und vielem mehr.
• Benutzerdefinierte Validatoren: Ermöglicht die einfache Erstellung eigener Regeln.
• TypeScript-Integration: Volle Unterstützung für Typen und Decorators.
• Asynchrone Validierung: Unterstützt Prüfungen, die asynchrone Operationen erfordern (z. B. Überprüfung der Eindeutigkeit in einer Datenbank).

Installation

Für die Verwendung von class-validator benötigen Sie Node.js und npm/yarn. Installieren Sie die Bibliothek und die erforderlichen Abhängigkeiten:

npm install class-validator class-transformer reflect-metadata

Oder mit yarn:

yarn add class-validator class-transformer reflect-metadata

Wichtig: Die Bibliothek reflect-metadata ist für die Funktion der Decorators erforderlich. Stellen Sie sicher, dass sie in Ihrer Hauptdatei (z. B. index.ts oder main.ts) importiert wird:

import 'reflect-metadata';

Stellen Sie außerdem sicher, dass in Ihrer tsconfig.json die folgenden Einstellungen aktiviert sind:

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

Schnellstart

Lassen Sie uns ein einfaches Benutzermodell erstellen und es validieren.

import 'reflect-metadata';
import { validate, IsString, IsEmail, MinLength } from 'class-validator';
import { plainToClass } from 'class-transformer';

class User {
    @IsString()
    @MinLength(3, { message: 'Der Name muss mindestens 3 Zeichen lang sein' })
    name: string;

    @IsEmail({}, { message: 'Ungültige E-Mail-Adresse' })
    email: string;

    constructor(name: string, email: string) {
        this.name = name;
        this.email = email;
    }
}

async function main() {
    // Erstellen eines Objekts mit ungültigen Daten
    const userData = { name: 'Jo', email: 'keine-email' };
    
    // Konvertieren des einfachen Objekts in eine Klasseninstanz
    const user = plainToClass(User, userData);
    
    // Validieren
    const errors = await validate(user);
    
    if (errors.length > 0) {
        console.log('Validierungsfehler:', errors);
        errors.forEach(error => {
            console.log(`Feld: ${error.property}`);
            for (const constraint in error.constraints) {
                console.log(`  - ${error.constraints[constraint]}`);
            }
        });
    } else {
        console.log('Validierung erfolgreich!');
    }
}

main();
// Ausgabe:
// Validierungsfehler: [...]
// Feld: name
//   - Der Name muss mindestens 3 Zeichen lang sein
// Feld: email
//   - Ungültige E-Mail-Adresse

Wichtige Methoden und Decorators

1. @IsString()

Funktion: Überprüft, ob der Wert ein String ist.

Parameter: Akzeptiert ein optionales Objekt mit Validierungsoptionen (z. B. { message: '...' }).

class Product {
    @IsString()
    title: string;
}

2. @IsNumber()

Funktion: Überprüft, ob der Wert eine Zahl ist.

Parameter: Optional können Optionen wie { allowNaN: false } übergeben werden.

class Order {
    @IsNumber()
    quantity: number;
}

3. @MinLength(length) und @MaxLength(length)

Funktion: Überprüft die minimale bzw. maximale Länge eines Strings.

class Comment {
    @MinLength(10, { message: 'Der Kommentar muss mindestens 10 Zeichen lang sein' })
    @MaxLength(500, { message: 'Der Kommentar darf maximal 500 Zeichen lang sein' })
    text: string;
}

4. @IsEmail()

Funktion: Überprüft, ob der Wert eine gültige E-Mail-Adresse ist.

class Contact {
    @IsEmail()
    email: string;
}

5. @IsArray()

Funktion: Überprüft, ob der Wert ein Array ist.

class BlogPost {
    @IsArray()
    tags: string[];
}

6. @ValidateNested()

Funktion: Ermöglicht die Validierung von verschachtelten Objekten. Wird oft mit @Type() aus class-transformer verwendet.

import { Type } from 'class-transformer';

class Address {
    @IsString()
    street: string;

    @IsString()
    city: string;
}

class Person {
    @ValidateNested()
    @Type(() => Address)
    address: Address;
}

Benutzerdefinierte Validatoren

Sie können ganz einfach eigene Validierungsregeln erstellen, indem Sie das Interface ValidatorConstraintInterface implementieren oder den Decorator @ValidatorConstraint() verwenden.

import { ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments, registerDecorator, ValidationOptions } from 'class-validator';

@ValidatorConstraint({ name: 'isLongerThan', async: false })
export class IsLongerThanConstraint implements ValidatorConstraintInterface {
    validate(value: any, args: ValidationArguments) {
        const [relatedPropertyName] = args.constraints;
        const relatedValue = (args.object as any)[relatedPropertyName];
        return typeof value === 'string' && typeof relatedValue === 'string' && value.length > relatedValue.length;
    }

    defaultMessage(args: ValidationArguments) {
        const [relatedPropertyName] = args.constraints;
        return `${args.property} muss länger sein als ${relatedPropertyName}`;
    }
}

export function IsLongerThan(property: string, validationOptions?: ValidationOptions) {
    return function (object: Object, propertyName: string) {
        registerDecorator({
            target: object.constructor,
            propertyName: propertyName,
            options: validationOptions,
            constraints: [property],
            validator: IsLongerThanConstraint,
        });
    };
}

class MyClass {
    @IsString()
    name: string;

    @IsLongerThan('name', { message: 'Die Beschreibung muss länger sein als der Name' })
    description: string;
}

Fehlerbehandlung und benutzerdefinierte Nachrichten

Jeder Decorator akzeptiert ein Optionsobjekt, in dem Sie eine benutzerdefinierte Fehlermeldung festlegen können:

class User {
    @MinLength(5, { message: 'Der Benutzername muss mindestens $constraint1 Zeichen lang sein' })
    username: string;
}

Sie können auch Platzhalter wie $value (der aktuelle Wert), $property (der Eigenschaftsname) und $constraint1, $constraint2 usw. verwenden.

Fazit

class-validator ist ein unverzichtbares Werkzeug für jeden TypeScript-Entwickler, der saubere, wartbare und zuverlässige Validierungslogik schreiben möchte. Mit seiner deklarativen Syntax, dem umfangreichen Satz an integrierten Validatoren und der Möglichkeit, benutzerdefinierte Regeln zu erstellen, vereinfacht es die Datenvalidierung erheblich und reduziert Boilerplate-Code.

Probieren Sie es in Ihrem nächsten Projekt aus – Sie werden den Unterschied in der Codequalität und Entwicklungsgeschwindigkeit sofort bemerken!