Projektüberblick

Quelldateien

Diese Seite wurde aus den folgenden Quelldateien erstellt:

• README.md
• packages/mermaid/package.json
• packages/mermaid/src/mermaid.ts
• packages/mermaid/src/utils.ts
• packages/mermaid/src/types.ts
• packages/mermaid/src/type.d.ts
• packages/mermaid/src/styles.ts
• packages/mermaid/src/logger.ts
• packages/mermaid/src/errors.ts
• packages/mermaid/src/config.ts

Mermaid ist ein JavaScript-basiertes Diagramm- und Charting-Tool, das Markdown-inspirierte Textdefinitionen verwendet, um komplexe Diagramme zu erstellen und zu modifizieren. Der Hauptzweck von Mermaid besteht darin, der Dokumentation zu helfen, mit der Entwicklung Schritt zu halten (README.md:69-79). Das Projekt zielt darauf ab, das sogenannte "Doc-Rot"-Problem zu lösen – ein Dilemma, bei dem die Erstellung von Diagrammen und Dokumentation wertvolle Entwicklerzeit kostet und schnell veraltet, während das Fehlen von Diagrammen oder Dokumentation die Produktivität beeinträchtigt und das organisationale Lernen behindert.

Die aktuelle Version 11.13.0 wird als ESM-Modul bereitgestellt und unterstützt eine breite Palette von Diagrammtypen, von Flowcharts über Sequenzdiagramme bis hin zu komplexen Architekturdiagrammen (packages/mermaid/package.json:1-5). Mermaid wurde 2019 mit dem JS Open Source Award in der Kategorie "The most exciting use of technology" ausgezeichnet und hat sich als Industriestandard für textbasierte Diagrammerstellung etabliert (README.md:43-47).

Technologie-Stack und Abhängigkeiten

Die folgende Tabelle zeigt die zentralen Technologien und deren Versionen, die im Mermaid-Kernpaket verwendet werden:

Die Abhängigkeitsstruktur verdeutlicht die modulare Architektur mit Fokus auf Sicherheit und Performance (packages/mermaid/package.json:69-91). Besonders hervorzuheben ist die Integration von @braintree/sanitize-url für URL-Sicherheit und dompurify zum Schutz vor Cross-Site-Scripting-Angriffen.

Unterstützte Diagrammtypen

Mermaid unterstützt eine umfangreiche Palette von Diagrammtypen, die als Keywords im Paketmanifest definiert sind (packages/mermaid/package.json:16-33):

• Flowchart: Klassische Flussdiagramme mit Entscheidungs Knoten und Verzweigungen
• Sequence Diagram: Interaktionsdiagramme für zeitliche Abläufe zwischen Akteuren
• Class Diagram: Objektorientierte Modellierung mit Klassen und Beziehungen
• State Diagram: Zustandsautomaten und Zustandsübergänge
• Entity Relationship Diagram: Datenbankmodellierung mit Entitäten und Relationen
• Gantt Chart: Projektplanung und Zeitstrahlen
• Pie Chart: Kreisdiagramme für proportionale Daten
• Git Graph: Visualisierung von Git-Branches und Commits
• Mindmap: Hierarchische Gedankenlandkarten
• C4 Diagram: Architekturdiagramme nach dem C4-Modell
• Quadrant Chart: Zwei-dimensionale Klassifikationsdiagramme
• Requirement Diagram: Anforderungsdiagramme für Systemanalyse
• Packet Diagram: Netzwerkpaket-Visualisierungen

Systemarchitektur

Die Architektur von Mermaid folgt einem modularen Design mit klar getrennten Verantwortlichkeiten. Das folgende Diagramm zeigt die Kernkomponenten und deren Beziehungen:

正在加载图表渲染器...

Architektur-Erklärung:

1. Eingabeschicht: Akzeptiert Textdefinitionen in Markdown-ähnlicher Syntax und optionale Konfigurationsobjekte zur Anpassung des Rendering-Verhaltens
2. Kernverarbeitung: Der Parser analysiert die Texteingabe, der Validator prüft die Syntaxkorrektheit, und der Renderer generiert das finale SVG
3. Unterstützungsmodule: Utils stellt Hilfsfunktionen bereit, Styles verwaltet das Theme-System, und Logger ermöglicht Debugging-Ausgaben
4. Ausgabeschicht: Produziert entweder ein fertiges SVG-Diagramm oder ein strukturiertes Fehlerobjekt bei Validierungsproblemen

Die Kernfunktion run() durchläuft das Dokument, findet Diagramdefinitionen und rendert diese (packages/mermaid/src/mermaid.ts:89-110). Dabei werden bereits verarbeitete Elemente mit dem Attribut data-processed markiert, um mehrfaches Rendering zu vermeiden.

