In manchen Situationen müssen Sie möglicherweise einen Proxy-Server wie Traefik oder Nginx verwenden, mit einer Konfiguration, die ein zusätzliches Pfadpräfix hinzufügt, das von Ihrer Anwendung nicht gesehen wird.
In diesen Fällen können Sie root_path verwenden, um Ihre Anwendung zu konfigurieren.
Der root_path („Wurzelpfad“) ist ein Mechanismus, der von der ASGI-Spezifikation bereitgestellt wird (auf der FastAPI via Starlette aufbaut).
Der root_path wird verwendet, um diese speziellen Fälle zu handhaben.
Und er wird auch intern beim Mounten von Unteranwendungen verwendet.
Ein Proxy mit einem abgetrennten Pfadpräfix bedeutet in diesem Fall, dass Sie einen Pfad unter /app in Ihrem Code deklarieren könnten, dann aber, eine Ebene darüber, den Proxy hinzufügen, der Ihre FastAPI-Anwendung unter einem Pfad wie /api/v1 platziert.
In diesem Fall würde der ursprüngliche Pfad /app tatsächlich unter /api/v1/app bereitgestellt.
Auch wenn Ihr gesamter Code unter der Annahme geschrieben ist, dass es nur /app gibt.
Und der Proxy würde das Pfadpräfix on-the-fly "entfernen", bevor er die Anfrage an Uvicorn übermittelt, dafür sorgend, dass Ihre Anwendung davon überzeugt ist, dass sie unter /app bereitgestellt wird, sodass Sie nicht Ihren gesamten Code dahingehend aktualisieren müssen, das Präfix /api/v1 zu verwenden.
Bis hierher würde alles wie gewohnt funktionieren.
Wenn Sie dann jedoch die Benutzeroberfläche der integrierten Dokumentation (das Frontend) öffnen, wird angenommen, dass sich das OpenAPI-Schema unter /openapi.json anstelle von /api/v1/openapi.json befindet.
Das Frontend (das im Browser läuft) würde also versuchen, /openapi.json zu erreichen und wäre nicht in der Lage, das OpenAPI-Schema abzurufen.
Da wir für unsere Anwendung einen Proxy mit dem Pfadpräfix /api/v1 haben, muss das Frontend das OpenAPI-Schema unter /api/v1/openapi.json abrufen.
Tipp
Die IP 0.0.0.0 wird üblicherweise verwendet, um anzudeuten, dass das Programm alle auf diesem Computer/Server verfügbaren IPs abhört.
Die Benutzeroberfläche der Dokumentation würde benötigen, dass das OpenAPI-Schema deklariert, dass sich dieser API-server unter /api/v1 (hinter dem Proxy) befindet. Zum Beispiel:
{"openapi":"3.1.0",// Hier mehr Einstellungen"servers":[{"url":"/api/v1"}],"paths":{// Hier mehr Einstellungen}}
In diesem Beispiel könnte der „Proxy“ etwa Traefik sein. Und der Server wäre so etwas wie Uvicorn, auf dem Ihre FastAPI-Anwendung ausgeführt wird.
Sie können den aktuellen root_path abrufen, der von Ihrer Anwendung für jede Anfrage verwendet wird. Er ist Teil des scope-Dictionarys (das ist Teil der ASGI-Spezifikation).
Hier fügen wir ihn, nur zu Demonstrationszwecken, in die Nachricht ein.
Falls Sie keine Möglichkeit haben, eine Kommandozeilenoption wie --root-path oder ähnlich zu übergeben, können Sie als Alternative beim Erstellen Ihrer FastAPI-Anwendung den Parameter root_path setzen:
Es wird also nicht erwartet, dass unter http://127.0.0.1:8000/api/v1/app darauf zugegriffen wird.
Uvicorn erwartet, dass der Proxy unter http://127.0.0.1:8000/app auf Uvicorn zugreift, und dann liegt es in der Verantwortung des Proxys, das zusätzliche /api/v1-Präfix darüber hinzuzufügen.
Bedenken Sie, dass ein Proxy mit abgetrennten Pfadpräfix nur eine von vielen Konfigurationsmöglichkeiten ist.
Wahrscheinlich wird in vielen Fällen die Standardeinstellung sein, dass der Proxy kein abgetrenntes Pfadpräfix hat.
In einem solchen Fall (ohne ein abgetrenntes Pfadpräfix) würde der Proxy auf etwas wie https://myawesomeapp.com lauschen, und wenn der Browser dann zu https://myawesomeapp.com/api/v1/ wechselt, und Ihr Server (z. B. Uvicorn) auf http://127.0.0.1:8000 lauscht, würde der Proxy (ohne ein abgetrenntes Pfadpräfix) über denselben Pfad auf Uvicorn zugreifen: http://127.0.0.1:8000/api/v1/app.
Wenn Sie nun zur URL mit dem Port für Uvicorn gehen: http://127.0.0.1:8000/app, sehen Sie die normale Response:
{"message":"Hello World","root_path":"/api/v1"}
Tipp
Beachten Sie, dass, obwohl Sie unter http://127.0.0.1:8000/app darauf zugreifen, als root_path angezeigt wird /api/v1, welches aus der Option --root-path stammt.
Diesmal jedoch unter der URL mit dem vom Proxy bereitgestellten Präfixpfad: /api/v1.
Die Idee hier ist natürlich, dass jeder über den Proxy auf die Anwendung zugreifen soll, daher ist die Version mit dem Pfadpräfix /api/v1 die „korrekte“.
Und die von Uvicorn direkt bereitgestellte Version ohne Pfadpräfix (http://127.0.0.1:8000/app) wäre ausschließlich für den Zugriff durch den Proxy (Traefik) bestimmt.
Dies demonstriert, wie der Proxy (Traefik) das Pfadpräfix verwendet und wie der Server (Uvicorn) den root_path aus der Option --root-path verwendet.
Der „offizielle“ Weg, auf die Anwendung zuzugreifen, wäre über den Proxy mit dem von uns definierten Pfadpräfix. Wenn Sie also die von Uvicorn direkt bereitgestellte Dokumentationsoberfläche ohne das Pfadpräfix in der URL ausprobieren, wird es erwartungsgemäß nicht funktionieren, da erwartet wird, dass der Zugriff über den Proxy erfolgt.
Wenn wir jedoch unter der „offiziellen“ URL, über den Proxy mit Port 9999, unter /api/v1/docs, auf die Dokumentationsoberfläche zugreifen, funktioniert es ordnungsgemäß! 🎉
Dies ist ein fortgeschrittener Anwendungsfall. Überspringen Sie das gerne.
Standardmäßig erstellt FastAPI einen server im OpenAPI-Schema mit der URL für den root_path.
Sie können aber auch andere alternative server bereitstellen, beispielsweise wenn Sie möchten, dass dieselbe Dokumentationsoberfläche mit einer Staging- und Produktionsumgebung interagiert.
Wenn Sie eine benutzerdefinierte Liste von Servern (servers) übergeben und es einen root_path gibt (da Ihre API hinter einem Proxy läuft), fügt FastAPI einen „Server“ mit diesem root_path am Anfang der Liste ein.
{"openapi":"3.1.0",// Hier mehr Einstellungen"servers":[{"url":"/api/v1"},{"url":"https://stag.example.com","description":"Staging environment"},{"url":"https://prod.example.com","description":"Production environment"}],"paths":{// Hier mehr Einstellungen}}
Tipp
Beachten Sie den automatisch generierten Server mit dem URL-Wert /api/v1, welcher vom root_path stammt.
Die Dokumentationsoberfläche interagiert mit dem von Ihnen ausgewählten Server.
Den automatischen Server von root_path deaktivieren¶
Wenn Sie nicht möchten, dass FastAPI einen automatischen Server inkludiert, welcher root_path verwendet, können Sie den Parameter root_path_in_servers=False verwenden:
Wenn Sie gleichzeitig eine Unteranwendung mounten (wie beschrieben in Unteranwendungen – Mounts) und einen Proxy mit root_path verwenden wollen, können Sie das normal tun, wie Sie es erwarten würden.
FastAPI verwendet intern den root_path auf intelligente Weise, sodass es einfach funktioniert. ✨