Rewrite Rules

Rewrite Rules ermöglichen die Transformation eingehender URLs, bevor jegliche andere Verarbeitung stattfindet. Sie funktionieren wie nginx Rewrite-Regeln und ermöglichen URL-Normalisierung, Legacy-URL-Unterstützung und saubere URL-Strukturen.

Rewrite Rules: eingehende URLs vor der Verarbeitung umschreiben.

Was sind Rewrite Rules?

Rewrite Rules modifizieren die Anfrage-URL basierend auf einem URL-Abgleich. Sie werden früh im Anfrageablauf ausgewertet, direkt nach Access Rules und vor Conditional Rules, wodurch URL-Transformationen stattfinden, bevor Konfigurationsregeln die URL auswerten.

Wichtige Eigenschaften:

• Werden als zweites in der Regelsequenz ausgeführt (nach Access Rules, vor Conditional Rules)
• Transformieren URLs vor der Cache-Abfrage
• nginx-artige URL-Umschreibung
• Werden in Positionsreihenfolge ausgewertet (1, 2, 3...)
• Stopp nach erstem Treffer – sobald eine Regel zutrifft, werden keine weiteren Rewrite Rules ausgewertet

Das Formular „Rewrite-Regel erstellen“: Name, Beschreibung, Übereinstimmungstyp, URI-Muster und Zielpfad.

Wie Rewrite Rules funktionieren

Rewrite Rules werden in aufsteigender Positionsreihenfolge (1 -> 2 -> 3...) für jede eingehende Anfrage ausgewertet. Wenn das URL-Muster einer Regel zutrifft, wird die URL zum Zielpfad umgeschrieben und die Auswertung stoppt.

Positionsbasierte Auswertung

Anfrage: /alter-pfad
    |
Rewrite Rule (Position 1) -> Treffer /alter-pfad? -> Umschreiben zu /neuer-pfad -> STOPP
    | (kein Treffer)
Rewrite Rule (Position 2) -> Treffer? -> Umschreiben -> STOPP
    | (kein Treffer)
Weiter zu Conditional Rules mit originaler oder umgeschriebener URL...

Wichtig: Sobald eine Rewrite Rule zutrifft, werden keine weiteren Rewrite Rules ausgewertet. Die umgeschriebene URL wird dann von allen nachfolgenden Conditional Rules verwendet.

URL-Abgleich

Rewrite Rules gleichen URLs mit drei verschiedenen Matchern ab:

Das Dropdown „Übereinstimmungstyp“: Gleich, regulärer Ausdruck und Regex ohne Groß-/Kleinschreibung.

Matcher

Gleich (=): Exakter Treffer

Matcher: Gleich
URL: /alte-seite
Ziel: /neue-seite

Trifft zu: /alte-seite
Trifft nicht zu: /alte-seite/, /alte-seite?query=1, /alte-seite-extra

Regulärer Ausdruck (~): Groß-/Kleinschreibung-sensitiver Regex

Matcher: Regulärer Ausdruck
URL: ^/blog/(\d+)
Ziel: /artikel/$1

Trifft zu: /blog/123 -> /artikel/123
Trifft nicht zu: /BLOG/123 (Groß-/Kleinschreibung-sensitiv)

Regex ohne Groß-/Kleinschreibung (~*): Groß-/Kleinschreibung-ignorierender Regex

Matcher: Regex ohne Groß-/Kleinschreibung
URL: ^/produkte/(.*)
Ziel: /shop/$1

Trifft zu: /produkte/artikel -> /shop/artikel
Trifft auch zu: /PRODUKTE/artikel -> /shop/artikel

URL vs URI

• URL: Die vollständige Webadresse inklusive Protokoll und Domain
  • Beispiel: https://www.beispiel.de/kategorie/daten.html
• URI: Nur der Pfad ohne Domain oder Protokoll
  • Beispiel: /kategorie/daten.html

Rewrite Rules arbeiten mit URIs (nur der Pfad).

Wann Rewrite Rules verwenden

Rewrite Rules verwenden wenn:

• Legacy-URLs unterstützt werden müssen, während die Site umstrukturiert wird
• saubere, SEO-freundliche URLs gewünscht sind (z. B. /produkt/123 statt /produkt.php?id=123)
• eine Migration von einer anderen Plattform erfolgt und alte URL-Strukturen beibehalten werden müssen
• URL-Normalisierung benötigt wird (z. B. Trailing-Slashes entfernen, URLs kleinschreiben)
• URL-Transformationen vor der Auswertung anderer Regeln stattfinden sollen

Rewrite Rules treiben auch die On-the-fly-Bildverarbeitung von smoxy an – sie bilden saubere, öffentliche URLs auf die Verarbeitungspfade /_sx/img/... ab.

Anwendungsfälle & Beispiele

Beispiel 1: Legacy-URL-Unterstützung

Szenario: Die Site wurde von /alter-bereich/seite.html zu /neuer-bereich/seite umstrukturiert, alte Links müssen aber weiter unterstützt werden.

Position: 1
Matcher: Regulärer Ausdruck
URL: ^/alter-bereich/(.*)\.html$
Ziel: /neuer-bereich/$1

Ergebnis:
/alter-bereich/ueber-uns.html -> /neuer-bereich/ueber-uns
/alter-bereich/kontakt.html -> /neuer-bereich/kontakt

Warum umschreiben statt weiterleiten? Umschreibungen sind transparent – der Benutzer sieht keine URL-Änderung, und der ursprüngliche Anfragekontext bleibt erhalten. Conditional Rules können dann Konfigurationen basierend auf der neuen URL anwenden.