Kernmodule und deren Verantwortlichkeiten

Parser- und Validierungsmodule

Das Parsing-Modul implementiert die Funktion parse(), die Texteingaben validiert und bei Fehlern detaillierte Informationen zurückgibt (packages/mermaid/src/mermaid.ts:328-349):

typescript
1// Beispiel für Parse-Aufrufe
2console.log(await mermaid.parse('flowchart \n a --> b'));
3// { diagramType: 'flowchart-v2' }
4
5console.log(await mermaid.parse('wrong \n a --> b', { suppressErrors: true }));
6// false
7
8console.log(await mermaid.parse('wrong \n a --> b', { suppressErrors: false }));
9// throws Error

Verantwortlichkeitsgrenzen:

• Tut: Syntaxvalidierung, Diagramtyperkennung, Fehlerunterdrückung
• Tut nicht: Rendering, SVG-Generierung, Layout-Berechnung

Eintrittspunkte:

• parse(text, parseOptions): Asynchrone Validierungsfunktion
• suppressErrors: Option zur Fehlerunterdrückung

Fehlerbehandlung: Die Funktion handleError() differenziert zwischen detaillierten Fehlern und einfachen Fehlerstrings (packages/mermaid/src/mermaid.ts:64-87). Bei DetailedError werden str, hash und message extrahiert, während bei regulären Error-Objekten nur message und name verwendet werden.

Typdefinitionen und Datenstrukturen

Das Typsystem definiert präzise Schnittstellen für alle Diagrammelemente (packages/mermaid/src/types.ts:1-46):

typescript
1// Knotenmetadaten
2interface NodeMetaData {
3  shape?: string;
4  label?: string;
5  icon?: string;
6  form?: string;
7  pos?: 't' | 'b';
8  img?: string;
9  w?: string;
10  h?: string;
11  constraint?: 'on' | 'off';
12  priority: 'Very High' | 'High' | 'Medium' | 'Low' | 'Very Low';
13  assigned?: string;
14  ticket?: string;
15  labelType?: string;
16}
17
18// Kantenmetadaten
19interface EdgeMetaData {
20  animation?: 'fast' | 'slow';
21  animate?: boolean;
22  curve?: 'basis' | 'bumpX' | 'bumpY' | 'cardinal' | 
23          'catmullRom' | 'linear' | 'monotoneX' | 
24          'monotoneY' | 'natural' | 'step' | 
25          'stepAfter' | 'stepBefore';
26}
27
28// Punktkoordinaten
29interface Point {
30  x: number;
31  y: number;
32}

Schlüsseldatenstrukturen:

• NodeMetaData: Definiert Knoteneigenschaften mit 13 optionalen Feldern für Form, Label, Icon, Positionierung und Priorität
• EdgeMetaData: Steuert Kantenanimation und Kurventypen mit 16 verschiedenen Kurvenoptionen
• Point und Bounds: Geometrische Grundtypen für Positionierung und Bemaßung

Hilfsfunktionen und Sicherheitsmodule

Das Utils-Modul stellt kritische Sicherheitsfunktionen bereit (packages/mermaid/src/utils.ts:241-260):

typescript
1export function formatUrl(linkStr: string, config: MermaidConfig): string | undefined {
2  const url = linkStr.trim();
3  
4  if (!url) {
5    return undefined;
6  }
7  
8  if (config.securityLevel !== 'loose') {
9    return sanitizeUrl(url);
10  }
11  
12  return url;
13}

Sicherheitsmechanismen:

• URL-Sanitisierung: Verwendet @braintree/sanitize-url zur Bereinigung von URLs
• Security-Level-Konfiguration: Unterscheidet zwischen 'loose' (keine Sanitisierung) und anderen Stufen (aktive Sanitisierung)
• Leerstring-Behandlung: Gibt undefined für leere URLs zurück

Zusätzliche Hilfsfunktionen:

• interpolateToCurve(): Wandelt Interpolationsnamen in D3-Curve-Factories um
• runFunc(): Führt Funktionen über Dot-Notation-Pfade aus (z.B. 'myApp.utils.helper')
• calcLabelPosition(): Berechnet die optimale Position für Kantenlabels

Style- und Theme-System

Das Styling-Modul generiert dynamische CSS-Styles basierend auf dem gewählten Theme (packages/mermaid/src/styles.ts:6-35):

