From 392b056dd98b74d162977629d644a6b38a234a3e Mon Sep 17 00:00:00 2001 From: AnshMNSoni Date: Tue, 13 Jan 2026 11:17:55 +0530 Subject: [PATCH] Fix duplicate make_authenticate_headers method in HTTPBasic class --- docs/fr/docs/advanced/response-directly.md | 14 ++--- docs/fr/docs/alternatives.md | 52 ++++++++--------- docs/fr/docs/benchmarks.md | 4 +- docs/fr/docs/features.md | 30 +++++----- docs/fr/docs/history-design-future.md | 18 +++--- docs/fr/docs/learn/index.md | 2 +- docs/fr/docs/tutorial/background-tasks.md | 24 ++++---- docs/fr/docs/tutorial/body.md | 36 ++++++------ docs/fr/docs/tutorial/debugging.md | 12 ++-- .../docs/advanced/additional-status-codes.md | 8 +-- docs/ja/docs/advanced/response-directly.md | 14 ++--- docs/ja/docs/deployment/concepts.md | 56 +++++++++---------- docs/ja/docs/deployment/versions.md | 20 +++---- docs/ja/docs/features.md | 30 +++++----- docs/ja/docs/learn/index.md | 2 +- docs/ja/docs/tutorial/background-tasks.md | 26 ++++----- docs/ja/docs/tutorial/body-updates.md | 22 ++++---- docs/ja/docs/tutorial/body.md | 38 ++++++------- docs/ja/docs/tutorial/cookie-param-models.md | 12 ++-- docs/ja/docs/tutorial/cookie-params.md | 12 ++-- docs/ja/docs/tutorial/debugging.md | 12 ++-- docs/ja/docs/tutorial/encoder.md | 6 +- docs/ja/docs/tutorial/extra-data-types.md | 14 ++--- docs/ja/docs/tutorial/header-params.md | 20 +++---- docs/ja/docs/tutorial/query-param-models.md | 10 ++-- docs/ja/docs/tutorial/response-status-code.md | 14 ++--- docs/ja/docs/tutorial/security/index.md | 16 +++--- docs/pt/docs/tutorial/extra-models.md | 12 ++-- docs/pt/docs/tutorial/sql-databases.md | 2 +- docs/pt/docs/virtual-environments.md | 2 +- docs/ru/docs/tutorial/extra-models.md | 12 ++-- docs/tr/docs/about/index.md | 2 +- docs/tr/docs/advanced/security/index.md | 6 +- docs/tr/docs/advanced/testing-websockets.md | 6 +- docs/tr/docs/advanced/wsgi.md | 10 ++-- docs/tr/docs/alternatives.md | 50 ++++++++--------- docs/tr/docs/benchmarks.md | 4 +- docs/tr/docs/history-design-future.md | 14 ++--- docs/tr/docs/how-to/general.md | 20 +++---- docs/tr/docs/learn/index.md | 2 +- docs/tr/docs/resources/index.md | 2 +- docs/tr/docs/tutorial/query-params.md | 18 +++--- docs/tr/docs/tutorial/static-files.md | 12 ++-- docs/uk/docs/alternatives.md | 50 ++++++++--------- docs/zh-hant/docs/about/index.md | 2 +- docs/zh-hant/docs/benchmarks.md | 4 +- docs/zh-hant/docs/how-to/index.md | 2 +- docs/zh-hant/docs/learn/index.md | 2 +- docs/zh-hant/docs/resources/index.md | 2 +- .../docs/tutorial/query-param-models.md | 10 ++-- .../docs/advanced/additional-status-codes.md | 8 +-- docs/zh/docs/advanced/async-tests.md | 22 ++++---- docs/zh/docs/advanced/middleware.md | 20 +++---- docs/zh/docs/advanced/openapi-callbacks.md | 38 ++++++------- docs/zh/docs/advanced/openapi-webhooks.md | 12 ++-- .../advanced/response-change-status-code.md | 8 +-- docs/zh/docs/advanced/response-cookies.md | 12 ++-- docs/zh/docs/advanced/response-directly.md | 14 ++--- .../docs/advanced/security/http-basic-auth.md | 16 +++--- docs/zh/docs/advanced/security/index.md | 6 +- .../docs/advanced/security/oauth2-scopes.md | 46 +++++++-------- docs/zh/docs/advanced/sub-applications.md | 22 ++++---- docs/zh/docs/advanced/testing-dependencies.md | 8 +-- .../docs/advanced/using-request-directly.md | 10 ++-- docs/zh/docs/advanced/wsgi.md | 8 +-- docs/zh/docs/async.md | 46 +++++++-------- docs/zh/docs/deployment/concepts.md | 56 +++++++++---------- docs/zh/docs/deployment/manually.md | 14 ++--- docs/zh/docs/deployment/versions.md | 32 +++++------ docs/zh/docs/features.md | 28 +++++----- docs/zh/docs/history-design-future.md | 14 ++--- docs/zh/docs/how-to/configure-swagger-ui.md | 20 +++---- docs/zh/docs/how-to/general.md | 22 ++++---- docs/zh/docs/how-to/index.md | 2 +- docs/zh/docs/project-generation.md | 12 ++-- docs/zh/docs/tutorial/cookie-param-models.md | 12 ++-- docs/zh/docs/tutorial/cookie-params.md | 8 +-- docs/zh/docs/tutorial/debugging.md | 12 ++-- ...pendencies-in-path-operation-decorators.md | 26 ++++----- .../dependencies/global-dependencies.md | 6 +- docs/zh/docs/tutorial/encoder.md | 4 +- docs/zh/docs/tutorial/extra-data-types.md | 10 ++-- docs/zh/docs/tutorial/header-params.md | 12 ++-- docs/zh/docs/tutorial/query-param-models.md | 10 ++-- docs/zh/docs/tutorial/request-form-models.md | 10 ++-- docs/zh/docs/tutorial/response-status-code.md | 14 ++--- .../tutorial/security/get-current-user.md | 28 +++++----- docs/zh/docs/tutorial/security/index.md | 16 +++--- .../docs/tutorial/security/simple-oauth2.md | 46 +++++++-------- fastapi/security/http.py | 2 - 90 files changed, 740 insertions(+), 742 deletions(-) diff --git a/docs/fr/docs/advanced/response-directly.md b/docs/fr/docs/advanced/response-directly.md index 4ff883c77..d26d0afb5 100644 --- a/docs/fr/docs/advanced/response-directly.md +++ b/docs/fr/docs/advanced/response-directly.md @@ -1,4 +1,4 @@ -# Renvoyer directement une réponse +# Renvoyer directement une réponse { #return-a-response-directly } Lorsque vous créez une *opération de chemins* **FastAPI**, vous pouvez normalement retourner n'importe quelle donnée : un `dict`, une `list`, un modèle Pydantic, un modèle de base de données, etc. @@ -10,7 +10,7 @@ Mais vous pouvez retourner une `JSONResponse` directement à partir de vos *opé Cela peut être utile, par exemple, pour retourner des en-têtes personnalisés ou des cookies. -## Renvoyer une `Response` +## Renvoyer une `Response` { #return-a-response } En fait, vous pouvez retourner n'importe quelle `Response` ou n'importe quelle sous-classe de celle-ci. @@ -26,7 +26,7 @@ Elle ne fera aucune conversion de données avec les modèles Pydantic, elle ne c Cela vous donne beaucoup de flexibilité. Vous pouvez retourner n'importe quel type de données, surcharger n'importe quelle déclaration ou validation de données. -## Utiliser le `jsonable_encoder` dans une `Response` +## Utiliser le `jsonable_encoder` dans une `Response` { #using-the-jsonable-encoder-in-a-response } Parce que **FastAPI** n'apporte aucune modification à une `Response` que vous retournez, vous devez vous assurer que son contenu est prêt à être utilisé (sérialisable). @@ -34,7 +34,7 @@ Par exemple, vous ne pouvez pas mettre un modèle Pydantic dans une `JSONRespons Pour ces cas, vous pouvez spécifier un appel à `jsonable_encoder` pour convertir vos données avant de les passer à une réponse : -{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *} +{* ../../docs_src/response_directly/tutorial001_py310.py hl[5:6,20:21] *} /// note | Détails techniques @@ -44,7 +44,7 @@ Vous pouvez aussi utiliser `from starlette.responses import JSONResponse`. /// -## Renvoyer une `Response` personnalisée +## Renvoyer une `Response` personnalisée { #returning-a-custom-response } L'exemple ci-dessus montre toutes les parties dont vous avez besoin, mais il n'est pas encore très utile, car vous auriez pu retourner l'`item` directement, et **FastAPI** l'aurait mis dans une `JSONResponse` pour vous, en le convertissant en `dict`, etc. Tout cela par défaut. @@ -54,9 +54,9 @@ Disons que vous voulez retourner une réponse Django +### Django { #django } C'est le framework Python le plus populaire et il bénéficie d'une grande confiance. Il est utilisé pour construire des systèmes tel qu'Instagram. @@ -28,7 +28,7 @@ stockage. Il a été créé pour générer le HTML en backend, pas pour créer des API consommées par un frontend moderne (comme React, Vue.js et Angular) ou par d'autres systèmes (comme les appareils IoT) communiquant avec lui. -### Django REST Framework +### Django REST Framework { #django-rest-framework } Django REST framework a été conçu comme une boîte à outils flexible permettant de construire des API Web à partir de Django, afin d'améliorer ses capacités en matière d'API. @@ -49,7 +49,7 @@ Avoir une interface de documentation automatique de l'API. /// -### Flask +### Flask { #flask } Flask est un "micro-framework", il ne comprend pas d'intégrations de bases de données ni beaucoup de choses qui sont fournies par défaut dans Django. @@ -73,7 +73,7 @@ Proposer un système de routage simple et facile à utiliser. /// -### Requests +### Requests { #requests } **FastAPI** n'est pas réellement une alternative à **Requests**. Leur cadre est très différent. @@ -115,7 +115,7 @@ Utiliser les noms de méthodes HTTP (opérations) directement, de manière simpl /// -### Swagger / OpenAPI +### Swagger / OpenAPI { #swagger-openapi } La principale fonctionnalité que j'ai emprunté à Django REST Framework était la documentation automatique des API. @@ -141,13 +141,13 @@ Ces deux-là ont été choisis parce qu'ils sont populaires et stables, mais en /// -### Frameworks REST pour Flask +### Frameworks REST pour Flask { #flask-rest-frameworks } Il y a plusieurs frameworks REST pour Flask, mais après avoir investi du temps et du travail pour les étudier, j'ai découvert que le développement de beaucoup d'entre eux sont suspendus ou abandonnés, avec plusieurs problèmes permanents qui les rendent inadaptés. -### Marshmallow +### Marshmallow { #marshmallow } L'une des principales fonctionnalités nécessaires aux systèmes API est la "sérialisation" des données, qui consiste à prendre les données du code (Python) et à @@ -172,7 +172,7 @@ Utilisez du code pour définir des "schémas" qui fournissent automatiquement le /// -### Webargs +### Webargs { #webargs } Une autre grande fonctionnalité requise par les API est le parsing des données provenant des requêtes entrantes. @@ -195,7 +195,7 @@ Disposer d'une validation automatique des données des requêtes entrantes. /// -### APISpec +### APISpec { #apispec } Marshmallow et Webargs fournissent la validation, l'analyse et la sérialisation en tant que plug-ins. @@ -225,7 +225,7 @@ Supporter la norme ouverte pour les API, OpenAPI. /// -### Flask-apispec +### Flask-apispec { #flask-apispec } C'est un plug-in pour Flask, qui relie Webargs, Marshmallow et APISpec. @@ -244,7 +244,7 @@ j'ai (ainsi que plusieurs équipes externes) utilisées jusqu'à présent : - https://github.com/tiangolo/full-stack-flask-couchbase - https://github.com/tiangolo/full-stack-flask-couchdb -Ces mêmes générateurs full-stack ont servi de base aux [Générateurs de projets pour **FastAPI**](project-generation.md){.internal-link target=\_blank}. +Ces mêmes générateurs full-stack ont servi de base aux [Générateurs de projets pour **FastAPI**](project-generation.md){.internal-link target=_blank}. /// info @@ -258,7 +258,7 @@ Générer le schéma OpenAPI automatiquement, à partir du même code qui défin /// -### NestJS (et Angular) +### NestJS (et Angular) { #nestjs-and-angular } Ce n'est même pas du Python, NestJS est un framework JavaScript (TypeScript) NodeJS inspiré d'Angular. @@ -281,7 +281,7 @@ Disposer d'un puissant système d'injection de dépendances. Trouver un moyen de /// -### Sanic +### Sanic { #sanic } C'était l'un des premiers frameworks Python extrêmement rapides basés sur `asyncio`. Il a été conçu pour être très similaire à Flask. @@ -301,7 +301,7 @@ C'est pourquoi **FastAPI** est basé sur Starlette, car il s'agit du framework l /// -### Falcon +### Falcon { #falcon } Falcon est un autre framework Python haute performance, il est conçu pour être minimal, et est utilisé comme fondation pour d'autres frameworks comme Hug. @@ -323,7 +323,7 @@ Bien que dans FastAPI, il est facultatif, et est utilisé principalement pour d /// -### Molten +### Molten { #molten } J'ai découvert Molten lors des premières étapes de développement de **FastAPI**. Et il a des idées assez similaires : @@ -351,7 +351,7 @@ Cela a en fait inspiré la mise à jour de certaines parties de Pydantic, afin d /// -### Hug +### Hug { #hug } Hug a été l'un des premiers frameworks à implémenter la déclaration des types de paramètres d'API en utilisant les type hints Python. C'était une excellente idée qui a inspiré d'autres outils à faire de même. @@ -383,7 +383,7 @@ Hug a inspiré **FastAPI** pour déclarer un paramètre `response` dans les fonc /// -### APIStar (<= 0.5) +### APIStar (<= 0.5) { #apistar-0-5 } Juste avant de décider de développer **FastAPI**, j'ai trouvé le serveur **APIStar**. Il contenait presque tout ce que je recherchais et avait un beau design. @@ -433,9 +433,9 @@ Je considère **FastAPI** comme un "successeur spirituel" d'APIStar, tout en am /// -## Utilisés par **FastAPI** +## Utilisés par **FastAPI** { #used-by-fastapi } -### Pydantic +### Pydantic { #pydantic } Pydantic est une bibliothèque permettant de définir la validation, la sérialisation et la documentation des données (à l'aide de JSON Schema) en se basant sur les Python type hints. @@ -452,7 +452,7 @@ Gérer toute la validation des données, leur sérialisation et la documentation /// -### Starlette +### Starlette { #starlette } Starlette est un framework/toolkit léger ASGI, qui est idéal pour construire des services asyncio performants. @@ -498,7 +498,7 @@ Ainsi, tout ce que vous pouvez faire avec Starlette, vous pouvez le faire direct /// -### Uvicorn +### Uvicorn { #uvicorn } Uvicorn est un serveur ASGI rapide comme l'éclair, basé sur uvloop et httptools. @@ -517,6 +517,6 @@ Pour plus de détails, consultez la section [Déploiement](deployment/index.md){ /// -## Benchmarks et vitesse +## Benchmarks et vitesse { #benchmarks-and-speed } -Pour comprendre, comparer et voir la différence entre Uvicorn, Starlette et FastAPI, consultez la section sur les [Benchmarks](benchmarks.md){.internal-link target=\_blank}. +Pour comprendre, comparer et voir la différence entre Uvicorn, Starlette et FastAPI, consultez la section sur les [Benchmarks](benchmarks.md){.internal-link target=_blank}. diff --git a/docs/fr/docs/benchmarks.md b/docs/fr/docs/benchmarks.md index d33c263a2..17fbac1c7 100644 --- a/docs/fr/docs/benchmarks.md +++ b/docs/fr/docs/benchmarks.md @@ -1,10 +1,10 @@ -# Test de performance +# Test de performance { #benchmarks } Les tests de performance de TechEmpower montrent que les applications **FastAPI** tournant sous Uvicorn comme étant l'un des frameworks Python les plus rapides disponibles, seulement inférieur à Starlette et Uvicorn (tous deux utilisés au cœur de FastAPI). (*) Mais en prêtant attention aux tests de performance et aux comparaisons, il faut tenir compte de ce qu'il suit. -## Tests de performance et rapidité +## Tests de performance et rapidité { #benchmarks-and-speed } Lorsque vous vérifiez les tests de performance, il est commun de voir plusieurs outils de différents types comparés comme équivalents. diff --git a/docs/fr/docs/features.md b/docs/fr/docs/features.md index bc63e11b4..97f8515bf 100644 --- a/docs/fr/docs/features.md +++ b/docs/fr/docs/features.md @@ -1,17 +1,17 @@ -# Fonctionnalités +# Fonctionnalités { #features } -## Fonctionnalités de FastAPI +## Fonctionnalités de FastAPI { #fastapi-features } **FastAPI** vous offre ceci: -### Basé sur des standards ouverts +### Basé sur des standards ouverts { #based-on-open-standards } * OpenAPI pour la création d'API, incluant la déclaration de path operations, paramètres, corps de requêtes, sécurité, etc. -* Documentation automatique des modèles de données avec JSON Schema (comme OpenAPI est aussi basée sur JSON Schema). +* Documentation automatique des modèles de données avec JSON Schema (comme OpenAPI est aussi basée sur JSON Schema). * Conçue avec ces standards après une analyse méticuleuse. Plutôt qu'en rajoutant des surcouches après coup. * Cela permet d'utiliser de la **génération automatique de code client** dans beaucoup de langages. -### Documentation automatique +### Documentation automatique { #automatic-docs } Documentation d'API interactive et interface web d'exploration. Comme le framework est basé sur OpenAPI, de nombreuses options sont disponibles. Deux d'entre-elles sont incluses par défaut. @@ -23,7 +23,7 @@ Documentation d'API interactive et interface web d'exploration. Comme le framewo ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) -### Faite en python moderne +### Faite en python moderne { #just-modern-python } Tout est basé sur la déclaration de type standard de **Python 3.8** (grâce à Pydantic). Pas de nouvelles syntaxes à apprendre. Juste du Python standard et moderne. @@ -70,7 +70,7 @@ Utilise les clés et valeurs du dictionnaire `second_user_data` directement comm /// -### Support d'éditeurs +### Support d'éditeurs { #editor-support } Tout le framework a été conçu pour être facile et intuitif d'utilisation, toutes les décisions de design ont été testées sur de nombreux éditeurs avant même de commencer le développement final afin d'assurer la meilleure expérience de développement possible. @@ -94,13 +94,13 @@ Vous aurez des propositions de complétion que vous n'auriez jamais imaginées. Plus jamais vous ne vous tromperez en tapant le nom d'une clé, vous ne ferez des aller-retour entre votre code et la documentation ou vous ne scrollerez de haut en bas afin d'enfin savoir si vous devez taper `username` ou `user_name`. -### Court +### Court { #short } Des **valeurs par défaut** sont définies pour tout, des configurations optionnelles sont présentent partout. Tous ces paramètres peuvent être ajustés afin de faire ce que vous voulez et définir l'API dont vous avez besoin. Mais, **tout fonctionne** par défaut. -### Validation +### Validation { #validation } * Validation pour la plupart (ou tous?) les **types de données** Python incluant: * objets JSON (`dict`). @@ -116,7 +116,7 @@ Mais, **tout fonctionne** par défaut. Toutes les validations sont gérées par le bien établi et robuste **Pydantic**. -### Sécurité et authentification +### Sécurité et authentification { #security-and-authentication } La sécurité et l'authentification sont intégrées. Sans aucun compromis avec les bases de données ou les modèles de données. @@ -133,7 +133,7 @@ Plus toutes les fonctionnalités de sécurités venant de Starlette (incluant le Le tout conçu en composant réutilisable facilement intégrable à vos systèmes, data stores, base de données relationnelle ou NoSQL, etc. -### Injection de dépendances +### Injection de dépendances { #dependency-injection } FastAPI contient un système simple mais extrêmement puissant d'Injection de Dépendances. @@ -144,19 +144,19 @@ FastAPI contient un système simple mais extrêmement puissant d'de couverture de test. * 100% d'annotations de type dans le code. * Utilisé dans des applications mises en production. -## Fonctionnalités de Starlette +## Fonctionnalités de Starlette { #starlette-features } **FastAPI** est complètement compatible (et basé sur) Starlette. Le code utilisant Starlette que vous ajouterez fonctionnera donc aussi. @@ -175,7 +175,7 @@ Avec **FastAPI** vous aurez toutes les fonctionnalités de **Starlette** (FastAP * Une couverture de test à 100 %. * 100 % de la base de code avec des annotations de type. -## Fonctionnalités de Pydantic +## Fonctionnalités de Pydantic { #pydantic-features } **FastAPI** est totalement compatible avec (et basé sur) Pydantic. Le code utilisant Pydantic que vous ajouterez fonctionnera donc aussi. diff --git a/docs/fr/docs/history-design-future.md b/docs/fr/docs/history-design-future.md index 15be545ee..f85f8f142 100644 --- a/docs/fr/docs/history-design-future.md +++ b/docs/fr/docs/history-design-future.md @@ -1,4 +1,4 @@ -# Histoire, conception et avenir +# Histoire, conception et avenir { #history-design-and-future } Il y a quelque temps, un utilisateur de **FastAPI** a demandé : @@ -6,7 +6,7 @@ Il y a quelque temps, @@ -28,7 +28,7 @@ Mais à un moment donné, il n'y avait pas d'autre option que de créer quelque -## Recherche +## Recherche { #investigation } En utilisant toutes les alternatives précédentes, j'ai eu la chance d'apprendre de toutes, de prendre des idées, et de les combiner de la meilleure façon que j'ai pu trouver pour moi-même et les équipes de développeurs avec lesquelles j'ai travaillé. @@ -38,7 +38,7 @@ De plus, la meilleure approche était d'utiliser des normes déjà existantes. Ainsi, avant même de commencer à coder **FastAPI**, j'ai passé plusieurs mois à étudier les spécifications d'OpenAPI, JSON Schema, OAuth2, etc. Comprendre leurs relations, leurs similarités et leurs différences. -## Conception +## Conception { #design } Ensuite, j'ai passé du temps à concevoir l'"API" de développeur que je voulais avoir en tant qu'utilisateur (en tant que développeur utilisant FastAPI). @@ -52,7 +52,7 @@ Ainsi, j'ai pu trouver les meilleurs moyens de réduire autant que possible la d Le tout de manière à offrir la meilleure expérience de développement à tous les développeurs. -## Exigences +## Exigences { #requirements } Après avoir testé plusieurs alternatives, j'ai décidé que j'allais utiliser **Pydantic** pour ses avantages. @@ -60,11 +60,11 @@ J'y ai ensuite contribué, pour le rendre entièrement compatible avec JSON Sche Pendant le développement, j'ai également contribué à **Starlette**, l'autre exigence clé. -## Développement +## Développement { #development } Au moment où j'ai commencé à créer **FastAPI** lui-même, la plupart des pièces étaient déjà en place, la conception était définie, les exigences et les outils étaient prêts, et la connaissance des normes et des spécifications était claire et fraîche. -## Futur +## Futur { #future } À ce stade, il est déjà clair que **FastAPI** et ses idées sont utiles pour de nombreuses personnes. @@ -76,4 +76,4 @@ Mais il y a encore de nombreuses améliorations et fonctionnalités à venir. **FastAPI** a un grand avenir devant lui. -Et [votre aide](help-fastapi.md){.internal-link target=\_blank} est grandement appréciée. +Et [votre aide](help-fastapi.md){.internal-link target=_blank} est grandement appréciée. diff --git a/docs/fr/docs/learn/index.md b/docs/fr/docs/learn/index.md index 46fc095dc..e74a53985 100644 --- a/docs/fr/docs/learn/index.md +++ b/docs/fr/docs/learn/index.md @@ -1,4 +1,4 @@ -# Apprendre +# Apprendre { #learn } Voici les sections introductives et les tutoriels pour apprendre **FastAPI**. diff --git a/docs/fr/docs/tutorial/background-tasks.md b/docs/fr/docs/tutorial/background-tasks.md index 6efd16e07..c8d720402 100644 --- a/docs/fr/docs/tutorial/background-tasks.md +++ b/docs/fr/docs/tutorial/background-tasks.md @@ -1,4 +1,4 @@ -# Tâches d'arrière-plan +# Tâches d'arrière-plan { #background-tasks } Vous pouvez définir des tâches d'arrière-plan qui seront exécutées après avoir retourné une réponse. @@ -12,15 +12,15 @@ Cela comprend, par exemple : * Par exemple, si vous recevez un fichier qui doit passer par un traitement lent, vous pouvez retourner une réponse «Accepted» (HTTP 202) puis faire le traitement en arrière-plan. -## Utiliser `BackgroundTasks` +## Utiliser `BackgroundTasks` { #using-backgroundtasks } Pour commencer, importez `BackgroundTasks` et définissez un paramètre dans votre *fonction de chemin* avec `BackgroundTasks` comme type déclaré. -{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *} +{* ../../docs_src/background_tasks/tutorial001_py39.py hl[1,13] *} **FastAPI** créera l'objet de type `BackgroundTasks` pour vous et le passera comme paramètre. -## Créer une fonction de tâche +## Créer une fonction de tâche { #create-a-task-function } Une fonction à exécuter comme tâche d'arrière-plan est juste une fonction standard qui peut recevoir des paramètres. @@ -30,14 +30,14 @@ Dans cet exemple, la fonction de tâche écrira dans un fichier (afin de simuler L'opération d'écriture n'utilisant ni `async` ni `await`, on définit la fonction avec un `def` normal. -{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *} +{* ../../docs_src/background_tasks/tutorial001_py39.py hl[6:9] *} -## Ajouter une tâche d'arrière-plan +## Ajouter une tâche d'arrière-plan { #add-the-background-task } Dans votre *fonction de chemin*, passez votre fonction de tâche à l'objet de type `BackgroundTasks` (`background_tasks` ici) grâce à la méthode `.add_task()` : -{* ../../docs_src/background_tasks/tutorial001.py hl[14] *} +{* ../../docs_src/background_tasks/tutorial001_py39.py hl[14] *} `.add_task()` reçoit comme arguments : @@ -45,13 +45,13 @@ Dans votre *fonction de chemin*, passez votre fonction de tâche à l'objet de t * Les arguments positionnels à passer à la fonction de tâche dans l'ordre (`email`). * Les arguments nommés à passer à la fonction de tâche (`message="some notification"`). -## Injection de dépendances +## Injection de dépendances { #dependency-injection } Utiliser `BackgroundTasks` fonctionne aussi avec le système d'injection de dépendances. Vous pouvez déclarer un paramètre de type `BackgroundTasks` à différents niveaux : dans une *fonction de chemin*, dans une dépendance, dans une sous-dépendance... **FastAPI** sait quoi faire dans chaque cas et comment réutiliser le même objet, afin que tous les paramètres de type `BackgroundTasks` soient fusionnés et que les tâches soient exécutées en arrière-plan : -{* ../../docs_src/background_tasks/tutorial002.py hl[13,15,22,25] *} +{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *} Dans cet exemple, les messages seront écrits dans le fichier `log.txt` après que la réponse soit envoyée. @@ -59,7 +59,7 @@ S'il y avait une `query` (paramètre nommé `q`) dans la requête, alors elle se Et ensuite une autre tâche d'arrière-plan (générée dans les paramètres de la *la fonction de chemin*) écrira un message dans `log.txt` comprenant le paramètre de chemin `email`. -## Détails techniques +## Détails techniques { #technical-details } La classe `BackgroundTasks` provient directement de `starlette.background`. @@ -71,7 +71,7 @@ Il est tout de même possible d'utiliser `BackgroundTask` seul dans **FastAPI**, Plus de détails sont disponibles dans la documentation officielle de Starlette sur les tâches d'arrière-plan (via leurs classes `BackgroundTasks`et `BackgroundTask`). -## Avertissement +## Avertissement { #caveat } Si vous avez besoin de réaliser des traitements lourds en tâche d'arrière-plan et que vous n'avez pas besoin que ces traitements aient lieu dans le même process (par exemple, pas besoin de partager la mémoire, les variables, etc.), il peut s'avérer profitable d'utiliser des outils plus importants tels que Celery. @@ -79,6 +79,6 @@ Ces outils nécessitent généralement des configurations plus complexes ainsi q Mais si vous avez besoin d'accéder aux variables et objets de la même application **FastAPI**, ou si vous avez besoin d'effectuer de petites tâches d'arrière-plan (comme envoyer des notifications par email), vous pouvez simplement vous contenter d'utiliser `BackgroundTasks`. -## Résumé +## Résumé { #recap } Importez et utilisez `BackgroundTasks` grâce aux paramètres de *fonction de chemin* et les dépendances pour ajouter des tâches d'arrière-plan. diff --git a/docs/fr/docs/tutorial/body.md b/docs/fr/docs/tutorial/body.md index 760b6d80a..2fa1b030c 100644 --- a/docs/fr/docs/tutorial/body.md +++ b/docs/fr/docs/tutorial/body.md @@ -1,4 +1,4 @@ -# Corps de la requête +# Corps de la requête { #request-body } Quand vous avez besoin d'envoyer de la donnée depuis un client (comme un navigateur) vers votre API, vous l'envoyez en tant que **corps de requête**. @@ -18,19 +18,19 @@ Ceci étant découragé, la documentation interactive générée par Swagger UI /// -## Importez le `BaseModel` de Pydantic +## Importez le `BaseModel` de Pydantic { #import-pydantics-basemodel } Commencez par importer la classe `BaseModel` du module `pydantic` : -{* ../../docs_src/body/tutorial001.py hl[4] *} +{* ../../docs_src/body/tutorial001_py310.py hl[2] *} -## Créez votre modèle de données +## Créez votre modèle de données { #create-your-data-model } Déclarez ensuite votre modèle de données en tant que classe qui hérite de `BaseModel`. Utilisez les types Python standard pour tous les attributs : -{* ../../docs_src/body/tutorial001.py hl[7:11] *} +{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *} Tout comme pour la déclaration de paramètres de requête, quand un attribut de modèle a une valeur par défaut, il n'est pas nécessaire. Sinon, cet attribut doit être renseigné dans le corps de la requête. Pour rendre ce champ optionnel simplement, utilisez `None` comme valeur par défaut. @@ -54,15 +54,15 @@ Par exemple, le modèle ci-dessus déclare un "objet" JSON (ou `dict` Python) te } ``` -## Déclarez-le comme paramètre +## Déclarez-le comme paramètre { #declare-it-as-a-parameter } Pour l'ajouter à votre *opération de chemin*, déclarez-le comme vous déclareriez des paramètres de chemin ou de requête : -{* ../../docs_src/body/tutorial001.py hl[18] *} +{* ../../docs_src/body/tutorial001_py310.py hl[16] *} ...et déclarez que son type est le modèle que vous avez créé : `Item`. -## Résultats +## Résultats { #results } En utilisant uniquement les déclarations de type Python, **FastAPI** réussit à : @@ -75,7 +75,7 @@ En utilisant uniquement les déclarations de type Python, **FastAPI** réussit * Générer des définitions JSON Schema pour votre modèle, qui peuvent être utilisées où vous en avez besoin dans votre projet ensuite. * Ces schémas participeront à la constitution du schéma généré OpenAPI, et seront donc utilisés par les documentations automatiquement générées. -## Documentation automatique +## Documentation automatique { #automatic-docs } Les schémas JSON de vos modèles seront intégrés au schéma OpenAPI global de votre application, et seront donc affichés dans la documentation interactive de l'API : @@ -85,7 +85,7 @@ Et seront aussi utilisés dans chaque *opération de chemin* de la documentation -## Support de l'éditeur +## Support de l'éditeur { #editor-support } Dans votre éditeur, vous aurez des annotations de types et de l'auto-complétion partout dans votre fonction (ce qui n'aurait pas été le cas si vous aviez utilisé un classique `dict` plutôt qu'un modèle Pydantic) : @@ -121,27 +121,27 @@ Ce qui améliore le support pour les modèles Pydantic avec : /// -## Utilisez le modèle +## Utilisez le modèle { #use-the-model } Dans la fonction, vous pouvez accéder à tous les attributs de l'objet du modèle directement : -{* ../../docs_src/body/tutorial002.py hl[21] *} +{* ../../docs_src/body/tutorial002_py310.py *} -## Corps de la requête + paramètres de chemin +## Corps de la requête + paramètres de chemin { #request-body-path-parameters } Vous pouvez déclarer des paramètres de chemin et un corps de requête pour la même *opération de chemin*. **FastAPI** est capable de reconnaître que les paramètres de la fonction qui correspondent aux paramètres de chemin doivent être **récupérés depuis le chemin**, et que les paramètres de fonctions déclarés comme modèles Pydantic devraient être **récupérés depuis le corps de la requête**. -{* ../../docs_src/body/tutorial003.py hl[17:18] *} +{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *} -## Corps de la requête + paramètres de chemin et de requête +## Corps de la requête + paramètres de chemin et de requête { #request-body-path-query-parameters } Vous pouvez aussi déclarer un **corps**, et des paramètres de **chemin** et de **requête** dans la même *opération de chemin*. **FastAPI** saura reconnaître chacun d'entre eux et récupérer la bonne donnée au bon endroit. -{* ../../docs_src/body/tutorial004.py hl[18] *} +{* ../../docs_src/body/tutorial004_py310.py hl[16] *} Les paramètres de la fonction seront reconnus comme tel : @@ -157,6 +157,6 @@ Le type `Optional` dans `Optional[str]` n'est pas utilisé par **FastAPI**, mais /// -## Sans Pydantic +## Sans Pydantic { #without-pydantic } -Si vous ne voulez pas utiliser des modèles Pydantic, vous pouvez aussi utiliser des paramètres de **Corps**. Pour cela, allez voir la partie de la documentation sur [Corps de la requête - Paramètres multiples](body-multiple-params.md){.internal-link target=_blank}. +Si vous ne voulez pas utiliser des modèles Pydantic, vous pouvez aussi utiliser des paramètres de **Corps**. Pour cela, allez voir la partie de la documentation sur [Corps de la requête - Paramètres multiples](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}. diff --git a/docs/fr/docs/tutorial/debugging.md b/docs/fr/docs/tutorial/debugging.md index ab00fbdeb..e13022bbc 100644 --- a/docs/fr/docs/tutorial/debugging.md +++ b/docs/fr/docs/tutorial/debugging.md @@ -1,14 +1,14 @@ -# Débogage +# Débogage { #debugging } Vous pouvez connecter le débogueur dans votre éditeur, par exemple avec Visual Studio Code ou PyCharm. -## Faites appel à `uvicorn` +## Faites appel à `uvicorn` { #call-uvicorn } Dans votre application FastAPI, importez et exécutez directement `uvicorn` : -{* ../../docs_src/debugging/tutorial001.py hl[1,15] *} +{* ../../docs_src/debugging/tutorial001_py39.py hl[1,15] *} -### À propos de `__name__ == "__main__"` +### À propos de `__name__ == "__main__"` { #about-name-main } Le but principal de `__name__ == "__main__"` est d'avoir du code qui est exécuté lorsque votre fichier est appelé avec : @@ -26,7 +26,7 @@ mais qui n'est pas appelé lorsqu'un autre fichier l'importe, comme dans : from myapp import app ``` -#### Pour davantage de détails +#### Pour davantage de détails { #more-details } Imaginons que votre fichier s'appelle `myapp.py`. @@ -78,7 +78,7 @@ Pour plus d'informations, consultez débogueur +## Exécutez votre code avec votre débogueur { #run-your-code-with-your-debugger } Parce que vous exécutez le serveur Uvicorn directement depuis votre code, vous pouvez appeler votre programme Python (votre application FastAPI) directement depuis le débogueur. diff --git a/docs/ja/docs/advanced/additional-status-codes.md b/docs/ja/docs/advanced/additional-status-codes.md index 33457f591..2f4b05bb2 100644 --- a/docs/ja/docs/advanced/additional-status-codes.md +++ b/docs/ja/docs/advanced/additional-status-codes.md @@ -1,10 +1,10 @@ -# 追加のステータスコード +# 追加のステータスコード { #additional-status-codes } デフォルトでは、 **FastAPI** は `JSONResponse` を使ってレスポンスを返します。その `JSONResponse` の中には、 *path operation* が返した内容が入ります。 それは、デフォルトのステータスコードか、 *path operation* でセットしたものを利用します。 -## 追加のステータスコード +## 追加のステータスコード { #additional-status-codes_1 } メインのステータスコードとは別に、他のステータスコードを返したい場合は、`Response` (`JSONResponse` など) に追加のステータスコードを設定して直接返します。 @@ -14,7 +14,7 @@ これを達成するには、 `JSONResponse` をインポートし、 `status_code` を設定して直接内容を返します。 -{* ../../docs_src/additional_status_codes/tutorial001.py hl[4,25] *} +{* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *} /// warning | 注意 @@ -34,7 +34,7 @@ /// -## OpenAPIとAPIドキュメント +## OpenAPIとAPIドキュメント { #openapi-and-api-docs } ステータスコードとレスポンスを直接返す場合、それらはOpenAPIスキーマ (APIドキュメント) には含まれません。なぜなら、FastAPIは何が返されるのか事前に知ることができないからです。 diff --git a/docs/ja/docs/advanced/response-directly.md b/docs/ja/docs/advanced/response-directly.md index 42412d507..7e83b9ffb 100644 --- a/docs/ja/docs/advanced/response-directly.md +++ b/docs/ja/docs/advanced/response-directly.md @@ -1,4 +1,4 @@ -# レスポンスを直接返す +# レスポンスを直接返す { #return-a-response-directly } **FastAPI** の *path operation* では、通常は任意のデータを返すことができます: 例えば、 `dict`、`list`、Pydanticモデル、データベースモデルなどです。 @@ -10,7 +10,7 @@ これは例えば、カスタムヘッダーやcookieを返すときに便利です。 -## `Response` を返す +## `Response` を返す { #return-a-response } 実際は、`Response` やそのサブクラスを返すことができます。 @@ -26,7 +26,7 @@ これは多くの柔軟性を提供します。任意のデータ型を返したり、任意のデータ宣言やバリデーションをオーバーライドできます。 -## `jsonable_encoder` を `Response` の中で使う +## `jsonable_encoder` を `Response` の中で使う { #using-the-jsonable-encoder-in-a-response } **FastAPI** はあなたが返す `Response` に対して何も変更を加えないので、コンテンツが準備できていることを保証しなければなりません。 @@ -34,7 +34,7 @@ このようなケースでは、レスポンスにデータを含める前に `jsonable_encoder` を使ってデータを変換できます。 -{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *} +{* ../../docs_src/response_directly/tutorial001_py310.py hl[5:6,20:21] *} /// note | 技術詳細 @@ -44,7 +44,7 @@ /// -## カスタム `Response` を返す +## カスタム `Response` を返す { #returning-a-custom-response } 上記の例では必要な部分を全て示していますが、あまり便利ではありません。`item` を直接返すことができるし、**FastAPI** はそれを `dict` に変換して `JSONResponse`　に含めてくれるなど。すべて、デフォルトの動作です。 @@ -54,9 +54,9 @@ XMLを文字列にし、`Response` に含め、それを返します。 -{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *} +{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *} -## 備考 +## 備考 { #notes } `Response` を直接返す場合、バリデーションや、変換 (シリアライズ) や、自動ドキュメントは行われません。 diff --git a/docs/ja/docs/deployment/concepts.md b/docs/ja/docs/deployment/concepts.md index a0d4fb35b..14b58b277 100644 --- a/docs/ja/docs/deployment/concepts.md +++ b/docs/ja/docs/deployment/concepts.md @@ -1,4 +1,4 @@ -# デプロイメントのコンセプト +# デプロイメントのコンセプト { #deployments-concepts } **FastAPI**を用いたアプリケーションをデプロイするとき、もしくはどのようなタイプのWeb APIであっても、おそらく気になるコンセプトがいくつかあります。 @@ -27,7 +27,7 @@ しかし、今はこれらの重要な**コンセプトに基づくアイデア**を確認しましょう。これらのコンセプトは、他のどのタイプのWeb APIにも当てはまります。💡 -## セキュリティ - HTTPS +## セキュリティ - HTTPS { #security-https } [前チャプターのHTTPSについて](https.md){.internal-link target=_blank}では、HTTPSがどのようにAPIを暗号化するのかについて学びました。 @@ -36,7 +36,7 @@ さらにセキュアな通信において、HTTPS証明書の定期的な更新を行いますが、これはTLS Termination Proxyと同じコンポーネントが担当することもあれば、別のコンポーネントが担当することもあります。 -### HTTPS 用ツールの例 +### HTTPS 用ツールの例 { #example-tools-for-https } TLS Termination Proxyとして使用できるツールには以下のようなものがあります： * Traefik @@ -59,11 +59,11 @@ TLS Termination Proxyとして使用できるツールには以下のような 次に考慮すべきコンセプトは、実際のAPIを実行するプログラム（例：Uvicorn）に関連するものすべてです。 -## プログラム と プロセス +## プログラム と プロセス { #program-and-process } 私たちは「**プロセス**」という言葉についてたくさん話すので、その意味や「**プログラム**」という言葉との違いを明確にしておくと便利です。 -### プログラムとは何か +### プログラムとは何か { #what-is-a-program } **プログラム**という言葉は、一般的にいろいろなものを表現するのに使われます： @@ -71,7 +71,7 @@ TLS Termination Proxyとして使用できるツールには以下のような * OSによって実行することができるファイル（例: `python`, `python.exe` or `uvicorn`） * OS上で**実行**している間、CPUを使用し、メモリ上に何かを保存する特定のプログラム（**プロセス**とも呼ばれる） -### プロセスとは何か +### プロセスとは何か { #what-is-a-process } **プロセス**という言葉は通常、より具体的な意味で使われ、OSで実行されているものだけを指します（先ほどの最後の説明のように）： @@ -92,11 +92,11 @@ OSの「タスク・マネージャー」や「システム・モニター」（ さて、**プロセス**と**プログラム**という用語の違いを確認したところで、デプロイメントについて話を続けます。 -## 起動時の実行 +## 起動時の実行 { #running-on-startup } ほとんどの場合、Web APIを作成するときは、クライアントがいつでもアクセスできるように、**常に**中断されることなく**実行される**ことを望みます。もちろん、特定の状況でのみ実行させたい特別な理由がある場合は別ですが、その時間のほとんどは、常に実行され、**利用可能**であることを望みます。 -### リモートサーバー上での実行 +### リモートサーバー上での実行 { #in-a-remote-server } リモートサーバー（クラウドサーバー、仮想マシンなど）をセットアップするときにできる最も簡単なことは、ローカルで開発するときと同じように、Uvicorn（または同様のもの）を手動で実行することです。 この方法は**開発中**には役に立つと思われます。 @@ -104,15 +104,15 @@ OSの「タスク・マネージャー」や「システム・モニター」（ そしてサーバーが再起動された場合（アップデートやクラウドプロバイダーからのマイグレーションの後など）、おそらくあなたはそれに**気づかないでしょう**。そのため、プロセスを手動で再起動しなければならないことすら気づかないでしょう。つまり、APIはダウンしたままなのです。😱 -### 起動時に自動的に実行 +### 起動時に自動的に実行 { #run-automatically-on-startup } 一般的に、サーバープログラム（Uvicornなど）はサーバー起動時に自動的に開始され、**人の介入**を必要とせずに、APIと一緒にプロセスが常に実行されるようにしたいと思われます（UvicornがFastAPIアプリを実行するなど）。 -### 別のプログラムの用意 +### 別のプログラムの用意 { #separate-program } これを実現するために、通常は**別のプログラム**を用意し、起動時にアプリケーションが実行されるようにします。そして多くの場合、他のコンポーネントやアプリケーション、例えばデータベースも実行されるようにします。 -### 起動時に実行するツールの例 +### 起動時に実行するツールの例 { #example-tools-to-run-at-startup } 実行するツールの例をいくつか挙げます: @@ -127,27 +127,27 @@ OSの「タスク・マネージャー」や「システム・モニター」（ 次の章で、より具体的な例を挙げていきます。 -## 再起動 +## 再起動 { #restarts } 起動時にアプリケーションが実行されることを確認するのと同様に、失敗後にアプリケーションが**再起動**されることも確認したいと思われます。 -### 我々は間違いを犯す +### 我々は間違いを犯す { #we-make-mistakes } 私たち人間は常に**間違い**を犯します。ソフトウェアには、ほとんど常に**バグ**があらゆる箇所に隠されています。🐛 -### 小さなエラーは自動的に処理される +### 小さなエラーは自動的に処理される { #small-errors-automatically-handled } FastAPIでWeb APIを構築する際に、コードにエラーがある場合、FastAPIは通常、エラーを引き起こした単一のリクエストにエラーを含めます。🛡 クライアントはそのリクエストに対して**500 Internal Server Error**を受け取りますが、アプリケーションは完全にクラッシュするのではなく、次のリクエストのために動作を続けます。 -### 重大なエラー - クラッシュ +### 重大なエラー - クラッシュ { #bigger-errors-crashes } しかしながら、**アプリケーション全体をクラッシュさせるようなコードを書いて**UvicornとPythonをクラッシュさせるようなケースもあるかもしれません。💥 それでも、ある箇所でエラーが発生したからといって、アプリケーションを停止させたままにしたくないでしょう。 少なくとも壊れていない*パスオペレーション*については、**実行し続けたい**はずです。 -### クラッシュ後の再起動 +### クラッシュ後の再起動 { #restart-after-crash } しかし、実行中の**プロセス**をクラッシュさせるような本当にひどいエラーの場合、少なくとも2〜3回ほどプロセスを**再起動**させる外部コンポーネントが必要でしょう。 @@ -161,7 +161,7 @@ FastAPIでWeb APIを構築する際に、コードにエラーがある場合、 あなたはおそらく**外部コンポーネント**がアプリケーションの再起動を担当することを望むと考えます。 なぜなら、その時点でUvicornとPythonを使った同じアプリケーションはすでにクラッシュしており、同じアプリケーションの同じコードに対して何もできないためです。 -### 自動的に再起動するツールの例 +### 自動的に再起動するツールの例 { #example-tools-to-restart-automatically } ほとんどの場合、前述した**起動時にプログラムを実行する**ために使用されるツールは、自動で**再起動**することにも利用されます。 @@ -176,19 +176,19 @@ FastAPIでWeb APIを構築する際に、コードにエラーがある場合、 * クラウドプロバイダーがサービスの一部として内部的に処理 * そのほか... -## レプリケーション - プロセスとメモリー +## レプリケーション - プロセスとメモリー { #replication-processes-and-memory } FastAPI アプリケーションでは、Uvicorn のようなサーバープログラムを使用し、**1つのプロセス**で1度に複数のクライアントに同時に対応できます。 しかし、多くの場合、複数のワーカー・プロセスを同時に実行したいと考えるでしょう。 -### 複数のプロセス - Worker +### 複数のプロセス - Worker { #multiple-processes-workers } クライアントの数が単一のプロセスで処理できる数を超えており（たとえば仮想マシンがそれほど大きくない場合）、かつサーバーの CPU に**複数のコア**がある場合、同じアプリケーションで同時に**複数のプロセス**を実行させ、すべてのリクエストを分散させることができます。 同じAPIプログラムの**複数のプロセス**を実行する場合、それらは一般的に**Worker／ワーカー**と呼ばれます。 -### ワーカー・プロセス と ポート +### ワーカー・プロセス と ポート { #worker-processes-and-ports } [HTTPSについて](https.md){.internal-link target=_blank}のドキュメントで、1つのサーバーで1つのポートとIPアドレスの組み合わせでリッスンできるのは1つのプロセスだけであることを覚えていますでしょうか？ @@ -197,13 +197,13 @@ FastAPI アプリケーションでは、Uvicorn のようなサーバープロ そのため、**複数のプロセス**を同時に持つには**ポートでリッスンしている単一のプロセス**が必要であり、それが何らかの方法で各ワーカー・プロセスに通信を送信することが求められます。 -### プロセスあたりのメモリー +### プロセスあたりのメモリー { #memory-per-process } さて、プログラムがメモリにロードする際には、例えば機械学習モデルや大きなファイルの内容を変数に入れたりする場合では、**サーバーのメモリ（RAM）**を少し消費します。 そして複数のプロセスは通常、**メモリを共有しません**。これは、実行中の各プロセスがそれぞれ独自の変数やメモリ等を持っていることを意味します。つまり、コード内で大量のメモリを消費している場合、**各プロセス**は同等の量のメモリを消費することになります。 -### サーバーメモリー +### サーバーメモリー { #server-memory } 例えば、あなたのコードが **1GBのサイズの機械学習モデル**をロードする場合、APIで1つのプロセスを実行すると、少なくとも1GBのRAMを消費します。 @@ -211,7 +211,7 @@ FastAPI アプリケーションでは、Uvicorn のようなサーバープロ リモートサーバーや仮想マシンのRAMが3GBしかない場合、4GB以上のRAMをロードしようとすると問題が発生します。🚨 -### 複数プロセス - 例 +### 複数プロセス - 例 { #multiple-processes-an-example } この例では、2つの**ワーカー・プロセス**を起動し制御する**マネージャー・ プロセス**があります。 @@ -227,7 +227,7 @@ FastAPI アプリケーションでは、Uvicorn のようなサーバープロ 毎回同程度の計算を行うAPIがあり、多くのクライアントがいるのであれば、**CPU使用率**もおそらく**安定**するでしょう（常に急激に上下するのではなく）。 -### レプリケーション・ツールと戦略の例 +### レプリケーション・ツールと戦略の例 { #examples-of-replication-tools-and-strategies } これを実現するにはいくつかのアプローチがありますが、具体的な戦略については次の章(Dockerやコンテナの章など)で詳しく説明します。 @@ -255,7 +255,7 @@ FastAPI アプリケーションでは、Uvicorn のようなサーバープロ /// -## 開始前の事前のステップ +## 開始前の事前のステップ { #previous-steps-before-starting } アプリケーションを**開始する前**に、いくつかのステップを実行したい場合が多くあります。 @@ -279,7 +279,7 @@ FastAPI アプリケーションでは、Uvicorn のようなサーバープロ /// -### 事前ステップの戦略例 +### 事前ステップの戦略例 { #examples-of-previous-steps-strategies } これは**システムを**デプロイする方法に**大きく依存**するだろうし、おそらくプログラムの起動方法や再起動の処理などにも関係してくるでしょう。 @@ -296,7 +296,7 @@ FastAPI アプリケーションでは、Uvicorn のようなサーバープロ /// -## リソースの利用 +## リソースの利用 { #resource-utilization } あなたのサーバーは**リソース**であり、プログラムを実行しCPUの計算時間や利用可能なRAMメモリを消費または**利用**することができます。 @@ -319,7 +319,7 @@ FastAPI アプリケーションでは、Uvicorn のようなサーバープロ `htop`のような単純なツールを使って、サーバーで使用されているCPUやRAM、あるいは各プロセスで使用されている量を見ることができます。あるいは、より複雑な監視ツールを使って、サーバに分散して使用することもできます。 -## まとめ +## まとめ { #recap } アプリケーションのデプロイ方法を決定する際に、考慮すべきであろう主要なコンセプトのいくつかを紹介していきました： diff --git a/docs/ja/docs/deployment/versions.md b/docs/ja/docs/deployment/versions.md index 7575fc4f7..8448b5ba4 100644 --- a/docs/ja/docs/deployment/versions.md +++ b/docs/ja/docs/deployment/versions.md @@ -1,4 +1,4 @@ -# FastAPIのバージョンについて +# FastAPIのバージョンについて { #about-fastapi-versions } **FastAPI** は既に多くのアプリケーションやシステムに本番環境で使われています。また、100%のテストカバレッジを維持しています。しかし、活発な開発が続いています。 @@ -8,7 +8,7 @@ **FastAPI** を使用すると本番用アプリケーションをすぐに作成できますが (すでに何度も経験しているかもしれませんが)、残りのコードが正しく動作するバージョンなのか確認しなければいけません。 -## `fastapi` のバージョンを固定 +## `fastapi` のバージョンを固定 { #pin-your-fastapi-version } 最初にすべきことは、アプリケーションが正しく動作する **FastAPI** のバージョンを固定することです。 @@ -17,7 +17,7 @@ `requirements.txt` を使っているなら、以下の様にバージョンを指定できます: ```txt -fastapi==0.45.0 +fastapi[standard]==0.112.0 ``` これは、厳密にバージョン `0.45.0` だけを使うことを意味します。 @@ -25,18 +25,18 @@ fastapi==0.45.0 または、以下の様に固定することもできます: ```txt -fastapi>=0.45.0,<0.46.0 +fastapi[standard]>=0.112.0,<0.113.0 ``` これは `0.45.0` 以上、`0.46.0` 未満のバージョンを使うことを意味します。例えば、バージョン `0.45.2` は使用可能です。 PoetryやPipenvなど、他のインストール管理ツールを使用している場合でも、それぞれパッケージのバージョンを指定する機能があります。 -## 利用可能なバージョン +## 利用可能なバージョン { #available-versions } [Release Notes](../release-notes.md){.internal-link target=_blank}で利用可能なバージョンが確認できます (現在の最新版の確認などのため)。 -## バージョンについて +## バージョンについて { #about-versions } セマンティック バージョニングの規約に従って、`1.0.0` 未満の全てのバージョンは破壊的な変更が加わる可能性があります。 @@ -62,7 +62,7 @@ fastapi>=0.45.0,<0.46.0 /// -## FastAPIのバージョンのアップグレード +## FastAPIのバージョンのアップグレード { #upgrading-the-fastapi-versions } アプリケーションにテストを加えるべきです。 @@ -72,7 +72,7 @@ fastapi>=0.45.0,<0.46.0 全てが動作するか、修正を行った上で全てのテストを通過した場合、使用している`fastapi` のバージョンをより最新のバージョンに固定できます。 -## Starletteについて +## Starletteについて { #about-starlette } `Starlette` のバージョンは固定すべきではありません。 @@ -80,7 +80,7 @@ fastapi>=0.45.0,<0.46.0 よって、最適なStarletteのバージョン選択を**FastAPI** に任せることができます。 -## Pydanticについて +## Pydanticについて { #about-pydantic } Pydanticは自身のテストだけでなく**FastAPI** のためのテストを含んでいます。なので、Pydanticの新たなバージョン ( `1.0.0` 以降) は全てFastAPIと整合性があります。 @@ -89,5 +89,5 @@ Pydanticのバージョンを、動作が保証できる`1.0.0`以降のいず 例えば: ```txt -pydantic>=1.2.0,<2.0.0 +pydantic>=2.7.0,<3.0.0 ``` diff --git a/docs/ja/docs/features.md b/docs/ja/docs/features.md index f78eab430..d63fd63eb 100644 --- a/docs/ja/docs/features.md +++ b/docs/ja/docs/features.md @@ -1,17 +1,17 @@ -# 機能 +# 機能 { #features } -## FastAPIの機能 +## FastAPIの機能 { #fastapi-features } **FastAPI** は以下の機能をもちます: -### オープンスタンダード準拠 +### オープンスタンダード準拠 { #based-on-open-standards } * API作成のためのOpenAPI。これは、path operationsの宣言、パラメータ、ボディリクエスト、セキュリティなどを含んでいます。 -* JSONスキーマを使用したデータモデルのドキュメント自動生成（OpenAPIはJSONスキーマに基づいている）。 +* JSONスキーマを使用したデータモデルのドキュメント自動生成（OpenAPIはJSONスキーマに基づいている）。 * 綿密な調査の結果、上層に後付けするのではなく、これらの基準に基づいて設計されました。 * これにより、多くの言語で自動 **クライアントコード生成** が可能です。 -### 自動ドキュメント生成 +### 自動ドキュメント生成 { #automatic-docs } 対話的なAPIドキュメントと探索的なwebユーザーインターフェースを提供します。フレームワークはOpenAPIを基にしているため、いくつかのオプションがあり、デフォルトで2つ含まれています。 * Swagger UIで、インタラクティブな探索をしながら、ブラウザから直接APIを呼び出してテストが行えます。 @@ -22,7 +22,7 @@ ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) -### 現代的なPython +### 現代的なPython { #just-modern-python } FastAPIの機能はすべて、標準のPython 3.8型宣言に基づいています（Pydanticの功績）。新しい構文はありません。ただの現代的な標準のPythonです。 @@ -70,7 +70,7 @@ my_second_user: User = User(**second_user_data) /// -### エディタのサポート +### エディタのサポート { #editor-support } すべてのフレームワークは使いやすく直感的に使用できるように設計されており、すべての決定は開発を開始する前でも複数のエディターでテストされ、最高の開発体験が保証されます。 @@ -94,13 +94,13 @@ my_second_user: User = User(**second_user_data) 間違ったキー名を入力したり、ドキュメント間を行き来したり、上下にスクロールして`username`と`user_name`のどちらを使用したか調べたりする必要はもうありません。 -### 簡潔 +### 簡潔 { #short } すべてに適切な**デフォルト**があり、オプションの構成ができます。必要なことを実行し、必要なAPIを定義するためにすべてのパラメーターを調整できます。 ただし、デフォルトでもすべて **うまくいきます**。 -### 検証 +### 検証 { #validation } * 以下の様な、ほとんどの（すべての？）Python **データ型**の検証: * JSONオブジェクト（`dict`） @@ -116,7 +116,7 @@ my_second_user: User = User(**second_user_data) すべての検証は、確立された堅牢な **Pydantic** によって処理されます。 -### セキュリティと認証 +### セキュリティと認証 { #security-and-authentication } セキュリティと認証が統合されています。 データベースまたはデータモデルについても妥協していません。 @@ -133,7 +133,7 @@ my_second_user: User = User(**second_user_data) これらは、システム、データストア、リレーショナルデータベース、NoSQLデータベースなどと簡単に統合できる再利用可能なツールとコンポーネントとして構築されています。 -### 依存性の注入（Dependency Injection） +### 依存性の注入（Dependency Injection） { #dependency-injection } FastAPIには非常に使いやすく、非常に強力な依存性の注入システムを備えています。 @@ -145,20 +145,20 @@ FastAPIには非常に使いやすく、非常に強力なPydantic と完全に互換性があります（そしてベースになっています）。したがって、追加のPydanticコードがあれば、それも機能します。 diff --git a/docs/ja/docs/learn/index.md b/docs/ja/docs/learn/index.md index 2f24c670a..8dc473107 100644 --- a/docs/ja/docs/learn/index.md +++ b/docs/ja/docs/learn/index.md @@ -1,4 +1,4 @@ -# 学習 +# 学習 { #learn } ここでは、**FastAPI** を学習するための入門セクションとチュートリアルを紹介します。 diff --git a/docs/ja/docs/tutorial/background-tasks.md b/docs/ja/docs/tutorial/background-tasks.md index b289faf12..39daf91cd 100644 --- a/docs/ja/docs/tutorial/background-tasks.md +++ b/docs/ja/docs/tutorial/background-tasks.md @@ -1,4 +1,4 @@ -# バックグラウンドタスク +# バックグラウンドタスク { #background-tasks } レスポンスを返した *後に* 実行されるバックグラウンドタスクを定義できます。 @@ -11,15 +11,15 @@ * データ処理: * たとえば、時間のかかる処理を必要とするファイル受信時には、「受信済み」(HTTP 202) のレスポンスを返し、バックグラウンドで処理できます。 -## `BackgroundTasks` の使用 +## `BackgroundTasks` の使用 { #using-backgroundtasks } まず初めに、`BackgroundTasks` をインポートし、` BackgroundTasks` の型宣言と共に、*path operation 関数* のパラメーターを定義します: -{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *} +{* ../../docs_src/background_tasks/tutorial001_py39.py hl[1,13] *} **FastAPI** は、`BackgroundTasks` 型のオブジェクトを作成し、そのパラメーターに渡します。 -## タスク関数の作成 +## タスク関数の作成 { #create-a-task-function } バックグラウンドタスクとして実行される関数を作成します。 @@ -31,13 +31,13 @@ また、書き込み操作では `async` と `await` を使用しないため、通常の `def` で関数を定義します。 -{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *} +{* ../../docs_src/background_tasks/tutorial001_py39.py hl[6:9] *} -## バックグラウンドタスクの追加 +## バックグラウンドタスクの追加 { #add-the-background-task } *path operations 関数* 内で、`.add_task()` メソッドを使用してタスク関数を *background tasks* オブジェクトに渡します。 -{* ../../docs_src/background_tasks/tutorial001.py hl[14] *} +{* ../../docs_src/background_tasks/tutorial001_py39.py hl[14] *} `.add_task()` は以下の引数を受け取ります: @@ -45,13 +45,13 @@ * タスク関数に順番に渡す必要のある引数の列 (`email`)。 * タスク関数に渡す必要のあるキーワード引数 (`message="some notification"`)。 -## 依存性注入 +## 依存性注入 { #dependency-injection } `BackgroundTasks` の使用は依存性注入システムでも機能し、様々な階層 (*path operations 関数*、依存性 (依存可能性)、サブ依存性など) で `BackgroundTasks` 型のパラメーターを宣言できます。 **FastAPI** は、それぞれの場合の処理​​方法と同じオブジェクトの再利用方法を知っているため、すべてのバックグラウンドタスクがマージされ、バックグラウンドで後で実行されます。 -{* ../../docs_src/background_tasks/tutorial002.py hl[13,15,22,25] *} +{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *} この例では、レスポンスが送信された *後* にメッセージが `log.txt` ファイルに書き込まれます。 @@ -59,7 +59,7 @@ そして、*path operations 関数* で生成された別のバックグラウンドタスクは、`email` パスパラメータを使用してメッセージを書き込みます。 -## 技術的な詳細 +## 技術的な詳細 { #technical-details } `BackgroundTasks` クラスは、`starlette.background`から直接取得されます。 @@ -71,14 +71,14 @@ 詳細については、バックグラウンドタスクに関する Starlette の公式ドキュメントを参照して下さい。 -## 警告 +## 警告 { #caveat } -大量のバックグラウンド計算が必要であり、必ずしも同じプロセスで実行する必要がない場合 (たとえば、メモリや変数などを共有する必要がない場合)、Celery のようなより大きな他のツールを使用するとメリットがあるかもしれません。 +大量のバックグラウンド計算が必要であり、必ずしも同じプロセスで実行する必要がない場合 (たとえば、メモリや変数などを共有する必要がない場合)、Celery のようなより大きな他のツールを使用するとメリットがあるかもしれません。 これらは、より複雑な構成、RabbitMQ や Redis などのメッセージ/ジョブキューマネージャーを必要とする傾向がありますが、複数のプロセス、特に複数のサーバーでバックグラウンドタスクを実行できます。 ただし、同じ **FastAPI** アプリから変数とオブジェクトにアクセスする必要がある場合、または小さなバックグラウンドタスク (電子メール通知の送信など) を実行する必要がある場合は、単に `BackgroundTasks` を使用できます。 -## まとめ +## まとめ { #recap } `BackgroundTasks` をインポートして、*path operations 関数* や依存関係のパラメータに `BackgroundTasks`を使用し、バックグラウンドタスクを追加して下さい。 diff --git a/docs/ja/docs/tutorial/body-updates.md b/docs/ja/docs/tutorial/body-updates.md index ffbe52e1d..e48161632 100644 --- a/docs/ja/docs/tutorial/body-updates.md +++ b/docs/ja/docs/tutorial/body-updates.md @@ -1,16 +1,16 @@ -# ボディ - 更新 +# ボディ - 更新 { #body-updates } -## `PUT`による置換での更新 +## `PUT`による置換での更新 { #update-replacing-with-put } 項目を更新するにはHTTPの`PUT`操作を使用することができます。 `jsonable_encoder`を用いて、入力データをJSON形式で保存できるデータに変換することができます（例：NoSQLデータベース）。例えば、`datetime`を`str`に変換します。 -{* ../../docs_src/body_updates/tutorial001.py hl[30,31,32,33,34,35] *} +{* ../../docs_src/body_updates/tutorial001_py310.py hl[28:33] *} 既存のデータを置き換えるべきデータを受け取るために`PUT`は使用されます。 -### 置換についての注意 +### 置換についての注意 { #warning-about-replacing } つまり、`PUT`を使用して以下のボディで項目`bar`を更新したい場合は: @@ -26,7 +26,7 @@ そして、データはその「新しい」`10.5`の`tax`と共に保存されます。 -## `PATCH`による部分的な更新 +## `PATCH`による部分的な更新 { #partial-updates-with-patch } また、HTTPの`PATCH`操作でデータを*部分的に*更新することもできます。 @@ -44,7 +44,7 @@ /// -### Pydanticの`exclude_unset`パラメータの使用 +### Pydanticの`exclude_unset`パラメータの使用 { #using-pydantics-exclude-unset-parameter } 部分的な更新を受け取りたい場合は、Pydanticモデルの`.dict()`の`exclude_unset`パラメータを使用すると非常に便利です。 @@ -54,17 +54,17 @@ これを使うことで、デフォルト値を省略して、設定された（リクエストで送られた）データのみを含む`dict`を生成することができます: -{* ../../docs_src/body_updates/tutorial002.py hl[34] *} +{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *} -### Pydanticの`update`パラメータ +### Pydanticの`update`パラメータ { #using-pydantics-update-parameter } ここで、`.copy()`を用いて既存のモデルのコピーを作成し、`update`パラメータに更新するデータを含む`dict`を渡すことができます。 `stored_item_model.copy(update=update_data)`のように: -{* ../../docs_src/body_updates/tutorial002.py hl[35] *} +{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *} -### 部分的更新のまとめ +### 部分的更新のまとめ { #partial-updates-recap } まとめると、部分的な更新を適用するには、次のようにします: @@ -79,7 +79,7 @@ * データをDBに保存します。 * 更新されたモデルを返します。 -{* ../../docs_src/body_updates/tutorial002.py hl[30,31,32,33,34,35,36,37] *} +{* ../../docs_src/body_updates/tutorial002_py310.py hl[28:35] *} /// tip | 豆知識 diff --git a/docs/ja/docs/tutorial/body.md b/docs/ja/docs/tutorial/body.md index 1298eec7e..b62a9b7e3 100644 --- a/docs/ja/docs/tutorial/body.md +++ b/docs/ja/docs/tutorial/body.md @@ -1,4 +1,4 @@ -# リクエストボディ +# リクエストボディ { #request-body } クライアント (ブラウザなど) からAPIにデータを送信する必要があるとき、データを **リクエストボディ (request body)** として送ります。 @@ -18,19 +18,19 @@ GET リクエストでボディを送信することは、仕様では未定義 /// -## Pydanticの `BaseModel` をインポート +## Pydanticの `BaseModel` をインポート { #import-pydantics-basemodel } ます初めに、 `pydantic` から `BaseModel` をインポートする必要があります: -{* ../../docs_src/body/tutorial001.py hl[4] *} +{* ../../docs_src/body/tutorial001_py310.py hl[2] *} -## データモデルの作成 +## データモデルの作成 { #create-your-data-model } そして、`BaseModel` を継承したクラスとしてデータモデルを宣言します。 すべての属性にpython標準の型を使用します: -{* ../../docs_src/body/tutorial001.py hl[7:11] *} +{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *} クエリパラメータの宣言と同様に、モデル属性がデフォルト値をもつとき、必須な属性ではなくなります。それ以外は必須になります。オプショナルな属性にしたい場合は `None` を使用してください。 @@ -54,15 +54,15 @@ GET リクエストでボディを送信することは、仕様では未定義 } ``` -## パラメータとして宣言 +## パラメータとして宣言 { #declare-it-as-a-parameter } *パスオペレーション* に加えるために、パスパラメータやクエリパラメータと同じ様に宣言します: -{* ../../docs_src/body/tutorial001.py hl[18] *} +{* ../../docs_src/body/tutorial001_py310.py hl[16] *} ...そして、作成したモデル `Item` で型を宣言します。 -## 結果 +## 結果 { #results } そのPythonの型宣言だけで **FastAPI** は以下のことを行います: @@ -72,10 +72,10 @@ GET リクエストでボディを送信することは、仕様では未定義 * データが無効な場合は、明確なエラーが返され、どこが不正なデータであったかを示します。 * 受け取ったデータをパラメータ `item` に変換します。 * 関数内で `Item` 型であると宣言したので、すべての属性とその型に対するエディタサポート（補完など）をすべて使用できます。 -* モデルのJSONスキーマ定義を生成し、好きな場所で使用することができます。 +* モデルのJSONスキーマ定義を生成し、好きな場所で使用することができます。 * これらのスキーマは、生成されたOpenAPIスキーマの一部となり、自動ドキュメントのUIに使用されます。 -## 自動ドキュメント生成 +## 自動ドキュメント生成 { #automatic-docs } モデルのJSONスキーマはOpenAPIで生成されたスキーマの一部になり、対話的なAPIドキュメントに表示されます: @@ -85,7 +85,7 @@ GET リクエストでボディを送信することは、仕様では未定義 -## エディターサポート +## エディターサポート { #editor-support } エディターによる型ヒントと補完が関数内で利用できます (Pydanticモデルではなく `dict` を受け取ると、同じサポートは受けられません): @@ -121,27 +121,27 @@ GET リクエストでボディを送信することは、仕様では未定義 /// -## モデルの使用 +## モデルの使用 { #use-the-model } 関数内部で、モデルの全ての属性に直接アクセスできます: -{* ../../docs_src/body/tutorial002.py hl[21] *} +{* ../../docs_src/body/tutorial002_py310.py *} -## リクエストボディ + パスパラメータ +## リクエストボディ + パスパラメータ { #request-body-path-parameters } パスパラメータとリクエストボディを同時に宣言できます。 **FastAPI** はパスパラメータである関数パラメータは**パスから受け取り**、Pydanticモデルによって宣言された関数パラメータは**リクエストボディから受け取る**ということを認識します。 -{* ../../docs_src/body/tutorial003.py hl[17:18] *} +{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *} -## リクエストボディ + パスパラメータ + クエリパラメータ +## リクエストボディ + パスパラメータ + クエリパラメータ { #request-body-path-query-parameters } また、**ボディ**と**パス**と**クエリ**のパラメータも同時に宣言できます。 **FastAPI** はそれぞれを認識し、適切な場所からデータを取得します。 -{* ../../docs_src/body/tutorial004.py hl[18] *} +{* ../../docs_src/body/tutorial004_py310.py hl[16] *} 関数パラメータは以下の様に認識されます: @@ -157,6 +157,6 @@ FastAPIは、`= None`があるおかげで、`q`がオプショナルだとわ /// -## Pydanticを使わない方法 +## Pydanticを使わない方法 { #without-pydantic } -もしPydanticモデルを使用したくない場合は、**Body**パラメータが利用できます。[Body - Multiple Parameters: Singular values in body](body-multiple-params.md#_2){.internal-link target=_blank}を確認してください。 +もしPydanticモデルを使用したくない場合は、**Body**パラメータが利用できます。[Body - Multiple Parameters: Singular values in body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}を確認してください。 diff --git a/docs/ja/docs/tutorial/cookie-param-models.md b/docs/ja/docs/tutorial/cookie-param-models.md index 8285f44ef..c77df0145 100644 --- a/docs/ja/docs/tutorial/cookie-param-models.md +++ b/docs/ja/docs/tutorial/cookie-param-models.md @@ -1,4 +1,4 @@ -# クッキーパラメータモデル +# クッキーパラメータモデル { #cookie-parameter-models } もし関連する**複数のクッキー**から成るグループがあるなら、それらを宣言するために、**Pydanticモデル**を作成できます。🍪 @@ -16,7 +16,7 @@ /// -## クッキーにPydanticモデルを使用する +## クッキーにPydanticモデルを使用する { #cookies-with-a-pydantic-model } 必要な複数の**クッキー**パラメータを**Pydanticモデル**で宣言し、さらに、それを `Cookie` として宣言しましょう: @@ -24,7 +24,7 @@ **FastAPI**は、リクエストの**クッキー**から**それぞれのフィールド**のデータを**抽出**し、定義された**Pydanticモデル**を提供します。 -## ドキュメントの確認 +## ドキュメントの確認 { #check-the-docs } 対話的APIドキュメントUI `/docs` で、定義されているクッキーを確認できます: @@ -43,7 +43,7 @@ /// -## 余分なクッキーを禁止する +## 余分なクッキーを禁止する { #forbid-extra-cookies } 特定の（あまり一般的ではないかもしれない）ケースで、受け付けるクッキーを**制限**する必要があるかもしれません。 @@ -51,7 +51,7 @@ Pydanticのモデルの Configuration を利用して、 `extra` フィールドを `forbid` とすることができます。 -{* ../../docs_src/cookie_param_models/tutorial002_an_py39.py hl[10] *} +{* ../../docs_src/cookie_param_models/tutorial002_an_py310.py hl[10] *} もしクライアントが**余分なクッキー**を送ろうとすると、**エラー**レスポンスが返されます。 @@ -72,6 +72,6 @@ Pydanticのモデルの Configuration を利用して、 `extra` フィールド } ``` -## まとめ +## まとめ { #summary } **FastAPI**では、**クッキー**を宣言するために、**Pydanticモデル**を使用できます。😎 diff --git a/docs/ja/docs/tutorial/cookie-params.md b/docs/ja/docs/tutorial/cookie-params.md index 13af6d3c7..501b5e015 100644 --- a/docs/ja/docs/tutorial/cookie-params.md +++ b/docs/ja/docs/tutorial/cookie-params.md @@ -1,20 +1,20 @@ -# クッキーのパラメータ +# クッキーのパラメータ { #cookie-parameters } クッキーのパラメータは、`Query`や`Path`のパラメータを定義するのと同じ方法で定義できます。 -## `Cookie`をインポート +## `Cookie`をインポート { #import-cookie } まず、`Cookie`をインポートします: -{* ../../docs_src/cookie_params/tutorial001.py hl[3] *} +{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *} -## `Cookie`のパラメータを宣言 +## `Cookie`のパラメータを宣言 { #declare-cookie-parameters } 次に、`Path`や`Query`と同じ構造を使ってクッキーのパラメータを宣言します。 最初の値がデフォルト値で、追加の検証パラメータや注釈パラメータをすべて渡すことができます: -{* ../../docs_src/cookie_params/tutorial001.py hl[9] *} +{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[9] *} /// note | 技術詳細 @@ -30,6 +30,6 @@ /// -## まとめ +## まとめ { #recap } クッキーは`Cookie`を使って宣言し、`Query`や`Path`と同じパターンを使用する。 diff --git a/docs/ja/docs/tutorial/debugging.md b/docs/ja/docs/tutorial/debugging.md index 6c29679ef..ced69c2eb 100644 --- a/docs/ja/docs/tutorial/debugging.md +++ b/docs/ja/docs/tutorial/debugging.md @@ -1,14 +1,14 @@ -# デバッグ +# デバッグ { #debugging } Visual Studio CodeやPyCharmなどを使用して、エディター上でデバッガーと連携できます。 -## `uvicorn` の実行 +## `uvicorn` の実行 { #call-uvicorn } FastAPIアプリケーション上で、`uvicorn` を直接インポートして実行します: -{* ../../docs_src/debugging/tutorial001.py hl[1,15] *} +{* ../../docs_src/debugging/tutorial001_py39.py hl[1,15] *} -### `__name__ == "__main__"` について +### `__name__ == "__main__"` について { #about-name-main } `__name__ == "__main__"` の主な目的は、ファイルが次のコマンドで呼び出されたときに実行されるコードを用意することです: @@ -26,7 +26,7 @@ $ python myapp.py from myapp import app ``` -#### より詳しい説明 +#### より詳しい説明 { #more-details } ファイルの名前が `myapp.py` だとします。 @@ -78,7 +78,7 @@ from myapp import app /// -## デバッガーでコードを実行 +## デバッガーでコードを実行 { #run-your-code-with-your-debugger } コードから直接Uvicornサーバーを実行しているため、デバッガーから直接Pythonプログラム (FastAPIアプリケーション) を呼び出せます。 diff --git a/docs/ja/docs/tutorial/encoder.md b/docs/ja/docs/tutorial/encoder.md index 309cf8857..07befcd63 100644 --- a/docs/ja/docs/tutorial/encoder.md +++ b/docs/ja/docs/tutorial/encoder.md @@ -1,4 +1,4 @@ -# JSON互換エンコーダ +# JSON互換エンコーダ { #json-compatible-encoder } データ型（Pydanticモデルのような）をJSONと互換性のあるもの（`dict`や`list`など）に変更する必要がある場合があります。 @@ -6,7 +6,7 @@ そのために、**FastAPI** は`jsonable_encoder()`関数を提供しています。 -## `jsonable_encoder`の使用 +## `jsonable_encoder`の使用 { #using-the-jsonable-encoder } JSON互換のデータのみを受信するデータベース`fake_db`があるとしましょう。 @@ -20,7 +20,7 @@ JSON互換のデータのみを受信するデータベース`fake_db`がある Pydanticモデルのようなオブジェクトを受け取り、JSON互換版を返します: -{* ../../docs_src/encoder/tutorial001.py hl[5,22] *} +{* ../../docs_src/encoder/tutorial001_py310.py hl[4,21] *} この例では、Pydanticモデルを`dict`に、`datetime`を`str`に変換します。 diff --git a/docs/ja/docs/tutorial/extra-data-types.md b/docs/ja/docs/tutorial/extra-data-types.md index 1be1c3f92..3ca2a2d8d 100644 --- a/docs/ja/docs/tutorial/extra-data-types.md +++ b/docs/ja/docs/tutorial/extra-data-types.md @@ -1,4 +1,4 @@ -# 追加データ型 +# 追加データ型 { #extra-data-types } 今までは、以下のような一般的なデータ型を使用してきました: @@ -17,7 +17,7 @@ * データの検証 * 自動注釈と文書化 -## 他のデータ型 +## 他のデータ型 { #other-data-types } ここでは、使用できる追加のデータ型のいくつかを紹介します: @@ -36,7 +36,7 @@ * `datetime.timedelta`: * Pythonの`datetime.timedelta`です。 * リクエストとレスポンスでは合計秒数の`float`で表現されます。 - * Pydanticでは「ISO 8601 time diff encoding」として表現することも可能です。詳細はドキュメントを参照してください。 + * Pydanticでは「ISO 8601 time diff encoding」として表現することも可能です。詳細はドキュメントを参照してください。 * `frozenset`: * リクエストとレスポンスでは`set`と同じように扱われます: * リクエストでは、リストが読み込まれ、重複を排除して`set`に変換されます。 @@ -50,13 +50,13 @@ * Pythonの標準的な`Decimal`です。 * リクエストやレスポンスでは`float`と同じように扱います。 -* Pydanticの全ての有効な型はこちらで確認できます: Pydantic data types。 -## 例 +* Pydanticの全ての有効な型はこちらで確認できます: Pydantic data types。 +## 例 { #example } ここでは、上記の型のいくつかを使用したパラメータを持つ*path operation*の例を示します。 -{* ../../docs_src/extra_data_types/tutorial001.py hl[1,2,12:16] *} +{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[1,3,12:16] *} 関数内のパラメータは自然なデータ型を持っていることに注意してください。そして、以下のように通常の日付操作を行うことができます: -{* ../../docs_src/extra_data_types/tutorial001.py hl[18,19] *} +{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[18:19] *} diff --git a/docs/ja/docs/tutorial/header-params.md b/docs/ja/docs/tutorial/header-params.md index ac89afbdb..a6fbd6b3d 100644 --- a/docs/ja/docs/tutorial/header-params.md +++ b/docs/ja/docs/tutorial/header-params.md @@ -1,20 +1,20 @@ -# ヘッダーのパラメータ +# ヘッダーのパラメータ { #header-parameters } ヘッダーのパラメータは、`Query`や`Path`、`Cookie`のパラメータを定義するのと同じように定義できます。 -## `Header`をインポート +## `Header`をインポート { #import-header } まず、`Header`をインポートします: -{* ../../docs_src/header_params/tutorial001.py hl[3] *} +{* ../../docs_src/header_params/tutorial001_an_py310.py hl[3] *} -## `Header`のパラメータの宣言 +## `Header`のパラメータの宣言 { #declare-header-parameters } 次に、`Path`や`Query`、`Cookie`と同じ構造を用いてヘッダーのパラメータを宣言します。 最初の値がデフォルト値で、追加の検証パラメータや注釈パラメータをすべて渡すことができます。 -{* ../../docs_src/header_params/tutorial001.py hl[9] *} +{* ../../docs_src/header_params/tutorial001_an_py310.py hl[9] *} /// note | 技術詳細 @@ -30,7 +30,7 @@ /// -## 自動変換 +## 自動変換 { #automatic-conversion } `Header`は`Path`や`Query`、`Cookie`が提供する機能に加え、少しだけ追加の機能を持っています。 @@ -46,7 +46,7 @@ もしなんらかの理由でアンダースコアからハイフンへの自動変換を無効にする必要がある場合は、`Header`の`convert_underscores`に`False`を設定してください: -{* ../../docs_src/header_params/tutorial002.py hl[9] *} +{* ../../docs_src/header_params/tutorial002_an_py310.py hl[10] *} /// warning | 注意 @@ -54,7 +54,7 @@ /// -## ヘッダーの重複 +## ヘッダーの重複 { #duplicate-headers } 受信したヘッダーが重複することがあります。つまり、同じヘッダーで複数の値を持つということです。 @@ -64,7 +64,7 @@ 例えば、複数回出現する可能性のある`X-Token`のヘッダを定義するには、以下のように書くことができます: -{* ../../docs_src/header_params/tutorial003.py hl[9] *} +{* ../../docs_src/header_params/tutorial003_an_py310.py hl[9] *} もし、その*path operation*で通信する場合は、次のように２つのHTTPヘッダーを送信します: @@ -84,7 +84,7 @@ X-Token: bar } ``` -## まとめ +## まとめ { #recap } ヘッダーは`Header`で宣言し、`Query`や`Path`、`Cookie`と同じパターンを使用する。 diff --git a/docs/ja/docs/tutorial/query-param-models.md b/docs/ja/docs/tutorial/query-param-models.md index 053d0740b..47c95a401 100644 --- a/docs/ja/docs/tutorial/query-param-models.md +++ b/docs/ja/docs/tutorial/query-param-models.md @@ -1,4 +1,4 @@ -# クエリパラメータモデル +# クエリパラメータモデル { #query-parameter-models } もし関連する**複数のクエリパラメータ**から成るグループがあるなら、それらを宣言するために、**Pydanticモデル**を作成できます。 @@ -10,7 +10,7 @@ /// -## クエリパラメータにPydanticモデルを使用する +## クエリパラメータにPydanticモデルを使用する { #query-parameters-with-a-pydantic-model } 必要な**複数のクエリパラメータ**を**Pydanticモデル**で宣言し、さらに、それを `Query` として宣言しましょう: @@ -18,7 +18,7 @@ **FastAPI**は、リクエストの**クエリパラメータ**からそれぞれの**フィールド**のデータを**抽出**し、定義された**Pydanticモデル**を提供します。 -## ドキュメントの確認 +## ドキュメントの確認 { #check-the-docs } 対話的APIドキュメント `/docs` でクエリパラメータを確認できます: @@ -26,7 +26,7 @@ -## 余分なクエリパラメータを禁止する +## 余分なクエリパラメータを禁止する { #forbid-extra-query-parameters } 特定の（あまり一般的ではないかもしれない）ケースで、受け付けるクエリパラメータを**制限**する必要があるかもしれません。 @@ -57,7 +57,7 @@ https://example.com/items/?limit=10&tool=plumbus } ``` -## まとめ +## まとめ { #summary } **FastAPI**では、**クエリパラメータ**を宣言するために、**Pydanticモデル**を使用できます。😎 diff --git a/docs/ja/docs/tutorial/response-status-code.md b/docs/ja/docs/tutorial/response-status-code.md index 6d197d543..8f268e31f 100644 --- a/docs/ja/docs/tutorial/response-status-code.md +++ b/docs/ja/docs/tutorial/response-status-code.md @@ -1,4 +1,4 @@ -# レスポンスステータスコード +# レスポンスステータスコード { #response-status-code } レスポンスモデルを指定するのと同じ方法で、レスポンスに使用されるHTTPステータスコードを以下の*path operations*のいずれかの`status_code`パラメータで宣言することもできます。 @@ -8,7 +8,7 @@ * `@app.delete()` * など。 -{* ../../docs_src/response_status_code/tutorial001.py hl[6] *} +{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *} /// note | 備考 @@ -39,7 +39,7 @@ FastAPIはこれを知っていて、レスポンスボディがないというO /// -## HTTPステータスコードについて +## HTTPステータスコードについて { #about-http-status-codes } /// note | 備考 @@ -70,11 +70,11 @@ HTTPでは、レスポンスの一部として３桁の数字のステータス /// -## 名前を覚えるための近道 +## 名前を覚えるための近道 { #shortcut-to-remember-the-names } 先ほどの例をもう一度見てみましょう: -{* ../../docs_src/response_status_code/tutorial001.py hl[6] *} +{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *} `201`は「作成完了」のためのステータスコードです。 @@ -82,7 +82,7 @@ HTTPでは、レスポンスの一部として３桁の数字のステータス `fastapi.status`の便利な変数を利用することができます。 -{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *} +{* ../../docs_src/response_status_code/tutorial002_py39.py hl[1,6] *} それらは便利です。それらは同じ番号を保持しており、その方法ではエディタの自動補完を使用してそれらを見つけることができます。 @@ -96,6 +96,6 @@ HTTPでは、レスポンスの一部として３桁の数字のステータス /// -## デフォルトの変更 +## デフォルトの変更 { #changing-the-default } 後に、[高度なユーザーガイド](../advanced/response-change-status-code.md){.internal-link target=_blank}で、ここで宣言しているデフォルトとは異なるステータスコードを返す方法を見ていきます。 diff --git a/docs/ja/docs/tutorial/security/index.md b/docs/ja/docs/tutorial/security/index.md index 14f2c8f44..b96021b7f 100644 --- a/docs/ja/docs/tutorial/security/index.md +++ b/docs/ja/docs/tutorial/security/index.md @@ -1,4 +1,4 @@ -# セキュリティ入門 +# セキュリティ入門 { #security } セキュリティ、認証、認可を扱うには多くの方法があります。 @@ -10,11 +10,11 @@ しかし、その前に、いくつかの小さな概念を確認しましょう。 -## お急ぎですか？ +## お急ぎですか？ { #in-a-hurry } もし、これらの用語に興味がなく、ユーザー名とパスワードに基づく認証でセキュリティを**今すぐ**確保する必要がある場合は、次の章に進んでください。 -## OAuth2 +## OAuth2 { #oauth2 } OAuth2は、認証と認可を処理するためのいくつかの方法を定義した仕様です。 @@ -24,7 +24,7 @@ OAuth2は、認証と認可を処理するためのいくつかの方法を定 これが、「Facebook、Google、X (Twitter)、GitHubを使ってログイン」を使用したすべてのシステムの背後で使われている仕組みです。 -### OAuth 1 +### OAuth 1 { #oauth-1 } OAuth 1というものもありましたが、これはOAuth2とは全く異なり、通信をどのように暗号化するかという仕様が直接的に含まれており、より複雑なものとなっています。 @@ -38,7 +38,7 @@ OAuth2は、通信を暗号化する方法を指定せず、アプリケーシ /// -## OpenID Connect +## OpenID Connect { #openid-connect } OpenID Connectは、**OAuth2**をベースにした別の仕様です。 @@ -48,7 +48,7 @@ OpenID Connectは、**OAuth2**をベースにした別の仕様です。 しかし、FacebookのログインはOpenID Connectをサポートしていません。OAuth2を独自にアレンジしています。 -### OpenID (「OpenID Connect」ではない) +### OpenID (「OpenID Connect」ではない) { #openid-not-openid-connect } また、「OpenID」という仕様もありました。それは、**OpenID Connect**と同じことを解決しようとしたものですが、OAuth2に基づいているわけではありませんでした。 @@ -56,7 +56,7 @@ OpenID Connectは、**OAuth2**をベースにした別の仕様です。 現在ではあまり普及していませんし、使われてもいません。 -## OpenAPI +## OpenAPI { #openapi } OpenAPI（以前はSwaggerとして知られていました）は、APIを構築するためのオープンな仕様です（現在はLinux Foundationの一部になっています）。 @@ -97,7 +97,7 @@ Google、Facebook、X (Twitter)、GitHubなど、他の認証/認可プロバイ /// -## **FastAPI** ユーティリティ +## **FastAPI** ユーティリティ { #fastapi-utilities } FastAPIは `fastapi.security` モジュールの中で、これらのセキュリティスキームごとにいくつかのツールを提供し、これらのセキュリティメカニズムを簡単に使用できるようにします。 diff --git a/docs/pt/docs/tutorial/extra-models.md b/docs/pt/docs/tutorial/extra-models.md index c0d22df57..d24d7db6d 100644 --- a/docs/pt/docs/tutorial/extra-models.md +++ b/docs/pt/docs/tutorial/extra-models.md @@ -30,9 +30,9 @@ Os exemplos aqui usam `.dict()` por compatibilidade com o Pydantic v1, mas você /// -### Sobre `**user_in.dict()` { #about-user-in-dict } +### Sobre `**user_in.dict()` { #about-user-in-model-dump } -#### O `.dict()` do Pydantic { #pydantics-dict } +#### O `.dict()` do Pydantic { #pydantics-model-dump } `user_in` é um modelo Pydantic da classe `UserIn`. @@ -47,7 +47,7 @@ user_in = UserIn(username="john", password="secret", email="john.doe@example.com e depois chamarmos: ```Python -user_dict = user_in.dict() +user_dict = user_in.model_dump() ``` agora temos um `dict` com os dados na variável `user_dict` (é um `dict` em vez de um objeto de modelo Pydantic). @@ -106,14 +106,14 @@ UserInDB( Como no exemplo acima, obtivemos o `user_dict` a partir do `user_in.dict()`, este código: ```Python -user_dict = user_in.dict() +user_dict = user_in.model_dump() UserInDB(**user_dict) ``` seria equivalente a: ```Python -UserInDB(**user_in.dict()) +UserInDB(**user_in.model_dump()) ``` ...porque `user_in.dict()` é um `dict`, e depois fazemos o Python "desembrulhá-lo" passando-o para `UserInDB` precedido por `**`. @@ -125,7 +125,7 @@ Então, obtemos um modelo Pydantic a partir dos dados em outro modelo Pydantic. E, então, adicionando o argumento de palavra-chave extra `hashed_password=hashed_password`, como em: ```Python -UserInDB(**user_in.dict(), hashed_password=hashed_password) +UserInDB(**user_in.model_dump(), hashed_password=hashed_password) ``` ...acaba sendo como: diff --git a/docs/pt/docs/tutorial/sql-databases.md b/docs/pt/docs/tutorial/sql-databases.md index 543e164e9..0f8467ee8 100644 --- a/docs/pt/docs/tutorial/sql-databases.md +++ b/docs/pt/docs/tutorial/sql-databases.md @@ -96,7 +96,7 @@ Vamos criar uma **dependência** do FastAPI com `yield` que fornecerá uma nova Então, criamos uma dependência `Annotated` chamada `SessionDep` para simplificar o restante do código que usará essa dependência. -{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[25:30] hl[25:27,30] *} +{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[25:30] hl[25:27,30] *} ### Criar Tabelas de Banco de Dados na Inicialização { #create-database-tables-on-startup } diff --git a/docs/pt/docs/virtual-environments.md b/docs/pt/docs/virtual-environments.md index 5736f7109..948b9f131 100644 --- a/docs/pt/docs/virtual-environments.md +++ b/docs/pt/docs/virtual-environments.md @@ -835,7 +835,7 @@ $ source .venv/bin/activate // Agora, quando você executar o python, ele encontrará o pacote sirius instalado neste ambiente virtual ✨ $ python main.py -Eu juro solenemente 🐺 +I solemnly swear 🐺 ``` diff --git a/docs/ru/docs/tutorial/extra-models.md b/docs/ru/docs/tutorial/extra-models.md index 2f0ce4e33..b7862ac86 100644 --- a/docs/ru/docs/tutorial/extra-models.md +++ b/docs/ru/docs/tutorial/extra-models.md @@ -30,9 +30,9 @@ /// -### Про `**user_in.dict()` { #about-user-in-dict } +### Про `**user_in.dict()` { #about-user-in-model-dump } -#### `.dict()` из Pydantic { #pydantics-dict } +#### `.dict()` из Pydantic { #pydantics-model-dump } `user_in` - это Pydantic-модель класса `UserIn`. @@ -47,7 +47,7 @@ user_in = UserIn(username="john", password="secret", email="john.doe@example.com и затем вызовем: ```Python -user_dict = user_in.dict() +user_dict = user_in.model_dump() ``` то теперь у нас есть `dict` с данными модели в переменной `user_dict` (это `dict` вместо объекта Pydantic-модели). @@ -106,14 +106,14 @@ UserInDB( Как в примере выше мы получили `user_dict` из `user_in.dict()`, этот код: ```Python -user_dict = user_in.dict() +user_dict = user_in.model_dump() UserInDB(**user_dict) ``` будет равнозначен такому: ```Python -UserInDB(**user_in.dict()) +UserInDB(**user_in.model_dump()) ``` ...потому что `user_in.dict()` - это `dict`, и затем мы указываем, чтобы Python его "распаковал", когда передаём его в `UserInDB` и ставим перед ним `**`. @@ -125,7 +125,7 @@ UserInDB(**user_in.dict()) И затем, если мы добавим дополнительный именованный аргумент `hashed_password=hashed_password` как здесь: ```Python -UserInDB(**user_in.dict(), hashed_password=hashed_password) +UserInDB(**user_in.model_dump(), hashed_password=hashed_password) ``` ... то мы получим что-то подобное: diff --git a/docs/tr/docs/about/index.md b/docs/tr/docs/about/index.md index e9dee5217..a638fb0cf 100644 --- a/docs/tr/docs/about/index.md +++ b/docs/tr/docs/about/index.md @@ -1,3 +1,3 @@ -# Hakkında +# Hakkında { #about } FastAPI, tasarımı, ilham kaynağı ve daha fazlası hakkında. 🤓 diff --git a/docs/tr/docs/advanced/security/index.md b/docs/tr/docs/advanced/security/index.md index 709f74c72..5e9b36468 100644 --- a/docs/tr/docs/advanced/security/index.md +++ b/docs/tr/docs/advanced/security/index.md @@ -1,6 +1,6 @@ -# Gelişmiş Güvenlik +# Gelişmiş Güvenlik { #advanced-security } -## Ek Özellikler +## Ek Özellikler { #additional-features } [Tutorial - User Guide: Security](../../tutorial/security/index.md){.internal-link target=_blank} sayfasında ele alınanların dışında güvenlikle ilgili bazı ek özellikler vardır. @@ -12,7 +12,7 @@ Kullanım şeklinize bağlı olarak, çözümünüz bu bölümlerden birinde ola /// -## Önce Öğreticiyi Okuyun +## Önce Öğreticiyi Okuyun { #read-the-tutorial-first } Sonraki bölümler [Tutorial - User Guide: Security](../../tutorial/security/index.md){.internal-link target=_blank} sayfasını okuduğunuzu varsayarak hazırlanmıştır. diff --git a/docs/tr/docs/advanced/testing-websockets.md b/docs/tr/docs/advanced/testing-websockets.md index effe557d1..244c095ad 100644 --- a/docs/tr/docs/advanced/testing-websockets.md +++ b/docs/tr/docs/advanced/testing-websockets.md @@ -1,13 +1,13 @@ -# WebSockets'i Test Etmek +# WebSockets'i Test Etmek { #testing-websockets } WebSockets testi yapmak için `TestClient`'ı kullanabilirsiniz. Bu işlem için, `TestClient`'ı bir `with` ifadesinde kullanarak WebSocket'e bağlanabilirsiniz: -{* ../../docs_src/app_testing/tutorial002.py hl[27:31] *} +{* ../../docs_src/app_testing/tutorial002_py39.py hl[27:31] *} /// note | Not -Daha fazla detay için Starlette'in Websockets'i Test Etmek dokümantasyonunu inceleyin. +Daha fazla detay için Starlette'in Websockets'i Test Etmek dokümantasyonunu inceleyin. /// diff --git a/docs/tr/docs/advanced/wsgi.md b/docs/tr/docs/advanced/wsgi.md index 00815a4b2..f41847185 100644 --- a/docs/tr/docs/advanced/wsgi.md +++ b/docs/tr/docs/advanced/wsgi.md @@ -1,10 +1,10 @@ -# WSGI - Flask, Django ve Daha Fazlasını FastAPI ile Kullanma +# WSGI - Flask, Django ve Daha Fazlasını FastAPI ile Kullanma { #including-wsgi-flask-django-others } WSGI uygulamalarını [Sub Applications - Mounts](sub-applications.md){.internal-link target=_blank}, [Behind a Proxy](behind-a-proxy.md){.internal-link target=_blank} bölümlerinde gördüğünüz gibi bağlayabilirsiniz. Bunun için `WSGIMiddleware` ile Flask, Django vb. WSGI uygulamanızı sarmalayabilir ve FastAPI'ya bağlayabilirsiniz. -## `WSGIMiddleware` Kullanımı +## `WSGIMiddleware` Kullanımı { #using-wsgimiddleware } `WSGIMiddleware`'ı projenize dahil edin. @@ -12,9 +12,9 @@ Ardından WSGI (örneğin Flask) uygulamanızı middleware ile sarmalayın. Son olarak da bir yol altında bağlama işlemini gerçekleştirin. -{* ../../docs_src/wsgi/tutorial001.py hl[2:3,23] *} +{* ../../docs_src/wsgi/tutorial001_py39.py hl[2:3,3] *} -## Kontrol Edelim +## Kontrol Edelim { #check-it } Artık `/v1/` yolunun altındaki her istek Flask uygulaması tarafından işlenecektir. @@ -26,7 +26,7 @@ Eğer uygulamanızı çalıştırıp http://localhost:8000/v2/ adresine giderseniz, FastAPI'dan gelen yanıtı göreceksiniz: +Eğer http://localhost:8000/v2/ adresine giderseniz, FastAPI'dan gelen yanıtı göreceksiniz: ```JSON { diff --git a/docs/tr/docs/alternatives.md b/docs/tr/docs/alternatives.md index 9b603ea81..f66250832 100644 --- a/docs/tr/docs/alternatives.md +++ b/docs/tr/docs/alternatives.md @@ -1,8 +1,8 @@ -# Alternatifler, İlham Kaynakları ve Karşılaştırmalar +# Alternatifler, İlham Kaynakları ve Karşılaştırmalar { #alternatives-inspiration-and-comparisons } **FastAPI**'ya neler ilham verdi? Diğer alternatiflerle karşılaştırıldığında farkları neler? **FastAPI** diğer alternatiflerinden neler öğrendi? -## Giriş +## Giriş { #intro } Başkalarının daha önceki çalışmaları olmasaydı, **FastAPI** var olmazdı. @@ -12,9 +12,9 @@ Yıllardır yeni bir framework oluşturmaktan kaçınıyordum. Başlangıçta ** Ancak bir noktada, geçmişteki diğer araçlardan en iyi fikirleri alarak bütün bu çözümleri kapsayan, ayrıca bütün bunları Python'ın daha önce mevcut olmayan özelliklerini (Python 3.6+ ile gelen tip belirteçleri) kullanarak yapan bir şey üretmekten başka seçenek kalmamıştı. -## Daha Önce Geliştirilen Araçlar +## Daha Önce Geliştirilen Araçlar { #previous-tools } -### Django +### Django { #django } Django geniş çapta güvenilen, Python ekosistemindeki en popüler web framework'üdür. Instagram gibi sistemleri geliştirmede kullanılmıştır. @@ -22,7 +22,7 @@ MySQL ve PostgreSQL gibi ilişkisel veritabanlarıyla nispeten sıkı bir şekil Modern ön uçlarda (React, Vue.js ve Angular gibi) veya diğer sistemler (örneğin nesnelerin interneti cihazları) tarafından kullanılan API'lar yerine arka uçta HTML üretmek için oluşturuldu. -### Django REST Framework +### Django REST Framework { #django-rest-framework } Django REST framework'ü, Django'nun API kabiliyetlerini arttırmak için arka planda Django kullanan esnek bir araç grubu olarak oluşturuldu. @@ -42,7 +42,7 @@ Kullanıcılar için otomatik API dökümantasyonu sunan bir web arayüzüne sah /// -### Flask +### Flask { #flask } Flask bir mikro framework olduğundan Django gibi framework'lerin aksine veritabanı entegrasyonu gibi Django ile gelen pek çok özelliği direkt barındırmaz. @@ -64,7 +64,7 @@ Basit ve kullanması kolay bir yönlendirme /// -### Requests +### Requests { #requests } **FastAPI** aslında **Requests**'in bir alternatifi değil. İkisininde kapsamı oldukça farklı. @@ -93,7 +93,7 @@ Bunun FastAPI'deki API *yol işlemi*< ```Python hl_lines="1" @app.get("/some/url") def read_url(): - return {"message": "Hello World!"} + return {"message": "Hello World"} ``` `requests.get(...)` ile `@app.get(...)` arasındaki benzerliklere bakın. @@ -106,7 +106,7 @@ def read_url(): /// -### Swagger / OpenAPI +### Swagger / OpenAPI { #swagger-openapi } Benim Django REST Framework'ünden istediğim ana özellik otomatik API dökümantasyonuydu. @@ -131,11 +131,11 @@ Yukarıdaki ikisi oldukça popüler ve istikrarlı olduğu için seçildi, ancak /// -### Flask REST framework'leri +### Flask REST framework'leri { #flask-rest-frameworks } Pek çok Flask REST framework'ü var, fakat bunları biraz araştırdıktan sonra pek çoğunun artık geliştirilmediğini ve göze batan bazı sorunlarının olduğunu gördüm. -### Marshmallow +### Marshmallow { #marshmallow } API sistemlerine gereken ana özelliklerden biri de koddan veriyi alıp ağ üzerinde gönderilebilecek bir şeye çevirmek, yani veri dönüşümü. Bu işleme veritabanındaki veriyi içeren bir objeyi JSON objesine çevirmek, `datetime` objelerini metinlere çevirmek gibi örnekler verilebilir. @@ -153,7 +153,7 @@ Kod kullanarak otomatik olarak veri tipini ve veri doğrulamayı belirten "şema /// -### Webargs +### Webargs { #webargs } API'ların ihtiyacı olan bir diğer önemli özellik ise gelen isteklerdeki verileri Python objelerine ayrıştırabilmektir. @@ -175,7 +175,7 @@ Gelen istek verisi için otomatik veri doğrulamaya sahip olmalı. /// -### APISpec +### APISpec { #apispec } Marshmallow ve Webargs eklentiler olarak; veri doğrulama, ayrıştırma ve dönüştürmeyi sağlıyor. @@ -203,7 +203,7 @@ API'lar için açık standart desteği olmalı (OpenAPI gibi). /// -### Flask-apispec +### Flask-apispec { #flask-apispec } Flask-apispec ise Webargs, Marshmallow ve APISpec'i birbirine bağlayan bir Flask eklentisi. @@ -235,7 +235,7 @@ Veri dönüşümü ve veri doğrulamayı tanımlayan kodu kullanarak otomatik ol /// -### NestJS (and Angular) +### NestJS (and Angular) { #nestjs-and-angular } Bu Python teknolojisi bile değil. NestJS, Angulardan ilham almış olan bir JavaScript (TypeScript) NodeJS framework'ü. @@ -257,7 +257,7 @@ Güçlü bir bağımlılık enjeksiyon sistemine sahip olmalı. Kod tekrarını /// -### Sanic +### Sanic { #sanic } Sanic, `asyncio`'ya dayanan son derece hızlı Python kütüphanelerinden biriydi. Flask'a epey benzeyecek şekilde geliştirilmişti. @@ -277,7 +277,7 @@ Tam da bu yüzden **FastAPI** Starlette'e dayanıyor, çünkü Starlette şu and /// -### Falcon +### Falcon { #falcon } Falcon ise bir diğer yüksek performanslı Python framework'ü. Minimal olacak şekilde Hug gibi diğer framework'lerin temeli olabilmek için tasarlandı. @@ -295,7 +295,7 @@ FastAPI'da opsiyonel olmasına rağmen, daha çok header'lar, çerezler ve alter /// -### Molten +### Molten { #molten } **FastAPI**'ı geliştirmenin ilk aşamalarında Molten'ı keşfettim. Pek çok ortak fikrimiz vardı: @@ -319,7 +319,7 @@ Bu aslında Pydantic'in de aynı doğrulama stiline geçmesinde ilham kaynağı /// -### Hug +### Hug { #hug } Hug, Python tip belirteçlerini kullanarak API parametrelerinin tipini belirlemeyi uygulayan ilk framework'lerdendi. Bu, diğer araçlara da ilham kaynağı olan harika bir fikirdi. @@ -349,7 +349,7 @@ Hug, APIStar'ın çeşitli kısımlarında esin kaynağı oldu ve APIStar'la bir /// -### APIStar (<= 0.5) +### APIStar (<= 0.5) { #apistar-0-5 } **FastAPI**'ı geliştirmeye başlamadan hemen önce **APIStar** sunucusunu buldum. Benim aradığım şeylerin neredeyse hepsine sahipti ve harika bir tasarımı vardı. @@ -397,9 +397,9 @@ Ben bu önceki araçlardan öğrendiklerime dayanarak **FastAPI**'ın özellikle /// -## **FastAPI** Tarafından Kullanılanlar +## **FastAPI** Tarafından Kullanılanlar { #used-by-fastapi } -### Pydantic +### Pydantic { #pydantic } Pydantic Python tip belirteçlerine dayanan; veri doğrulama, veri dönüştürme ve dökümantasyon tanımlamak (JSON Şema kullanarak) için bir kütüphanedir. @@ -415,7 +415,7 @@ Bütün veri doğrulama, veri dönüştürme ve JSON Şemasına bağlı otomatik /// -### Starlette +### Starlette { #starlette } Starlette hafif bir ASGI framework'ü ve yüksek performanslı asyncio servisleri oluşturmak için ideal. @@ -460,7 +460,7 @@ Yani, Starlette ile yapabileceğiniz her şeyi, Starlette'in bir nevi güçlendi /// -### Uvicorn +### Uvicorn { #uvicorn } Uvicorn, uvlook ile httptools üzerine kurulu ışık hzında bir ASGI sunucusudur. @@ -478,6 +478,6 @@ Daha fazla detay için [Deployment](deployment/index.md){.internal-link target=_ /// -## Karşılaştırma ve Hız +## Karşılaştırma ve Hız { #benchmarks-and-speed } Uvicorn, Starlette ve FastAPI arasındakı farkı daha iyi anlamak ve karşılaştırma yapmak için [Kıyaslamalar](benchmarks.md){.internal-link target=_blank} bölümüne bakın! diff --git a/docs/tr/docs/benchmarks.md b/docs/tr/docs/benchmarks.md index eb5472869..82ae97018 100644 --- a/docs/tr/docs/benchmarks.md +++ b/docs/tr/docs/benchmarks.md @@ -1,10 +1,10 @@ -# Kıyaslamalar +# Kıyaslamalar { #benchmarks } Bağımsız TechEmpower kıyaslamaları gösteriyor ki en hızlı Python frameworklerinden birisi olan Uvicorn ile çalıştırılan **FastAPI** uygulamaları, sadece Starlette ve Uvicorn'dan daha düşük sıralamada (FastAPI bu frameworklerin üzerine kurulu) yer alıyor. (*) Fakat kıyaslamaları ve karşılaştırmaları incelerken şunları aklınızda bulundurmalısınız. -## Kıyaslamalar ve Hız +## Kıyaslamalar ve Hız { #benchmarks-and-speed } Kıyaslamaları incelediğinizde, farklı özelliklere sahip araçların eşdeğer olarak karşılaştırıldığını yaygın bir şekilde görebilirsiniz. diff --git a/docs/tr/docs/history-design-future.md b/docs/tr/docs/history-design-future.md index cad290828..764a51957 100644 --- a/docs/tr/docs/history-design-future.md +++ b/docs/tr/docs/history-design-future.md @@ -1,4 +1,4 @@ -# Geçmişi, Tasarımı ve Geleceği +# Geçmişi, Tasarımı ve Geleceği { #history-design-and-future } Bir süre önce, bir **FastAPI** kullanıcısı sordu: @@ -6,7 +6,7 @@ Bir süre önce, **Pydantic**'i kullanmaya karar verdim. @@ -60,11 +60,11 @@ Sonra, JSON Schema ile tamamen uyumlu olmasını sağlamak, kısıtlama bildirim Geliştirme sırasında, diğer ana gereksinim olan **Starlette**'e de katkıda bulundum. -## Geliştirme +## Geliştirme { #development } **FastAPI**'ı oluşturmaya başladığımda, parçaların çoğu zaten yerindeydi, tasarım tanımlanmıştı, gereksinimler ve araçlar hazırdı, standartlar ve tanımlamalar hakkındaki bilgi net ve tazeydi. -## Gelecek +## Gelecek { #future } Şimdiye kadar, **FastAPI**'ın fikirleriyle birçok kişiye faydalı olduğu apaçık ortada. diff --git a/docs/tr/docs/how-to/general.md b/docs/tr/docs/how-to/general.md index cbfa7beb2..ca84847fb 100644 --- a/docs/tr/docs/how-to/general.md +++ b/docs/tr/docs/how-to/general.md @@ -1,39 +1,39 @@ -# Genel - Nasıl Yapılır - Tarifler +# Genel - Nasıl Yapılır - Tarifler { #general-how-to-recipes } Bu sayfada genel ve sıkça sorulan sorular için dokümantasyonun diğer sayfalarına yönlendirmeler bulunmaktadır. -## Veri Filtreleme - Güvenlik +## Veri Filtreleme - Güvenlik { #filter-data-security } Döndürmeniz gereken veriden fazlasını döndürmediğinizden emin olmak için, [Tutorial - Response Model - Return Type](../tutorial/response-model.md){.internal-link target=_blank} sayfasını okuyun. -## Dokümantasyon Etiketleri - OpenAPI +## Dokümantasyon Etiketleri - OpenAPI { #documentation-tags-openapi } *Yol operasyonlarınıza* etiketler ekleyerek dokümantasyon arayüzünde gruplar halinde görünmesini sağlamak için, [Tutorial - Path Operation Configurations - Tags](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank} sayfasını okuyun. -## Dokümantasyon Özeti ve Açıklaması - OpenAPI +## Dokümantasyon Özeti ve Açıklaması - OpenAPI { #documentation-summary-and-description-openapi } *Yol operasyonlarınıza* özet ve açıklama ekleyip dokümantasyon arayüzünde görünmesini sağlamak için, [Tutorial - Path Operation Configurations - Summary and Description](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank} sayfasını okuyun. -## Yanıt Açıklaması Dokümantasyonu - OpenAPI +## Yanıt Açıklaması Dokümantasyonu - OpenAPI { #documentation-response-description-openapi } Dokümantasyon arayüzünde yer alan yanıt açıklamasını tanımlamak için, [Tutorial - Path Operation Configurations - Response description](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank} sayfasını okuyun. -## *Yol Operasyonunu* Kullanımdan Kaldırma - OpenAPI +## *Yol Operasyonunu* Kullanımdan Kaldırma - OpenAPI { #documentation-deprecate-a-path-operation-openapi } Bir *yol işlemi*ni kullanımdan kaldırmak ve bunu dokümantasyon arayüzünde göstermek için, [Tutorial - Path Operation Configurations - Deprecation](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank} sayfasını okuyun. -## Herhangi Bir Veriyi JSON Uyumlu Hale Getirme +## Herhangi Bir Veriyi JSON Uyumlu Hale Getirme { #convert-any-data-to-json-compatible } Herhangi bir veriyi JSON uyumlu hale getirmek için, [Tutorial - JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank} sayfasını okuyun. -## OpenAPI Meta Verileri - Dokümantasyon +## OpenAPI Meta Verileri - Dokümantasyon { #openapi-metadata-docs } OpenAPI şemanıza lisans, sürüm, iletişim vb. meta veriler eklemek için, [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md){.internal-link target=_blank} sayfasını okuyun. -## OpenAPI Bağlantı Özelleştirme +## OpenAPI Bağlantı Özelleştirme { #openapi-custom-url } OpenAPI bağlantısını özelleştirmek (veya kaldırmak) için, [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md#openapi-url){.internal-link target=_blank} sayfasını okuyun. -## OpenAPI Dokümantasyon Bağlantıları +## OpenAPI Dokümantasyon Bağlantıları { #openapi-docs-urls } Dokümantasyonu arayüzünde kullanılan bağlantıları güncellemek için, [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md#docs-urls){.internal-link target=_blank} sayfasını okuyun. diff --git a/docs/tr/docs/learn/index.md b/docs/tr/docs/learn/index.md index 52e3aa54d..424a70916 100644 --- a/docs/tr/docs/learn/index.md +++ b/docs/tr/docs/learn/index.md @@ -1,4 +1,4 @@ -# Öğren +# Öğren { #learn } **FastAPI** öğrenmek için giriş bölümleri ve öğreticiler burada yer alıyor. diff --git a/docs/tr/docs/resources/index.md b/docs/tr/docs/resources/index.md index fc71a9ca1..c8d3dda2f 100644 --- a/docs/tr/docs/resources/index.md +++ b/docs/tr/docs/resources/index.md @@ -1,3 +1,3 @@ -# Kaynaklar +# Kaynaklar { #resources } Ek kaynaklar, dış bağlantılar, makaleler ve daha fazlası. ✈️ diff --git a/docs/tr/docs/tutorial/query-params.md b/docs/tr/docs/tutorial/query-params.md index a8ba883ed..51e3d71ad 100644 --- a/docs/tr/docs/tutorial/query-params.md +++ b/docs/tr/docs/tutorial/query-params.md @@ -1,8 +1,8 @@ -# Sorgu Parametreleri +# Sorgu Parametreleri { #query-parameters } Fonksiyonda yol parametrelerinin parçası olmayan diğer tanımlamalar otomatik olarak "sorgu" parametresi olarak yorumlanır. -{* ../../docs_src/query_params/tutorial001.py hl[9] *} +{* ../../docs_src/query_params/tutorial001_py39.py hl[9] *} Sorgu, bağlantıdaki `?` kısmından sonra gelen ve `&` işareti ile ayrılan anahtar-değer çiftlerinin oluşturduğu bir kümedir. @@ -28,7 +28,7 @@ Yol parametreleri için geçerli olan her türlü işlem aynı şekilde sorgu pa * Veri doğrulama * Otomatik dokümantasyon -## Varsayılanlar +## Varsayılanlar { #defaults } Sorgu parametreleri, adres yolunun sabit bir parçası olmadıklarından dolayı isteğe bağlı ve varsayılan değere sahip olabilirler. @@ -57,7 +57,7 @@ Fonksiyonunuzdaki parametre değerleri aşağıdaki gibi olacaktır: * `skip=20`: çünkü bağlantıda böyle tanımlandı. * `limit=10`: çünkü varsayılan değer buydu. -## İsteğe Bağlı Parametreler +## İsteğe Bağlı Parametreler { #optional-parameters } Aynı şekilde, varsayılan değerlerini `None` olarak atayarak isteğe bağlı parametreler tanımlayabilirsiniz: @@ -71,7 +71,7 @@ Ayrıca, dikkatinizi çekerim ki; **FastAPI**, `item_id` parametresinin bir yol /// -## Sorgu Parametresi Tip Dönüşümü +## Sorgu Parametresi Tip Dönüşümü { #query-parameter-type-conversion } Aşağıda görüldüğü gibi dönüştürülmek üzere `bool` tipleri de tanımlayabilirsiniz: @@ -110,7 +110,7 @@ http://127.0.0.1:8000/items/foo?short=yes veya adres, herhangi farklı bir harf varyasyonu içermesi durumuna rağmen (büyük harf, sadece baş harfi büyük kelime, vb.) fonksiyonunuz, `bool` tipli `short` parametresini `True` olarak algılayacaktır. Aksi halde `False` olarak algılanacaktır. -## Çoklu Yol ve Sorgu Parametreleri +## Çoklu Yol ve Sorgu Parametreleri { #multiple-path-and-query-parameters } **FastAPI** neyin ne olduğunu ayırt edebileceğinden dolayı aynı anda birden fazla yol ve sorgu parametresi tanımlayabilirsiniz. @@ -120,7 +120,7 @@ Ve parametreleri, herhangi bir sıraya koymanıza da gerek yoktur. {* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *} -## Zorunlu Sorgu Parametreleri +## Zorunlu Sorgu Parametreleri { #required-query-parameters } Türü yol olmayan bir parametre (şu ana kadar sadece sorgu parametrelerini gördük) için varsayılan değer tanımlarsanız o parametre zorunlu olmayacaktır. @@ -128,7 +128,7 @@ Parametre için belirli bir değer atamak istemeyip parametrenin sadece isteğe Fakat, bir sorgu parametresini zorunlu yapmak istiyorsanız varsayılan bir değer atamamanız yeterli olacaktır: -{* ../../docs_src/query_params/tutorial005.py hl[6:7] *} +{* ../../docs_src/query_params/tutorial005_py39.py hl[6:7] *} Burada `needy` parametresi `str` tipinden oluşan zorunlu bir sorgu parametresidir. @@ -183,6 +183,6 @@ Bu durumda, 3 tane sorgu parametresi var olacaktır: /// tip | İpucu -Ayrıca, [Yol Parametrelerinde](path-params.md#on-tanml-degerler){.internal-link target=_blank} de kullanıldığı şekilde `Enum` sınıfından faydalanabilirsiniz. +Ayrıca, [Yol Parametrelerinde](path-params.md#predefined-values){.internal-link target=_blank} de kullanıldığı şekilde `Enum` sınıfından faydalanabilirsiniz. /// diff --git a/docs/tr/docs/tutorial/static-files.md b/docs/tr/docs/tutorial/static-files.md index 4542aca77..3e468423d 100644 --- a/docs/tr/docs/tutorial/static-files.md +++ b/docs/tr/docs/tutorial/static-files.md @@ -1,13 +1,13 @@ -# Statik Dosyalar +# Statik Dosyalar { #static-files } `StaticFiles`'ı kullanarak statik dosyaları bir yol altında sunabilirsiniz. -## `StaticFiles` Kullanımı +## `StaticFiles` Kullanımı { #use-staticfiles } * `StaticFiles` sınıfını projenize dahil edin. * Bir `StaticFiles()` örneğini belirli bir yola bağlayın. -{* ../../docs_src/static_files/tutorial001.py hl[2,6] *} +{* ../../docs_src/static_files/tutorial001_py39.py hl[2,6] *} /// note | Teknik Detaylar @@ -17,7 +17,7 @@ Projenize dahil etmek için `from starlette.staticfiles import StaticFiles` kull /// -### Bağlama (Mounting) Nedir? +### Bağlama (Mounting) Nedir? { #what-is-mounting } "Bağlamak", belirli bir yola tamamen "bağımsız" bir uygulama eklemek anlamına gelir ve ardından tüm alt yollara gelen istekler bu uygulama tarafından işlenir. @@ -25,7 +25,7 @@ Bu, bir `APIRouter` kullanmaktan farklıdır çünkü bağlanmış bir uygulama [Advanced User Guide](../advanced/index.md){.internal-link target=_blank} bölümünde daha fazla bilgi edinebilirsiniz. -## Detaylar +## Detaylar { #details } `"/static"` ifadesi, bu "alt uygulamanın" "bağlanacağı" alt yolu belirtir. Bu nedenle, `"/static"` ile başlayan her yol, bu uygulama tarafından işlenir. @@ -35,6 +35,6 @@ Bu, bir `APIRouter` kullanmaktan farklıdır çünkü bağlanmış bir uygulama Bu parametrelerin hepsi "`static`"den farklı olabilir, bunları kendi uygulamanızın ihtiyaçlarına göre belirleyebilirsiniz. -## Daha Fazla Bilgi +## Daha Fazla Bilgi { #more-info } Daha fazla detay ve seçenek için Starlette'in Statik Dosyalar hakkındaki dokümantasyonunu incelleyin. diff --git a/docs/uk/docs/alternatives.md b/docs/uk/docs/alternatives.md index 786df45c5..066a6150d 100644 --- a/docs/uk/docs/alternatives.md +++ b/docs/uk/docs/alternatives.md @@ -1,8 +1,8 @@ -# Альтернативи, натхнення та порівняння +# Альтернативи, натхнення та порівняння { #alternatives-inspiration-and-comparisons } Що надихнуло на створення **FastAPI**, який він у порінянні з іншими альтернативами та чого він у них навчився. -## Вступ +## Вступ { #intro } **FastAPI** не існувало б, якби не попередні роботи інших. @@ -12,9 +12,9 @@ Але в якийсь момент не було іншого виходу, окрім створення чогось, що надавало б усі ці функції, взявши найкращі ідеї з попередніх інструментів і поєднавши їх найкращим чином, використовуючи мовні функції, які навіть не були доступні раніше (Python 3.6+ підказки типів). -## Попередні інструменти +## Попередні інструменти { #previous-tools } -### Django +### Django { #django } Це найпопулярніший фреймворк Python, який користується широкою довірою. Він використовується для створення таких систем, як Instagram. @@ -22,7 +22,7 @@ Він був створений для створення HTML у серверній частині, а не для створення API, які використовуються сучасним інтерфейсом (як-от React, Vue.js і Angular) або іншими системами (як-от IoT пристрої), які спілкуються з ним. -### Django REST Framework +### Django REST Framework { #django-rest-framework } Фреймворк Django REST був створений як гнучкий інструментарій для створення веб-інтерфейсів API використовуючи Django в основі, щоб покращити його можливості API. @@ -42,7 +42,7 @@ Django REST Framework створив Том Крісті. Той самий тв /// -### Flask +### Flask { #flask } Flask — це «мікрофреймворк», він не включає інтеграцію бази даних, а також багато речей, які за замовчуванням є в Django. @@ -64,7 +64,7 @@ Flask — це «мікрофреймворк», він не включає ін /// -### Requests +### Requests { #requests } **FastAPI** насправді не є альтернативою **Requests**. Сфера їх застосування дуже різна. @@ -93,7 +93,7 @@ response = requests.get("http://example.com/some/url") ```Python hl_lines="1" @app.get("/some/url") def read_url(): - return {"message": "Hello World"} + return {"message": "Hello World"} ``` Зверніть увагу на схожість у `requests.get(...)` і `@app.get(...)`. @@ -106,7 +106,7 @@ def read_url(): /// -### Swagger / OpenAPI +### Swagger / OpenAPI { #swagger-openapi } Головною функцією, яку я хотів від Django REST Framework, була автоматична API документація. @@ -131,11 +131,11 @@ def read_url(): /// -### Фреймворки REST для Flask +### Фреймворки REST для Flask { #flask-rest-frameworks } Існує кілька фреймворків Flask REST, але, витративши час і роботу на їх дослідження, я виявив, що багато з них припинено або залишено, з кількома постійними проблемами, які зробили їх непридатними. -### Marshmallow +### Marshmallow { #marshmallow } Однією з головних функцій, необхідних для систем API, є "серіалізація", яка бере дані з коду (Python) і перетворює їх на щось, що можна надіслати через мережу. Наприклад, перетворення об’єкта, що містить дані з бази даних, на об’єкт JSON. Перетворення об’єктів `datetime` на строки тощо. @@ -153,7 +153,7 @@ Marshmallow створено для забезпечення цих функці /// -### Webargs +### Webargs { #webargs } Іншою важливою функцією, необхідною для API, є аналіз даних із вхідних запитів. @@ -175,7 +175,7 @@ Webargs був створений тими ж розробниками Marshmall /// -### APISpec +### APISpec { #apispec } Marshmallow і Webargs забезпечують перевірку, аналіз і серіалізацію як плагіни. @@ -205,7 +205,7 @@ APISpec був створений тими ж розробниками Marshmall /// -### Flask-apispec +### Flask-apispec { #flask-apispec } Це плагін Flask, який об’єднує Webargs, Marshmallow і APISpec. @@ -237,7 +237,7 @@ Flask-apispec був створений тими ж розробниками Mar /// -### NestJS (та Angular) +### NestJS (та Angular) { #nestjs-and-angular } Це навіть не Python, NestJS — це фреймворк NodeJS JavaScript (TypeScript), натхненний Angular. @@ -259,7 +259,7 @@ Flask-apispec був створений тими ж розробниками Mar /// -### Sanic +### Sanic { #sanic } Це був один із перших надзвичайно швидких фреймворків Python на основі `asyncio`. Він був дуже схожий на Flask. @@ -279,7 +279,7 @@ Flask-apispec був створений тими ж розробниками Mar /// -### Falcon +### Falcon { #falcon } Falcon — ще один високопродуктивний фреймворк Python, він розроблений як мінімальний і працює як основа інших фреймворків, таких як Hug. @@ -297,7 +297,7 @@ Falcon — ще один високопродуктивний фреймворк /// -### Molten +### Molten { #molten } Я відкрив для себе Molten на перших етапах створення **FastAPI**. І він має досить схожі ідеї: @@ -321,7 +321,7 @@ Falcon — ще один високопродуктивний фреймворк /// -### Hug +### Hug { #hug } Hug був одним із перших фреймворків, який реалізував оголошення типів параметрів API за допомогою підказок типу Python. Це була чудова ідея, яка надихнула інші інструменти зробити те саме. @@ -351,7 +351,7 @@ Hug надихнув частину APIStar і був одним із найбі /// -### APIStar (<= 0,5) +### APIStar (<= 0,5) { #apistar-0-5 } Безпосередньо перед тим, як вирішити створити **FastAPI**, я знайшов сервер **APIStar**. Він мав майже все, що я шукав, і мав чудовий дизайн. @@ -397,9 +397,9 @@ APIStar створив Том Крісті. Той самий хлопець, я /// -## Використовується **FastAPI** +## Використовується **FastAPI** { #used-by-fastapi } -### Pydantic +### Pydantic { #pydantic } Pydantic — це бібліотека для визначення перевірки даних, серіалізації та документації (за допомогою схеми JSON) на основі підказок типу Python. @@ -415,7 +415,7 @@ Pydantic — це бібліотека для визначення переві /// -### Starlette +### Starlette { #starlette } Starlette — це легкий фреймворк/набір інструментів ASGI, який ідеально підходить для створення високопродуктивних asyncio сервісів. @@ -460,7 +460,7 @@ ASGI — це новий «стандарт», який розробляєтьс /// -### Uvicorn +### Uvicorn { #uvicorn } Uvicorn — це блискавичний сервер ASGI, побудований на uvloop і httptools. @@ -478,6 +478,6 @@ Uvicorn — це блискавичний сервер ASGI, побудован /// -## Орієнтири та швидкість +## Орієнтири та швидкість { #benchmarks-and-speed } Щоб зрозуміти, порівняти та побачити різницю між Uvicorn, Starlette і FastAPI, перегляньте розділ про [Бенчмарки](benchmarks.md){.internal-link target=_blank}. diff --git a/docs/zh-hant/docs/about/index.md b/docs/zh-hant/docs/about/index.md index 5dcee68f2..ece7e45d1 100644 --- a/docs/zh-hant/docs/about/index.md +++ b/docs/zh-hant/docs/about/index.md @@ -1,3 +1,3 @@ -# 關於 FastAPI +# 關於 FastAPI { #about } 關於 FastAPI、其設計、靈感來源等更多資訊。 🤓 diff --git a/docs/zh-hant/docs/benchmarks.md b/docs/zh-hant/docs/benchmarks.md index c59e8e71c..0767b4f9a 100644 --- a/docs/zh-hant/docs/benchmarks.md +++ b/docs/zh-hant/docs/benchmarks.md @@ -1,10 +1,10 @@ -# 基準測試 +# 基準測試 { #benchmarks } 由第三方機構 TechEmpower 的基準測試表明在 Uvicorn 下運行的 **FastAPI** 應用程式是 最快的 Python 可用框架之一，僅次於 Starlette 和 Uvicorn 本身（於 FastAPI 內部使用）。 但是在查看基準得分和對比時，請注意以下幾點。 -## 基準測試和速度 +## 基準測試和速度 { #benchmarks-and-speed } 當你查看基準測試時，時常會見到幾個不同類型的工具被同時進行測試。 diff --git a/docs/zh-hant/docs/how-to/index.md b/docs/zh-hant/docs/how-to/index.md index db740140d..6c9a8202c 100644 --- a/docs/zh-hant/docs/how-to/index.md +++ b/docs/zh-hant/docs/how-to/index.md @@ -1,4 +1,4 @@ -# 使用指南 - 範例集 +# 使用指南 - 範例集 { #how-to-recipes } 在這裡，你將會看到**不同主題**的範例或「如何使用」的指南。 diff --git a/docs/zh-hant/docs/learn/index.md b/docs/zh-hant/docs/learn/index.md index eb7d7096a..a6a8915c8 100644 --- a/docs/zh-hant/docs/learn/index.md +++ b/docs/zh-hant/docs/learn/index.md @@ -1,4 +1,4 @@ -# 學習 +# 學習 { #learn } 以下是學習 FastAPI 的入門介紹和教學。 diff --git a/docs/zh-hant/docs/resources/index.md b/docs/zh-hant/docs/resources/index.md index f4c70a3a0..cc6f59da5 100644 --- a/docs/zh-hant/docs/resources/index.md +++ b/docs/zh-hant/docs/resources/index.md @@ -1,3 +1,3 @@ -# 資源 +# 資源 { #resources } 額外的資源、外部連結、文章等。 ✈️ diff --git a/docs/zh-hant/docs/tutorial/query-param-models.md b/docs/zh-hant/docs/tutorial/query-param-models.md index 76ee74016..e36028199 100644 --- a/docs/zh-hant/docs/tutorial/query-param-models.md +++ b/docs/zh-hant/docs/tutorial/query-param-models.md @@ -1,4 +1,4 @@ -# 查詢參數模型 +# 查詢參數模型 { #query-parameter-models } 如果你有一組具有相關性的**查詢參數**，你可以建立一個 **Pydantic 模型**來聲明它們。 @@ -10,7 +10,7 @@ FastAPI 從 `0.115.0` 版本開始支援這個特性。🤓 /// -## 使用 Pydantic 模型的查詢參數 +## 使用 Pydantic 模型的查詢參數 { #query-parameters-with-a-pydantic-model } 在一個 **Pydantic 模型**中聲明你需要的**查詢參數**，然後將參數聲明為 `Query`： @@ -18,7 +18,7 @@ FastAPI 從 `0.115.0` 版本開始支援這個特性。🤓 **FastAPI** 將會從請求的**查詢參數**中**提取**出**每個欄位**的資料，並將其提供給你定義的 Pydantic 模型。 -## 查看文件 +## 查看文件 { #check-the-docs } 你可以在 `/docs` 頁面的 UI 中查看查詢參數： @@ -26,7 +26,7 @@ FastAPI 從 `0.115.0` 版本開始支援這個特性。🤓 -## 禁止額外的查詢參數 +## 禁止額外的查詢參數 { #forbid-extra-query-parameters } 在一些特殊的使用場景中（可能不是很常見），你可能希望**限制**你要收到的查詢參數。 @@ -57,7 +57,7 @@ https://example.com/items/?limit=10&tool=plumbus } ``` -## 總結 +## 總結 { #summary } 你可以使用 **Pydantic 模型**在 **FastAPI** 中聲明**查詢參數**。😎 diff --git a/docs/zh/docs/advanced/additional-status-codes.md b/docs/zh/docs/advanced/additional-status-codes.md index b048a2a17..921e73133 100644 --- a/docs/zh/docs/advanced/additional-status-codes.md +++ b/docs/zh/docs/advanced/additional-status-codes.md @@ -1,10 +1,10 @@ -# 额外的状态码 +# 额外的状态码 { #additional-status-codes } **FastAPI** 默认使用 `JSONResponse` 返回一个响应，将你的 *路径操作* 中的返回内容放到该 `JSONResponse` 中。 **FastAPI** 会自动使用默认的状态码或者使用你在 *路径操作* 中设置的状态码。 -## 额外的状态码 +## 额外的状态码 { #additional-status-codes_1 } 如果你想要返回主要状态码之外的状态码，你可以通过直接返回一个 `Response` 来实现，比如 `JSONResponse`，然后直接设置额外的状态码。 @@ -14,7 +14,7 @@ 要实现它，导入 `JSONResponse`，然后在其中直接返回你的内容，并将 `status_code` 设置为为你要的值。 -{* ../../docs_src/additional_status_codes/tutorial001.py hl[4,25] *} +{* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *} /// warning | 警告 @@ -34,7 +34,7 @@ FastAPI 不会用模型等对该响应进行序列化。 /// -## OpenAPI 和 API 文档 +## OpenAPI 和 API 文档 { #openapi-and-api-docs } 如果你直接返回额外的状态码和响应，它们不会包含在 OpenAPI 方案（API 文档）中，因为 FastAPI 没办法预先知道你要返回什么。 diff --git a/docs/zh/docs/advanced/async-tests.md b/docs/zh/docs/advanced/async-tests.md index b5ac15b5b..42e8fa1d3 100644 --- a/docs/zh/docs/advanced/async-tests.md +++ b/docs/zh/docs/advanced/async-tests.md @@ -1,4 +1,4 @@ -# 异步测试 +# 异步测试 { #async-tests } 您已经了解了如何使用 `TestClient` 测试 **FastAPI** 应用程序。但是到目前为止，您只了解了如何编写同步测试，而没有使用 `async` 异步函数。 @@ -6,11 +6,11 @@ 让我们看看如何才能实现这一点。 -## pytest.mark.anyio +## pytest.mark.anyio { #pytest-mark-anyio } 如果我们想在测试中调用异步函数，那么我们的测试函数必须是异步的。 AnyIO 为此提供了一个简洁的插件，它允许我们指定一些测试函数要异步调用。 -## HTTPX +## HTTPX { #httpx } 即使您的 **FastAPI** 应用程序使用普通的 `def` 函数而不是 `async def` ，它本质上仍是一个 `async` 异步应用程序。 @@ -18,7 +18,7 @@ `TestClient` 是基于 HTTPX 的。幸运的是，我们可以直接使用它来测试API。 -## 示例 +## 示例 { #example } 举个简单的例子，让我们来看一个[更大的应用](../tutorial/bigger-applications.md){.internal-link target=_blank}和[测试](../tutorial/testing.md){.internal-link target=_blank}中描述的类似文件结构： @@ -32,13 +32,13 @@ 文件 `main.py` 将包含: -{* ../../docs_src/async_tests/main.py *} +{* ../../docs_src/async_tests/app_a_py39/main.py *} 文件 `test_main.py` 将包含针对 `main.py` 的测试，现在它可能看起来如下： -{* ../../docs_src/async_tests/test_main.py *} +{* ../../docs_src/async_tests/app_a_py39/test_main.py *} -## 运行测试 +## 运行测试 { #run-it } 您可以通过以下方式照常运行测试： @@ -52,11 +52,11 @@ $ pytest -## 详细说明 +## 详细说明 { #in-detail } 这个标记 `@pytest.mark.anyio` 会告诉 pytest 该测试函数应该被异步调用： -{* ../../docs_src/async_tests/test_main.py hl[7] *} +{* ../../docs_src/async_tests/app_a_py39/test_main.py hl[7] *} /// tip @@ -66,7 +66,7 @@ $ pytest 我们现在可以使用应用程序创建一个 `AsyncClient` ，并使用 `await` 向其发送异步请求。 -{* ../../docs_src/async_tests/test_main.py hl[9:12] *} +{* ../../docs_src/async_tests/app_a_py39/test_main.py hl[9:12] *} 这相当于： @@ -88,7 +88,7 @@ response = client.get('/') /// -## 其他异步函数调用 +## 其他异步函数调用 { #other-asynchronous-function-calls } 由于测试函数现在是异步的，因此除了在测试中向 FastAPI 应用程序发送请求之外，您现在还可以调用（和使用 `await` 等待）其他 `async` 异步函数，就和您在代码中的其他任何地方调用它们的方法一样。 diff --git a/docs/zh/docs/advanced/middleware.md b/docs/zh/docs/advanced/middleware.md index 65e8c183f..c5656f90d 100644 --- a/docs/zh/docs/advanced/middleware.md +++ b/docs/zh/docs/advanced/middleware.md @@ -1,4 +1,4 @@ -# 高级中间件 +# 高级中间件 { #advanced-middleware } 用户指南介绍了如何为应用添加[自定义中间件](../tutorial/middleware.md){.internal-link target=_blank} 。 @@ -6,7 +6,7 @@ 本章学习如何使用其它中间件。 -## 添加 ASGI 中间件 +## 添加 ASGI 中间件 { #adding-asgi-middlewares } 因为 **FastAPI** 基于 Starlette，且执行 ASGI 规范，所以可以使用任意 ASGI 中间件。 @@ -39,7 +39,7 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") `app.add_middleware()` 的第一个参数是中间件的类，其它参数则是要传递给中间件的参数。 -## 集成中间件 +## 集成中间件 { #integrated-middlewares } **FastAPI** 为常见用例提供了一些中间件，下面介绍怎么使用这些中间件。 @@ -51,19 +51,19 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") /// -## `HTTPSRedirectMiddleware` +## `HTTPSRedirectMiddleware` { #httpsredirectmiddleware } 强制所有传入请求必须是 `https` 或 `wss`。 任何传向 `http` 或 `ws` 的请求都会被重定向至安全方案。 -{* ../../docs_src/advanced_middleware/tutorial001.py hl[2,6] *} +{* ../../docs_src/advanced_middleware/tutorial001_py39.py hl[2,6] *} -## `TrustedHostMiddleware` +## `TrustedHostMiddleware` { #trustedhostmiddleware } 强制所有传入请求都必须正确设置 `Host` 请求头，以防 HTTP 主机头攻击。 -{* ../../docs_src/advanced_middleware/tutorial002.py hl[2,6:8] *} +{* ../../docs_src/advanced_middleware/tutorial002_py39.py hl[2,6:8] *} 支持以下参数： @@ -71,19 +71,19 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") 如果传入的请求没有通过验证，则发送 `400` 响应。 -## `GZipMiddleware` +## `GZipMiddleware` { #gzipmiddleware } 处理 `Accept-Encoding` 请求头中包含 `gzip` 请求的 GZip 响应。 中间件会处理标准响应与流响应。 -{* ../../docs_src/advanced_middleware/tutorial003.py hl[2,6] *} +{* ../../docs_src/advanced_middleware/tutorial003_py39.py hl[2,6] *} 支持以下参数： * `minimum_size` - 小于最小字节的响应不使用 GZip。 默认值是 `500`。 -## 其它中间件 +## 其它中间件 { #other-middlewares } 除了上述中间件外，FastAPI 还支持其它ASGI 中间件。 diff --git a/docs/zh/docs/advanced/openapi-callbacks.md b/docs/zh/docs/advanced/openapi-callbacks.md index f021eb10a..6a0400ebe 100644 --- a/docs/zh/docs/advanced/openapi-callbacks.md +++ b/docs/zh/docs/advanced/openapi-callbacks.md @@ -1,4 +1,4 @@ -# OpenAPI 回调 +# OpenAPI 回调 { #openapi-callbacks } 您可以创建触发外部 API 请求的*路径操作* API，这个外部 API 可以是别人创建的，也可以是由您自己创建的。 @@ -6,7 +6,7 @@ API 应用调用外部 API 时的流程叫做**回调**。因为外部开发者 此时，我们需要存档外部 API 的*信息*，比如应该有哪些*路径操作*，返回什么样的请求体，应该返回哪种响应等。 -## 使用回调的应用 +## 使用回调的应用 { #an-app-with-callbacks } 示例如下。 @@ -23,7 +23,7 @@ API 的用户 （外部开发者）要在您的 API 内使用 POST 请求创建 * 把通知发送至 API 的用户（外部开发者） * 通过（从您的 API）发送 POST 请求至外部 API （即**回调**）来完成 -## 常规 **FastAPI** 应用 +## 常规 **FastAPI** 应用 { #the-normal-fastapi-app } 添加回调前，首先看下常规 API 应用是什么样子。 @@ -31,17 +31,17 @@ API 的用户 （外部开发者）要在您的 API 内使用 POST 请求创建 这部分代码很常规，您对绝大多数代码应该都比较熟悉了： -{* ../../docs_src/openapi_callbacks/tutorial001.py hl[10:14,37:54] *} +{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[7:11,34:51] *} /// tip | 提示 -`callback_url` 查询参数使用 Pydantic 的 URL 类型。 +`callback_url` 查询参数使用 Pydantic 的 URL 类型。 /// 此处唯一比较新的内容是*路径操作装饰器*中的 `callbacks=invoices_callback_router.routes` 参数，下文介绍。 -## 存档回调 +## 存档回调 { #documenting-the-callback } 实际的回调代码高度依赖于您自己的 API 应用。 @@ -51,7 +51,7 @@ API 的用户 （外部开发者）要在您的 API 内使用 POST 请求创建 ```Python callback_url = "https://example.com/api/v1/invoices/events/" -requests.post(callback_url, json={"description": "Invoice paid", "paid": True}) +httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) ``` 但回调最重要的部分可能是，根据 API 要发送给回调请求体的数据等内容，确保您的 API 用户（外部开发者）正确地实现*外部 API*。 @@ -66,11 +66,11 @@ requests.post(callback_url, json={"description": "Invoice paid", "paid": True}) 实际的回调只是 HTTP 请求。 -实现回调时，要使用 HTTPX 或 Requests。 +实现回调时，要使用 HTTPX 或 Requests。 /// -## 编写回调文档代码 +## 编写回调文档代码 { #write-the-callback-documentation-code } 应用不执行这部分代码，只是用它来*记录 外部 API* 。 @@ -86,13 +86,13 @@ requests.post(callback_url, json={"description": "Invoice paid", "paid": True}) /// -### 创建回调的 `APIRouter` +### 创建回调的 `APIRouter` { #create-a-callback-apirouter } 首先，新建包含一些用于回调的 `APIRouter`。 -{* ../../docs_src/openapi_callbacks/tutorial001.py hl[5,26] *} +{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[1,23] *} -### 创建回调*路径操作* +### 创建回调*路径操作* { #create-the-callback-path-operation } 创建回调*路径操作*也使用之前创建的 `APIRouter`。 @@ -101,16 +101,16 @@ requests.post(callback_url, json={"description": "Invoice paid", "paid": True}) * 声明要接收的请求体，例如，`body: InvoiceEvent` * 还要声明要返回的响应，例如，`response_model=InvoiceEventReceived` -{* ../../docs_src/openapi_callbacks/tutorial001.py hl[17:19,22:23,29:33] *} +{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[14:16,19:20,26:30] *} 回调*路径操作*与常规*路径操作*有两点主要区别： * 它不需要任何实际的代码，因为应用不会调用这段代码。它只是用于存档*外部 API*。因此，函数的内容只需要 `pass` 就可以了 -* *路径*可以包含 OpenAPI 3 表达式（详见下文），可以使用带参数的变量，以及发送至您的 API 的原始请求的部分 +* *路径*可以包含 OpenAPI 3 表达式（详见下文），可以使用带参数的变量，以及发送至您的 API 的原始请求的部分 -### 回调路径表达式 +### 回调路径表达式 { #the-callback-path-expression } -回调*路径*支持包含发送给您的 API 的原始请求的部分的 OpenAPI 3 表达式。 +回调*路径*支持包含发送给您的 API 的原始请求的部分的 OpenAPI 3 表达式。 本例中是**字符串**： @@ -163,13 +163,13 @@ JSON 请求体包含如下内容： /// -### 添加回调路由 +### 添加回调路由 { #add-the-callback-router } 至此，在上文创建的回调路由里就包含了*回调路径操作*（外部开发者要在外部 API 中实现）。 现在使用 API *路径操作装饰器*的参数 `callbacks`，从回调路由传递属性 `.routes`（实际上只是路由/路径操作的**列表**）： -{* ../../docs_src/openapi_callbacks/tutorial001.py hl[36] *} +{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *} /// tip | 提示 @@ -177,7 +177,7 @@ JSON 请求体包含如下内容： /// -### 查看文档 +### 查看文档 { #check-the-docs } 现在，使用 Uvicorn 启动应用，打开 http://127.0.0.1:8000/docs。 diff --git a/docs/zh/docs/advanced/openapi-webhooks.md b/docs/zh/docs/advanced/openapi-webhooks.md index 92ae8db15..7fe68573e 100644 --- a/docs/zh/docs/advanced/openapi-webhooks.md +++ b/docs/zh/docs/advanced/openapi-webhooks.md @@ -1,4 +1,4 @@ -# OpenAPI 网络钩子 +# OpenAPI 网络钩子 { #openapi-webhooks } 有些情况下，您可能想告诉您的 API **用户**，您的应用程序可以携带一些数据调用*他们的*应用程序（给它们发送请求），通常是为了**通知**某种**事件**。 @@ -6,7 +6,7 @@ 这通常被称为**网络钩子**（Webhook）。 -## 使用网络钩子的步骤 +## 使用网络钩子的步骤 { #webhooks-steps } 通常的过程是**您**在代码中**定义**要发送的消息，即**请求的主体**。 @@ -16,7 +16,7 @@ 所有关于注册网络钩子的 URL 的**逻辑**以及发送这些请求的实际代码都由您决定。您可以在**自己的代码**中以任何想要的方式来编写它。 -## 使用 `FastAPI` 和 OpenAPI 文档化网络钩子 +## 使用 `FastAPI` 和 OpenAPI 文档化网络钩子 { #documenting-webhooks-with-fastapi-and-openapi } 使用 **FastAPI**，您可以利用 OpenAPI 来自定义这些网络钩子的名称、您的应用可以发送的 HTTP 操作类型（例如 `POST`、`PUT` 等）以及您的应用将发送的**请求体**。 @@ -28,11 +28,11 @@ /// -## 带有网络钩子的应用程序 +## 带有网络钩子的应用程序 { #an-app-with-webhooks } 当您创建一个 **FastAPI** 应用程序时，有一个 `webhooks` 属性可以用来定义网络钩子，方式与您定义*路径操作*的时候相同，例如使用 `@app.webhooks.post()` 。 -{* ../../docs_src/openapi_webhooks/tutorial001.py hl[9:13,36:53] *} +{* ../../docs_src/openapi_webhooks/tutorial001_py39.py hl[9:13,36:53] *} 您定义的网络钩子将被包含在 `OpenAPI` 的架构中，并出现在自动生成的**文档 UI** 中。 @@ -46,7 +46,7 @@ 这是因为我们预计**您的用户**会以其他方式（例如通过网页仪表板）来定义他们希望接收网络钩子的请求的实际 **URL 路径**。 -### 查看文档 +### 查看文档 { #check-the-docs } 现在您可以启动您的应用程序并访问 http://127.0.0.1:8000/docs. diff --git a/docs/zh/docs/advanced/response-change-status-code.md b/docs/zh/docs/advanced/response-change-status-code.md index cc1f2a73e..baf79356c 100644 --- a/docs/zh/docs/advanced/response-change-status-code.md +++ b/docs/zh/docs/advanced/response-change-status-code.md @@ -1,10 +1,10 @@ -# 响应 - 更改状态码 +# 响应 - 更改状态码 { #response-change-status-code } 你可能之前已经了解到，你可以设置默认的[响应状态码](../tutorial/response-status-code.md){.internal-link target=_blank}。 但在某些情况下，你需要返回一个不同于默认值的状态码。 -## 使用场景 +## 使用场景 { #use-case } 例如，假设你想默认返回一个HTTP状态码为“OK”`200`。 @@ -14,13 +14,13 @@ 对于这些情况，你可以使用一个`Response`参数。 -## 使用 `Response` 参数 +## 使用 `Response` 参数 { #use-a-response-parameter } 你可以在你的*路径操作函数*中声明一个`Response`类型的参数（就像你可以为cookies和头部做的那样）。 然后你可以在这个*临时*响应对象中设置`status_code`。 -{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *} +{* ../../docs_src/response_change_status_code/tutorial001_py39.py hl[1,9,12] *} 然后你可以像平常一样返回任何你需要的对象（例如一个`dict`或者一个数据库模型）。如果你声明了一个`response_model`，它仍然会被用来过滤和转换你返回的对象。 diff --git a/docs/zh/docs/advanced/response-cookies.md b/docs/zh/docs/advanced/response-cookies.md index d5f2fe6fc..e42baaaeb 100644 --- a/docs/zh/docs/advanced/response-cookies.md +++ b/docs/zh/docs/advanced/response-cookies.md @@ -1,10 +1,10 @@ -# 响应Cookies +# 响应Cookies { #response-cookies } -## 使用 `Response` 参数 +## 使用 `Response` 参数 { #use-a-response-parameter } 你可以在 *路径函数* 中定义一个类型为 `Response`的参数，这样你就可以在这个临时响应对象中设置cookie了。 -{* ../../docs_src/response_cookies/tutorial002.py hl[1,8:9] *} +{* ../../docs_src/response_cookies/tutorial002_py39.py hl[1, 8:9] *} 而且你还可以根据你的需要响应不同的对象，比如常用的 `dict`，数据库model等。 @@ -14,7 +14,7 @@ 你也可以在depend中定义`Response`参数，并设置cookie和header。 -## 直接响应 `Response` +## 直接响应 `Response` { #return-a-response-directly } 你还可以在直接响应`Response`时直接创建cookies。 @@ -22,7 +22,7 @@ 然后设置Cookies，并返回： -{* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *} +{* ../../docs_src/response_cookies/tutorial001_py39.py hl[10:12] *} /// tip @@ -34,7 +34,7 @@ /// -### 更多信息 +### 更多信息 { #more-info } /// note | 技术细节 diff --git a/docs/zh/docs/advanced/response-directly.md b/docs/zh/docs/advanced/response-directly.md index 4d9cd53f2..8fce3843a 100644 --- a/docs/zh/docs/advanced/response-directly.md +++ b/docs/zh/docs/advanced/response-directly.md @@ -1,4 +1,4 @@ -# 直接返回响应 +# 直接返回响应 { #return-a-response-directly } 当你创建一个 **FastAPI** *路径操作* 时，你可以正常返回以下任意一种数据：`dict`，`list`，Pydantic 模型，数据库模型等等。 @@ -10,7 +10,7 @@ 直接返回响应可能会有用处，比如返回自定义的响应头和 cookies。 -## 返回 `Response` +## 返回 `Response` { #return-a-response } 事实上，你可以返回任意 `Response` 或者任意 `Response` 的子类。 @@ -26,7 +26,7 @@ 这种特性给你极大的可扩展性。你可以返回任何数据类型，重写任何数据声明或者校验，等等。 -## 在 `Response` 中使用 `jsonable_encoder` +## 在 `Response` 中使用 `jsonable_encoder` { #using-the-jsonable-encoder-in-a-response } 由于 **FastAPI** 并未对你返回的 `Response` 做任何改变，你必须确保你已经准备好响应内容。 @@ -35,7 +35,7 @@ 对于这些情况，在将数据传递给响应之前，你可以使用 `jsonable_encoder` 来转换你的数据。 -{* ../../docs_src/response_directly/tutorial001.py hl[4,6,20,21] *} +{* ../../docs_src/response_directly/tutorial001_py310.py hl[5:6,20:21] *} /// note | 技术细节 @@ -45,7 +45,7 @@ /// -## 返回自定义 `Response` +## 返回自定义 `Response` { #returning-a-custom-response } 上面的例子展示了需要的所有部分，但还不够实用，因为你本可以只是直接返回 `item`，而**FastAPI** 默认帮你把这个 `item` 放到 `JSONResponse` 中，又默认将其转换成了 `dict`等等。 @@ -55,9 +55,9 @@ 你可以把你的 XML 内容放到一个字符串中，放到一个 `Response` 中，然后返回。 -{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *} +{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *} -## 说明 +## 说明 { #notes } 当你直接返回 `Response` 时，它的数据既没有校验，又不会进行转换（序列化），也不会自动生成文档。 diff --git a/docs/zh/docs/advanced/security/http-basic-auth.md b/docs/zh/docs/advanced/security/http-basic-auth.md index 599429f9d..7601bf979 100644 --- a/docs/zh/docs/advanced/security/http-basic-auth.md +++ b/docs/zh/docs/advanced/security/http-basic-auth.md @@ -1,4 +1,4 @@ -# HTTP 基础授权 +# HTTP 基础授权 { #http-basic-auth } 最简单的用例是使用 HTTP 基础授权（HTTP Basic Auth）。 @@ -12,7 +12,7 @@ HTTP 基础授权让浏览器显示内置的用户名与密码提示。 输入用户名与密码后，浏览器会把它们自动发送至请求头。 -## 简单的 HTTP 基础授权 +## 简单的 HTTP 基础授权 { #simple-http-basic-auth } * 导入 `HTTPBasic` 与 `HTTPBasicCredentials` * 使用 `HTTPBasic` 创建**安全概图** @@ -26,7 +26,7 @@ HTTP 基础授权让浏览器显示内置的用户名与密码提示。 -## 检查用户名 +## 检查用户名 { #check-the-username } 以下是更完整的示例。 @@ -52,7 +52,7 @@ if not (credentials.username == "stanleyjobson") or not (credentials.password == 但使用 `secrets.compare_digest()`，可以防御**时差攻击**，更加安全。 -### 时差攻击 +### 时差攻击 { #timing-attacks } 什么是**时差攻击**？ @@ -80,19 +80,19 @@ if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish": 此时，Python 要对比 `stanleyjobsox` 与 `stanleyjobson` 中的 `stanleyjobso`，才能知道这两个字符串不一样。因此会多花费几微秒来返回**错误的用户或密码**。 -#### 反应时间对攻击者的帮助 +#### 反应时间对攻击者的帮助 { #the-time-to-answer-helps-the-attackers } 通过服务器花费了更多微秒才发送**错误的用户或密码**响应，攻击者会知道猜对了一些内容，起码开头字母是正确的。 然后，他们就可以放弃 `johndoe`，再用类似 `stanleyjobsox` 的内容进行尝试。 -#### **专业**攻击 +#### **专业**攻击 { #a-professional-attack } 当然，攻击者不用手动操作，而是编写每秒能执行成千上万次测试的攻击程序，每次都会找到更多正确字符。 但是，在您的应用的**帮助**下，攻击者利用时间差，就能在几分钟或几小时内，以这种方式猜出正确的用户名和密码。 -#### 使用 `secrets.compare_digest()` 修补 +#### 使用 `secrets.compare_digest()` 修补 { #fix-it-with-secrets-compare-digest } 在此，代码中使用了 `secrets.compare_digest()`。 @@ -100,7 +100,7 @@ if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish": 在代码中使用 `secrets.compare_digest()` ，就可以安全地防御全面攻击了。 -### 返回错误 +### 返回错误 { #return-the-error } 检测到凭证不正确后，返回 `HTTPException` 及状态码 401（与无凭证时返回的内容一样），并添加请求头 `WWW-Authenticate`，让浏览器再次显示登录提示： diff --git a/docs/zh/docs/advanced/security/index.md b/docs/zh/docs/advanced/security/index.md index 267e7ced7..01f456157 100644 --- a/docs/zh/docs/advanced/security/index.md +++ b/docs/zh/docs/advanced/security/index.md @@ -1,6 +1,6 @@ -# 高级安全 +# 高级安全 { #advanced-security } -## 附加特性 +## 附加特性 { #additional-features } 除 [教程 - 用户指南: 安全性](../../tutorial/security/index.md){.internal-link target=_blank} 中涵盖的功能之外，还有一些额外的功能来处理安全性. @@ -12,7 +12,7 @@ /// -## 先阅读教程 +## 先阅读教程 { #read-the-tutorial-first } 接下来的部分假设你已经阅读了主要的 [教程 - 用户指南: 安全性](../../tutorial/security/index.md){.internal-link target=_blank}. diff --git a/docs/zh/docs/advanced/security/oauth2-scopes.md b/docs/zh/docs/advanced/security/oauth2-scopes.md index 784c38490..0ef738f92 100644 --- a/docs/zh/docs/advanced/security/oauth2-scopes.md +++ b/docs/zh/docs/advanced/security/oauth2-scopes.md @@ -1,4 +1,4 @@ -# OAuth2 作用域 +# OAuth2 作用域 { #oauth2-scopes } **FastAPI** 无缝集成 OAuth2 作用域（`Scopes`），可以直接使用。 @@ -26,7 +26,7 @@ OAuth2 作用域不是必需的，没有它，您也可以处理身份验证与 /// -## OAuth2 作用域与 OpenAPI +## OAuth2 作用域与 OpenAPI { #oauth2-scopes-and-openapi } OAuth2 规范的**作用域**是由空格分割的字符串组成的列表。 @@ -58,21 +58,21 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 /// -## 全局纵览 +## 全局纵览 { #global-view } 首先，快速浏览一下以下代码与**用户指南**中 [OAuth2 实现密码哈希与 Bearer JWT 令牌验证](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}一章中代码的区别。以下代码使用 OAuth2 作用域： -{* ../../docs_src/security/tutorial005.py hl[2,4,8,12,46,64,105,107:115,121:124,128:134,139,153] *} +{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *} 下面，我们逐步说明修改的代码内容。 -## OAuth2 安全方案 +## OAuth2 安全方案 { #oauth2-security-scheme } 第一个修改的地方是，使用两个作用域 `me` 和 `items ` 声明 OAuth2 安全方案。 `scopes` 参数接收**字典**，键是作用域、值是作用域的描述： -{* ../../docs_src/security/tutorial005.py hl[62:65] *} +{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *} 因为声明了作用域，所以登录或授权时会在 API 文档中显示。 @@ -82,7 +82,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 -## JWT 令牌作用域 +## JWT 令牌作用域 { #jwt-token-with-scopes } 现在，修改令牌*路径操作*，返回请求的作用域。 @@ -98,9 +98,9 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 /// -{* ../../docs_src/security/tutorial005.py hl[153] *} +{* ../../docs_src/security/tutorial005_an_py310.py hl[157] *} -## 在*路径操作*与依赖项中声明作用域 +## 在*路径操作*与依赖项中声明作用域 { #declare-scopes-in-path-operations-and-dependencies } 接下来，为*路径操作* `/users/me/items/` 声明作用域 `items`。 @@ -124,7 +124,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 /// -{* ../../docs_src/security/tutorial005.py hl[4,139,166] *} +{* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *} /// info | 技术细节 @@ -136,7 +136,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 /// -## 使用 `SecurityScopes` +## 使用 `SecurityScopes` { #use-securityscopes } 修改依赖项 `get_current_user`。 @@ -150,9 +150,9 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 `SecuriScopes` 类与 `Request` 类似（`Request` 用于直接提取请求对象）。 -{* ../../docs_src/security/tutorial005.py hl[8,105] *} +{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *} -## 使用 `scopes` +## 使用 `scopes` { #use-the-scopes } 参数 `security_scopes` 的类型是 `SecurityScopes`。 @@ -164,9 +164,9 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 该异常包含了作用域所需的（如有），以空格分割的字符串（使用 `scope_str`）。该字符串要放到包含作用域的 `WWW-Authenticate` 请求头中（这也是规范的要求）。 -{* ../../docs_src/security/tutorial005.py hl[105,107:115] *} +{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *} -## 校验 `username` 与数据形状 +## 校验 `username` 与数据形状 { #verify-the-username-and-data-shape } 我们可以校验是否获取了 `username`，并抽取作用域。 @@ -180,17 +180,17 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 还可以使用用户名验证用户，如果没有用户，也会触发之前创建的异常。 -{* ../../docs_src/security/tutorial005.py hl[46,116:127] *} +{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:129] *} -## 校验 `scopes` +## 校验 `scopes` { #verify-the-scopes } 接下来，校验所有依赖项和依赖要素（包括*路径操作*）所需的作用域。这些作用域包含在令牌的 `scopes` 里，如果不在其中就会触发 `HTTPException` 异常。 为此，要使用包含所有作用域**字符串列表**的 `security_scopes.scopes`， 。 -{* ../../docs_src/security/tutorial005.py hl[128:134] *} +{* ../../docs_src/security/tutorial005_an_py310.py hl[130:136] *} -## 依赖项树与作用域 +## 依赖项树与作用域 { #dependency-tree-and-scopes } 再次查看这个依赖项树与作用域。 @@ -223,7 +223,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 /// -## `SecurityScopes` 的更多细节 +## `SecurityScopes` 的更多细节 { #more-details-about-securityscopes } 您可以任何位置或多个位置使用 `SecurityScopes`，不一定非得在**根**依赖项中使用。 @@ -233,7 +233,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 它们会为每个*路径操作*进行单独检查。 -## 查看文档 +## 查看文档 { #check-it } 打开 API 文档，进行身份验证，并指定要授权的作用域。 @@ -245,7 +245,7 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 这就是通过用户提供的令牌使用第三方应用访问这些*路径操作*时会发生的情况，具体怎样取决于用户授予第三方应用的权限。 -## 关于第三方集成 +## 关于第三方集成 { #about-third-party-integrations } 本例使用 OAuth2 **密码**流。 @@ -269,6 +269,6 @@ OAuth2 中，**作用域**只是声明特定权限的字符串。 **FastAPI** 的 `fastapi.security.oauth2` 里包含了所有 OAuth2 身份验证流工具。 -## 装饰器 `dependencies` 中的 `Security` +## 装饰器 `dependencies` 中的 `Security` { #security-in-decorator-dependencies } 同样，您可以在装饰器的 `dependencies` 参数中定义 `Depends` 列表，（详见[路径操作装饰器依赖项](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank})），也可以把 `scopes` 与 `Security` 一起使用。 diff --git a/docs/zh/docs/advanced/sub-applications.md b/docs/zh/docs/advanced/sub-applications.md index c42be2849..223060df8 100644 --- a/docs/zh/docs/advanced/sub-applications.md +++ b/docs/zh/docs/advanced/sub-applications.md @@ -1,41 +1,41 @@ -# 子应用 - 挂载 +# 子应用 - 挂载 { #sub-applications-mounts } 如果需要两个独立的 FastAPI 应用，拥有各自独立的 OpenAPI 与文档，则需设置一个主应用，并**挂载**一个（或多个）子应用。 -## 挂载 **FastAPI** 应用 +## 挂载 **FastAPI** 应用 { #mounting-a-fastapi-application } **挂载**是指在特定路径中添加完全**独立**的应用，然后在该路径下使用*路径操作*声明的子应用处理所有事务。 -### 顶层应用 +### 顶层应用 { #top-level-application } 首先，创建主（顶层）**FastAPI** 应用及其*路径操作*： -{* ../../docs_src/sub_applications/tutorial001.py hl[3,6:8] *} +{* ../../docs_src/sub_applications/tutorial001_py39.py hl[3, 6:8] *} -### 子应用 +### 子应用 { #sub-application } 接下来，创建子应用及其*路径操作*。 子应用只是另一个标准 FastAPI 应用，但这个应用是被**挂载**的应用： -{* ../../docs_src/sub_applications/tutorial001.py hl[11,14:16] *} +{* ../../docs_src/sub_applications/tutorial001_py39.py hl[11, 14:16] *} -### 挂载子应用 +### 挂载子应用 { #mount-the-sub-application } 在顶层应用 `app` 中，挂载子应用 `subapi`。 本例的子应用挂载在 `/subapi` 路径下： -{* ../../docs_src/sub_applications/tutorial001.py hl[11,19] *} +{* ../../docs_src/sub_applications/tutorial001_py39.py hl[11, 19] *} -### 查看文档 +### 查看文档 { #check-the-automatic-api-docs } 如果主文件是 `main.py`，则用以下 `uvicorn` 命令运行主应用：
```console -$ uvicorn main:app --reload +$ fastapi dev main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -56,7 +56,7 @@ $ uvicorn main:app --reload 两个用户界面都可以正常运行，因为浏览器能够与每个指定的应用或子应用会话。 -### 技术细节：`root_path` +### 技术细节：`root_path` { #technical-details-root-path } 以上述方式挂载子应用时，FastAPI 使用 ASGI 规范中的 `root_path` 机制处理挂载子应用路径之间的通信。 diff --git a/docs/zh/docs/advanced/testing-dependencies.md b/docs/zh/docs/advanced/testing-dependencies.md index 8d53a6d49..54d5e8520 100644 --- a/docs/zh/docs/advanced/testing-dependencies.md +++ b/docs/zh/docs/advanced/testing-dependencies.md @@ -1,6 +1,6 @@ -# 测试依赖项 +# 测试依赖项 { #testing-dependencies-with-overrides } -## 测试时覆盖依赖项 +## 测试时覆盖依赖项 { #overriding-dependencies-during-testing } 有些场景下，您可能需要在测试时覆盖依赖项。 @@ -8,7 +8,7 @@ 反之，要在测试期间（或只是为某些特定测试）提供只用于测试的依赖项，并使用此依赖项的值替换原有依赖项的值。 -### 用例：外部服务 +### 用例：外部服务 { #use-cases-external-service } 常见实例是调用外部第三方身份验证应用。 @@ -20,7 +20,7 @@ 此时，最好覆盖调用外部验证应用的依赖项，使用返回模拟测试用户的自定义依赖项就可以了。 -### 使用 `app.dependency_overrides` 属性 +### 使用 `app.dependency_overrides` 属性 { #use-the-app-dependency-overrides-attribute } 对于这些用例，**FastAPI** 应用支持 `app.dependency_overrides` 属性，该属性就是**字典**。 diff --git a/docs/zh/docs/advanced/using-request-directly.md b/docs/zh/docs/advanced/using-request-directly.md index a9658c034..971c5b4cc 100644 --- a/docs/zh/docs/advanced/using-request-directly.md +++ b/docs/zh/docs/advanced/using-request-directly.md @@ -1,4 +1,4 @@ -# 直接使用请求 +# 直接使用请求 { #using-the-request-directly } 至此，我们已经使用多种类型声明了请求的各种组件。 @@ -13,7 +13,7 @@ 但有时，我们也需要直接访问 `Request` 对象。 -## `Request` 对象的细节 +## `Request` 对象的细节 { #details-about-the-request-object } 实际上，**FastAPI** 的底层是 **Starlette**，**FastAPI** 只不过是在 **Starlette** 顶层提供了一些工具，所以能直接使用 Starlette 的 `Request` 对象。 @@ -23,13 +23,13 @@ 但在某些特定情况下，还是需要提取 `Request` 对象。 -## 直接使用 `Request` 对象 +## 直接使用 `Request` 对象 { #use-the-request-object-directly } 假设要在*路径操作函数*中获取客户端 IP 地址和主机。 此时，需要直接访问请求。 -{* ../../docs_src/using_request_directly/tutorial001.py hl[1,7:8] *} +{* ../../docs_src/using_request_directly/tutorial001_py39.py hl[1,7:8] *} 把*路径操作函数*的参数类型声明为 `Request`，**FastAPI** 就能把 `Request` 传递到参数里。 @@ -43,7 +43,7 @@ /// -## `Request` 文档 +## `Request` 文档 { #request-documentation } 更多细节详见 Starlette 官档 - `Request` 对象。 diff --git a/docs/zh/docs/advanced/wsgi.md b/docs/zh/docs/advanced/wsgi.md index 363025a34..0c6878547 100644 --- a/docs/zh/docs/advanced/wsgi.md +++ b/docs/zh/docs/advanced/wsgi.md @@ -1,10 +1,10 @@ -# 包含 WSGI - Flask，Django，其它 +# 包含 WSGI - Flask，Django，其它 { #including-wsgi-flask-django-others } 您可以挂载多个 WSGI 应用，正如您在 [Sub Applications - Mounts](sub-applications.md){.internal-link target=_blank}, [Behind a Proxy](behind-a-proxy.md){.internal-link target=_blank} 中所看到的那样。 为此, 您可以使用 `WSGIMiddleware` 来包装你的 WSGI 应用，如：Flask，Django，等等。 -## 使用 `WSGIMiddleware` +## 使用 `WSGIMiddleware` { #using-wsgimiddleware } 您需要导入 `WSGIMiddleware`。 @@ -12,9 +12,9 @@ 之后将其挂载到某一个路径下。 -{* ../../docs_src/wsgi/tutorial001.py hl[2:3,22] *} +{* ../../docs_src/wsgi/tutorial001_py39.py hl[2:3,3] *} -## 检查 +## 检查 { #check-it } 现在，所有定义在 `/v1/` 路径下的请求将会被 Flask 应用处理。 diff --git a/docs/zh/docs/async.md b/docs/zh/docs/async.md index 4028ed51a..ab982adf1 100644 --- a/docs/zh/docs/async.md +++ b/docs/zh/docs/async.md @@ -1,8 +1,8 @@ -# 并发 async / await +# 并发 async / await { #concurrency-and-async-await } 有关路径操作函数的 `async def` 语法以及异步代码、并发和并行的一些背景知识。 -## 赶时间吗？ +## 赶时间吗？ { #in-a-hurry } TL;DR: @@ -54,7 +54,7 @@ def results(): 但是，通过遵循上述步骤，它将能够进行一些性能优化。 -## 技术细节 +## 技术细节 { #technical-details } Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 `await` 语法的东西来写**”异步代码“**。 @@ -64,7 +64,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 * **`async` 和 `await`** * **协程** -## 异步代码 +## 异步代码 { #asynchronous-code } 异步代码仅仅意味着编程语言 💬 有办法告诉计算机/程序 🤖 在代码中的某个点，它 🤖 将不得不等待在某些地方完成一些事情。让我们假设一些事情被称为 "慢文件"📝. @@ -93,7 +93,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 对于"同步"（与"异步"相反），他们通常也使用"顺序"一词，因为计算机程序在切换到另一个任务之前是按顺序执行所有步骤，即使这些步骤涉及到等待。 -### 并发与汉堡 +### 并发与汉堡 { #concurrency-and-burgers } 上述异步代码的思想有时也被称为“并发”，它不同于“并行”。 @@ -103,7 +103,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 要了解差异，请想象以下关于汉堡的故事： -### 并发汉堡 +### 并发汉堡 { #concurrent-burgers } 你和你的恋人一起去快餐店，你排队在后面，收银员从你前面的人接单。😍 @@ -163,7 +163,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 然后你去柜台🔀， 到现在初始任务已经完成⏯， 拿起汉堡，说声谢谢，然后把它们送到桌上。这就完成了与计数器交互的步骤/任务⏹. 这反过来又产生了一项新任务，即"吃汉堡"🔀 ⏯， 上一个"拿汉堡"的任务已经结束了⏹. -### 并行汉堡 +### 并行汉堡 { #parallel-burgers } 现在让我们假设不是"并发汉堡"，而是"并行汉堡"。 @@ -233,7 +233,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 你可不会想带你的恋人 😍 和你一起去银行办事🏦. -### 汉堡结论 +### 汉堡结论 { #burger-conclusion } 在"你与恋人一起吃汉堡"的这个场景中，因为有很多人在等待🕙， 使用并发系统更有意义⏸🔀⏯. @@ -253,7 +253,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和 你可以同时拥有并行性和异步性，你可以获得比大多数经过测试的 NodeJS 框架更高的性能，并且与 Go 不相上下， Go 是一种更接近于 C 的编译语言（全部归功于 Starlette）。 -### 并发比并行好吗？ +### 并发比并行好吗？ { #is-concurrency-better-than-parallelism } 不！这不是故事的本意。 @@ -290,7 +290,7 @@ CPU 密集型操作的常见示例是需要复杂的数学处理。 * **机器学习**: 它通常需要大量的"矩阵"和"向量"乘法。想象一个包含数字的巨大电子表格，并同时将所有数字相乘； * **深度学习**: 这是机器学习的一个子领域，同样适用。只是没有一个数字的电子表格可以相乘，而是一个庞大的数字集合，在很多情况下，你需要使用一个特殊的处理器来构建和使用这些模型。 -### 并发 + 并行: Web + 机器学习 +### 并发 + 并行: Web + 机器学习 { #concurrency-parallelism-web-machine-learning } 使用 **FastAPI**，你可以利用 Web 开发中常见的并发机制的优势（NodeJS 的主要吸引力）。 @@ -300,7 +300,7 @@ CPU 密集型操作的常见示例是需要复杂的数学处理。 了解如何在生产环境中实现这种并行性，可查看此文 [Deployment](deployment/index.md){.internal-link target=_blank}。 -## `async` 和 `await` +## `async` 和 `await` { #async-and-await } 现代版本的 Python 有一种非常直观的方式来定义异步代码。这使它看起来就像正常的"顺序"代码，并在适当的时候"等待"。 @@ -349,7 +349,7 @@ async def read_burgers(): return burgers ``` -### 更多技术细节 +### 更多技术细节 { #more-technical-details } 你可能已经注意到，`await` 只能在 `async def` 定义的函数内部使用。 @@ -361,7 +361,7 @@ async def read_burgers(): 但如果你想在没有 FastAPI 的情况下使用 `async` / `await`，则可以这样做。 -### 编写自己的异步代码 +### 编写自己的异步代码 { #write-your-own-async-code } Starlette （和 **FastAPI**） 是基于 AnyIO 实现的，这使得它们可以兼容 Python 的标准库 asyncio 和 Trio。 @@ -371,7 +371,7 @@ Starlette （和 **FastAPI**） 是基于 Asyncer。如果你有**结合使用异步代码和常规**（阻塞/同步）代码的需求，这个库会特别有用。 -### 其他形式的异步代码 +### 其他形式的异步代码 { #other-forms-of-asynchronous-code } 这种使用 `async` 和 `await` 的风格在语言中相对较新。 @@ -385,13 +385,13 @@ Starlette （和 **FastAPI**） 是基于 I/O 的代码。 -在这两种情况下，与你之前的框架相比，**FastAPI** 可能[仍然很快](index.md#_11){.internal-link target=_blank}。 +在这两种情况下，与你之前的框架相比，**FastAPI** 可能[仍然很快](index.md#performance){.internal-link target=_blank}。 -### 依赖 +### 依赖 { #dependencies } 这同样适用于[依赖](tutorial/dependencies/index.md){.internal-link target=_blank}。如果一个依赖是标准的 `def` 函数而不是 `async def`，它将被运行在外部线程池中。 -### 子依赖 +### 子依赖 { #sub-dependencies } 你可以拥有多个相互依赖的依赖以及[子依赖](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank} （作为函数的参数），它们中的一些可能是通过 `async def` 声明，也可能是通过 `def` 声明。它们仍然可以正常工作，这些通过 `def` 声明的函数将会在外部线程中调用（来自线程池），而不是"被等待"。 -### 其他函数 +### 其他函数 { #other-utility-functions } 你可直接调用通过 `def` 或 `async def` 创建的任何其他函数，FastAPI 不会影响你调用它们的方式。 @@ -441,4 +441,4 @@ Starlette （和 **FastAPI**） 是基于 赶时间吗？. +否则，你最好应该遵守的指导原则赶时间吗？. diff --git a/docs/zh/docs/deployment/concepts.md b/docs/zh/docs/deployment/concepts.md index f7208da7c..9ea6f7437 100644 --- a/docs/zh/docs/deployment/concepts.md +++ b/docs/zh/docs/deployment/concepts.md @@ -1,4 +1,4 @@ -# 部署概念 +# 部署概念 { #deployments-concepts } 在部署 **FastAPI** 应用程序或任何类型的 Web API 时，有几个概念值得了解，通过掌握这些概念您可以找到**最合适的**方法来**部署您的应用程序**。 @@ -23,7 +23,7 @@ 但现在，让我们仔细看一下这些重要的**概念**。 这些概念也适用于任何其他类型的 Web API。 💡 -## 安全性 - HTTPS +## 安全性 - HTTPS { #security-https } 在[上一章有关 HTTPS](https.md){.internal-link target=_blank} 中，我们了解了 HTTPS 如何为您的 API 提供加密。 @@ -32,7 +32,7 @@ 并且必须有某个东西负责**更新 HTTPS 证书**，它可以是相同的组件，也可以是不同的组件。 -### HTTPS 示例工具 +### HTTPS 示例工具 { #example-tools-for-https } 您可以用作 TLS 终止代理的一些工具包括： @@ -56,11 +56,11 @@ 接下来要考虑的概念都是关于运行实际 API 的程序（例如 Uvicorn）。 -## 程序和进程 +## 程序和进程 { #program-and-process } 我们将讨论很多关于正在运行的“**进程**”的内容，因此弄清楚它的含义以及与“**程序**”这个词有什么区别是很有用的。 -### 什么是程序 +### 什么是程序 { #what-is-a-program } **程序**这个词通常用来描述很多东西： @@ -68,7 +68,7 @@ * 操作系统可以**执行**的**文件**，例如：`python`、`python.exe`或`uvicorn`。 * 在操作系统上**运行**、使用CPU 并将内容存储在内存上的特定程序。 这也被称为**进程**。 -### 什么是进程 +### 什么是进程 { #what-is-a-process } **进程** 这个词通常以更具体的方式使用，仅指在操作系统中运行的东西（如上面的最后一点）： @@ -89,11 +89,11 @@ 现在我们知道了术语“进程”和“程序”之间的区别，让我们继续讨论部署。 -## 启动时运行 +## 启动时运行 { #running-on-startup } 在大多数情况下，当您创建 Web API 时，您希望它**始终运行**、不间断，以便您的客户端始终可以访问它。 这是当然的，除非您有特定原因希望它仅在某些情况下运行，但大多数时候您希望它不断运行并且**可用**。 -### 在远程服务器中 +### 在远程服务器中 { #in-a-remote-server } 当您设置远程服务器（云服务器、虚拟机等）时，您可以做的最简单的事情就是手动运行 Uvicorn（或类似的），就像本地开发时一样。 @@ -104,15 +104,15 @@ 如果服务器重新启动（例如更新后或从云提供商迁移后），您可能**不会注意到它**。 因此，您甚至不知道必须手动重新启动该进程。 所以，你的 API 将一直处于挂掉的状态。 😱 -### 启动时自动运行 +### 启动时自动运行 { #run-automatically-on-startup } 一般来说，您可能希望服务器程序（例如 Uvicorn）在服务器启动时自动启动，并且不需要任何**人为干预**，让进程始终与您的 API 一起运行（例如 Uvicorn 运行您的 FastAPI 应用程序） 。 -### 单独的程序 +### 单独的程序 { #separate-program } 为了实现这一点，您通常会有一个**单独的程序**来确保您的应用程序在启动时运行。 在许多情况下，它还可以确保其他组件或应用程序也运行，例如数据库。 -### 启动时运行的示例工具 +### 启动时运行的示例工具 { #example-tools-to-run-at-startup } 可以完成这项工作的工具的一些示例是： @@ -128,29 +128,29 @@ 我将在接下来的章节中为您提供更具体的示例。 -## 重新启动 +## 重新启动 { #restarts } 与确保应用程序在启动时运行类似，您可能还想确保它在挂掉后**重新启动**。 -### 我们会犯错误 +### 我们会犯错误 { #we-make-mistakes } 作为人类，我们总是会犯**错误**。 软件几乎*总是*在不同的地方隐藏着**bug**。 🐛 作为开发人员，当我们发现这些bug并实现新功能（也可能添加新bug😅）时，我们会不断改进代码。 -### 自动处理小错误 +### 自动处理小错误 { #small-errors-automatically-handled } 使用 FastAPI 构建 Web API 时，如果我们的代码中存在错误，FastAPI 通常会将其包含到触发错误的单个请求中。 🛡 对于该请求，客户端将收到 **500 内部服务器错误**，但应用程序将继续处理下一个请求，而不是完全崩溃。 -### 更大的错误 - 崩溃 +### 更大的错误 - 崩溃 { #bigger-errors-crashes } 尽管如此，在某些情况下，我们编写的一些代码可能会导致整个应用程序崩溃，从而导致 Uvicorn 和 Python 崩溃。 💥 尽管如此，您可能不希望应用程序因为某个地方出现错误而保持死机状态，您可能希望它**继续运行**，至少对于未破坏的*路径操作*。 -### 崩溃后重新启动 +### 崩溃后重新启动 { #restart-after-crash } 但在那些严重错误导致正在运行的**进程**崩溃的情况下，您需要一个外部组件来负责**重新启动**进程，至少尝试几次...... @@ -164,7 +164,7 @@ 您可能希望让这个东西作为 **外部组件** 负责重新启动您的应用程序，因为到那时，使用 Uvicorn 和 Python 的同一应用程序已经崩溃了，因此同一应用程序的相同代码中没有东西可以对此做出什么。 -### 自动重新启动的示例工具 +### 自动重新启动的示例工具 { #example-tools-to-restart-automatically } 在大多数情况下，用于**启动时运行程序**的同一工具也用于处理自动**重新启动**。 @@ -179,19 +179,19 @@ * 作为其服务的一部分由云提供商内部处理 * 其他的... -## 复制 - 进程和内存 +## 复制 - 进程和内存 { #replication-processes-and-memory } 对于 FastAPI 应用程序，使用像 Uvicorn 这样的服务器程序，在**一个进程**中运行一次就可以同时为多个客户端提供服务。 但在许多情况下，您会希望同时运行多个工作进程。 -### 多进程 - Workers +### 多进程 - Workers { #multiple-processes-workers } 如果您的客户端数量多于单个进程可以处理的数量（例如，如果虚拟机不是太大），并且服务器的 CPU 中有 **多个核心**，那么您可以让 **多个进程** 运行 同时处理同一个应用程序，并在它们之间分发所有请求。 当您运行同一 API 程序的**多个进程**时，它们通常称为 **workers**。 -### 工作进程和端口 +### 工作进程和端口 { #worker-processes-and-ports } 还记得文档 [About HTTPS](https.md){.internal-link target=_blank} 中只有一个进程可以侦听服务器中的端口和 IP 地址的一种组合吗？ @@ -199,20 +199,20 @@ 因此，为了能够同时拥有**多个进程**，必须有一个**单个进程侦听端口**，然后以某种方式将通信传输到每个工作进程。 -### 每个进程的内存 +### 每个进程的内存 { #memory-per-process } 现在，当程序将内容加载到内存中时，例如，将机器学习模型加载到变量中，或者将大文件的内容加载到变量中，所有这些都会消耗服务器的一点内存 (RAM) 。 多个进程通常**不共享任何内存**。 这意味着每个正在运行的进程都有自己的东西、变量和内存。 如果您的代码消耗了大量内存，**每个进程**将消耗等量的内存。 -### 服务器内存 +### 服务器内存 { #server-memory } 例如，如果您的代码加载 **1 GB 大小**的机器学习模型，则当您使用 API 运行一个进程时，它将至少消耗 1 GB RAM。 如果您启动 **4 个进程**（4 个工作进程），每个进程将消耗 1 GB RAM。 因此，您的 API 总共将消耗 **4 GB RAM**。 如果您的远程服务器或虚拟机只有 3 GB RAM，尝试加载超过 4 GB RAM 将导致问题。 🚨 -### 多进程 - 一个例子 +### 多进程 - 一个例子 { #multiple-processes-an-example } 在此示例中，有一个 **Manager Process** 启动并控制两个 **Worker Processes**。 @@ -228,7 +228,7 @@ 如果您有一个每次执行相当数量的计算的 API，并且您有很多客户端，那么 **CPU 利用率** 可能也会保持稳定（而不是不断快速上升和下降）。 -### 复制工具和策略示例 +### 复制工具和策略示例 { #examples-of-replication-tools-and-strategies } 可以通过多种方法来实现这一目标，我将在接下来的章节中向您详细介绍具体策略，例如在谈论 Docker 和容器时。 @@ -255,7 +255,7 @@ /// -## 启动之前的步骤 +## 启动之前的步骤 { #previous-steps-before-starting } 在很多情况下，您希望在**启动**应用程序之前执行一些步骤。 @@ -277,7 +277,7 @@ /// -### 前面步骤策略的示例 +### 前面步骤策略的示例 { #examples-of-previous-steps-strategies } 这将在**很大程度上取决于您部署系统的方式**，并且可能与您启动程序、处理重启等的方式有关。 @@ -293,7 +293,7 @@ /// -## 资源利用率 +## 资源利用率 { #resource-utilization } 您的服务器是一个**资源**，您可以通过您的程序消耗或**利用**CPU 上的计算时间以及可用的 RAM 内存。 @@ -314,7 +314,7 @@ 您可以使用“htop”等简单工具来查看服务器中使用的 CPU 和 RAM 或每个进程使用的数量。 或者您可以使用更复杂的监控工具，这些工具可能分布在服务器等上。 -## 回顾 +## 回顾 { #recap } 您在这里阅读了一些在决定如何部署应用程序时可能需要牢记的主要概念： diff --git a/docs/zh/docs/deployment/manually.md b/docs/zh/docs/deployment/manually.md index 2c2784a64..32c06499e 100644 --- a/docs/zh/docs/deployment/manually.md +++ b/docs/zh/docs/deployment/manually.md @@ -1,6 +1,6 @@ -# 手动运行服务器 +# 手动运行服务器 { #run-a-server-manually } -## 使用 `fastapi run` 命令 +## 使用 `fastapi run` 命令 { #use-the-fastapi-run-command } 简而言之，使用 `fastapi run` 来运行您的 FastAPI 应用程序： @@ -42,7 +42,7 @@ $ fastapi run Granian：基于 Rust 的 HTTP 服务器，专为 Python 应用设计。 * NGINX Unit：NGINX Unit 是一个轻量级且灵活的 Web 应用运行时环境。 -## 服务器主机和服务器程序 +## 服务器主机和服务器程序 { #server-machine-and-server-program } 关于名称，有一个小细节需要记住。 💡 @@ -69,7 +69,7 @@ FastAPI 使用了一种用于构建 Python Web 框架和服务器的标准，称 当提到远程主机时，通常将其称为**服务器**，但也称为**机器**(machine)、**VM**（虚拟机）、**节点**。 这些都是指某种类型的远程计算机，通常运行 Linux，您可以在其中运行程序。 -## 安装服务器程序 +## 安装服务器程序 { #install-the-server-program } 当您安装 FastAPI 时，它自带一个生产环境服务器——Uvicorn，并且您可以使用 `fastapi run` 命令来启动它。 @@ -101,7 +101,7 @@ $ pip install "uvicorn[standard]" /// -## 运行服务器程序 +## 运行服务器程序 { #run-the-server-program } 如果您手动安装了 ASGI 服务器，通常需要以特定格式传递一个导入字符串，以便服务器能够正确导入您的 FastAPI 应用： @@ -142,7 +142,7 @@ Uvicorn 和其他服务器支持 `--reload` 选项，该选项在开发过程中 /// -## 部署概念 +## 部署概念 { #deployment-concepts } 这些示例运行服务器程序（例如 Uvicorn），启动**单个进程**，在所有 IP（`0.0.0.0`）上监听预定义端口（例如`80`）。 diff --git a/docs/zh/docs/deployment/versions.md b/docs/zh/docs/deployment/versions.md index 228bb0765..a088d3e57 100644 --- a/docs/zh/docs/deployment/versions.md +++ b/docs/zh/docs/deployment/versions.md @@ -1,4 +1,4 @@ -# 关于 FastAPI 版本 +# 关于 FastAPI 版本 { #about-fastapi-versions } **FastAPI** 已在许多应用程序和系统的生产环境中使用。 并且测试覆盖率保持在100%。 但其开发进度仍在快速推进。 @@ -8,7 +8,7 @@ 你现在就可以使用 **FastAPI** 创建生产环境应用程序（你可能已经这样做了一段时间），你只需确保使用的版本可以与其余代码正确配合即可。 -## 固定你的 `fastapi` 版本 +## 固定你的 `fastapi` 版本 { #pin-your-fastapi-version } 你应该做的第一件事是将你正在使用的 **FastAPI** 版本“固定”到你知道适用于你的应用程序的特定最新版本。 @@ -16,27 +16,27 @@ 如果你使用`requirements.txt`文件，你可以使用以下命令指定版本： -````txt -fastapi==0.45.0 -```` +```txt +fastapi[standard]==0.112.0 +``` 这意味着你将使用版本`0.45.0`。 或者你也可以将其固定为： -````txt -fastapi>=0.45.0,<0.46.0 -```` +```txt +fastapi[standard]>=0.112.0,<0.113.0 +``` 这意味着你将使用`0.45.0`或更高版本，但低于`0.46.0`，例如，版本`0.45.2`仍会被接受。 如果你使用任何其他工具来管理你的安装，例如 Poetry、Pipenv 或其他工具，它们都有一种定义包的特定版本的方法。 -## 可用版本 +## 可用版本 { #available-versions } 你可以在[发行说明](../release-notes.md){.internal-link target=_blank}中查看可用版本（例如查看当前最新版本）。 -## 关于版本 +## 关于版本 { #about-versions } 遵循语义版本控制约定，任何低于`1.0.0`的版本都可能会添加 breaking changes。 @@ -62,7 +62,7 @@ fastapi>=0.45.0,<0.46.0 /// -## 升级FastAPI版本 +## 升级FastAPI版本 { #upgrading-the-fastapi-versions } 你应该为你的应用程序添加测试。 @@ -72,7 +72,7 @@ fastapi>=0.45.0,<0.46.0 如果一切正常，或者在进行必要的更改之后，并且所有测试都通过了，那么你可以将`fastapi`固定到新的版本。 -## 关于Starlette +## 关于Starlette { #about-starlette } 你不应该固定`starlette`的版本。 @@ -80,7 +80,7 @@ fastapi>=0.45.0,<0.46.0 因此，**FastAPI** 自己可以使用正确的 Starlette 版本。 -## 关于 Pydantic +## 关于 Pydantic { #about-pydantic } Pydantic 包含针对 **FastAPI** 的测试及其自己的测试，因此 Pydantic 的新版本（`1.0.0`以上）始终与 FastAPI 兼容。 @@ -88,6 +88,6 @@ Pydantic 包含针对 **FastAPI** 的测试及其自己的测试，因此 Pydant 例如： -````txt -pydantic>=1.2.0,<2.0.0 -```` +```txt +pydantic>=2.7.0,<3.0.0 +``` diff --git a/docs/zh/docs/features.md b/docs/zh/docs/features.md index eaf8daff7..5a8152f21 100644 --- a/docs/zh/docs/features.md +++ b/docs/zh/docs/features.md @@ -1,10 +1,10 @@ -# 特性 +# 特性 { #features } -## FastAPI 特性 +## FastAPI 特性 { #fastapi-features } **FastAPI** 提供了以下内容： -### 基于开放标准 +### 基于开放标准 { #based-on-open-standards } * 用于创建 API 的 OpenAPI 包含了路径操作，请求参数，请求体，安全性等的声明。 @@ -12,7 +12,7 @@ * 经过了缜密的研究后围绕这些标准而设计。并非狗尾续貂。 * 这也允许了在很多语言中自动**生成客户端代码**。 -### 自动生成文档 +### 自动生成文档 { #automatic-docs } 交互式 API 文档以及具探索性 web 界面。因为该框架是基于 OpenAPI，所以有很多可选项，FastAPI 默认自带两个交互式 API 文档。 @@ -24,7 +24,7 @@ ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) -### 更主流的 Python +### 更主流的 Python { #just-modern-python } 全部都基于标准的 **Python 3.6 类型**声明（感谢 Pydantic ）。没有新的语法需要学习。只需要标准的 Python 。 @@ -73,7 +73,7 @@ my_second_user: User = User(**second_user_data) /// -### 编辑器支持 +### 编辑器支持 { #editor-support } 整个框架都被设计得易于使用且直观，所有的决定都在开发之前就在多个编辑器上进行了测试，来确保最佳的开发体验。 @@ -99,13 +99,13 @@ my_second_user: User = User(**second_user_data) -### 简洁 +### 简洁 { #short } 任何类型都有合理的**默认值**，任何和地方都有可选配置。所有的参数被微调，来满足你的需求，定义成你需要的 API。 但是默认情况下，一切都能**“顺利工作”**。 -### 验证 +### 验证 { #validation } * 校验大部分（甚至所有？）的 Python **数据类型**，包括： * JSON 对象 (`dict`). @@ -121,7 +121,7 @@ my_second_user: User = User(**second_user_data) 所有的校验都由完善且强大的 **Pydantic** 处理。 -### 安全性及身份验证 +### 安全性及身份验证 { #security-and-authentication } 集成了安全性和身份认证。杜绝数据库或者数据模型的渗透风险。 @@ -140,7 +140,7 @@ OpenAPI 中定义的安全模式，包括： -### 依赖注入 +### 依赖注入 { #dependency-injection } FastAPI 有一个使用非常简单，但是非常强大的依赖注入系统。 @@ -151,19 +151,19 @@ FastAPI 有一个使用非常简单，但是非常强大的Pydantic 完全兼容(并基于)。所以，你有的其他的 Pydantic 代码也能正常工作。 diff --git a/docs/zh/docs/history-design-future.md b/docs/zh/docs/history-design-future.md index 4db5c8472..ec9350eff 100644 --- a/docs/zh/docs/history-design-future.md +++ b/docs/zh/docs/history-design-future.md @@ -1,4 +1,4 @@ -# 历史、设计、未来 +# 历史、设计、未来 { #history-design-and-future } 不久前，曾有 **FastAPI** 用户问过： @@ -6,7 +6,7 @@ 在此，我们简单回顾一下 **FastAPI** 的历史。 -## 备选方案 +## 备选方案 { #alternatives } 有那么几年，我曾领导数个开发团队为诸多复杂需求创建各种 API，这些需求包括机器学习、分布系统、异步任务、NoSQL 数据库等领域。 @@ -27,7 +27,7 @@ -## 调研 +## 调研 { #investigation } 通过使用之前所有的备选方案，我有机会从它们之中学到了很多东西，获取了很多想法，并以我和我的开发团队能想到的最好方式把这些思路整合成一体。 @@ -37,7 +37,7 @@ 因此，甚至在开发 **FastAPI** 前，我就花了几个月的时间研究 OpenAPI、JSON Schema、OAuth2 等规范。深入理解它们之间的关系、重叠及区别之处。 -## 设计 +## 设计 { #design } 然后，我又花了一些时间从用户角度（使用 FastAPI 的开发者）设计了开发者 **API**。 @@ -51,7 +51,7 @@ 所有这些都是为了给开发者提供最佳的开发体验。 -## 需求项 +## 需求项 { #requirements } 经过测试多种备选方案，我最终决定使用 **Pydantic**，并充分利用它的优势。 @@ -59,11 +59,11 @@ 在开发期间，我还为 **Starlette** 做了不少贡献，这是另一个关键需求项。 -## 开发 +## 开发 { #development } 当我启动 **FastAPI** 开发的时候，绝大多数部件都已经就位，设计已经定义，需求项和工具也已经准备就绪，相关标准与规范的知识储备也非常清晰而新鲜。 -## 未来 +## 未来 { #future } 至此，**FastAPI** 及其理念已经为很多人所用。 diff --git a/docs/zh/docs/how-to/configure-swagger-ui.md b/docs/zh/docs/how-to/configure-swagger-ui.md index 108e0cb95..e9057a595 100644 --- a/docs/zh/docs/how-to/configure-swagger-ui.md +++ b/docs/zh/docs/how-to/configure-swagger-ui.md @@ -1,4 +1,4 @@ -# 配置 Swagger UI +# 配置 Swagger UI { #configure-swagger-ui } 你可以配置一些额外的 Swagger UI 参数. @@ -8,7 +8,7 @@ FastAPI会将这些配置转换为 **JSON**，使其与 JavaScript 兼容，因为这是 Swagger UI 需要的。 -## 不使用语法高亮 +## 不使用语法高亮 { #disable-syntax-highlighting } 比如，你可以禁用 Swagger UI 中的语法高亮。 @@ -18,41 +18,41 @@ FastAPI会将这些配置转换为 **JSON**，使其与 JavaScript 兼容，因 但是你可以通过设置 `syntaxHighlight` 为 `False` 来禁用 Swagger UI 中的语法高亮： -{* ../../docs_src/configure_swagger_ui/tutorial001.py hl[3] *} +{* ../../docs_src/configure_swagger_ui/tutorial001_py39.py hl[3] *} ...在此之后，Swagger UI 将不会高亮代码: -## 改变主题 +## 改变主题 { #change-the-theme } 同样地，你也可以通过设置键 `"syntaxHighlight.theme"` 来设置语法高亮主题（注意中间有一个点）： -{* ../../docs_src/configure_swagger_ui/tutorial002.py hl[3] *} +{* ../../docs_src/configure_swagger_ui/tutorial002_py39.py hl[3] *} 这个配置会改变语法高亮主题： -## 改变默认 Swagger UI 参数 +## 改变默认 Swagger UI 参数 { #change-default-swagger-ui-parameters } FastAPI 包含了一些默认配置参数，适用于大多数用例。 其包括这些默认配置参数： -{* ../../fastapi/openapi/docs.py ln[7:23] *} +{* ../../fastapi/openapi/docs.py ln[9:24] hl[18:24] *} 你可以通过在 `swagger_ui_parameters` 中设置不同的值来覆盖它们。 比如，如果要禁用 `deepLinking`，你可以像这样传递设置到 `swagger_ui_parameters` 中： -{* ../../docs_src/configure_swagger_ui/tutorial003.py hl[3] *} +{* ../../docs_src/configure_swagger_ui/tutorial003_py39.py hl[3] *} -## 其他 Swagger UI 参数 +## 其他 Swagger UI 参数 { #other-swagger-ui-parameters } 查看其他 Swagger UI 参数，请阅读 docs for Swagger UI parameters。 -## JavaScript-only 配置 +## JavaScript-only 配置 { #javascript-only-settings } Swagger UI 同样允许使用 **JavaScript-only** 配置对象（例如，JavaScript 函数）。 diff --git a/docs/zh/docs/how-to/general.md b/docs/zh/docs/how-to/general.md index e8b6dd3b2..caf94d9e0 100644 --- a/docs/zh/docs/how-to/general.md +++ b/docs/zh/docs/how-to/general.md @@ -1,39 +1,39 @@ -# 通用 - 如何操作 - 诀窍 +# 通用 - 如何操作 - 诀窍 { #general-how-to-recipes } 这里是一些指向文档中其他部分的链接，用于解答一般性或常见问题。 -## 数据过滤 - 安全性 +## 数据过滤 - 安全性 { #filter-data-security } 为确保不返回超过需要的数据，请阅读 [教程 - 响应模型 - 返回类型](../tutorial/response-model.md){.internal-link target=_blank} 文档。 -## 文档的标签 - OpenAPI +## 文档的标签 - OpenAPI { #documentation-tags-openapi } 在文档界面中添加**路径操作**的标签和进行分组，请阅读 [教程 - 路径操作配置 - Tags 参数](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank} 文档。 -## 文档的概要和描述 - OpenAPI +## 文档的概要和描述 - OpenAPI { #documentation-summary-and-description-openapi } -在文档界面中添加**路径操作**的概要和描述，请阅读 [教程 - 路径操作配置 - Summary 和 Description 参数](../tutorial/path-operation-configuration.md#summary-description){.internal-link target=_blank} 文档。 +在文档界面中添加**路径操作**的概要和描述，请阅读 [教程 - 路径操作配置 - Summary 和 Description 参数](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank} 文档。 -## 文档的响应描述 - OpenAPI +## 文档的响应描述 - OpenAPI { #documentation-response-description-openapi } 在文档界面中定义并显示响应描述，请阅读 [教程 - 路径操作配置 - 响应描述](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank} 文档。 -## 文档弃用**路径操作** - OpenAPI +## 文档弃用**路径操作** - OpenAPI { #documentation-deprecate-a-path-operation-openapi } 在文档界面中显示弃用的**路径操作**，请阅读 [教程 - 路径操作配置 - 弃用](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank} 文档。 -## 将任何数据转换为 JSON 兼容格式 +## 将任何数据转换为 JSON 兼容格式 { #convert-any-data-to-json-compatible } 要将任何数据转换为 JSON 兼容格式，请阅读 [教程 - JSON 兼容编码器](../tutorial/encoder.md){.internal-link target=_blank} 文档。 -## OpenAPI 元数据 - 文档 +## OpenAPI 元数据 - 文档 { #openapi-metadata-docs } 要添加 OpenAPI 的元数据，包括许可证、版本、联系方式等，请阅读 [教程 - 元数据和文档 URL](../tutorial/metadata.md){.internal-link target=_blank} 文档。 -## OpenAPI 自定义 URL +## OpenAPI 自定义 URL { #openapi-custom-url } 要自定义 OpenAPI 的 URL（或删除它），请阅读 [教程 - 元数据和文档 URL](../tutorial/metadata.md#openapi-url){.internal-link target=_blank} 文档。 -## OpenAPI 文档 URL +## OpenAPI 文档 URL { #openapi-docs-urls } 要更改用于自动生成文档的 URL，请阅读 [教程 - 元数据和文档 URL](../tutorial/metadata.md#docs-urls){.internal-link target=_blank}. diff --git a/docs/zh/docs/how-to/index.md b/docs/zh/docs/how-to/index.md index ac097618b..e3552fb2f 100644 --- a/docs/zh/docs/how-to/index.md +++ b/docs/zh/docs/how-to/index.md @@ -1,4 +1,4 @@ -# 如何操作 - 诀窍 +# 如何操作 - 诀窍 { #how-to-recipes } 在这里，你将看到关于**多个主题**的不同诀窍或“如何操作”指南。 diff --git a/docs/zh/docs/project-generation.md b/docs/zh/docs/project-generation.md index 48eb990df..9ea1a3fcb 100644 --- a/docs/zh/docs/project-generation.md +++ b/docs/zh/docs/project-generation.md @@ -1,20 +1,20 @@ -# FastAPI全栈模板 +# FastAPI全栈模板 { #full-stack-fastapi-template } 模板通常带有特定的设置，而且被设计为灵活和可定制的。这允许您根据项目的需求修改和调整它们，使它们成为一个很好的起点。🏁 您可以使用此模板开始，因为它包含了许多已经为您完成的初始设置、安全性、数据库和一些API端点。 -代码仓： Full Stack FastAPI Template +代码仓： Full Stack FastAPI Template -## FastAPI全栈模板 - 技术栈和特性 +## FastAPI全栈模板 - 技术栈和特性 { #full-stack-fastapi-template-technology-stack-and-features } -- ⚡ [**FastAPI**](https://fastapi.tiangolo.com) 用于Python后端API. +- ⚡ [**FastAPI**](https://fastapi.tiangolo.com/zh) 用于Python后端API. - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) 用于Python和SQL数据库的集成（ORM）。 - 🔍 [Pydantic](https://docs.pydantic.dev) FastAPI的依赖项之一，用于数据验证和配置管理。 - 💾 [PostgreSQL](https://www.postgresql.org) 作为SQL数据库。 - 🚀 [React](https://react.dev) 用于前端。 - - 💃 使用了TypeScript、hooks、[Vite](https://vitejs.dev)和其他一些现代化的前端技术栈。 - - 🎨 [Chakra UI](https://chakra-ui.com) 用于前端组件。 + - 💃 使用了TypeScript、hooks、[Vite](https://tailwindcss.com)和其他一些现代化的前端技术栈。 + - 🎨 [Chakra UI](https://ui.shadcn.com) 用于前端组件。 - 🤖 一个自动化生成的前端客户端。 - 🧪 [Playwright](https://playwright.dev)用于端到端测试。 - 🦇 支持暗黑主题（Dark mode）。 diff --git a/docs/zh/docs/tutorial/cookie-param-models.md b/docs/zh/docs/tutorial/cookie-param-models.md index 6a7b09e25..4f9b323d1 100644 --- a/docs/zh/docs/tutorial/cookie-param-models.md +++ b/docs/zh/docs/tutorial/cookie-param-models.md @@ -1,4 +1,4 @@ -# Cookie 参数模型 +# Cookie 参数模型 { #cookie-parameter-models } 如果您有一组相关的 **cookie**，您可以创建一个 **Pydantic 模型**来声明它们。🍪 @@ -16,7 +16,7 @@ /// -## 带有 Pydantic 模型的 Cookie +## 带有 Pydantic 模型的 Cookie { #cookies-with-a-pydantic-model } 在 **Pydantic** 模型中声明所需的 **cookie** 参数，然后将参数声明为 `Cookie` ： @@ -24,7 +24,7 @@ **FastAPI** 将从请求中接收到的 **cookie** 中**提取**出**每个字段**的数据，并提供您定义的 Pydantic 模型。 -## 查看文档 +## 查看文档 { #check-the-docs } 您可以在文档 UI 的 `/docs` 中查看定义的 cookie： @@ -42,7 +42,7 @@ /// -## 禁止额外的 Cookie +## 禁止额外的 Cookie { #forbid-extra-cookies } 在某些特殊使用情况下（可能并不常见），您可能希望**限制**您想要接收的 cookie。 @@ -50,7 +50,7 @@ 您可以使用 Pydantic 的模型配置来禁止（ `forbid` ）任何额外（ `extra` ）字段： -{* ../../docs_src/cookie_param_models/tutorial002_an_py39.py hl[10] *} +{* ../../docs_src/cookie_param_models/tutorial002_an_py310.py hl[10] *} 如果客户尝试发送一些**额外的 cookie**，他们将收到**错误**响应。 @@ -71,6 +71,6 @@ } ``` -## 总结 +## 总结 { #summary } 您可以使用 **Pydantic 模型**在 **FastAPI** 中声明 **cookie**。😎 diff --git a/docs/zh/docs/tutorial/cookie-params.md b/docs/zh/docs/tutorial/cookie-params.md index 495600814..b5dc1b1f8 100644 --- a/docs/zh/docs/tutorial/cookie-params.md +++ b/docs/zh/docs/tutorial/cookie-params.md @@ -1,14 +1,14 @@ -# Cookie 参数 +# Cookie 参数 { #cookie-parameters } 定义 `Cookie` 参数与定义 `Query` 和 `Path` 参数一样。 -## 导入 `Cookie` +## 导入 `Cookie` { #import-cookie } 首先，导入 `Cookie`： {* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *} -## 声明 `Cookie` 参数 +## 声明 `Cookie` 参数 { #declare-cookie-parameters } 声明 `Cookie` 参数的方式与声明 `Query` 和 `Path` 参数相同。 @@ -31,6 +31,6 @@ /// -## 小结 +## 小结 { #recap } 使用 `Cookie` 声明 cookie 参数的方式与 `Query` 和 `Path` 相同。 diff --git a/docs/zh/docs/tutorial/debugging.md b/docs/zh/docs/tutorial/debugging.md index 734b85565..e08b51ed4 100644 --- a/docs/zh/docs/tutorial/debugging.md +++ b/docs/zh/docs/tutorial/debugging.md @@ -1,14 +1,14 @@ -# 调试 +# 调试 { #debugging } 你可以在编辑器中连接调试器，例如使用 Visual Studio Code 或 PyCharm。 -## 调用 `uvicorn` +## 调用 `uvicorn` { #call-uvicorn } 在你的 FastAPI 应用中直接导入 `uvicorn` 并运行： -{* ../../docs_src/debugging/tutorial001.py hl[1,15] *} +{* ../../docs_src/debugging/tutorial001_py39.py hl[1,15] *} -### 关于 `__name__ == "__main__"` +### 关于 `__name__ == "__main__"` { #about-name-main } `__name__ == "__main__"` 的主要目的是使用以下代码调用文件时执行一些代码： @@ -26,7 +26,7 @@ $ python myapp.py from myapp import app ``` -#### 更多细节 +#### 更多细节 { #more-details } 假设你的文件命名为 `myapp.py`。 @@ -74,7 +74,7 @@ from myapp import app /// -## 使用你的调试器运行代码 +## 使用你的调试器运行代码 { #run-your-code-with-your-debugger } 由于是从代码直接运行的 Uvicorn 服务器，所以你可以从调试器直接调用 Python 程序（你的 FastAPI 应用）。 diff --git a/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md index 51b3e9fc3..879a0a14b 100644 --- a/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md +++ b/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md @@ -1,4 +1,4 @@ -# 路径操作装饰器依赖项 +# 路径操作装饰器依赖项 { #dependencies-in-path-operation-decorators } 有时，我们并不需要在*路径操作函数*中使用依赖项的返回值。 @@ -8,13 +8,13 @@ 对于这种情况，不必在声明*路径操作函数*的参数时使用 `Depends`，而是可以在*路径操作装饰器*中添加一个由 `dependencies` 组成的 `list`。 -## 在*路径操作装饰器*中添加 `dependencies` 参数 +## 在*路径操作装饰器*中添加 `dependencies` 参数 { #add-dependencies-to-the-path-operation-decorator } *路径操作装饰器*支持可选参数 ~ `dependencies`。 该参数的值是由 `Depends()` 组成的 `list`： -{* ../../docs_src/dependencies/tutorial006.py hl[17] *} +{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[19] *} 路径操作装饰器依赖项（以下简称为**“路径装饰器依赖项”**）的执行或解析方式和普通依赖项一样，但就算这些依赖项会返回值，它们的值也不会传递给*路径操作函数*。 @@ -36,34 +36,34 @@ /// -## 依赖项错误和返回值 +## 依赖项错误和返回值 { #dependencies-errors-and-return-values } 路径装饰器依赖项也可以使用普通的依赖项*函数*。 -### 依赖项的需求项 +### 依赖项的需求项 { #dependency-requirements } 路径装饰器依赖项可以声明请求的需求项（比如响应头）或其他子依赖项： -{* ../../docs_src/dependencies/tutorial006.py hl[6,11] *} +{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[8,13] *} -### 触发异常 +### 触发异常 { #raise-exceptions } 路径装饰器依赖项与正常的依赖项一样，可以 `raise` 异常： -{* ../../docs_src/dependencies/tutorial006.py hl[8,13] *} +{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[10,15] *} -### 返回值 +### 返回值 { #return-values } 无论路径装饰器依赖项是否返回值，路径操作都不会使用这些值。 因此，可以复用在其他位置使用过的、（能返回值的）普通依赖项，即使没有使用这个值，也会执行该依赖项： -{* ../../docs_src/dependencies/tutorial006.py hl[9,14] *} +{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[11,16] *} -## 为一组路径操作定义依赖项 +## 为一组路径操作定义依赖项 { #dependencies-for-a-group-of-path-operations } -稍后，[大型应用 - 多文件](../../tutorial/bigger-applications.md){.internal-link target=\_blank}一章中会介绍如何使用多个文件创建大型应用程序，在这一章中，您将了解到如何为一组*路径操作*声明单个 `dependencies` 参数。 +稍后，[大型应用 - 多文件](../../tutorial/bigger-applications.md){.internal-link target=_blank}一章中会介绍如何使用多个文件创建大型应用程序，在这一章中，您将了解到如何为一组*路径操作*声明单个 `dependencies` 参数。 -## 全局依赖项 +## 全局依赖项 { #global-dependencies } 接下来，我们将学习如何为 `FastAPI` 应用程序添加全局依赖项，创建应用于每个*路径操作*的依赖项。 diff --git a/docs/zh/docs/tutorial/dependencies/global-dependencies.md b/docs/zh/docs/tutorial/dependencies/global-dependencies.md index 797fd76b7..5d8e41082 100644 --- a/docs/zh/docs/tutorial/dependencies/global-dependencies.md +++ b/docs/zh/docs/tutorial/dependencies/global-dependencies.md @@ -1,4 +1,4 @@ -# 全局依赖项 +# 全局依赖项 { #global-dependencies } 有时，我们要为整个应用添加依赖项。 @@ -6,10 +6,10 @@ 这样一来，就可以为所有*路径操作*应用该依赖项： -{* ../../docs_src/dependencies/tutorial012.py hl[15] *} +{* ../../docs_src/dependencies/tutorial012_an_py39.py hl[17] *} [*路径装饰器依赖项*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} 一章的思路均适用于全局依赖项， 在本例中，这些依赖项可以用于应用中的所有*路径操作*。 -## 为一组路径操作定义依赖项 +## 为一组路径操作定义依赖项 { #dependencies-for-groups-of-path-operations } 稍后，[大型应用 - 多文件](../../tutorial/bigger-applications.md){.internal-link target=_blank}一章中会介绍如何使用多个文件创建大型应用程序，在这一章中，您将了解到如何为一组*路径操作*声明单个 `dependencies` 参数。 diff --git a/docs/zh/docs/tutorial/encoder.md b/docs/zh/docs/tutorial/encoder.md index e52aaa2ed..fed92b080 100644 --- a/docs/zh/docs/tutorial/encoder.md +++ b/docs/zh/docs/tutorial/encoder.md @@ -1,4 +1,4 @@ -# JSON 兼容编码器 +# JSON 兼容编码器 { #json-compatible-encoder } 在某些情况下，您可能需要将数据类型（如Pydantic模型）转换为与JSON兼容的数据类型（如`dict`、`list`等）。 @@ -6,7 +6,7 @@ 对于这种要求， **FastAPI**提供了`jsonable_encoder()`函数。 -## 使用`jsonable_encoder` +## 使用`jsonable_encoder` { #using-the-jsonable-encoder } 让我们假设你有一个数据库名为`fake_db`，它只能接收与JSON兼容的数据。 diff --git a/docs/zh/docs/tutorial/extra-data-types.md b/docs/zh/docs/tutorial/extra-data-types.md index b064ee551..97f1dc5e8 100644 --- a/docs/zh/docs/tutorial/extra-data-types.md +++ b/docs/zh/docs/tutorial/extra-data-types.md @@ -1,4 +1,4 @@ -# 额外数据类型 +# 额外数据类型 { #extra-data-types } 到目前为止，您一直在使用常见的数据类型，如: @@ -17,7 +17,7 @@ * 数据验证。 * 自动补全和文档。 -## 其他数据类型 +## 其他数据类型 { #other-data-types } 下面是一些你可以使用的其他数据类型: @@ -36,7 +36,7 @@ * `datetime.timedelta`: * 一个 Python `datetime.timedelta`. * 在请求和响应中将表示为 `float` 代表总秒数。 - * Pydantic 也允许将其表示为 "ISO 8601 时间差异编码", 查看文档了解更多信息。 + * Pydantic 也允许将其表示为 "ISO 8601 时间差异编码", 查看文档了解更多信息。 * `frozenset`: * 在请求和响应中，作为 `set` 对待： * 在请求中，列表将被读取，消除重复，并将其转换为一个 `set`。 @@ -49,9 +49,9 @@ * `Decimal`: * 标准的 Python `Decimal`。 * 在请求和响应中被当做 `float` 一样处理。 -* 您可以在这里检查所有有效的pydantic数据类型: Pydantic data types. +* 您可以在这里检查所有有效的pydantic数据类型: Pydantic data types. -## 例子 +## 例子 { #example } 下面是一个*路径操作*的示例，其中的参数使用了上面的一些类型。 diff --git a/docs/zh/docs/tutorial/header-params.md b/docs/zh/docs/tutorial/header-params.md index 19bb455cf..9f14990da 100644 --- a/docs/zh/docs/tutorial/header-params.md +++ b/docs/zh/docs/tutorial/header-params.md @@ -1,14 +1,14 @@ -# Header 参数 +# Header 参数 { #header-parameters } 定义 `Header` 参数的方式与定义 `Query`、`Path`、`Cookie` 参数相同。 -## 导入 `Header` +## 导入 `Header` { #import-header } 首先，导入 `Header`： {* ../../docs_src/header_params/tutorial001_an_py310.py hl[3] *} -## 声明 `Header` 参数 +## 声明 `Header` 参数 { #declare-header-parameters } 然后，使用和 `Path`、`Query`、`Cookie` 一样的结构定义 header 参数。 @@ -30,7 +30,7 @@ /// -## 自动转换 +## 自动转换 { #automatic-conversion } `Header` 比 `Path`、`Query` 和 `Cookie` 提供了更多功能。 @@ -54,7 +54,7 @@ /// -## 重复的请求头 +## 重复的请求头 { #duplicate-headers } 有时，可能需要接收重复的请求头。即同一个请求头有多个值。 @@ -84,7 +84,7 @@ X-Token: bar } ``` -## 小结 +## 小结 { #recap } 使用 `Header` 声明请求头的方式与 `Query`、`Path` 、`Cookie` 相同。 diff --git a/docs/zh/docs/tutorial/query-param-models.md b/docs/zh/docs/tutorial/query-param-models.md index c6a79a71a..13555b496 100644 --- a/docs/zh/docs/tutorial/query-param-models.md +++ b/docs/zh/docs/tutorial/query-param-models.md @@ -1,4 +1,4 @@ -# 查询参数模型 +# 查询参数模型 { #query-parameter-models } 如果你有一组具有相关性的**查询参数**，你可以创建一个 **Pydantic 模型**来声明它们。 @@ -10,7 +10,7 @@ FastAPI 从 `0.115.0` 版本开始支持这个特性。🤓 /// -## 使用 Pydantic 模型的查询参数 +## 使用 Pydantic 模型的查询参数 { #query-parameters-with-a-pydantic-model } 在一个 **Pydantic 模型**中声明你需要的**查询参数**，然后将参数声明为 `Query`： @@ -18,7 +18,7 @@ FastAPI 从 `0.115.0` 版本开始支持这个特性。🤓 **FastAPI** 将会从请求的**查询参数**中**提取**出**每个字段**的数据，并将其提供给你定义的 Pydantic 模型。 -## 查看文档 +## 查看文档 { #check-the-docs } 你可以在 `/docs` 页面的 UI 中查看查询参数： @@ -26,7 +26,7 @@ FastAPI 从 `0.115.0` 版本开始支持这个特性。🤓
-## 禁止额外的查询参数 +## 禁止额外的查询参数 { #forbid-extra-query-parameters } 在一些特殊的使用场景中（可能不是很常见），你可能希望**限制**你要接收的查询参数。 @@ -57,7 +57,7 @@ https://example.com/items/?limit=10&tool=plumbus } ``` -## 总结 +## 总结 { #summary } 你可以使用 **Pydantic 模型**在 **FastAPI** 中声明**查询参数**。😎 diff --git a/docs/zh/docs/tutorial/request-form-models.md b/docs/zh/docs/tutorial/request-form-models.md index e639e4b9f..b3c5d5399 100644 --- a/docs/zh/docs/tutorial/request-form-models.md +++ b/docs/zh/docs/tutorial/request-form-models.md @@ -1,4 +1,4 @@ -# 表单模型 +# 表单模型 { #form-models } 您可以使用 **Pydantic 模型**在 FastAPI 中声明**表单字段**。 @@ -20,7 +20,7 @@ $ pip install python-multipart /// -## 表单的 Pydantic 模型 +## 表单的 Pydantic 模型 { #pydantic-models-for-forms } 您只需声明一个 **Pydantic 模型**，其中包含您希望接收的**表单字段**，然后将参数声明为 `Form` : @@ -28,7 +28,7 @@ $ pip install python-multipart **FastAPI** 将从请求中的**表单数据**中**提取**出**每个字段**的数据，并提供您定义的 Pydantic 模型。 -## 检查文档 +## 检查文档 { #check-the-docs } 您可以在文档 UI 中验证它，地址为 `/docs` ： @@ -36,7 +36,7 @@ $ pip install python-multipart -## 禁止额外的表单字段 +## 禁止额外的表单字段 { #forbid-extra-form-fields } 在某些特殊使用情况下（可能并不常见），您可能希望将表单字段**限制**为仅在 Pydantic 模型中声明过的字段，并**禁止**任何**额外**的字段。 @@ -73,6 +73,6 @@ $ pip install python-multipart } ``` -## 总结 +## 总结 { #summary } 您可以使用 Pydantic 模型在 FastAPI 中声明表单字段。😎 diff --git a/docs/zh/docs/tutorial/response-status-code.md b/docs/zh/docs/tutorial/response-status-code.md index aa8032ada..e3cf41227 100644 --- a/docs/zh/docs/tutorial/response-status-code.md +++ b/docs/zh/docs/tutorial/response-status-code.md @@ -1,4 +1,4 @@ -# 响应状态码 +# 响应状态码 { #response-status-code } 与指定响应模型的方式相同，在以下任意*路径操作*中，可以使用 `status_code` 参数声明用于响应的 HTTP 状态码： @@ -8,7 +8,7 @@ * `@app.delete()` * 等…… -{* ../../docs_src/response_status_code/tutorial001.py hl[6] *} +{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *} /// note | 笔记 @@ -39,7 +39,7 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。 /// -## 关于 HTTP 状态码 +## 关于 HTTP 状态码 { #about-http-status-codes } /// note | 笔记 @@ -70,11 +70,11 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。 /// -## 状态码名称快捷方式 +## 状态码名称快捷方式 { #shortcut-to-remember-the-names } 再看下之前的例子： -{* ../../docs_src/response_status_code/tutorial001.py hl[6] *} +{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *} `201` 表示**已创建**的状态码。 @@ -82,7 +82,7 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。 可以使用 `fastapi.status` 中的快捷变量。 -{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *} +{* ../../docs_src/response_status_code/tutorial002_py39.py hl[1,6] *} 这只是一种快捷方式，具有相同的数字代码，但它可以使用编辑器的自动补全功能： @@ -96,6 +96,6 @@ FastAPI 可以进行识别，并生成表明无响应体的 OpenAPI 文档。 /// -## 更改默认状态码 +## 更改默认状态码 { #changing-the-default } [高级用户指南](../advanced/response-change-status-code.md){.internal-link target=_blank}中，将介绍如何返回与在此声明的默认状态码不同的状态码。 diff --git a/docs/zh/docs/tutorial/security/get-current-user.md b/docs/zh/docs/tutorial/security/get-current-user.md index 1f254a103..c14bba28a 100644 --- a/docs/zh/docs/tutorial/security/get-current-user.md +++ b/docs/zh/docs/tutorial/security/get-current-user.md @@ -1,23 +1,23 @@ -# 获取当前用户 +# 获取当前用户 { #get-current-user } 上一章中，（基于依赖注入系统的）安全系统向*路径操作函数*传递了 `str` 类型的 `token`： -{* ../../docs_src/security/tutorial001.py hl[10] *} +{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *} 但这并不实用。 接下来，我们学习如何返回当前用户。 -## 创建用户模型 +## 创建用户模型 { #create-a-user-model } 首先，创建 Pydantic 用户模型。 与使用 Pydantic 声明请求体相同，并且可在任何位置使用： -{* ../../docs_src/security/tutorial002.py hl[5,12:16] *} +{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:6] *} -## 创建 `get_current_user` 依赖项 +## 创建 `get_current_user` 依赖项 { #create-a-get-current-user-dependency } 创建 `get_current_user` 依赖项。 @@ -27,19 +27,19 @@ 与之前直接在路径操作中的做法相同，新的 `get_current_user` 依赖项从子依赖项 `oauth2_scheme` 中接收 `str` 类型的 `token`： -{* ../../docs_src/security/tutorial002.py hl[25] *} +{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *} -## 获取用户 +## 获取用户 { #get-the-user } `get_current_user` 使用创建的（伪）工具函数，该函数接收 `str` 类型的令牌，并返回 Pydantic 的 `User` 模型： -{* ../../docs_src/security/tutorial002.py hl[19:22,26:27] *} +{* ../../docs_src/security/tutorial002_an_py310.py hl[19:22,26:27] *} -## 注入当前用户 +## 注入当前用户 { #inject-the-current-user } 在*路径操作* 的 `Depends` 中使用 `get_current_user`： -{* ../../docs_src/security/tutorial002.py hl[31] *} +{* ../../docs_src/security/tutorial002_an_py310.py hl[31] *} 注意，此处把 `current_user` 的类型声明为 Pydantic 的 `User` 模型。 @@ -61,7 +61,7 @@ /// -## 其它模型 +## 其它模型 { #other-models } 接下来，直接在*路径操作函数*中获取当前用户，并用 `Depends` 在**依赖注入**系统中处理安全机制。 @@ -78,7 +78,7 @@ 尽管使用应用所需的任何模型、类、数据库。**FastAPI** 通过依赖注入系统都能帮您搞定。 -## 代码大小 +## 代码大小 { #code-size } 这个示例看起来有些冗长。毕竟这个文件同时包含了安全、数据模型的工具函数，以及路径操作等代码。 @@ -94,9 +94,9 @@ 所有*路径操作*只需 3 行代码就可以了： -{* ../../docs_src/security/tutorial002.py hl[30:32] *} +{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *} -## 小结 +## 小结 { #recap } 现在，我们可以直接在*路径操作函数*中获取当前用户。 diff --git a/docs/zh/docs/tutorial/security/index.md b/docs/zh/docs/tutorial/security/index.md index 1484b99fd..9d110e358 100644 --- a/docs/zh/docs/tutorial/security/index.md +++ b/docs/zh/docs/tutorial/security/index.md @@ -1,4 +1,4 @@ -# 安全性 +# 安全性 { #security } 有许多方法可以处理安全性、身份认证和授权等问题。 @@ -10,11 +10,11 @@ 但首先，让我们来看一些小的概念。 -## 没有时间？ +## 没有时间？ { #in-a-hurry } 如果你不关心这些术语，而只需要*立即*通过基于用户名和密码的身份认证来增加安全性，请跳转到下一章。 -## OAuth2 +## OAuth2 { #oauth2 } OAuth2是一个规范，它定义了几种处理身份认证和授权的方法。 @@ -24,7 +24,7 @@ OAuth2是一个规范，它定义了几种处理身份认证和授权的方法 这就是所有带有「使用 Facebook，Google，X (Twitter)，GitHub 登录」的系统背后所使用的机制。 -### OAuth 1 +### OAuth 1 { #oauth-1 } 有一个 OAuth 1，它与 OAuth2 完全不同，并且更为复杂，因为它直接包含了有关如何加密通信的规范。 @@ -38,7 +38,7 @@ OAuth2 没有指定如何加密通信，它期望你为应用程序使用 HTTPS /// -## OpenID Connect +## OpenID Connect { #openid-connect } OpenID Connect 是另一个基于 **OAuth2** 的规范。 @@ -48,7 +48,7 @@ OpenID Connect 是另一个基于 **OAuth2** 的规范。 但是 Facebook 登录不支持 OpenID Connect。它具有自己的 OAuth2 风格。 -### OpenID（非「OpenID Connect」） +### OpenID（非「OpenID Connect」） { #openid-not-openid-connect } 还有一个「OpenID」规范。它试图解决与 **OpenID Connect** 相同的问题，但它不是基于 OAuth2。 @@ -56,7 +56,7 @@ OpenID Connect 是另一个基于 **OAuth2** 的规范。 如今它已经不是很流行，没有被广泛使用了。 -## OpenAPI +## OpenAPI { #openapi } OpenAPI（以前称为 Swagger）是用于构建 API 的开放规范（现已成为 Linux Foundation 的一部分）。 @@ -97,7 +97,7 @@ OpenAPI 定义了以下安全方案： /// -## **FastAPI** 实用工具 +## **FastAPI** 实用工具 { #fastapi-utilities } FastAPI 在 `fastapi.security` 模块中为每个安全方案提供了几种工具，这些工具简化了这些安全机制的使用方法。 diff --git a/docs/zh/docs/tutorial/security/simple-oauth2.md b/docs/zh/docs/tutorial/security/simple-oauth2.md index f70678df8..6b0e80626 100644 --- a/docs/zh/docs/tutorial/security/simple-oauth2.md +++ b/docs/zh/docs/tutorial/security/simple-oauth2.md @@ -1,8 +1,8 @@ -# OAuth2 实现简单的 Password 和 Bearer 验证 +# OAuth2 实现简单的 Password 和 Bearer 验证 { #simple-oauth2-with-password-and-bearer } 本章添加上一章示例中欠缺的部分，实现完整的安全流。 -## 获取 `username` 和 `password` +## 获取 `username` 和 `password` { #get-the-username-and-password } 首先，使用 **FastAPI** 安全工具获取 `username` 和 `password`。 @@ -18,7 +18,7 @@ OAuth2 规范要求使用**密码流**时，客户端或用户必须以表单数 该规范要求必须以表单数据形式发送 `username` 和 `password`，因此，不能使用 JSON 对象。 -### `Scope`（作用域） +### `Scope`（作用域） { #scope } OAuth2 还支持客户端发送**`scope`**表单字段。 @@ -44,15 +44,15 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。 /// -## 获取 `username` 和 `password` 的代码 +## 获取 `username` 和 `password` 的代码 { #code-to-get-the-username-and-password } 接下来，使用 **FastAPI** 工具获取用户名与密码。 -### `OAuth2PasswordRequestForm` +### `OAuth2PasswordRequestForm` { #oauth2passwordrequestform } 首先，导入 `OAuth2PasswordRequestForm`，然后，在 `/token` *路径操作* 中，用 `Depends` 把该类作为依赖项。 -{* ../../docs_src/security/tutorial003.py hl[4,76] *} +{* ../../docs_src/security/tutorial003_an_py310.py hl[4,78] *} `OAuth2PasswordRequestForm` 是用以下几项内容声明表单请求体的类依赖项： @@ -84,7 +84,7 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。 /// -### 使用表单数据 +### 使用表单数据 { #use-the-form-data } /// tip | 提示 @@ -100,9 +100,9 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。 本例使用 `HTTPException` 异常显示此错误： -{* ../../docs_src/security/tutorial003.py hl[3,77:79] *} +{* ../../docs_src/security/tutorial003_an_py310.py hl[3,79:81] *} -### 校验密码 +### 校验密码 { #check-the-password } 至此，我们已经从数据库中获取了用户数据，但尚未校验密码。 @@ -112,7 +112,7 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。 如果密码不匹配，则返回与上面相同的错误。 -#### 密码哈希 +#### 密码哈希 { #password-hashing } **哈希**是指，将指定内容（本例中为密码）转换为形似乱码的字节序列（其实就是字符串）。 @@ -120,15 +120,15 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。 但这个乱码无法转换回传入的密码。 -##### 为什么使用密码哈希 +##### 为什么使用密码哈希 { #why-use-password-hashing } 原因很简单，假如数据库被盗，窃贼无法获取用户的明文密码，得到的只是哈希值。 这样一来，窃贼就无法在其它应用中使用窃取的密码，要知道，很多用户在所有系统中都使用相同的密码，风险超大。 -{* ../../docs_src/security/tutorial003.py hl[80:83] *} +{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *} -#### 关于 `**user_dict` +#### 关于 `**user_dict` { #about-user-dict } `UserInDB(**user_dict)` 是指： @@ -146,11 +146,11 @@ UserInDB( /// info | 说明 -`user_dict` 的说明，详见[**更多模型**一章](../extra-models.md#user_indict){.internal-link target=_blank}。 +`user_dict` 的说明，详见[**更多模型**一章](../extra-models.md#about-user-in-dict){.internal-link target=_blank}。 /// -## 返回 Token +## 返回 Token { #return-the-token } `token` 端点的响应必须是 JSON 对象。 @@ -168,7 +168,7 @@ UserInDB( /// -{* ../../docs_src/security/tutorial003.py hl[85] *} +{* ../../docs_src/security/tutorial003_an_py310.py hl[87] *} /// tip | 提示 @@ -182,7 +182,7 @@ UserInDB( /// -## 更新依赖项 +## 更新依赖项 { #update-the-dependencies } 接下来，更新依赖项。 @@ -194,7 +194,7 @@ UserInDB( 因此，在端点中，只有当用户存在、通过身份验证、且状态为激活时，才能获得该用户： -{* ../../docs_src/security/tutorial003.py hl[58:67,69:72,90] *} +{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *} /// info | 说明 @@ -214,11 +214,11 @@ UserInDB( /// -## 实际效果 +## 实际效果 { #see-it-in-action } 打开 API 文档：http://127.0.0.1:8000/docs。 -### 身份验证 +### 身份验证 { #authenticate } 点击**Authorize**按钮。 @@ -234,7 +234,7 @@ UserInDB( -### 获取当前用户数据 +### 获取当前用户数据 { #get-your-own-user-data } 使用 `/users/me` 路径的 `GET` 操作。 @@ -260,7 +260,7 @@ UserInDB( } ``` -### 未激活用户 +### 未激活用户 { #inactive-user } 测试未激活用户，输入以下信息，进行身份验证： @@ -278,7 +278,7 @@ UserInDB( } ``` -## 小结 +## 小结 { #recap } 使用本章的工具实现基于 `username` 和 `password` 的完整 API 安全系统。 diff --git a/fastapi/security/http.py b/fastapi/security/http.py index a8ddf0c16..ae25ad219 100644 --- a/fastapi/security/http.py +++ b/fastapi/security/http.py @@ -118,10 +118,8 @@ class HTTPBasic(HTTPBase): self.realm = realm # keep for OpenAPI compatibility self.auto_error = auto_error - def make_authenticate_headers(self) -> dict[str, str]: return {"WWW-Authenticate": "Basic"} - async def __call__( # type: ignore self, request: Request