reflect-metadata für TypeScript: Komplettguide mit Beispielen

Willkommen zum ausführlichen Guide zur Bibliothek reflect-metadata für TypeScript. Diese Bibliothek ist die Grundlage vieler moderner Frameworks wie Angular, NestJS und TypeORM. Sie ermöglicht es, Metadaten (Daten über Daten) für Klassen, Methoden, Eigenschaften und Parameter zur Laufzeit hinzuzufügen und auszulesen. Wenn Sie verstehen möchten, wie Decorators und Dependency Injection (DI) in TypeScript funktionieren, ist reflect-metadata ein Muss.

1. Was ist reflect-metadata und wozu braucht man es?

reflect-metadata ist ein Polyfill (eine Implementierung) für das eingebaute Reflect-Objekt, das Teil der ES2016 (ES7)-Spezifikation ist. Das Hauptziel der Bibliothek ist es, eine API für die Arbeit mit Metadaten bereitzustellen, die verschiedenen Code-Elementen (Klassen, Methoden, Eigenschaften) zugeordnet werden können. In standardmäßigem JavaScript fehlt diese Funktionalität, daher ist für TypeScript die Installation eines separaten Pakets erforderlich.

Wozu das Ganze? Stellen Sie sich vor, Sie entwickeln ein Framework. Sie müssen wissen, welche Abhängigkeiten eine Klasse benötigt, welche Routen an die Methoden eines Controllers gebunden sind oder welche Felder einer Entität in JSON serialisiert werden sollen. Ohne Metadaten müssten Sie diese Informationen in separaten Konfigurationsdateien speichern oder komplexe Muster verwenden. reflect-metadata erlaubt es, diese Informationen direkt im Code zu speichern, was ihn selbstdokumentierend und leichter analysierbar macht.

Die Bibliothek ist eng mit Decorators verbunden. Ein Decorator ist eine Funktion, die auf eine Klasse, Methode oder Eigenschaft angewendet wird. Innerhalb eines Decorators können Sie Reflect.defineMetadata aufrufen, um Informationen zu speichern, und später an anderer Stelle im Programm Reflect.getMetadata verwenden, um sie abzurufen. Dies ist die Grundlage für die Implementierung von Dependency Injection, ORM (Object-Relational Mapping), Validierung und vielen anderen Patterns.

2. Installation

Die Installation der Bibliothek erfolgt über npm (Node Package Manager). Stellen Sie sicher, dass Node.js (Version 12 oder höher) installiert ist.

npm install reflect-metadata --save

Nach der Installation muss die Bibliothek ganz am Anfang Ihrer Einstiegsdatei (normalerweise main.ts oder index.ts) importiert werden, damit sie global verfügbar ist.

import "reflect-metadata";

Wichtig: Der Import muss vor jedem anderen Code erfolgen, der Reflect verwendet. Wenn Sie ein Framework (z. B. Angular) nutzen, erledigt es das automatisch für Sie. Andernfalls fügen Sie diese Zeile am Anfang Ihrer Datei hinzu.

Außerdem müssen Sie die Unterstützung für Decorators und Metadaten in Ihrer tsconfig.json-Datei aktivieren:

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

Das Flag emitDecoratorMetadata veranlasst den TypeScript-Compiler, Typ-Metadaten für dekorierte Elemente zu generieren. Dies ist für die Arbeit vieler Frameworks erforderlich.

3. Schnellstart – Ein minimales funktionierendes Beispiel

Erstellen wir ein einfaches Beispiel, das zeigt, wie man Metadaten zu einer Klasse hinzufügt und sie ausliest.

import "reflect-metadata";

// 1. Einen Schlüssel für die Metadaten definieren
const METADATA_KEY = "my_custom_key";

// 2. Einen Decorator erstellen, der Metadaten hinzufügt
function MyDecorator(value: string) {
    return function (target: any) {
        // target ist der Klassenkonstruktor
        Reflect.defineMetadata(METADATA_KEY, value, target);
    };
}

// 3. Den Decorator auf eine Klasse anwenden
@MyDecorator("Das ist meine Klasse")
class MyClass {
    greet() {
        console.l