Jede URL, die Sie jemals eingegeben oder angeklickt haben, wurde durch URL-Kodierung verarbeitet. Das Leerzeichen in “meine Datei.txt” wird zu %20. Das & in einer Abfragezeichenkette wird zu %26. Das / in einem Pfad bleibt / — aber nur weil der Kodierer weiß, welche Zeichen sicher sind und welche nicht.
URL-Kodierung (offiziell “Prozentkodierung”) ist die Art und Weise, wie URLs Zeichen darstellen, die nicht im unreservierten Zeichensatz enthalten sind. Es ist eine einfache Transformation, aber die Grenzfälle sind dort, wo die meisten API-Fehler leben.
Die unreservierten Zeichen
Diese Zeichen sind immer sicher in URLs und benötigen niemals Kodierung:
A-Z a-z 0-9 - _ . ~Alles andere — Leerzeichen, Schrägstriche, Et-Zeichen, Gleichheitszeichen, Nicht-ASCII-Zeichen — muss als Prozentzeichen gefolgt von zwei Hexadezimalziffern kodiert werden:
- Leerzeichen →
%20 &→%26=→%3D/→%2F?→%3F#→%23
Die Kodierung sind die UTF-8-Byte-Werte des Zeichens, die jeweils als zwei Hexadezimalziffern dargestellt werden. Ein Multibyte-Zeichen wie é (UTF-8: 0xC3 0xA9) wird zu %C3%A9.
W wo die Kodierung wichtig ist
Abfrageparameter. Hier verursacht URL-Kodierung die meisten Fehler. Wenn ein Abfrage-Wert & oder = enthält, trennt der URL-Parser an diesen Zeichen und zerstört die Parameterstruktur:
/search?q=cats&dogs ← mehrdeutig: ist "dogs" ein separater Parameter?
/search?q=cats%26dogs ← korrekt: "cats&dogs" ist ein einziger WertJede HTTP-Bibliothek hat eine Funktion zum Kodieren von Abfrageparametern. Verwenden Sie sie. Verketten Sie niemals manuell Strings in eine Abfragezeichenkette.
Pfade. Leerzeichen in Dateinamen müssen kodiert werden:
/download/my file.pdf ← kaputt
/download/my%20file.pdf ← funktioniertAber Schrägstriche innerhalb eines Pfadsegments müssen auch kodiert werden:
/file/path/segment ← zwei Segmente: "file/path" geteilt bei /
/file%2Fpath/segment ← ein Segment: "file/path"Nicht-ASCII-Zeichen. URLs sind nur ASCII. Jedes Nicht-ASCII-Zeichen (akzentierte Buchstaben, CJK-Zeichen, Emoji) muss prozentkodiert werden:
café→caf%C3%A9日本語→%E6%97%A5%E6%9C%AC%E8%AA%9E🎉→%F0%9F%8E%89
Die meisten Browser zeigen die dekodierte Version in der Adressleiste an, aber die tatsächlich über das Netzwerk gesendeten Bytes sind kodiert.
Die Falle der doppelten Kodierung
Der häufigste URL-Kodierungsfehler: Kodieren eines bereits kodierten Strings.
Nehmen Sie den Pfad /hello%20world. Wenn Sie ihn erneut URL-kodieren, wird % zu %25:
/hello%20world ← Original (korrekt)
/hello%2520world ← doppelt kodiert (kaputt)Der Server dekodiert %25 zu %, sieht dann %20 und dekodiert dies zu einem Leerzeichen. Sie enden mit /hello world — aber nur, wenn der Server eine einzige Dekodierung durchführt. Wenn er zwei Dekodierungen durchführt (manche tun das), erhalten Sie das Original zurück. Das Verhalten ist inkonsistent und unvorhersehbar.
Die Regel: Einmal kodieren, einmal dekodieren. Wenn Sie einen kodierten String empfangen, dekodieren Sie ihn vor dem Rekodieren. Prüfen Sie, ob der URL-Builder Ihrer HTTP-Bibliothek rohe oder vorab-kodierte Werte erwartet — der Unterschied zwischen path und rawPath in den meisten Frameworks ist wichtig.
Abfragezeichenketten-Kodierung
Abfragezeichenketten haben ihre eigenen Kodierungsregeln. Der Hauptunterschied zu Pfaden: + repräsentiert ein Leerzeichen in Abfragezeichenketten (application/x-www-form-urlencoded), aber %20 repräsentiert auch ein Leerzeichen. Beides ist gültig, aber sie kommen aus unterschiedlichen Standards:
application/x-www-form-urlencoded(Formularübermittlungen) —+für Leerzeichen- Prozentkodierung (URLs) —
%20für Leerzeichen
Die meisten modernen APIs akzeptieren beides. Aber wenn Sie eine Abfragezeichenkette aus einer Formularübermittlung analysieren, wird + zu Leerzeichen. Wenn Sie eine URL aufbauen, wird %20 zu Leerzeichen. Das Vermischen verursacht subtile Fehler, bei denen Leerzeichen zu +-Zeichen werden oder umgekehrt.
Verwenden Sie die URL-Kodierungsfunktion Ihrer Sprache. Sie kümmert sich um die Unterscheidung für Sie.
Kodierung vs. Escaping
URL-Kodierung ist kein HTML-Escaping. Sie lösen unterschiedliche Probleme:
- URL-Kodierung (
%20) — für Zeichen in URLs. Verhindert, dass Zeichen als URL-Syntax interpretiert werden. - HTML-Escaping (
&,<) — für Zeichen in HTML. Verhindert, dass Zeichen als HTML-Tags oder Entitäten interpretiert werden.
Eine URL in einem HTML-href benötigt beides: URL-kodieren Sie die Parameterwerte und dann HTML-kodieren Sie die gesamte URL:
<a href="/search?q=cats%26d&page=1">Das %26 hindert & daran, als Abfragetrennzeichen interpretiert zu werden. Das &amp; hindert & daran, als Beginn einer HTML-Entität interpretiert zu werden.
Häufige Fallstricke
Leerzeichen in verschiedenen Kontexten. %20 in einer URL, + in einem Formularkörper, %2520 wenn Sie versehentlich doppelt kodiert haben. Wissen Sie, in welchem Kontext Sie sich befinden.
Hash-Fragmente. Alles nach # wird nicht an den Server gesendet. Wenn Sie eine URL mit einem Fragment kodieren und das Fragment ? oder & enthält, sieht der Server sie nie. Das Fragment ist nur clientseitig.
Kodieren des Prozentzeichens. % → %25. Wenn ein wörtliches % in Ihren Daten vorkommt (wie ein Passwort mit %), muss es kodiert werden. Wenn Sie es nicht kodieren, interpretiert die beiden Zeichen danach als Hexadezimalsequenz.
Unicode-Normalisierung. Manche Systeme normalisieren Unicode vor der Kodierung. café (mit kombinierendem Akzent) und café (mit vorkomponiertem é) kodieren zu unterschiedlichen Prozentsquenzen. Dies verursacht Probleme mit Dateinamen und internationalisierten Domainnamen.
Schnellreferenz
| Zeichen | Prozentkodiert | Kontext |
|---|---|---|
| Leerzeichen | %20 |
URL |
| Leerzeichen | + |
Formularkörper |
& |
%26 |
Abfragezeichenkette |
= |
%3D |
Abfragezeichenkette |
/ |
%2F |
Pfadsegment |
? |
%3F |
Abfragezeichenkette |
# |
%23 |
Pfad/Abfrage |
% |
%25 |
Überall |
+ |
%2B |
Abfragezeichenkette |
Ausprobieren
Wenn Sie eine URL oder einen kodierten String dekodieren müssen (oder rohe Daten kodieren müssen), verwenden Sie ein lokales Tool, damit die Konvertierung in Ihrem Browser erfolgt — keine Daten werden irgendwohin gesendet.