typescript
1const getStyles = (
2  type: string,
3  userStyles: string,
4  options: {
5    fontFamily: string;
6    fontSize: string;
7    textColor: string;
8    errorBkgColor: string;
9    errorTextColor: string;
10    lineColor: string;
11  } & FlowChartStyleOptions
12) => {
13  let diagramStyles = '';
14  if (type in themes && themes[type]) {
15    diagramStyles = themes[type](options);
16  } else {
17    log.warn(`No theme found for ${type}`);
18  }
19  return ` & {
20    font-family: ${options.fontFamily};
21    font-size: ${options.fontSize};
22    fill: ${options.textColor}
23  }
24  @keyframes edge-animation-frame { ... }
25  ...
26}

Style-Generierungsprozess:

1. Theme-Lookup: Sucht nach dem passenden Theme basierend auf dem Diagramtyp
2. Fallback: Warnt bei fehlendem Theme und fährt mit leeren Styles fort
3. CSS-Generierung: Kombiniert Theme-Styles mit globalen Einstellungen für Schriftart, Schriftgröße und Farben
4. Animation-Keyframes: Fügt Keyframe-Animationen für Kantenanimationen hinzu

Datenfluss und Rendering-Pipeline

Der folgende Ablauf zeigt den vollständigen Datenfluss von der Texteingabe bis zum fertigen SVG-Diagramm:

正在加载图表渲染器...

Datenfluss-Erklärung:

1. Initialisierung: mermaid.run() durchsucht das DOM nach Elementen ohne data-processed-Attribut
2. Parsing-Phase: Der Parser führt eine lexikalische Analyse durch und erstellt einen Abstract Syntax Tree (AST)
3. Validierung: Der Validator prüft die Syntax gegen die Grammatikregeln des jeweiligen Diagramtyps
4. Rendering: Bei erfolgreicher Validierung fordert der Renderer Styles vom Theme-System an und generiert SVG
5. Fehlerbehandlung: Bei Validierungsfehlern wird ein strukturiertes Fehlerobjekt mit str, hash und message erstellt

Die asynchrone Ausführung wird durch eine Queue verwaltet, die parallele Rendering-Anfragen serialisiert (packages/mermaid/src/mermaid.ts:310-326).

Verzeichnisstruktur

Die Kernstruktur des Mermaid-Pakets folgt einer klaren Trennung zwischen Quellcode, Typdefinitionen und Build-Artefakten:

packages/mermaid/
├── src/
│   ├── mermaid.ts          # Haupteinstiegspunkt und API
│   ├── config.ts           # Konfigurationsmanagement
│   ├── types.ts            # TypeScript-Typdefinitionen
│   ├── type.d.ts           // Globale Typdeklarationen
│   ├── utils.ts            # Hilfsfunktionen
│   ├── styles.ts           # Style-Generierung
│   ├── logger.ts           # Logging-Infrastruktur
│   └── errors.ts           # Fehlerklassen
├── dist/                   # Kompilierte Ausgabe
│   ├── mermaid.core.mjs    # ESM-Bundle
│   └── mermaid.d.ts        # Typdeklarationen
└── package.json            # Paketmanifest

Quantifizierte Projektkennzahlen

Basierend auf der Analyse der Quellcodedateien und des Paketmanifests:

Anwendungsszenarien

Mermaid eignet sich für folgende primäre Einsatzbereiche:

Dokumentationssysteme:

• Integration in Markdown-basierte Dokumentationsplattformen
• Automatische Diagramgenerierung aus Code-Kommentaren
• Live-Updates bei Dokumentationsänderungen

Entwicklungsworkflows:

• Architekturdokumentation in README-Dateien
• CI/CD-Pipeline-Visualisierung
• Git-Workflow-Darstellung

Projektmanagement:

• Gantt-Diagramme für Projektzeitpläne
• Anforderungsanalyse mit Requirement Diagrams
• Stakeholder-Kommunikation durch C4-Modelle

Bildung und Training:

• Erstellung von Lehrmaterialien
• Visualisierung komplexer Konzepte
• Interaktive Diagramme im Live Editor

Leseempfehlung für den Technologiebericht

Die folgende Grafik zeigt die empfohlene Lesereihenfolge für die einzelnen Kapitel dieses Technologieberichts:

正在加载图表渲染器...

Lesepfad-Erklärung:

1. Projektüberblick: Verständnis der Grundkonzepte und des Technologie-Stacks
2. Architektur: Tiefere Einblicke in die modulare Struktur und Komponenteninteraktionen
3. Features: Detaillierte Analyse der unterstützten Diagrammtypen und deren Implementierung
4. API-Design: Schnittstellen und Integrationsmöglichkeiten für Entwickler
5. Datenmodell: Typsystem und Datenstrukturen der Diagramdefinitionen
6. Abhängigkeiten: Externe Bibliotheken und deren Rolle im System
7. Zusammenfassung: Konsolidierte Erkenntnisse und Bewertung

Diese Struktur ermöglicht sowohl einen linearen Durchgang für neue Leser als auch gezieltes Nachschlagen spezifischer Aspekte für erfahrene Entwickler.