Beispiel 2: Saubere URL-Struktur

Szenario: Die Anwendung verwendet Query-Parameter, saubere URLs für SEO sind aber gewünscht.

Position: 1
Matcher: Regulärer Ausdruck
URL: ^/produkt/([0-9]+)$
Ziel: /produkt.php?id=$1

Ergebnis:
/produkt/12345 -> /produkt.php?id=12345
(Saubere URL wird zur tatsächlichen Backend-URL umgeschrieben)

Warum das funktioniert: Benutzer und Suchmaschinen sehen saubere URLs (/produkt/12345), aber das Backend erhält das Query-Parameter-Format, das es erwartet.

Beispiel 3: Plattform-Migration

Szenario: Migration von WordPress zu einer neuen Plattform, wobei alte Post-URLs unterstützt werden müssen.

Position: 1
Matcher: Regulärer Ausdruck
URL: ^/([0-9]{4})/([0-9]{2})/(.*)$
Ziel: /posts/$1-$2-$3

Ergebnis:
/2024/03/mein-blog-post -> /posts/2024-03-mein-blog-post
/2023/12/ein-anderer-post -> /posts/2023-12-ein-anderer-post

Kombiniert mit Conditional Rules: Nach dem Umschreiben kann eine Conditional Rule, die /posts/* matched, spezifische Caching- oder Optimierungseinstellungen anwenden.

Zielpfad

Der Zielpfad ist das Ziel, zu dem die URL umgeschrieben wird. Er kann sein:

• Statischer Pfad: /neuer-ort
• Mit Capture-Groups: /bereich/$1 (verwendet Regex-Capture-Groups aus dem URL-Muster)
• Mehrere Captures: /kategorie/$1/artikel/$2

Wichtig: Der Zielpfad ist der tatsächliche Backend-Pfad, den die Anwendung erhält. Es muss sichergestellt sein, dass es ein gültiger Pfad ist, den die Anwendung verarbeiten kann.

Best Practices für die Regelreihenfolge

Da Rewrite Rules beim ersten Treffer stoppen, ist eine sorgfältige Anordnung wichtig. Wie die Rewrite-Reihenfolge in die Gesamtpipeline passt, ist unter Ausführung & Reihenfolge beschrieben.

1. Spezifischste zuerst

Position 1: /exakt/spezifischer/pfad -> /ziel1
Position 2: /spezifisch/* -> /ziel2
Position 3: /* -> /ziel3

2. Exakte Treffer vor Mustern

Position 1: = /spezial-seite -> /neue-spezial
Position 2: ~ ^/spezial -> /regulaer-spezial

3. Nachfolgende Regeln bedenken

Zu beachten: Conditional Rules werten gegen die umgeschriebene URL aus, nicht die originale:

Rewrite Rule: /alt/* -> /neu/*
Conditional Rule: Match /neu/* (nicht /alt/*)

4. Ähnliche Muster zusammenfassen

Regex einsetzen, um mehrere Fälle effizient zu behandeln:

Weniger effizient (mehrere Regeln):

/alt-ueber-uns -> /ueber-uns
/alt-kontakt -> /kontakt
/alt-hilfe -> /hilfe

Effizienter (eine Regel):

^/alt-(.*)$ -> /$1

Regex für Flexibilität einsetzen:

Mehrere spezifische Regeln:

/produkt-1 -> /artikel/1
/produkt-2 -> /artikel/2
...

Eine flexible Regel:

^/produkt-([0-9]+)$ -> /artikel/$1

Eindeutigkeit

Jede Zone muss eindeutige haben:

• Regelnamen – jede Regel muss einen eindeutigen Namen haben
• URL-Muster – doppelte URL-Muster sind nicht zulässig

Beim Versuch, ein Duplikat zu erstellen, erscheint: "Name existiert bereits" oder "Gleicher Matcher existiert."

Häufige Fehler

Catch-all-Umschreibung auf Position 1

Position 1: ~ ^/(.*)$ -> /neu/$1
-> Schreibt ALLES um, andere Regeln treffen nie zu

Spezifische Muster zuerst

Position 1: = /spezial -> /neu-spezial
Position 2: ~ ^/blog/(.*)$ -> /artikel/$1
Position 3: ~ ^/alt-(.*)$ -> /$1

---

Conditional Rules vergessen

Rewrite Rule: /alt-admin -> /admin
Conditional Rule: Match /alt-admin/* -> TRIFFT NIE ZU
Sollte matchen: /admin/*

Conditional Rules matchen umgeschriebene URLs

Rewrite Rule: /alt-admin -> /admin
Conditional Rule: Match /admin/* -> Trifft nach Umschreibung zu

---

Ungültiger Zielpfad

URL: ^/produkt/(.*)$
Ziel: /ungueltig/$2 (Capture-Group $2 existiert nicht)
-> Fehlerhafte Umschreibung

Gültige Capture-Groups

URL: ^/produkt/(.*)$
Ziel: /artikel/$1 (verwendet Capture-Group $1)

Rewrite Rules testen

1. Debug-Header aktivieren in der Zonen-Konfiguration
2. Testanfragen mit den originalen URLs durchführen
3. Response-Header prüfen um zu sehen, welche Regeln angewendet wurden und wie die URL transformiert wurde
4. Verifizieren, dass Conditional Rules die umgeschriebene URL matchen, nicht die originale