Quellkarten: Schnell und einfach

Der Source Maps-Mechanismus wird verwendet, um die Quellcodes des Programms Skripten zuzuordnen, die auf ihrer Basis generiert wurden. Trotz der Tatsache, dass das Thema nicht neu ist und bereits eine Reihe von Artikeln darüber geschrieben wurden (zum Beispiel dies , dies und das ), müssen einige Aspekte noch geklärt werden. Dieser Artikel ist ein Versuch, alles, was zu diesem Thema bekannt ist, in einer kurzen und zugänglichen Form zu rationalisieren und zu systematisieren.



In diesem Artikel werden Quellzuordnungen in Bezug auf die Cliententwicklung in der Umgebung gängiger Browser (z. B. Google Chrome DevTools) erläutert, obwohl ihr Umfang nicht an eine bestimmte Sprache oder Umgebung gebunden ist. Die Hauptquelle für Quellkarten ist natürlich der Standard , obwohl er noch nicht übernommen wurde (Status - Vorschlag), aber dennoch von Browsern weitgehend unterstützt wird.



Die Arbeit an Quellkarten wurde Ende der 2000er Jahre begonnen, die erste Version wurde für das Plugin Firebug Closure Inspector erstellt. Die zweite Version wurde 2010 veröffentlicht und enthielt Änderungen hinsichtlich der Reduzierung der Größe der Kartendatei. Die dritte Version wurde in Zusammenarbeit zwischen Google und Mozilla entwickelt und 2011 vorgeschlagen (zuletzt 2013 überarbeitet).



Derzeit gibt es in der Client-Entwicklungsumgebung eine Situation, in der der Quellcode fast nie direkt in die Webseite integriert wird, sondern verschiedene Verarbeitungsstufen durchläuft: Minimierung, Optimierung, Verkettung. Darüber hinaus kann der Quellcode selbst in Sprachen geschrieben werden, die eine Transpilation erfordern ... In diesem Fall benötigen Sie zum Debuggen einen Mechanismus, mit dem Sie im Debugger genau den von Menschen lesbaren Quellcode beobachten können.



Für Quellkarten sind die folgenden Dateien erforderlich:

• die tatsächlich generierte JavaScript-Datei
• die Menge der Quelldateien, die zum Erstellen verwendet wurden
• Zuordnungsdatei, die sie einander zuordnet

Kartendatei

Alle Arbeiten von Source Maps basieren auf einer Map-Datei, die beispielsweise folgendermaßen aussehen kann:

{
    "version":3,
    "file":"index.js",
    "sourceRoot":"",
    "sources":["../src/index.ts"],
    "names":[],
    "mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,SAAS,SAAS;IACd,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;",
    "sourcesContent": []
}

Normalerweise ist der Name der Map-Datei die Summe des Namens des Skripts, zu dem sie gehört, mit der Erweiterung ".map", bundle.js - bundle.js.map. Dies ist eine reguläre JSON-Datei mit den folgenden Feldern:

• "Version" - Quellkartenversion;
• "Datei" - (optional) der Name der generierten Datei, zu der die aktuelle Kartendatei gehört;
• "SourceRoot" - (optionales) Präfix für Pfade zu Quelldateien;
• "Quellen" - eine Liste von Pfaden zu Quelldateien (aufgelöst auf die gleiche Weise wie die Quelladressen des Skript-Tags, können Sie file: //. Verwenden;);
• "Namen" - eine Liste von Namen von Variablen und Funktionen, die in der generierten Datei geändert wurden;
• "Zuordnungen" - Koordinaten der Zuordnung von Variablen und Funktionen von Quelldateien zu einer generierten Datei im Base64 VLQ-Format;
• "SourcesContent" - (optional) im Fall einer in sich geschlossenen Kartendatei, einer Liste von Zeilen, von denen jede den Quelltext der Datei aus Quellen enthält;

Quellkarten herunterladen

Damit der Browser die Kartendatei laden kann, kann eine der folgenden Methoden verwendet werden:

• Die JavaScript-Datei wurde mit einem HTTP-Header geliefert: SourceMap: <url> (zuvor veraltete X-SourceMap: <url> wurde zuvor verwendet)
• Die generierte JavaScript-Datei enthält einen speziellen Kommentar zum Formular:

//# sourceMappingURL=<url> ( CSS /*# sourceMappingURL=<url> */)

Nachdem die Kartendatei geladen wurde, ruft der Browser die Quellen aus dem Feld "Quellen" ab und zeigt sie anhand der Daten im Feld "Zuordnungen" im generierten Skript an. Auf der Registerkarte Sources DevTools finden Sie beide Optionen.



Die Datei: // Pseudoprotokoll kann verwendet werden, um den Pfad anzugeben. Der Inhalt der Base64-codierten Map-Datei kann auch in der <url> enthalten sein. In der Webpack-Terminologie werden solche Quellzuordnungen als Inline-Quellzuordnungen bezeichnet.

//# sourceMappingURL=data:application/json;charset=utf-8;base64,<source maps Base64 code>

In sich geschlossene Kartendateien

Der Quelldateicode kann direkt in die Kartendatei im Feld "sourcesContent" aufgenommen werden. Wenn dieses Feld verfügbar ist, müssen sie nicht separat heruntergeladen werden. In diesem Fall geben die Dateinamen in „Quellen“ nicht ihre tatsächliche Adresse wieder und können völlig willkürlich sein. Aus diesem Grund können Sie solche seltsamen "Protokolle" auf der Registerkarte "Quellen DevTools" sehen: webpack: //, ng: // usw.

Zuordnungen

Der Zuordnungsmechanismus besteht im Wesentlichen darin, dass die Koordinaten (Zeile / Spalte) der Namen von Variablen und Funktionen in der generierten Datei den Koordinaten in der entsprechenden Quellcodedatei zugeordnet werden. Damit der Anzeigemechanismus funktioniert, sind die folgenden Informationen erforderlich:



(# 1) Zeilennummer in der generierten Datei;

(# 2) Spaltennummer in der generierten Datei;

(# 3) Index der Quelle in "Quellen";

(# 4) Quellzeilennummer;

(# 5) Quellenspaltennummer;



Alle diese Daten befinden sich im Feld "Zuordnungen", dessen Wert eine lange Zeichenfolge mit einer speziellen Struktur und in Base64 VLQ codierten Werten ist.



Die Zeile ist durch Semikolons (;) in Abschnitte unterteilt, die den Zeilen in der generierten Datei (# 1) entsprechen.



Jeder Abschnitt ist durch Kommas (,) in Segmente unterteilt, von denen jedes 1,4 oder 5 Werte enthalten kann:

• Spaltennummer in der generierten Datei (# 2);
• Quellindex in "Quellen" (# 3);
• Quellzeilennummer (# 4);
• Quellenspaltennummer (# 5);
• der Index des Variablen- / Funktionsnamens aus der Liste "Namen";

Die Werte der Zeilen- und Spaltennummern sind relativ, geben den Versatz relativ zu den vorherigen Koordinaten an und nur den ersten vom Anfang der Datei oder des Abschnitts.



Jeder Wert ist eine Base64-VLQ-Nummer. VLQ (Variable Length Quantity) ist ein Prinzip zum Codieren einer beliebig großen Zahl unter Verwendung einer beliebigen Anzahl von Binärblöcken fester Länge.



Source Maps verwendet Sechs-Bit-Blöcke, die von niedrig nach hoch geordnet sind. Das höchste 6. Bit jedes Blocks (Fortsetzungsbit) ist reserviert. Wenn es gesetzt ist, folgt auf den aktuellen Block der nächste Block derselben Nummer. Wenn er zurückgesetzt wird, ist die Sequenz abgeschlossen.



Da Quellkarten ein Vorzeichen haben müssen, ist auch das Vorzeichenbit dafür reserviert, jedoch nur im ersten Block der Sequenz. Wie erwartet bedeutet ein gesetztes Vorzeichenbit eine negative Zahl.



Wenn also eine Nummer in einem einzelnen Block codiert werden kann, kann sie nicht Modulo 15 (1111 ₂ ) sein, da im ersten Sechs-Bit-Block der Sequenz zwei Bits reserviert sind: Das Fortsetzungsbit wird immer gelöscht, das Vorzeichenbit wird abhängig vom Vorzeichen der Nummer gesetzt.



Sechs-Bit-VLQ-Blöcke werden der Base64-Codierung zugeordnet, wobei jede Sechs-Bit-Sequenz einem bestimmten ASCII-Zeichen zugeordnet wird.







Wir dekodieren die Zahl mE. Invertieren Sie die Reihenfolge, der letzte Teil ist Em. Wir dekodieren die Zahlen von Base64: E - 000100, m - 100110. Im ersten verwerfen wir das höchste Fortsetzungsbit und zwei führende Nullen - 100. Im zweiten verwerfen wir die höchsten Fortsetzungs- und niedrigen Vorzeichenbits (das Vorzeichenbit wird gelöscht - die Zahl ist positiv) - 0011. Als Ergebnis erhalten wir 100 0011 ₂ , was der Dezimalzahl 67 entspricht.



Sie können auch in die entgegengesetzte Richtung 41 codieren. Der Binärcode lautet 101001 ₂Wir teilen es in zwei Blöcke auf: Der obere Teil ist 10, der jüngste Teil (immer 4-Bit) ist 1001. Fügen Sie das höchstwertige Fortsetzungsbit (gelöscht) zum oberen Teil und die drei führenden Nullen - 000010 hinzu. Fügen Sie das höchstwertige Fortsetzungsbit (gesetzt) ​​zum unteren Teil und hinzu Das Bit mit niedrigem Vorzeichen (gelöscht - eine positive Zahl) ist 110010. Wir codieren die Zahlen in Base64: 000010 - C, 110010 - y. Wir kehren die Reihenfolge um und erhalten als Ergebnis yC.



Die gleichnamige Bibliothek ist sehr nützlich für die Arbeit mit VLQ .