diff --git a/docs/ru/docs/advanced/additional-responses.md b/docs/ru/docs/advanced/additional-responses.md index ca36ba20e3..f7e8d9dec0 100644 --- a/docs/ru/docs/advanced/additional-responses.md +++ b/docs/ru/docs/advanced/additional-responses.md @@ -243,5 +243,5 @@ new_dict = {**old_dict, "new key": "new value"} Чтобы увидеть, что именно можно включать в ответы, посмотрите эти разделы спецификации OpenAPI: -* Объект Responses OpenAPI, он включает `Response Object`. -* Объект Response OpenAPI, вы можете включить всё из этого объекта напрямую в каждый ответ внутри вашего параметра `responses`. Включая `description`, `headers`, `content` (внутри него вы объявляете разные типы содержимого и JSON‑схемы) и `links`. +* [Объект Responses OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object), он включает `Response Object`. +* [Объект Response OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object), вы можете включить всё из этого объекта напрямую в каждый ответ внутри вашего параметра `responses`. Включая `description`, `headers`, `content` (внутри него вы объявляете разные типы содержимого и JSON‑схемы) и `links`. diff --git a/docs/ru/docs/advanced/advanced-dependencies.md b/docs/ru/docs/advanced/advanced-dependencies.md index 686a0cf91e..fe37a79c1f 100644 --- a/docs/ru/docs/advanced/advanced-dependencies.md +++ b/docs/ru/docs/advanced/advanced-dependencies.md @@ -48,7 +48,7 @@ checker(q="somequery") ``` -…и передаст возвращённое значение как значение зависимости в параметр `fixed_content_included` нашей *функции-обработчика пути*: +…и передаст возвращённое значение как значение зависимости в параметр `fixed_content_included` нашей *функции-обработчику пути*: {* ../../docs_src/dependencies/tutorial011_an_py310.py hl[22] *} @@ -132,7 +132,7 @@ checker(q="somequery") Так сессия освободит подключение к базе данных, и другие запросы смогут его использовать. -Если у вас есть другой сценарий, где нужно раннее завершение зависимости с `yield`, пожалуйста, создайте вопрос в GitHub Discussions с описанием конкретного кейса и почему вам было бы полезно иметь раннее закрытие для зависимостей с `yield`. +Если у вас есть другой сценарий, где нужно раннее завершение зависимости с `yield`, пожалуйста, создайте [вопрос в GitHub Discussions](https://github.com/fastapi/fastapi/discussions/new?category=questions) с описанием конкретного кейса и почему вам было бы полезно иметь раннее закрытие для зависимостей с `yield`. Если появятся веские причины для раннего закрытия в зависимостях с `yield`, я рассмотрю добавление нового способа опционально включать раннее закрытие. @@ -144,7 +144,7 @@ checker(q="somequery") ### Фоновые задачи и зависимости с `yield`, технические детали { #background-tasks-and-dependencies-with-yield-technical-details } -До FastAPI 0.106.0 вызывать исключения после `yield` было невозможно: код после `yield` в зависимостях выполнялся уже после отправки ответа, поэтому [Обработчики исключений](../tutorial/handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} к тому моменту уже отработали. +До FastAPI 0.106.0 вызывать исключения после `yield` было невозможно: код после `yield` в зависимостях выполнялся уже после отправки ответа, поэтому [Обработчики исключений](../tutorial/handling-errors.md#install-custom-exception-handlers) к тому моменту уже отработали. Так было сделано в основном для того, чтобы можно было использовать те же объекты, «отданные» зависимостями через `yield`, внутри фоновых задач, потому что код после `yield` выполнялся после завершения фоновых задач. diff --git a/docs/ru/docs/advanced/async-tests.md b/docs/ru/docs/advanced/async-tests.md index 52939c2559..1c0b888cc9 100644 --- a/docs/ru/docs/advanced/async-tests.md +++ b/docs/ru/docs/advanced/async-tests.md @@ -16,11 +16,11 @@ Чтобы работать с асинхронным FastAPI приложением в ваших обычных тестовых функциях `def`, используя стандартный pytest, `TestClient` внутри себя делает некоторую магию. Но эта магия перестает работать, когда мы используем его внутри асинхронных функций. Запуская наши тесты асинхронно, мы больше не можем использовать `TestClient` внутри наших тестовых функций. -`TestClient` основан на HTTPX, и, к счастью, мы можем использовать его (`HTTPX`) напрямую для тестирования API. +`TestClient` основан на [HTTPX](https://www.python-httpx.org), и, к счастью, мы можем использовать его (`HTTPX`) напрямую для тестирования API. ## Пример { #example } -В качестве простого примера, давайте рассмотрим файловую структуру, схожую с описанной в [Большие приложения](../tutorial/bigger-applications.md){.internal-link target=_blank} и [Тестирование](../tutorial/testing.md){.internal-link target=_blank}: +В качестве простого примера, давайте рассмотрим файловую структуру, схожую с описанной в [Большие приложения](../tutorial/bigger-applications.md) и [Тестирование](../tutorial/testing.md): ``` . @@ -84,7 +84,7 @@ response = client.get('/') /// warning | Внимание -Если ваше приложение полагается на lifespan события, то `AsyncClient` не запустит эти события. Чтобы обеспечить их срабатывание используйте `LifespanManager` из florimondmanca/asgi-lifespan. +Если ваше приложение полагается на lifespan события, то `AsyncClient` не запустит эти события. Чтобы обеспечить их срабатывание используйте `LifespanManager` из [florimondmanca/asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan#usage). /// @@ -94,6 +94,6 @@ response = client.get('/') /// tip | Подсказка -Если вы столкнулись с `RuntimeError: Task attached to a different loop` при вызове асинхронных функций в ваших тестах (например, при использовании MongoDB's MotorClient), то не забывайте инициализировать объекты, которым нужен цикл событий (event loop), только внутри асинхронных функций, например, в `@app.on_event("startup")` callback. +Если вы столкнулись с `RuntimeError: Task attached to a different loop` при вызове асинхронных функций в ваших тестах (например, при использовании [MongoDB's MotorClient](https://stackoverflow.com/questions/41584243/runtimeerror-task-attached-to-a-different-loop)), то не забывайте создавать экземпляры объектов, которым нужен цикл событий (event loop), только внутри асинхронных функций, например, в `@app.on_event("startup")` callback. /// diff --git a/docs/ru/docs/advanced/behind-a-proxy.md b/docs/ru/docs/advanced/behind-a-proxy.md index ec75ed3698..4f212868ad 100644 --- a/docs/ru/docs/advanced/behind-a-proxy.md +++ b/docs/ru/docs/advanced/behind-a-proxy.md @@ -16,9 +16,9 @@ Заголовки прокси: -* X-Forwarded-For -* X-Forwarded-Proto -* X-Forwarded-Host +* [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-For) +* [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Proto) +* [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Host) /// @@ -60,7 +60,7 @@ https://mysuperapp.com/items/ /// tip | Совет -Если хотите узнать больше об HTTPS, смотрите руководство [О HTTPS](../deployment/https.md){.internal-link target=_blank}. +Если хотите узнать больше об HTTPS, смотрите руководство [О HTTPS](../deployment/https.md). /// @@ -228,7 +228,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 Учтите, что сервер (Uvicorn) не использует `root_path` ни для чего, кроме как передать его в приложение. -Если вы откроете в браузере http://127.0.0.1:8000/app, вы увидите обычный ответ: +Если вы откроете в браузере [http://127.0.0.1:8000/app](http://127.0.0.1:8000/app), вы увидите обычный ответ: ```JSON { @@ -251,9 +251,9 @@ Uvicorn ожидает, что прокси обратится к нему по ## Локальное тестирование с Traefik { #testing-locally-with-traefik } -Вы можете легко поэкспериментировать локально с функцией удаления префикса пути, используя Traefik. +Вы можете легко поэкспериментировать локально с функцией удаления префикса пути, используя [Traefik](https://docs.traefik.io/). -Скачайте Traefik — это один бинарный файл; распакуйте архив и запустите его прямо из терминала. +[Скачайте Traefik](https://github.com/containous/traefik/releases) — это один бинарный файл; распакуйте архив и запустите его прямо из терминала. Затем создайте файл `traefik.toml` со следующим содержимым: @@ -330,7 +330,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 ### Проверьте ответы { #check-the-responses } -Теперь, если вы перейдёте на URL с портом Uvicorn: http://127.0.0.1:8000/app, вы увидите обычный ответ: +Теперь, если вы перейдёте на URL с портом Uvicorn: [http://127.0.0.1:8000/app](http://127.0.0.1:8000/app), вы увидите обычный ответ: ```JSON { @@ -345,7 +345,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 /// -А теперь откройте URL с портом Traefik и префиксом пути: http://127.0.0.1:9999/api/v1/app. +А теперь откройте URL с портом Traefik и префиксом пути: [http://127.0.0.1:9999/api/v1/app](http://127.0.0.1:9999/api/v1/app). Мы получим тот же ответ: @@ -370,13 +370,13 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 «Официальный» способ доступа к приложению — через прокси с заданным префиксом пути. Поэтому, как и ожидается, если открыть интерфейс документации, отдаваемый напрямую Uvicorn, без префикса пути в URL, он не будет работать, так как предполагается доступ через прокси. -Проверьте по адресу http://127.0.0.1:8000/docs: +Проверьте по адресу [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs): А вот если открыть интерфейс документации по «официальному» URL через прокси на порту `9999`, по `/api/v1/docs`, всё работает корректно! 🎉 -Проверьте по адресу http://127.0.0.1:9999/api/v1/docs: +Проверьте по адресу [http://127.0.0.1:9999/api/v1/docs](http://127.0.0.1:9999/api/v1/docs): @@ -433,7 +433,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 /// -В интерфейсе документации по адресу http://127.0.0.1:9999/api/v1/docs это будет выглядеть так: +В интерфейсе документации по адресу [http://127.0.0.1:9999/api/v1/docs](http://127.0.0.1:9999/api/v1/docs) это будет выглядеть так: @@ -461,6 +461,6 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 ## Монтирование вложенного приложения { #mounting-a-sub-application } -Если вам нужно смонтировать вложенное приложение (как описано в [Вложенные приложения — монтирование](sub-applications.md){.internal-link target=_blank}), и при этом вы используете прокси с `root_path`, делайте это обычным образом — всё будет работать, как ожидается. +Если вам нужно смонтировать вложенное приложение (как описано в [Вложенные приложения — монтирование](sub-applications.md)), и при этом вы используете прокси с `root_path`, делайте это обычным образом — всё будет работать, как ожидается. FastAPI умно использует `root_path` внутри, так что всё просто работает. ✨ diff --git a/docs/ru/docs/advanced/custom-response.md b/docs/ru/docs/advanced/custom-response.md index b9f91373da..fdfe2c5498 100644 --- a/docs/ru/docs/advanced/custom-response.md +++ b/docs/ru/docs/advanced/custom-response.md @@ -1,52 +1,36 @@ # Кастомные ответы — HTML, поток, файл и другие { #custom-response-html-stream-file-others } -По умолчанию **FastAPI** возвращает ответы с помощью `JSONResponse`. +По умолчанию **FastAPI** возвращает ответы в формате JSON. -Вы можете переопределить это, вернув `Response` напрямую, как показано в разделе [Вернуть Response напрямую](response-directly.md){.internal-link target=_blank}. +Вы можете переопределить это, вернув `Response` напрямую, как показано в разделе [Вернуть Response напрямую](response-directly.md). Но если вы возвращаете `Response` напрямую (или любой его подкласс, например `JSONResponse`), данные не будут автоматически преобразованы (даже если вы объявили `response_model`), и документация не будет автоматически сгенерирована (например, со специфичным «типом содержимого» в HTTP-заголовке `Content-Type` как частью сгенерированного OpenAPI). -Но вы можете также объявить `Response`, который хотите использовать (например, любой подкласс `Response`), в декораторе операции пути, используя параметр `response_class`. +Но вы также можете объявить `Response`, который хотите использовать (например, любой подкласс `Response`), в декораторе операции пути, указав параметр `response_class`. Содержимое, которое вы возвращаете из своей функции-обработчика пути, будет помещено внутрь этого `Response`. -И если у этого `Response` тип содержимого JSON (`application/json`), как в случае с `JSONResponse` и `UJSONResponse`, данные, которые вы возвращаете, будут автоматически преобразованы (и отфильтрованы) любым объявленным вами в декораторе операции пути Pydantic `response_model`. - /// note | Примечание Если вы используете класс ответа без типа содержимого, FastAPI будет ожидать, что у вашего ответа нет содержимого, поэтому он не будет документировать формат ответа в сгенерированной документации OpenAPI. /// -## Используйте `ORJSONResponse` { #use-orjsonresponse } - -Например, если вы выжимаете максимум производительности, вы можете установить и использовать `orjson` и задать ответ как `ORJSONResponse`. - -Импортируйте класс (подкласс) `Response`, который вы хотите использовать, и объявите его в декораторе операции пути. - -Для больших ответов возвращать `Response` напрямую значительно быстрее, чем возвращать словарь. - -Это потому, что по умолчанию FastAPI проверяет каждый элемент внутри и убеждается, что он сериализуем в JSON, используя тот же [JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank}, объяснённый в руководстве. Это позволяет возвращать **произвольные объекты**, например модели из базы данных. - -Но если вы уверены, что содержимое, которое вы возвращаете, **сериализуемо в JSON**, вы можете передать его напрямую в класс ответа и избежать дополнительных накладных расходов, которые FastAPI понёс бы, пропуская возвращаемое содержимое через `jsonable_encoder` перед передачей в класс ответа. +## JSON-ответы { #json-responses } -{* ../../docs_src/custom_response/tutorial001b_py310.py hl[2,7] *} +По умолчанию FastAPI возвращает ответы в формате JSON. -/// info | Информация - -Параметр `response_class` также используется для указания «типа содержимого» ответа. +Если вы объявите [Модель ответа](../tutorial/response-model.md), FastAPI использует её для сериализации данных в JSON с помощью Pydantic. -В этом случае HTTP-заголовок `Content-Type` будет установлен в `application/json`. +Если вы не объявите модель ответа, FastAPI использует `jsonable_encoder`, описанный в разделе [JSON-совместимый энкодер](../tutorial/encoder.md), и поместит результат в `JSONResponse`. -И это будет задокументировано как таковое в OpenAPI. +Если вы объявите `response_class` с JSON типом содержимого (`application/json`), как в случае с `JSONResponse`, данные, которые вы возвращаете, будут автоматически преобразованы (и отфильтрованы) любой Pydantic-моделью ответа (`response_model`), объявленной вами в декораторе операции пути. Но данные не будут сериализованы в JSON-байты через Pydantic; вместо этого они будут преобразованы с помощью `jsonable_encoder`, а затем переданы в класс `JSONResponse`, который сериализует их в байты, используя стандартную JSON-библиотеку Python. -/// +### Производительность JSON { #json-performance } -/// tip | Совет +Коротко: если вам нужна максимальная производительность, используйте [Модель ответа](../tutorial/response-model.md) и не объявляйте `response_class` в декораторе операции пути. -`ORJSONResponse` доступен только в FastAPI, а не в Starlette. - -/// +{* ../../docs_src/response_model/tutorial001_01_py310.py ln[15:17] hl[16] *} ## HTML-ответ { #html-response } @@ -69,7 +53,7 @@ ### Вернуть `Response` { #return-a-response } -Как показано в разделе [Вернуть Response напрямую](response-directly.md){.internal-link target=_blank}, вы также можете переопределить ответ прямо в своей операции пути, просто вернув его. +Как показано в разделе [Вернуть Response напрямую](response-directly.md), вы также можете переопределить ответ прямо в своей операции пути, просто вернув его. Тот же пример сверху, возвращающий `HTMLResponse`, может выглядеть так: @@ -154,37 +138,11 @@ FastAPI (фактически Starlette) автоматически добави Это ответ по умолчанию, используемый в **FastAPI**, как было сказано выше. -### `ORJSONResponse` { #orjsonresponse } - -Быстрая альтернативная реализация JSON-ответа с использованием `orjson`, как было сказано выше. - -/// info | Информация - -Требуется установка `orjson`, например командой `pip install orjson`. - -/// - -### `UJSONResponse` { #ujsonresponse } - -Альтернативная реализация JSON-ответа с использованием `ujson`. - -/// info | Информация - -Требуется установка `ujson`, например командой `pip install ujson`. - -/// - -/// warning | Предупреждение - -`ujson` менее аккуратен, чем встроенная реализация Python, в обработке некоторых крайних случаев. - -/// - -{* ../../docs_src/custom_response/tutorial001_py310.py hl[2,7] *} +/// note | Технические детали -/// tip | Совет +Но если вы объявите модель ответа или тип возвращаемого значения, они будут использованы напрямую для сериализации данных в JSON, и ответ с корректным типом содержимого для JSON будет возвращён напрямую, без использования класса `JSONResponse`. -Возможно, `ORJSONResponse` окажется более быстрым вариантом. +Это идеальный способ получить наилучшую производительность. /// @@ -214,31 +172,25 @@ FastAPI (фактически Starlette) автоматически добави ### `StreamingResponse` { #streamingresponse } -Принимает асинхронный генератор или обычный генератор/итератор и отправляет тело ответа потоково. - -{* ../../docs_src/custom_response/tutorial007_py310.py hl[2,14] *} - -#### Использование `StreamingResponse` с файлоподобными объектами { #using-streamingresponse-with-file-like-objects } +Принимает асинхронный генератор или обычный генератор/итератор (функцию с `yield`) и отправляет тело ответа потоково. -Если у вас есть файлоподобный объект (например, объект, возвращаемый `open()`), вы можете создать функцию-генератор для итерации по этому файлоподобному объекту. +{* ../../docs_src/custom_response/tutorial007_py310.py hl[3,16] *} -Таким образом, вам не нужно сначала читать всё в память, вы можете передать эту функцию-генератор в `StreamingResponse` и вернуть его. - -Это включает многие библиотеки для работы с облачным хранилищем, обработки видео и т.д. +/// note | Технические детали -{* ../../docs_src/custom_response/tutorial008_py310.py hl[2,10:12,14] *} +Задача `async` может быть отменена только при достижении `await`. Если `await` отсутствует, генератор (функция с `yield`) не может быть корректно отменён и может продолжить работу даже после запроса на отмену. -1. Это функция-генератор. Она является «функцией-генератором», потому что содержит оператор(ы) `yield` внутри. -2. Используя блок `with`, мы гарантируем, что файлоподобный объект будет закрыт после завершения работы функции-генератора. То есть после того, как она закончит отправку ответа. -3. Этот `yield from` говорит функции итерироваться по объекту с именем `file_like`. И затем, для каждой итерации, отдавать эту часть как исходящую из этой функции-генератора (`iterfile`). +Так как этому небольшому примеру не нужны операторы `await`, мы добавляем `await anyio.sleep(0)`, чтобы дать циклу событий возможность обработать отмену. - Таким образом, это функция-генератор, которая внутренне передаёт работу по «генерации» чему-то другому. +Это ещё более важно для больших или бесконечных потоков. - Делая это таким образом, мы можем поместить её в блок `with` и тем самым гарантировать, что файлоподобный объект будет закрыт после завершения. +/// /// tip | Совет -Заметьте, что здесь мы используем стандартный `open()`, который не поддерживает `async` и `await`, поэтому объявляем операцию пути обычной `def`. +Вместо того чтобы возвращать `StreamingResponse` напрямую, вероятно, лучше следовать стилю из раздела [Передача данных потоком](./stream-data.md) - так гораздо удобнее, и отмена обрабатывается «за кулисами». + +Если вы передаёте JSON Lines потоком, следуйте руководству [Поток JSON Lines](../tutorial/stream-json-lines.md). /// @@ -267,7 +219,7 @@ FastAPI (фактически Starlette) автоматически добави Вы можете создать собственный класс ответа, унаследовавшись от `Response`, и использовать его. -Например, предположим, что вы хотите использовать `orjson`, но с некоторыми пользовательскими настройками, которые не используются во встроенном классе `ORJSONResponse`. +Например, предположим, что вы хотите использовать [`orjson`](https://github.com/ijl/orjson) с некоторыми настройками. Скажем, вы хотите, чтобы возвращался отформатированный JSON с отступами, то есть хотите использовать опцию orjson `orjson.OPT_INDENT_2`. @@ -291,13 +243,21 @@ FastAPI (фактически Starlette) автоматически добави Разумеется, вы наверняка найдёте гораздо более полезные способы воспользоваться этим, чем просто форматирование JSON. 😉 +### `orjson` или Модель ответа { #orjson-or-response-model } + +Если вы стремитесь увеличить производительность, вероятно, лучше использовать [Модель ответа](../tutorial/response-model.md), чем ответ на базе `orjson`. + +С моделью ответа FastAPI использует Pydantic для сериализации данных в JSON, без промежуточных шагов, таких как преобразование через `jsonable_encoder`, которое происходило бы в любом другом случае. + +А под капотом Pydantic использует те же базовые механизмы на Rust, что и `orjson`, для сериализации в JSON, так что с моделью ответа вы и так получите лучшую производительность. + ## Класс ответа по умолчанию { #default-response-class } При создании экземпляра класса **FastAPI** или `APIRouter` вы можете указать, какой класс ответа использовать по умолчанию. Параметр, который это определяет, — `default_response_class`. -В примере ниже **FastAPI** будет использовать `ORJSONResponse` по умолчанию во всех операциях пути вместо `JSONResponse`. +В примере ниже **FastAPI** будет использовать `HTMLResponse` по умолчанию во всех операциях пути, вместо JSON. {* ../../docs_src/custom_response/tutorial010_py310.py hl[2,4] *} @@ -309,4 +269,4 @@ FastAPI (фактически Starlette) автоматически добави ## Дополнительная документация { #additional-documentation } -Вы также можете объявить тип содержимого и многие другие детали в OpenAPI с помощью `responses`: [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}. +Вы также можете объявить тип содержимого и многие другие детали в OpenAPI с помощью `responses`: [Дополнительные ответы в OpenAPI](additional-responses.md). diff --git a/docs/ru/docs/advanced/dataclasses.md b/docs/ru/docs/advanced/dataclasses.md index 87a5763c10..f9f8689b04 100644 --- a/docs/ru/docs/advanced/dataclasses.md +++ b/docs/ru/docs/advanced/dataclasses.md @@ -2,11 +2,11 @@ FastAPI построен поверх **Pydantic**, и я показывал вам, как использовать Pydantic-модели для объявления HTTP-запросов и HTTP-ответов. -Но FastAPI также поддерживает использование `dataclasses` тем же способом: +Но FastAPI также поддерживает использование [`dataclasses`](https://docs.python.org/3/library/dataclasses.html) тем же способом: {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -Это по-прежнему поддерживается благодаря **Pydantic**, так как в нём есть встроенная поддержка `dataclasses`. +Это по-прежнему поддерживается благодаря **Pydantic**, так как в нём есть [встроенная поддержка `dataclasses`](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel). Так что даже если в коде выше Pydantic не используется явно, FastAPI использует Pydantic, чтобы конвертировать стандартные dataclasses в собственный вариант dataclasses от Pydantic. @@ -74,7 +74,7 @@ FastAPI построен поверх **Pydantic**, и я показывал в Как и всегда в FastAPI, вы можете сочетать `def` и `async def` по необходимости. - Если хотите освежить в памяти, когда что использовать, посмотрите раздел _"Нет времени?"_ в документации про [`async` и `await`](../async.md#in-a-hurry){.internal-link target=_blank}. + Если хотите освежить в памяти, когда что использовать, посмотрите раздел _"Нет времени?"_ в документации про [`async` и `await`](../async.md#in-a-hurry). 9. Эта *функция-обработчик пути* возвращает не dataclasses (хотя могла бы), а список словарей с внутренними данными. @@ -88,7 +88,7 @@ FastAPI построен поверх **Pydantic**, и я показывал в Вы также можете комбинировать `dataclasses` с другими Pydantic-моделями, наследоваться от них, включать их в свои модели и т.д. -Чтобы узнать больше, посмотрите документацию Pydantic о dataclasses. +Чтобы узнать больше, посмотрите [документацию Pydantic о dataclasses](https://docs.pydantic.dev/latest/concepts/dataclasses/). ## Версия { #version } diff --git a/docs/ru/docs/advanced/events.md b/docs/ru/docs/advanced/events.md index bcb5b000a4..464bba93e9 100644 --- a/docs/ru/docs/advanced/events.md +++ b/docs/ru/docs/advanced/events.md @@ -150,11 +150,11 @@ async with lifespan(app): Немного технических подробностей для любопытных умников. 🤓 -Под капотом, в ASGI-технической спецификации, это часть Протокола Lifespan, и он определяет события `startup` и `shutdown`. +Под капотом, в ASGI-технической спецификации, это часть [Протокола Lifespan](https://asgi.readthedocs.io/en/latest/specs/lifespan.html), и он определяет события `startup` и `shutdown`. /// info | Информация -Вы можете прочитать больше про обработчики `lifespan` в Starlette в документации Starlette по Lifespan. +Вы можете прочитать больше про обработчики `lifespan` в Starlette в [документации Starlette по Lifespan](https://www.starlette.dev/lifespan/). Включая то, как работать с состоянием lifespan, которое можно использовать в других частях вашего кода. @@ -162,4 +162,4 @@ async with lifespan(app): ## Подприложения { #sub-applications } -🚨 Имейте в виду, что эти события lifespan (startup и shutdown) будут выполнены только для основного приложения, а не для [Подприложения — Mounts](sub-applications.md){.internal-link target=_blank}. +🚨 Имейте в виду, что эти события lifespan (startup и shutdown) будут выполнены только для основного приложения, а не для [Подприложения — Mounts](sub-applications.md). diff --git a/docs/ru/docs/advanced/generate-clients.md b/docs/ru/docs/advanced/generate-clients.md index 4eb098a88f..75bd7c47c4 100644 --- a/docs/ru/docs/advanced/generate-clients.md +++ b/docs/ru/docs/advanced/generate-clients.md @@ -8,11 +8,11 @@ ## Генераторы SDK с открытым исходным кодом { #open-source-sdk-generators } -Гибкий вариант — OpenAPI Generator, который поддерживает **многие языки программирования** и умеет генерировать SDK из вашей спецификации OpenAPI. +Гибкий вариант — [OpenAPI Generator](https://openapi-generator.tech/), который поддерживает **многие языки программирования** и умеет генерировать SDK из вашей спецификации OpenAPI. -Для **TypeScript‑клиентов** Hey API — специализированное решение, обеспечивающее оптимальный опыт для экосистемы TypeScript. +Для **TypeScript‑клиентов** [Hey API](https://heyapi.dev/) — специализированное решение, обеспечивающее оптимальный опыт для экосистемы TypeScript. -Больше генераторов SDK можно найти на OpenAPI.Tools. +Больше генераторов SDK можно найти на [OpenAPI.Tools](https://openapi.tools/#sdk). /// tip | Совет @@ -24,15 +24,15 @@ FastAPI автоматически генерирует спецификации В этом разделе представлены решения с **венчурной поддержкой** и **поддержкой компаний** от компаний, которые спонсируют FastAPI. Эти продукты предоставляют **дополнительные возможности** и **интеграции** сверх высококачественно генерируемых SDK. -Благодаря ✨ [**спонсорству FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨ эти компании помогают обеспечивать, чтобы фреймворк и его **экосистема** оставались здоровыми и **устойчивыми**. +Благодаря ✨ [**спонсорству FastAPI**](../help-fastapi.md#sponsor-the-author) ✨ эти компании помогают обеспечивать, чтобы фреймворк и его **экосистема** оставались здоровыми и **устойчивыми**. Их спонсорство также демонстрирует серьёзную приверженность **сообществу** FastAPI (вам), показывая, что им важно не только предоставлять **отличный сервис**, но и поддерживать **надёжный и процветающий фреймворк** FastAPI. 🙇 Например, вы можете попробовать: -* Speakeasy -* Stainless -* liblab +* [Speakeasy](https://speakeasy.com/editor?utm_source=fastapi+repo&utm_medium=github+sponsorship) +* [Stainless](https://www.stainless.com/?utm_source=fastapi&utm_medium=referral) +* [liblab](https://developers.liblab.com/tutorials/sdk-for-fastapi?utm_source=fastapi) Некоторые из этих решений также могут быть open source или иметь бесплатные тарифы, так что вы сможете попробовать их без финансовых затрат. Другие коммерческие генераторы SDK доступны и их можно найти онлайн. 🤓 @@ -66,11 +66,11 @@ npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client Это сгенерирует TypeScript SDK в `./src/client`. -Вы можете узнать, как установить `@hey-api/openapi-ts` и почитать о сгенерированном результате на их сайте. +Вы можете узнать, как [установить `@hey-api/openapi-ts`](https://heyapi.dev/openapi-ts/get-started) и почитать о [сгенерированном результате](https://heyapi.dev/openapi-ts/output) на их сайте. ### Использование SDK { #using-the-sdk } -Теперь вы можете импортировать и использовать клиентский код. Это может выглядеть так, обратите внимание, что вы получаете автозавершение для методoв: +Теперь вы можете импортировать и использовать клиентский код. Это может выглядеть так, обратите внимание, что вы получаете автозавершение для методов: diff --git a/docs/ru/docs/advanced/index.md b/docs/ru/docs/advanced/index.md index c0a52c6c14..6cb92dd004 100644 --- a/docs/ru/docs/advanced/index.md +++ b/docs/ru/docs/advanced/index.md @@ -2,7 +2,7 @@ ## Дополнительные возможности { #additional-features } -Основное [Учебник - Руководство пользователя](../tutorial/index.md){.internal-link target=_blank} должно быть достаточно, чтобы познакомить вас со всеми основными функциями **FastAPI**. +Основное [Учебник - Руководство пользователя](../tutorial/index.md) должно быть достаточно, чтобы познакомить вас со всеми основными функциями **FastAPI**. В следующих разделах вы увидите другие варианты, конфигурации и дополнительные возможности. @@ -16,6 +16,6 @@ ## Сначала прочитайте Учебник - Руководство пользователя { #read-the-tutorial-first } -Вы все еще можете использовать большинство функций **FastAPI** со знаниями из [Учебник - Руководство пользователя](../tutorial/index.md){.internal-link target=_blank}. +Вы все еще можете использовать большинство функций **FastAPI** со знаниями из [Учебник - Руководство пользователя](../tutorial/index.md). И следующие разделы предполагают, что вы уже прочитали его, и предполагают, что вы знаете эти основные идеи. diff --git a/docs/ru/docs/advanced/middleware.md b/docs/ru/docs/advanced/middleware.md index 1f1a160604..805866499c 100644 --- a/docs/ru/docs/advanced/middleware.md +++ b/docs/ru/docs/advanced/middleware.md @@ -1,8 +1,8 @@ # Расширенное использование middleware { #advanced-middleware } -В основном руководстве вы читали, как добавить [пользовательское middleware](../tutorial/middleware.md){.internal-link target=_blank} в ваше приложение. +В основном руководстве вы читали, как добавить [пользовательское middleware](../tutorial/middleware.md) в ваше приложение. -А затем — как работать с [CORS с помощью `CORSMiddleware`](../tutorial/cors.md){.internal-link target=_blank}. +А затем — как работать с [CORS с помощью `CORSMiddleware`](../tutorial/cors.md). В этом разделе посмотрим, как использовать другие middleware. @@ -91,7 +91,7 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") Например: -- `ProxyHeadersMiddleware` от Uvicorn -- MessagePack +- [`ProxyHeadersMiddleware` от Uvicorn](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) +- [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -Чтобы увидеть другие доступные middleware, посмотрите документацию по middleware в Starlette и список ASGI Awesome. +Чтобы увидеть другие доступные middleware, посмотрите [документацию по middleware в Starlette](https://www.starlette.dev/middleware/) и [список ASGI Awesome](https://github.com/florimondmanca/awesome-asgi). diff --git a/docs/ru/docs/advanced/openapi-callbacks.md b/docs/ru/docs/advanced/openapi-callbacks.md index de7e283017..3d791de2c6 100644 --- a/docs/ru/docs/advanced/openapi-callbacks.md +++ b/docs/ru/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ /// tip | Совет -Query-параметр `callback_url` использует тип Pydantic Url. +Query-параметр `callback_url` использует тип Pydantic [Url](https://docs.pydantic.dev/latest/api/networks/). /// @@ -66,7 +66,7 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) Сам обратный вызов — это всего лишь HTTP-запрос. -Реализуя обратный вызов, вы можете использовать, например, HTTPX или Requests. +Реализуя обратный вызов, вы можете использовать, например, [HTTPX](https://www.python-httpx.org) или [Requests](https://requests.readthedocs.io/). /// @@ -106,11 +106,11 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) Есть 2 основных отличия от обычной *операции пути*: * Ей не нужен реальный код, потому что ваше приложение никогда не будет вызывать эту функцию. Она используется только для документирования *внешнего API*. Поэтому в функции может быть просто `pass`. -* *Путь* может содержать выражение OpenAPI 3 (подробнее ниже), где можно использовать переменные с параметрами и части исходного HTTP-запроса, отправленного *вашему API*. +* *Путь* может содержать [выражение OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) (подробнее ниже), где можно использовать переменные с параметрами и части исходного HTTP-запроса, отправленного *вашему API*. ### Выражение пути для обратного вызова { #the-callback-path-expression } -*Путь* обратного вызова может содержать выражение OpenAPI 3, которое может включать части исходного запроса, отправленного *вашему API*. +*Путь* обратного вызова может содержать [выражение OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression), которое может включать части исходного запроса, отправленного *вашему API*. В нашем случае это `str`: @@ -179,7 +179,7 @@ https://www.external.org/events/invoices/2expen51ve ### Проверьте документацию { #check-the-docs } -Теперь вы можете запустить приложение и перейти по адресу http://127.0.0.1:8000/docs. +Теперь вы можете запустить приложение и перейти по адресу [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). Вы увидите документацию, включающую раздел «Callbacks» для вашей *операции пути*, который показывает, как должен выглядеть *внешний API*: diff --git a/docs/ru/docs/advanced/openapi-webhooks.md b/docs/ru/docs/advanced/openapi-webhooks.md index b477075c11..9b1988ff31 100644 --- a/docs/ru/docs/advanced/openapi-webhooks.md +++ b/docs/ru/docs/advanced/openapi-webhooks.md @@ -10,7 +10,7 @@ Обычно процесс таков: вы определяете в своем коде, какое сообщение вы будете отправлять, то есть тело запроса. -Вы также определяете, в какие моменты (при каких событиях) ваше приложение будет отправлять эти запросы. +Вы также определяете, в какие моменты (при каких событиях) ваше приложение будет отправлять эти запросы (события). А ваши пользователи каким-то образом (например, в веб‑панели) указывают URL-адрес, на который ваше приложение должно отправлять эти запросы. @@ -48,7 +48,7 @@ ### Посмотрите документацию { #check-the-docs } -Теперь вы можете запустить приложение и перейти по ссылке http://127.0.0.1:8000/docs. +Теперь вы можете запустить приложение и перейти по ссылке [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). Вы увидите, что в документации есть обычные операции пути, а также появились вебхуки: diff --git a/docs/ru/docs/advanced/path-operation-advanced-configuration.md b/docs/ru/docs/advanced/path-operation-advanced-configuration.md index b8c879bf6f..fe2996362b 100644 --- a/docs/ru/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/ru/docs/advanced/path-operation-advanced-configuration.md @@ -60,7 +60,7 @@ Также можно объявлять дополнительные ответы с их моделями, статус-кодами и т.д. -В документации есть целая глава об этом — [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}. +В документации есть целая глава об этом — [Дополнительные ответы в OpenAPI](additional-responses.md). ## Дополнительные данные OpenAPI { #openapi-extra } @@ -68,7 +68,7 @@ /// note | Технические детали -В спецификации OpenAPI это называется Объект операции. +В спецификации OpenAPI это называется [Объект операции](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object). /// @@ -82,7 +82,7 @@ Это низкоуровневая возможность расширения. -Если вам нужно лишь объявить дополнительные ответы, удобнее сделать это через [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}. +Если вам нужно лишь объявить дополнительные ответы, удобнее сделать это через [Дополнительные ответы в OpenAPI](additional-responses.md). /// diff --git a/docs/ru/docs/advanced/response-change-status-code.md b/docs/ru/docs/advanced/response-change-status-code.md index 273862bae9..3dd0c9446e 100644 --- a/docs/ru/docs/advanced/response-change-status-code.md +++ b/docs/ru/docs/advanced/response-change-status-code.md @@ -1,6 +1,6 @@ # Response - Изменение статус-кода { #response-change-status-code } -Вы, вероятно, уже читали о том, что можно установить [статус-код ответа по умолчанию](../tutorial/response-status-code.md){.internal-link target=_blank}. +Вы, вероятно, уже читали о том, что можно установить [статус-код ответа по умолчанию](../tutorial/response-status-code.md). Но в некоторых случаях нужно вернуть другой статус-код, отличный от значения по умолчанию. diff --git a/docs/ru/docs/advanced/response-cookies.md b/docs/ru/docs/advanced/response-cookies.md index d3662ef8ed..2adc1af85a 100644 --- a/docs/ru/docs/advanced/response-cookies.md +++ b/docs/ru/docs/advanced/response-cookies.md @@ -20,7 +20,7 @@ Вы также можете установить Cookies, если возвращаете `Response` напрямую в вашем коде. -Для этого создайте объект `Response`, как описано в разделе [Возвращение ответа напрямую](response-directly.md){.internal-link target=_blank}. +Для этого создайте объект `Response`, как описано в разделе [Возвращение ответа напрямую](response-directly.md). Затем установите cookies и верните этот объект: @@ -48,4 +48,4 @@ /// -Чтобы увидеть все доступные параметры и настройки, ознакомьтесь с документацией Starlette. +Чтобы увидеть все доступные параметры и настройки, ознакомьтесь с [документацией Starlette](https://www.starlette.dev/responses/#set-cookie). diff --git a/docs/ru/docs/advanced/response-directly.md b/docs/ru/docs/advanced/response-directly.md index 60facdd857..4269b6bdfb 100644 --- a/docs/ru/docs/advanced/response-directly.md +++ b/docs/ru/docs/advanced/response-directly.md @@ -2,19 +2,23 @@ Когда вы создаёте **FastAPI** *операцию пути*, вы можете возвращать из неё любые данные: `dict`, `list`, Pydantic-модель, модель базы данных и т.д. -По умолчанию **FastAPI** автоматически преобразует возвращаемое значение в JSON с помощью `jsonable_encoder`, как описано в [JSON кодировщик](../tutorial/encoder.md){.internal-link target=_blank}. +Если вы объявите [Модель ответа](../tutorial/response-model.md), FastAPI будет использовать её для сериализации данных в JSON с помощью Pydantic. -Затем "под капотом" эти данные, совместимые с JSON (например `dict`), помещаются в `JSONResponse`, который используется для отправки ответа клиенту. +Если вы не объявите модель ответа, FastAPI использует `jsonable_encoder`, как описано в [JSON кодировщик](../tutorial/encoder.md){.internal-link target=_blank}, и поместит результат в `JSONResponse`. -Но вы можете возвращать `JSONResponse` напрямую из ваших *операций пути*. +Также вы можете создать `JSONResponse` напрямую и вернуть его. -Это может быть полезно, например, если нужно вернуть пользовательские HTTP-заголовки или cookie. +/// tip | Подсказка + +Обычно вы получите значительно лучшую производительность, если будете использовать [Модель ответа](../tutorial/response-model.md), а не возвращать `JSONResponse` напрямую, так как в этом случае сериализация данных с помощью Pydantic происходит на стороне Rust. + +/// ## Возврат `Response` { #return-a-response } -На самом деле, вы можете возвращать любой объект `Response` или его подкласс. +Вы можете возвращать `Response` или любой его подкласс. -/// tip | Подсказка +/// info | Информация `JSONResponse` сам по себе является подклассом `Response`. @@ -26,6 +30,8 @@ Это даёт вам большую гибкость. Вы можете возвращать любые типы данных, переопределять любые объявления или валидацию данных и т.д. +Это также накладывает на вас ответственность. Вам нужно удостовериться, что возвращаемые данные корректны, в правильном формате, что их можно сериализовать и т.д. + ## Использование `jsonable_encoder` в `Response` { #using-the-jsonable-encoder-in-a-response } Поскольку **FastAPI** не изменяет объект `Response`, который вы возвращаете, вы должны убедиться, что его содержимое готово к отправке. @@ -50,12 +56,24 @@ Теперь давайте посмотрим, как можно использовать это для возврата пользовательского ответа. -Допустим, вы хотите вернуть ответ в формате XML. +Допустим, вы хотите вернуть ответ в формате [XML](https://en.wikipedia.org/wiki/XML). Вы можете поместить ваш XML-контент в строку, поместить её в `Response` и вернуть: {* ../../docs_src/response_directly/tutorial002_py310.py hl[1,18] *} +## Как работает модель ответа { #how-a-response-model-works } + +Когда вы объявляете [Модель ответа - возвращаемый тип](../tutorial/response-model.md) в операции пути, **FastAPI** будет использовать её для сериализации данных в JSON с помощью Pydantic. + +{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *} + +Поскольку это происходит на стороне Rust, производительность будет значительно выше, чем если бы это выполнялось обычным Python и классом `JSONResponse`. + +При использовании `response_model` или возвращаемого типа FastAPI не будет использовать `jsonable_encoder` для преобразования данных (что было бы медленнее) и не будет использовать класс `JSONResponse`. + +Вместо этого он берёт JSON-байты, сгенерированные Pydantic с использованием модели ответа (или возвращаемого типа), и возвращает `Response` с правильным типом содержимого для JSON (`application/json`) напрямую. + ## Примечания { #notes } Когда вы возвращаете объект `Response` напрямую, его данные не валидируются, не преобразуются (не сериализуются) и не документируются автоматически. diff --git a/docs/ru/docs/advanced/response-headers.md b/docs/ru/docs/advanced/response-headers.md index dc821983bc..806b89e1f8 100644 --- a/docs/ru/docs/advanced/response-headers.md +++ b/docs/ru/docs/advanced/response-headers.md @@ -20,7 +20,7 @@ Вы также можете добавить HTTP-заголовки, когда возвращаете `Response` напрямую. -Создайте ответ, как описано в [Вернуть Response напрямую](response-directly.md){.internal-link target=_blank}, и передайте заголовки как дополнительный параметр: +Создайте ответ, как описано в [Вернуть Response напрямую](response-directly.md), и передайте заголовки как дополнительный параметр: {* ../../docs_src/response_headers/tutorial001_py310.py hl[10:12] *} @@ -36,6 +36,6 @@ ## Пользовательские HTTP-заголовки { #custom-headers } -Помните, что собственные проприетарные заголовки можно добавлять, используя префикс `X-`. +Помните, что собственные проприетарные заголовки можно добавлять, [используя префикс `X-`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). -Но если у вас есть пользовательские заголовки, которые вы хотите показывать клиенту в браузере, вам нужно добавить их в настройки CORS (подробнее см. в [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}), используя параметр `expose_headers`, описанный в документации Starlette по CORS. +Но если у вас есть пользовательские заголовки, которые вы хотите показывать клиенту в браузере, вам нужно добавить их в настройки CORS (подробнее см. в [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)), используя параметр `expose_headers`, описанный в [документации Starlette по CORS](https://www.starlette.dev/middleware/#corsmiddleware). diff --git a/docs/ru/docs/advanced/security/http-basic-auth.md b/docs/ru/docs/advanced/security/http-basic-auth.md index a6bfb7c546..b094fec773 100644 --- a/docs/ru/docs/advanced/security/http-basic-auth.md +++ b/docs/ru/docs/advanced/security/http-basic-auth.md @@ -32,7 +32,7 @@ Используйте зависимость, чтобы проверить, корректны ли имя пользователя и пароль. -Для этого используйте стандартный модуль Python `secrets` для проверки имени пользователя и пароля. +Для этого используйте стандартный модуль Python [`secrets`](https://docs.python.org/3/library/secrets.html) для проверки имени пользователя и пароля. `secrets.compare_digest()` должен получать `bytes` или `str`, который содержит только символы ASCII (английские символы). Это значит, что он не будет работать с символами вроде `á`, как в `Sebastián`. diff --git a/docs/ru/docs/advanced/security/index.md b/docs/ru/docs/advanced/security/index.md index 912e4812a5..89a7236d81 100644 --- a/docs/ru/docs/advanced/security/index.md +++ b/docs/ru/docs/advanced/security/index.md @@ -2,11 +2,11 @@ ## Дополнительные возможности { #additional-features } -Есть дополнительные возможности для работы с безопасностью помимо тех, что описаны в [Учебник — Руководство пользователя: Безопасность](../../tutorial/security/index.md){.internal-link target=_blank}. +Есть дополнительные возможности для работы с безопасностью помимо тех, что описаны в [Учебник — Руководство пользователя: Безопасность](../../tutorial/security/index.md). /// tip | Совет -Следующие разделы **не обязательно являются «продвинутыми»**. +Следующие разделы не обязательно являются «продвинутыми». И возможно, что решение для вашего варианта использования находится в одном из них. @@ -14,6 +14,6 @@ ## Сначала прочитайте руководство { #read-the-tutorial-first } -В следующих разделах предполагается, что вы уже прочитали основной [Учебник — Руководство пользователя: Безопасность](../../tutorial/security/index.md){.internal-link target=_blank}. +В следующих разделах предполагается, что вы уже прочитали основной [Учебник — Руководство пользователя: Безопасность](../../tutorial/security/index.md). Все они основаны на тех же концепциях, но предоставляют дополнительные возможности. diff --git a/docs/ru/docs/advanced/security/oauth2-scopes.md b/docs/ru/docs/advanced/security/oauth2-scopes.md index 8788df1991..944baeeeb6 100644 --- a/docs/ru/docs/advanced/security/oauth2-scopes.md +++ b/docs/ru/docs/advanced/security/oauth2-scopes.md @@ -1,6 +1,6 @@ # OAuth2 scopes { #oauth2-scopes } -Вы можете использовать OAuth2 scopes (scope - область, рамки) напрямую с **FastAPI** — они интегрированы и работают бесшовно. +Вы можете использовать OAuth2 scopes напрямую с **FastAPI** — они интегрированы и работают бесшовно. Это позволит вам иметь более детальную систему разрешений по стандарту OAuth2, интегрированную в ваше OpenAPI‑приложение (и документацию API). @@ -60,7 +60,7 @@ OAuth2 со scopes — это механизм, который использу ## Взгляд издалека { #global-view } -Сначала быстро посмотрим, что изменилось по сравнению с примерами из основного раздела **Учебник - Руководство пользователя** — [OAuth2 с паролем (и хешированием), Bearer с JWT-токенами](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. Теперь — с использованием OAuth2 scopes: +Сначала быстро посмотрим, что изменилось по сравнению с примерами из основного раздела **Учебник - Руководство пользователя** — [OAuth2 с паролем (и хешированием), Bearer с JWT-токенами](../../tutorial/security/oauth2-jwt.md). Теперь — с использованием OAuth2 scopes: {* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *} @@ -267,8 +267,8 @@ OAuth2 со scopes — это механизм, который использу /// -FastAPI включает утилиты для всех этих OAuth2‑flows в `fastapi.security.oauth2`. +**FastAPI** включает утилиты для всех этих OAuth2‑flows в `fastapi.security.oauth2`. ## `Security` в параметре `dependencies` декоратора { #security-in-decorator-dependencies } -Точно так же, как вы можете определить `list` из `Depends` в параметре `dependencies` декоратора (см. [Зависимости в декораторах операции пути](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}), вы можете использовать там и `Security` со `scopes`. +Точно так же, как вы можете определить `list` из `Depends` в параметре `dependencies` декоратора (см. [Зависимости в декораторах операции пути](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md)), вы можете использовать там и `Security` со `scopes`. diff --git a/docs/ru/docs/advanced/settings.md b/docs/ru/docs/advanced/settings.md index 15537e2b40..3ae063340b 100644 --- a/docs/ru/docs/advanced/settings.md +++ b/docs/ru/docs/advanced/settings.md @@ -8,7 +8,7 @@ /// tip | Совет -Чтобы понять, что такое переменные окружения, вы можете прочитать [Переменные окружения](../environment-variables.md){.internal-link target=_blank}. +Чтобы понять, что такое переменные окружения, вы можете прочитать [Переменные окружения](../environment-variables.md). /// @@ -20,11 +20,11 @@ ## Pydantic `Settings` { #pydantic-settings } -К счастью, Pydantic предоставляет отличную утилиту для работы с этими настройками, поступающими из переменных окружения, — Pydantic: управление настройками. +К счастью, Pydantic предоставляет отличную утилиту для работы с этими настройками, поступающими из переменных окружения, — [Pydantic: управление настройками](https://docs.pydantic.dev/latest/concepts/pydantic_settings/). ### Установка `pydantic-settings` { #install-pydantic-settings } -Сначала убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его, а затем установили пакет `pydantic-settings`: +Сначала убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его, а затем установили пакет `pydantic-settings`:
@@ -100,7 +100,7 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p ## Настройки в другом модуле { #settings-in-another-module } -Вы можете вынести эти настройки в другой модуль, как показано в разделе [Большие приложения — несколько файлов](../tutorial/bigger-applications.md){.internal-link target=_blank}. +Вы можете вынести эти настройки в другой модуль, как показано в разделе [Большие приложения — несколько файлов](../tutorial/bigger-applications.md). Например, у вас может быть файл `config.py` со следующим содержимым: @@ -112,7 +112,7 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// tip | Совет -Вам также понадобится файл `__init__.py`, как в разделе [Большие приложения — несколько файлов](../tutorial/bigger-applications.md){.internal-link target=_blank}. +Вам также понадобится файл `__init__.py`, как в разделе [Большие приложения — несколько файлов](../tutorial/bigger-applications.md). /// @@ -172,7 +172,7 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// -Pydantic поддерживает чтение таких файлов с помощью внешней библиотеки. Подробнее вы можете прочитать здесь: Pydantic Settings: поддержка Dotenv (.env). +Pydantic поддерживает чтение таких файлов с помощью внешней библиотеки. Подробнее вы можете прочитать здесь: [Pydantic Settings: поддержка Dotenv (.env)](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support). /// tip | Совет @@ -197,7 +197,7 @@ APP_NAME="ChimichangApp" /// tip | Совет -Атрибут `model_config` используется только для конфигурации Pydantic. Подробнее см. Pydantic: Concepts: Configuration. +Атрибут `model_config` используется только для конфигурации Pydantic. Подробнее см. [Pydantic: Concepts: Configuration](https://docs.pydantic.dev/latest/concepts/config/). /// @@ -291,7 +291,7 @@ participant execute as Execute function Таким образом, она ведет себя почти как глобальная переменная. Но так как используется функция‑зависимость, мы можем легко переопределить ее для тестирования. -`@lru_cache` — часть `functools`, что входит в стандартную библиотеку Python. Подробнее можно прочитать в документации Python по `@lru_cache`. +`@lru_cache` — часть `functools`, что входит в стандартную библиотеку Python. Подробнее можно прочитать в [документации Python по `@lru_cache`](https://docs.python.org/3/library/functools.html#functools.lru_cache). ## Итоги { #recap } diff --git a/docs/ru/docs/advanced/sub-applications.md b/docs/ru/docs/advanced/sub-applications.md index 4fd5649ce3..37257e0f3b 100644 --- a/docs/ru/docs/advanced/sub-applications.md +++ b/docs/ru/docs/advanced/sub-applications.md @@ -30,25 +30,25 @@ ### Проверьте автоматическую документацию API { #check-the-automatic-api-docs } -Теперь запустите команду `fastapi` с вашим файлом: +Теперь запустите команду `fastapi`:
```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
-И откройте документацию по адресу http://127.0.0.1:8000/docs. +И откройте документацию по адресу [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). Вы увидите автоматическую документацию API для основного приложения, включающую только его собственные _операции пути_: -Затем откройте документацию для подприложения по адресу http://127.0.0.1:8000/subapi/docs. +Затем откройте документацию для подприложения по адресу [http://127.0.0.1:8000/subapi/docs](http://127.0.0.1:8000/subapi/docs). Вы увидите автоматическую документацию API для подприложения, включающую только его собственные _операции пути_, все под корректным префиксом подпути `/subapi`: @@ -64,4 +64,4 @@ $ fastapi dev main.py У подприложения также могут быть свои собственные смонтированные подприложения, и всё будет работать корректно, потому что FastAPI автоматически обрабатывает все эти `root_path`. -Вы узнаете больше о `root_path` и о том, как использовать его явно, в разделе [За прокси](behind-a-proxy.md){.internal-link target=_blank}. +Вы узнаете больше о `root_path` и о том, как использовать его явно, в разделе [За прокси](behind-a-proxy.md). diff --git a/docs/ru/docs/advanced/templates.md b/docs/ru/docs/advanced/templates.md index 68adcb5151..5fc938eec2 100644 --- a/docs/ru/docs/advanced/templates.md +++ b/docs/ru/docs/advanced/templates.md @@ -8,7 +8,7 @@ ## Установка зависимостей { #install-dependencies } -Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его и установили `jinja2`: +Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его и установили `jinja2`:
@@ -123,4 +123,4 @@ Item ID: 42 ## Подробнее { #more-details } -Больше подробностей, включая то, как тестировать шаблоны, смотрите в документации Starlette по шаблонам. +Больше подробностей, включая то, как тестировать шаблоны, смотрите в [документации Starlette по шаблонам](https://www.starlette.dev/templates/). diff --git a/docs/ru/docs/advanced/testing-websockets.md b/docs/ru/docs/advanced/testing-websockets.md index f6fa6a04be..6ab395f8f4 100644 --- a/docs/ru/docs/advanced/testing-websockets.md +++ b/docs/ru/docs/advanced/testing-websockets.md @@ -8,6 +8,6 @@ /// note | Примечание -Подробности смотрите в документации Starlette по тестированию WebSocket. +Подробности смотрите в документации Starlette по [тестированию WebSocket](https://www.starlette.dev/testclient/#testing-websocket-sessions). /// diff --git a/docs/ru/docs/advanced/using-request-directly.md b/docs/ru/docs/advanced/using-request-directly.md index 0c091cdeda..99074bf7b6 100644 --- a/docs/ru/docs/advanced/using-request-directly.md +++ b/docs/ru/docs/advanced/using-request-directly.md @@ -15,7 +15,7 @@ ## Подробности об объекте `Request` { #details-about-the-request-object } -Так как под капотом **FastAPI** — это **Starlette** с дополнительным слоем инструментов, вы можете при необходимости напрямую использовать объект `Request` из Starlette. +Так как под капотом **FastAPI** — это **Starlette** с дополнительным слоем инструментов, вы можете при необходимости напрямую использовать объект [`Request`](https://www.starlette.dev/requests/) из Starlette. Это также означает, что если вы получаете данные напрямую из объекта `Request` (например, читаете тело запроса), то они не будут валидироваться, конвертироваться или документироваться (с OpenAPI, для автоматического пользовательского интерфейса API) средствами FastAPI. @@ -45,7 +45,7 @@ ## Документация по `Request` { #request-documentation } -Подробнее об объекте `Request` на официальном сайте документации Starlette. +Подробнее об [объекте `Request` на официальном сайте документации Starlette](https://www.starlette.dev/requests/). /// note | Технические детали diff --git a/docs/ru/docs/advanced/websockets.md b/docs/ru/docs/advanced/websockets.md index d565d507bc..abfd789a48 100644 --- a/docs/ru/docs/advanced/websockets.md +++ b/docs/ru/docs/advanced/websockets.md @@ -1,10 +1,10 @@ # Веб-сокеты { #websockets } -Вы можете использовать веб-сокеты в **FastAPI**. +Вы можете использовать [веб-сокеты](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) в **FastAPI**. ## Установка `websockets` { #install-websockets } -Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его и установили `websockets` (библиотека Python, упрощающая работу с протоколом "WebSocket"): +Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его и установили `websockets` (библиотека Python, упрощающая работу с протоколом "WebSocket"):
@@ -64,19 +64,19 @@ $ pip install websockets ## Проверка в действии { #try-it } -Если ваш файл называется `main.py`, то запустите приложение командой: +Поместите ваш код в файл `main.py`, затем запустите приложение:
```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
-Откройте браузер по адресу http://127.0.0.1:8000. +Откройте браузер по адресу [http://127.0.0.1:8000](http://127.0.0.1:8000). Вы увидите следующую простенькую страницу: @@ -115,25 +115,25 @@ $ fastapi dev main.py В веб-сокете вызывать `HTTPException` не имеет смысла. Вместо этого нужно использовать `WebSocketException`. -Закрывающий статус код можно использовать из valid codes defined in the specification. +Вы можете использовать код закрытия из [допустимых кодов, определённых в спецификации](https://tools.ietf.org/html/rfc6455#section-7.4.1). /// ### Веб-сокеты с зависимостями: проверка в действии { #try-the-websockets-with-dependencies } -Если ваш файл называется `main.py`, то запустите приложение командой: +Запустите приложение:
```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
-Откройте браузер по адресу http://127.0.0.1:8000. +Откройте браузер по адресу [http://127.0.0.1:8000](http://127.0.0.1:8000). Там вы можете задать: @@ -152,7 +152,7 @@ $ fastapi dev main.py ## Обработка отключений и работа с несколькими клиентами { #handling-disconnections-and-multiple-clients } -Если веб-сокет соединение закрыто, то `await websocket.receive_text()` вызовет исключение `WebSocketDisconnect`, которое можно поймать и обработать как в этом примере: +Если веб-сокет соединение закрыто, то `await websocket.receive_text()` вызовет исключение `WebSocketDisconnect`, которое можно поймать и обработать как в этом примере. {* ../../docs_src/websockets_/tutorial003_py310.py hl[79:81] *} @@ -174,7 +174,7 @@ Client #1596980209979 left the chat Но имейте в виду, что это будет работать только в одном процессе и только пока он активен, так как всё обрабатывается в простом списке в оперативной памяти. -Если нужно что-то легко интегрируемое с FastAPI, но более надежное и с поддержкой Redis, PostgreSQL или другого, то можно воспользоваться encode/broadcaster. +Если нужно что-то легко интегрируемое с FastAPI, но более надежное и с поддержкой Redis, PostgreSQL или другого, то можно воспользоваться [encode/broadcaster](https://github.com/encode/broadcaster). /// @@ -182,5 +182,5 @@ Client #1596980209979 left the chat Для более глубокого изучения темы воспользуйтесь документацией Starlette: -* The `WebSocket` class. -* Class-based WebSocket handling. +* [Класс `WebSocket`](https://www.starlette.dev/websockets/). +* [Обработка WebSocket на основе классов](https://www.starlette.dev/endpoints/#websocketendpoint). diff --git a/docs/ru/docs/deployment/cloud.md b/docs/ru/docs/deployment/cloud.md index 955db2a157..cbd517e36e 100644 --- a/docs/ru/docs/deployment/cloud.md +++ b/docs/ru/docs/deployment/cloud.md @@ -6,7 +6,7 @@ ## FastAPI Cloud { #fastapi-cloud } -**FastAPI Cloud** создан тем же автором и командой, стоящими за **FastAPI**. +**[FastAPI Cloud](https://fastapicloud.com)** создан тем же автором и командой, стоящими за **FastAPI**. Он упрощает процесс **создания образа**, **развертывания** и **доступа** к API с минимальными усилиями. @@ -16,9 +16,9 @@ FastAPI Cloud — основной спонсор и источник финан ## Облачные провайдеры — спонсоры { #cloud-providers-sponsors } -Некоторые другие облачные провайдеры ✨ [**спонсируют FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨ тоже. 🙇 +Некоторые другие облачные провайдеры ✨ [**спонсируют FastAPI**](../help-fastapi.md#sponsor-the-author) ✨ тоже. 🙇 Возможно, вы захотите попробовать их сервисы и воспользоваться их руководствами: -* Render -* Railway +* [Render](https://docs.render.com/deploy-fastapi?utm_source=deploydoc&utm_medium=referral&utm_campaign=fastapi) +* [Railway](https://docs.railway.com/guides/fastapi?utm_medium=integration&utm_source=docs&utm_campaign=fastapi) diff --git a/docs/ru/docs/deployment/concepts.md b/docs/ru/docs/deployment/concepts.md index 173dbb962d..900b842f9a 100644 --- a/docs/ru/docs/deployment/concepts.md +++ b/docs/ru/docs/deployment/concepts.md @@ -25,7 +25,7 @@ ## Безопасность — HTTPS { #security-https } -В [предыдущей главе про HTTPS](https.md){.internal-link target=_blank} мы разобрались, как HTTPS обеспечивает шифрование для вашего API. +В [предыдущей главе про HTTPS](https.md) мы разобрались, как HTTPS обеспечивает шифрование для вашего API. Также мы увидели, что HTTPS обычно обеспечивает компонент, **внешний** по отношению к серверу вашего приложения — **прокси-сервер TSL-терминации**. @@ -190,7 +190,7 @@ ### Процессы‑воркеры и порты { #worker-processes-and-ports } -Помните из раздела [Об HTTPS](https.md){.internal-link target=_blank}, что на сервере только один процесс может слушать конкретную комбинацию порта и IP‑адреса? +Помните из раздела [Об HTTPS](https.md), что на сервере только один процесс может слушать конкретную комбинацию порта и IP‑адреса? Это по‑прежнему так. @@ -243,7 +243,7 @@ Не беспокойтесь, если некоторые пункты про **контейнеры**, Docker или Kubernetes пока кажутся неочевидными. -Я расскажу больше про образы контейнеров, Docker, Kubernetes и т.п. в следующей главе: [FastAPI внутри контейнеров — Docker](docker.md){.internal-link target=_blank}. +Я расскажу больше про образы контейнеров, Docker, Kubernetes и т.п. в следующей главе: [FastAPI внутри контейнеров — Docker](docker.md). /// @@ -281,7 +281,7 @@ /// tip | Совет -Я приведу более конкретные примеры с контейнерами в следующей главе: [FastAPI внутри контейнеров — Docker](docker.md){.internal-link target=_blank}. +Я приведу более конкретные примеры с контейнерами в следующей главе: [FastAPI внутри контейнеров — Docker](docker.md). /// diff --git a/docs/ru/docs/deployment/docker.md b/docs/ru/docs/deployment/docker.md index 5dfa211599..3b16d7798b 100644 --- a/docs/ru/docs/deployment/docker.md +++ b/docs/ru/docs/deployment/docker.md @@ -1,6 +1,6 @@ # FastAPI в контейнерах — Docker { #fastapi-in-containers-docker } -При развёртывании приложений FastAPI распространённый подход — собирать **образ контейнера на Linux**. Обычно это делают с помощью **Docker**. Затем такой образ контейнера можно развернуть несколькими способами. +При развёртывании приложений FastAPI распространённый подход — собирать **образ контейнера на Linux**. Обычно это делают с помощью [**Docker**](https://www.docker.com/). Затем такой образ контейнера можно развернуть несколькими способами. Использование Linux-контейнеров даёт ряд преимуществ: **безопасность**, **воспроизводимость**, **простоту** и другие. @@ -60,16 +60,16 @@ Linux-контейнеры запускаются, используя то же Docker — один из основных инструментов для создания и управления **образами контейнеров** и **контейнерами**. -Существует публичный Docker Hub с готовыми **официальными образами** для многих инструментов, окружений, баз данных и приложений. +Существует публичный [Docker Hub](https://hub.docker.com/) с готовыми **официальными образами** для многих инструментов, окружений, баз данных и приложений. -Например, есть официальный образ Python. +Например, есть официальный [образ Python](https://hub.docker.com/_/python). А также множество образов для разных вещей, например баз данных: -* PostgreSQL -* MySQL -* MongoDB -* Redis, и т.д. +* [PostgreSQL](https://hub.docker.com/_/postgres) +* [MySQL](https://hub.docker.com/_/mysql) +* [MongoDB](https://hub.docker.com/_/mongo) +* [Redis](https://hub.docker.com/_/redis), и т.д. Используя готовые образы, очень легко **комбинировать** разные инструменты и использовать их. Например, чтобы попробовать новую базу данных. В большинстве случаев можно воспользоваться **официальными образами** и просто настроить их через переменные окружения. @@ -111,7 +111,7 @@ Docker — один из основных инструментов для соз Чаще всего используется файл `requirements.txt` с именами пакетов и их версиями по одному на строку. -Разумеется, вы будете придерживаться тех же идей, что описаны здесь: [О версиях FastAPI](versions.md){.internal-link target=_blank}, чтобы задать диапазоны версий. +Разумеется, вы будете придерживаться тех же идей, что описаны здесь: [О версиях FastAPI](versions.md), чтобы задать диапазоны версий. Например, ваш `requirements.txt` может выглядеть так: @@ -238,7 +238,7 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80"] #### Используйте `CMD` — exec-форма { #use-cmd-exec-form } -Инструкцию Docker `CMD` можно писать в двух формах: +Инструкцию Docker [`CMD`](https://docs.docker.com/reference/dockerfile/#cmd) можно писать в двух формах: ✅ **Exec**-форма: @@ -254,11 +254,11 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80"] CMD fastapi run app/main.py --port 80 ``` -Обязательно используйте **exec**-форму, чтобы FastAPI мог корректно завершаться и чтобы срабатывали [события lifespan](../advanced/events.md){.internal-link target=_blank}. +Обязательно используйте **exec**-форму, чтобы FastAPI мог корректно завершаться и чтобы срабатывали [события lifespan](../advanced/events.md). -Подробнее об этом читайте в документации Docker о shell- и exec-формах. +Подробнее об этом читайте в [документации Docker о shell- и exec-формах](https://docs.docker.com/reference/dockerfile/#shell-and-exec-form). -Это особенно заметно при использовании `docker compose`. См. раздел FAQ Docker Compose с техническими подробностями: Почему мои сервисы пересоздаются или останавливаются 10 секунд?. +Это особенно заметно при использовании `docker compose`. См. раздел FAQ Docker Compose с техническими подробностями: [Почему мои сервисы пересоздаются или останавливаются 10 секунд?](https://docs.docker.com/compose/faq/#why-do-my-services-take-10-seconds-to-recreate-or-stop). #### Структура директорий { #directory-structure } @@ -352,7 +352,7 @@ $ docker run -d --name mycontainer -p 80:80 myimage ## Проверка { #check-it } -Проверьте работу по адресу вашего Docker-хоста, например: http://192.168.99.100/items/5?q=somequery или http://127.0.0.1/items/5?q=somequery (или аналогичный URL вашего Docker-хоста). +Проверьте работу по адресу вашего Docker-хоста, например: [http://192.168.99.100/items/5?q=somequery](http://192.168.99.100/items/5?q=somequery) или [http://127.0.0.1/items/5?q=somequery](http://127.0.0.1/items/5?q=somequery) (или аналогичный URL вашего Docker-хоста). Вы увидите что-то вроде: @@ -362,17 +362,17 @@ $ docker run -d --name mycontainer -p 80:80 myimage ## Интерактивная документация API { #interactive-api-docs } -Теперь зайдите на http://192.168.99.100/docs или http://127.0.0.1/docs (или аналогичный URL вашего Docker-хоста). +Теперь зайдите на [http://192.168.99.100/docs](http://192.168.99.100/docs) или [http://127.0.0.1/docs](http://127.0.0.1/docs) (или аналогичный URL вашего Docker-хоста). -Вы увидите автоматическую интерактивную документацию API (на базе Swagger UI): +Вы увидите автоматическую интерактивную документацию API (на базе [Swagger UI](https://github.com/swagger-api/swagger-ui)): ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) ## Альтернативная документация API { #alternative-api-docs } -Также можно открыть http://192.168.99.100/redoc или http://127.0.0.1/redoc (или аналогичный URL вашего Docker-хоста). +Также можно открыть [http://192.168.99.100/redoc](http://192.168.99.100/redoc) или [http://127.0.0.1/redoc](http://127.0.0.1/redoc) (или аналогичный URL вашего Docker-хоста). -Вы увидите альтернативную автоматическую документацию (на базе ReDoc): +Вы увидите альтернативную автоматическую документацию (на базе [ReDoc](https://github.com/Rebilly/ReDoc)): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -413,7 +413,7 @@ CMD ["fastapi", "run", "main.py", "--port", "80"] ## Концепции развертывания { #deployment-concepts } -Ещё раз рассмотрим [концепции развертывания](concepts.md){.internal-link target=_blank} применительно к контейнерам. +Ещё раз рассмотрим [концепции развертывания](concepts.md) применительно к контейнерам. Контейнеры главным образом упрощают **сборку и развёртывание** приложения, но не навязывают конкретный подход к этим **концепциям развертывания**, и существует несколько стратегий. @@ -432,7 +432,7 @@ CMD ["fastapi", "run", "main.py", "--port", "80"] Если мы рассматриваем только **образ контейнера** для приложения FastAPI (и далее запущенный **контейнер**), то HTTPS обычно обрабатывается **внешним** инструментом. -Это может быть другой контейнер, например с Traefik, который берёт на себя **HTTPS** и **автоматическое** получение **сертификатов**. +Это может быть другой контейнер, например с [Traefik](https://traefik.io/), который берёт на себя **HTTPS** и **автоматическое** получение **сертификатов**. /// tip | Подсказка @@ -558,7 +558,7 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"] /// info | Информация -Если вы используете Kubernetes, это, вероятно, будет Init Container. +Если вы используете Kubernetes, это, вероятно, будет [Init Container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/). /// @@ -570,7 +570,7 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"] ### Базовый Docker-образ { #base-docker-image } -Ранее существовал официальный Docker-образ FastAPI: tiangolo/uvicorn-gunicorn-fastapi. Сейчас он помечен как устаревший. ⛔️ +Ранее существовал официальный Docker-образ FastAPI: [tiangolo/uvicorn-gunicorn-fastapi](https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker). Сейчас он помечен как устаревший. ⛔️ Скорее всего, вам **не стоит** использовать этот базовый образ (или какой-либо аналогичный). @@ -600,7 +600,7 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"] ## Docker-образ с `uv` { #docker-image-with-uv } -Если вы используете uv для установки и управления проектом, следуйте их руководству по Docker для uv. +Если вы используете [uv](https://github.com/astral-sh/uv) для установки и управления проектом, следуйте их [руководству по Docker для uv](https://docs.astral.sh/uv/guides/integration/docker/). ## Резюме { #recap } @@ -615,4 +615,4 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"] В большинстве случаев вы, вероятно, не захотите использовать какой-либо базовый образ, а вместо этого **соберёте образ контейнера с нуля** на основе официального Docker-образа Python. -Заботясь о **порядке** инструкций в `Dockerfile`и используя **кэш Docker**, вы можете **минимизировать время сборки**, чтобы повысить продуктивность (и не скучать). 😎 +Заботясь о **порядке** инструкций в `Dockerfile` и используя **кэш Docker**, вы можете **минимизировать время сборки**, чтобы повысить продуктивность (и не скучать). 😎 diff --git a/docs/ru/docs/deployment/fastapicloud.md b/docs/ru/docs/deployment/fastapicloud.md index 9e7430ecb0..95db3387f2 100644 --- a/docs/ru/docs/deployment/fastapicloud.md +++ b/docs/ru/docs/deployment/fastapicloud.md @@ -1,6 +1,6 @@ # FastAPI Cloud { #fastapi-cloud } -Вы можете развернуть своё приложение FastAPI в FastAPI Cloud одной командой, присоединяйтесь к списку ожидания, если ещё не сделали этого. 🚀 +Вы можете развернуть своё приложение FastAPI в [FastAPI Cloud](https://fastapicloud.com) одной командой, присоединяйтесь к списку ожидания, если ещё не сделали этого. 🚀 ## Вход { #login } @@ -40,7 +40,7 @@ Deploying to FastAPI Cloud... ## О FastAPI Cloud { #about-fastapi-cloud } -**FastAPI Cloud** создан тем же автором и командой, что и **FastAPI**. +**[FastAPI Cloud](https://fastapicloud.com)** создан тем же автором и командой, что и **FastAPI**. Он упрощает процесс **создания образа**, **развертывания** и **доступа** к API с минимальными усилиями. diff --git a/docs/ru/docs/deployment/https.md b/docs/ru/docs/deployment/https.md index ffeccfd7da..181cac0d89 100644 --- a/docs/ru/docs/deployment/https.md +++ b/docs/ru/docs/deployment/https.md @@ -10,7 +10,7 @@ /// -Чтобы **изучить основы HTTPS** с точки зрения пользователя, загляните на https://howhttps.works/. +Чтобы **изучить основы HTTPS** с точки зрения пользователя, загляните на [https://howhttps.works/](https://howhttps.works/). Теперь, со стороны **разработчика**, вот несколько вещей, которые стоит держать в голове, размышляя об HTTPS: @@ -28,13 +28,13 @@ * **По умолчанию** это означает, что вы можете иметь **лишь один HTTPS-сертификат на один IP-адрес**. * Неважно, насколько мощный у вас сервер или насколько маленькие приложения на нём работают. * Однако у этого есть **решение**. -* Есть **расширение** протокола **TLS** (того самого, что занимается шифрованием на уровне TCP, до HTTP) под названием **SNI**. +* Есть **расширение** протокола **TLS** (того самого, что занимается шифрованием на уровне TCP, до HTTP) под названием **[SNI](https://en.wikipedia.org/wiki/Server_Name_Indication)**. * Это расширение SNI позволяет одному серверу (с **одним IP-адресом**) иметь **несколько HTTPS-сертификатов** и обслуживать **несколько HTTPS-доменов/приложений**. * Чтобы это работало, **один** компонент (программа), запущенный на сервере и слушающий **публичный IP-адрес**, должен иметь **все HTTPS-сертификаты** на этом сервере. * **После** установления защищённого соединения, протокол обмена данными — **всё ещё HTTP**. * Содержимое **зашифровано**, несмотря на то, что оно отправляется по **протоколу HTTP**. -Обычно на сервере (машине, хосте и т.п.) запускают **одну программу/HTTP‑сервер**, которая **управляет всей частью, связанной с HTTPS**: принимает **зашифрованные HTTPS-запросы**, отправляет **расшифрованные HTTP-запросы** в само HTTP‑приложение, работающее на том же сервере (в нашем случае это приложение **FastAPI**), получает **HTTP-ответ** от приложения, **шифрует его** с использованием подходящего **HTTPS‑сертификата** и отправляет клиенту по **HTTPS**. Такой сервер часто называют **прокси‑сервером TLS-терминации**. +Обычно на сервере (машине, хосте и т.п.) запускают **одну программу/HTTP‑сервер**, которая **управляет всей частью, связанной с HTTPS**: принимает **зашифрованные HTTPS-запросы**, отправляет **расшифрованные HTTP-запросы** в само HTTP‑приложение, работающее на том же сервере (в нашем случае это приложение **FastAPI**), получает **HTTP-ответ** от приложения, **шифрует его** с использованием подходящего **HTTPS‑сертификата** и отправляет клиенту по **HTTPS**. Такой сервер часто называют **[прокси‑сервером TLS-терминации](https://en.wikipedia.org/wiki/TLS_termination_proxy)**. Некоторые варианты, которые вы можете использовать как прокси‑сервер TLS-терминации: @@ -49,7 +49,7 @@ Процесс получения таких сертификатов был неудобным, требовал бумажной волокиты, а сами сертификаты были довольно дорогими. -Затем появился **Let's Encrypt**. +Затем появился **[Let's Encrypt](https://letsencrypt.org/)**. Это проект Linux Foundation. Он предоставляет **HTTPS‑сертификаты бесплатно**, в автоматическом режиме. Эти сертификаты используют стандартные криптографические механизмы и имеют короткий срок действия (около 3 месяцев), поэтому **безопасность фактически выше** благодаря уменьшенному сроку жизни. @@ -200,9 +200,9 @@ DNS‑серверы ответят браузеру, какой **конкре Заголовки прокси: -* X-Forwarded-For -* X-Forwarded-Proto -* X-Forwarded-Host +* [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-For) +* [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Proto) +* [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Host) /// @@ -218,7 +218,7 @@ DNS‑серверы ответят браузеру, какой **конкре /// tip | Совет -Подробнее об этом вы можете узнать в документации: [За прокси — Включить пересылаемые заголовки прокси](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers){.internal-link target=_blank} +Подробнее об этом вы можете узнать в документации: [За прокси — Включить пересылаемые заголовки прокси](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers) /// diff --git a/docs/ru/docs/deployment/index.md b/docs/ru/docs/deployment/index.md index 7e735593be..a64366d4da 100644 --- a/docs/ru/docs/deployment/index.md +++ b/docs/ru/docs/deployment/index.md @@ -16,7 +16,7 @@ Вы можете **развернуть сервер** самостоятельно, используя различные инструменты. Например, можно использовать **облачный сервис**, который выполнит часть работы за вас. Также возможны и другие варианты. -Например, мы, команда, стоящая за FastAPI, создали **FastAPI Cloud**, чтобы сделать развёртывание приложений FastAPI в облаке как можно более простым и прямолинейным, с тем же удобством для разработчика, что и при работе с FastAPI. +Например, мы, команда, стоящая за FastAPI, создали [**FastAPI Cloud**](https://fastapicloud.com), чтобы сделать развёртывание приложений FastAPI в облаке как можно более простым и прямолинейным, с тем же удобством для разработчика, что и при работе с FastAPI. Я покажу вам некоторые из основных концепций, которые вы, вероятно, должны иметь в виду при развертывании приложения **FastAPI** (хотя большинство из них применимо к любому другому типу веб-приложений). diff --git a/docs/ru/docs/deployment/manually.md b/docs/ru/docs/deployment/manually.md index 93287372a2..3169f31893 100644 --- a/docs/ru/docs/deployment/manually.md +++ b/docs/ru/docs/deployment/manually.md @@ -52,11 +52,11 @@ FastAPI использует стандарт для построения Python Есть несколько альтернатив, например: -* Uvicorn: высокопроизводительный ASGI‑сервер. -* Hypercorn: ASGI‑сервер, среди прочего совместимый с HTTP/2 и Trio. -* Daphne: ASGI‑сервер, созданный для Django Channels. -* Granian: HTTP‑сервер на Rust для Python‑приложений. -* NGINX Unit: NGINX Unit — лёгкая и многофункциональная среда выполнения веб‑приложений. +* [Uvicorn](https://www.uvicorn.dev/): высокопроизводительный ASGI‑сервер. +* [Hypercorn](https://hypercorn.readthedocs.io/): ASGI‑сервер, среди прочего совместимый с HTTP/2 и Trio. +* [Daphne](https://github.com/django/daphne): ASGI‑сервер, созданный для Django Channels. +* [Granian](https://github.com/emmett-framework/granian): HTTP‑сервер на Rust для Python‑приложений. +* [NGINX Unit](https://unit.nginx.org/howto/fastapi/): NGINX Unit — лёгкая и многофункциональная среда выполнения веб‑приложений. ## Сервер как машина и сервер как программа { #server-machine-and-server-program } @@ -74,7 +74,7 @@ FastAPI использует стандарт для построения Python Но вы также можете установить ASGI‑сервер вручную. -Создайте [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активируйте его и затем установите серверное приложение. +Создайте [виртуальное окружение](../virtual-environments.md), активируйте его и затем установите серверное приложение. Например, чтобы установить Uvicorn: diff --git a/docs/ru/docs/deployment/server-workers.md b/docs/ru/docs/deployment/server-workers.md index e756ab3774..2caf79f7d8 100644 --- a/docs/ru/docs/deployment/server-workers.md +++ b/docs/ru/docs/deployment/server-workers.md @@ -13,13 +13,13 @@ При деплое приложения вам, скорее всего, захочется использовать **репликацию процессов**, чтобы задействовать **несколько ядер** и иметь возможность обрабатывать больше запросов. -Как вы видели в предыдущей главе о [Концепциях деплоя](concepts.md){.internal-link target=_blank}, существует несколько стратегий. +Как вы видели в предыдущей главе о [Концепциях деплоя](concepts.md), существует несколько стратегий. Здесь я покажу, как использовать **Uvicorn** с **воркер-процессами** через команду `fastapi` или напрямую через команду `uvicorn`. /// info | Информация -Если вы используете контейнеры, например Docker или Kubernetes, я расскажу об этом подробнее в следующей главе: [FastAPI в контейнерах — Docker](docker.md){.internal-link target=_blank}. +Если вы используете контейнеры, например Docker или Kubernetes, я расскажу об этом подробнее в следующей главе: [FastAPI в контейнерах — Docker](docker.md). В частности, при запуске в **Kubernetes** вам, скорее всего, **не** понадобится использовать воркеры — вместо этого запускайте **один процесс Uvicorn на контейнер**, но об этом подробнее далее в той главе. @@ -126,7 +126,7 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 ## Контейнеры и Docker { #containers-and-docker } -В следующей главе о [FastAPI в контейнерах — Docker](docker.md){.internal-link target=_blank} я объясню стратегии, которые можно использовать для решения остальных **концепций деплоя**. +В следующей главе о [FastAPI в контейнерах — Docker](docker.md) я объясню стратегии, которые можно использовать для решения остальных **концепций деплоя**. Я покажу, как **собрать свой образ с нуля**, чтобы запускать один процесс Uvicorn. Это простой подход и, вероятно, именно то, что вам нужно при использовании распределённой системы управления контейнерами, такой как **Kubernetes**. diff --git a/docs/ru/docs/deployment/versions.md b/docs/ru/docs/deployment/versions.md index 4195d689fe..b52ca456f2 100644 --- a/docs/ru/docs/deployment/versions.md +++ b/docs/ru/docs/deployment/versions.md @@ -4,7 +4,7 @@ Часто добавляются новые функции, регулярно исправляются баги, код продолжает постоянно совершенствоваться. -По указанным причинам текущие версии до сих пор `0.x.x`. Это говорит о том, что каждая версия может содержать обратно несовместимые изменения, следуя Семантическому версионированию. +По указанным причинам текущие версии до сих пор `0.x.x`. Это говорит о том, что каждая версия может содержать обратно несовместимые изменения, следуя [Семантическому версионированию](https://semver.org/). Уже сейчас вы можете создавать приложения в продакшн, используя **FastAPI** (и скорее всего так и делаете), главное убедиться в том, что вы используете версию, которая корректно работает с вашим кодом. @@ -34,7 +34,7 @@ fastapi[standard]>=0.112.0,<0.113.0 ## Доступные версии { #available-versions } -Вы можете посмотреть доступные версии (например, проверить последнюю на данный момент) в [Примечаниях к выпуску](../release-notes.md){.internal-link target=_blank}. +Вы можете посмотреть доступные версии (например, проверить последнюю на данный момент) в [Примечаниях к выпуску](../release-notes.md). ## О версиях { #about-versions } @@ -66,7 +66,7 @@ fastapi>=0.45.0,<0.46.0 Вам следует добавить тесты для вашего приложения. -С помощью **FastAPI** это очень просто (благодаря Starlette), см. документацию: [Тестирование](../tutorial/testing.md){.internal-link target=_blank} +С помощью **FastAPI** это очень просто (благодаря Starlette), см. документацию: [Тестирование](../tutorial/testing.md) После создания тестов вы можете обновить свою версию **FastAPI** до более новой. После этого следует убедиться, что ваш код работает корректно, запустив тесты. diff --git a/docs/ru/docs/how-to/authentication-error-status-code.md b/docs/ru/docs/how-to/authentication-error-status-code.md index 596563c541..acbc18f336 100644 --- a/docs/ru/docs/how-to/authentication-error-status-code.md +++ b/docs/ru/docs/how-to/authentication-error-status-code.md @@ -2,7 +2,7 @@ До версии FastAPI `0.122.0`, когда встроенные утилиты безопасности возвращали ошибку клиенту после неудачной аутентификации, они использовали HTTP статус-код `403 Forbidden`. -Начиная с версии FastAPI `0.122.0`, используется более подходящий HTTP статус-код `401 Unauthorized`, и в ответе возвращается имеющий смысл HTTP-заголовок `WWW-Authenticate` в соответствии со спецификациями HTTP, RFC 7235, RFC 9110. +Начиная с версии FastAPI `0.122.0`, используется более подходящий HTTP статус-код `401 Unauthorized`, и в ответе возвращается имеющий смысл HTTP-заголовок `WWW-Authenticate` в соответствии со спецификациями HTTP, [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-3.1), [RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#name-401-unauthorized). Но если по какой-то причине ваши клиенты зависят от старого поведения, вы можете вернуть его, переопределив метод `make_not_authenticated_error` в ваших Security-классах. diff --git a/docs/ru/docs/how-to/conditional-openapi.md b/docs/ru/docs/how-to/conditional-openapi.md index 6efa30608e..5fece06c14 100644 --- a/docs/ru/docs/how-to/conditional-openapi.md +++ b/docs/ru/docs/how-to/conditional-openapi.md @@ -10,7 +10,7 @@ Если в вашем коде есть уязвимость, она всё равно останется. -Сокрытие документации лишь усложняет понимание того, как взаимодействовать с вашим API, и может усложнить его отладку в продакшн. Это можно считать просто разновидностью безопасности через сокрытие. +Сокрытие документации лишь усложняет понимание того, как взаимодействовать с вашим API, и может усложнить его отладку в продакшн. Это можно считать просто разновидностью [безопасности через сокрытие](https://en.wikipedia.org/wiki/Security_through_obscurity). Если вы хотите обезопасить свой API, есть несколько более эффективных вещей, которые можно сделать, например: diff --git a/docs/ru/docs/how-to/configure-swagger-ui.md b/docs/ru/docs/how-to/configure-swagger-ui.md index f4f2a0e549..b57a086b6c 100644 --- a/docs/ru/docs/how-to/configure-swagger-ui.md +++ b/docs/ru/docs/how-to/configure-swagger-ui.md @@ -1,6 +1,6 @@ # Настройка Swagger UI { #configure-swagger-ui } -Вы можете настроить дополнительные параметры Swagger UI. +Вы можете настроить дополнительные [параметры Swagger UI](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/). Чтобы настроить их, передайте аргумент `swagger_ui_parameters` при создании объекта приложения `FastAPI()` или в функцию `get_swagger_ui_html()`. @@ -50,7 +50,7 @@ FastAPI включает некоторые параметры конфигур ## Другие параметры Swagger UI { #other-swagger-ui-parameters } -Чтобы увидеть все остальные возможные настройки, прочитайте официальную документацию по параметрам Swagger UI. +Чтобы увидеть все остальные возможные настройки, прочитайте официальную [документацию по параметрам Swagger UI](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/). ## Настройки только для JavaScript { #javascript-only-settings } diff --git a/docs/ru/docs/how-to/custom-docs-ui-assets.md b/docs/ru/docs/how-to/custom-docs-ui-assets.md index e3c31b32c5..b8398cdb08 100644 --- a/docs/ru/docs/how-to/custom-docs-ui-assets.md +++ b/docs/ru/docs/how-to/custom-docs-ui-assets.md @@ -54,7 +54,7 @@ Swagger UI сделает это за вас «за кулисами», но д ### Тестирование { #test-it } -Теперь вы должны иметь возможность открыть свою документацию по адресу http://127.0.0.1:8000/docs и перезагрузить страницу — «ассеты» (статические файлы) будут загружаться с нового CDN. +Теперь вы должны иметь возможность открыть свою документацию по адресу [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) и перезагрузить страницу — «ассеты» (статические файлы) будут загружаться с нового CDN. ## Самостоятельный хостинг JavaScript и CSS для документации { #self-hosting-javascript-and-css-for-docs } @@ -93,12 +93,12 @@ Swagger UI сделает это за вас «за кулисами», но д **Swagger UI** использует файлы: -* `swagger-ui-bundle.js` -* `swagger-ui.css` +* [`swagger-ui-bundle.js`](https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js) +* [`swagger-ui.css`](https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css) А **ReDoc** использует файл: -* `redoc.standalone.js` +* [`redoc.standalone.js`](https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js) После этого структура файлов может выглядеть так: @@ -122,7 +122,7 @@ Swagger UI сделает это за вас «за кулисами», но д ### Протестируйте статические файлы { #test-the-static-files } -Запустите своё приложение и откройте http://127.0.0.1:8000/static/redoc.standalone.js. +Запустите своё приложение и откройте [http://127.0.0.1:8000/static/redoc.standalone.js](http://127.0.0.1:8000/static/redoc.standalone.js). Вы должны увидеть очень длинный JavaScript-файл для **ReDoc**. @@ -180,6 +180,6 @@ Swagger UI сделает это за вас «за кулисами», но д ### Тестирование UI со статическими файлами { #test-static-files-ui } -Теперь вы можете отключить Wi‑Fi, открыть свою документацию по адресу http://127.0.0.1:8000/docs и перезагрузить страницу. +Теперь вы можете отключить Wi‑Fi, открыть свою документацию по адресу [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) и перезагрузить страницу. Даже без Интернета вы сможете видеть документацию к своему API и взаимодействовать с ним. diff --git a/docs/ru/docs/how-to/custom-request-and-route.md b/docs/ru/docs/how-to/custom-request-and-route.md index feef9670ad..1e3a608562 100644 --- a/docs/ru/docs/how-to/custom-request-and-route.md +++ b/docs/ru/docs/how-to/custom-request-and-route.md @@ -18,7 +18,7 @@ Некоторые сценарии: -* Преобразование тел запросов, не в формате JSON, в JSON (например, `msgpack`). +* Преобразование тел запросов, не в формате JSON, в JSON (например, [`msgpack`](https://msgpack.org/index.html)). * Распаковка тел запросов, сжатых с помощью gzip. * Автоматическое логирование всех тел запросов. @@ -32,7 +32,7 @@ /// tip | Совет -Это учебный пример, демонстрирующий принцип работы. Если вам нужна поддержка Gzip, вы можете использовать готовый [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank}. +Это учебный пример, демонстрирующий принцип работы. Если вам нужна поддержка Gzip, вы можете использовать готовый [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware). /// @@ -66,7 +66,7 @@ Именно этих двух компонентов — `scope` и `receive` — достаточно, чтобы создать новый экземпляр `Request`. -Чтобы узнать больше о `Request`, см. документацию Starlette о запросах. +Чтобы узнать больше о `Request`, см. [документацию Starlette о запросах](https://www.starlette.dev/requests/). /// @@ -82,7 +82,7 @@ /// tip | Совет -Для решения этой задачи, вероятно, намного проще использовать `body` в пользовательском обработчике `RequestValidationError` ([Обработка ошибок](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}). +Для решения этой задачи, вероятно, намного проще использовать `body` в пользовательском обработчике `RequestValidationError` ([Обработка ошибок](../tutorial/handling-errors.md#use-the-requestvalidationerror-body)). Но этот пример всё равно актуален и показывает, как взаимодействовать с внутренними компонентами. diff --git a/docs/ru/docs/how-to/extending-openapi.md b/docs/ru/docs/how-to/extending-openapi.md index 197a1790a2..c1e369f5e5 100644 --- a/docs/ru/docs/how-to/extending-openapi.md +++ b/docs/ru/docs/how-to/extending-openapi.md @@ -37,7 +37,7 @@ Используя информацию выше, вы можете той же вспомогательной функцией сгенерировать схему OpenAPI и переопределить любые нужные части. -Например, добавим расширение OpenAPI ReDoc для включения собственного логотипа. +Например, добавим [расширение OpenAPI ReDoc для включения собственного логотипа](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo). ### Обычный **FastAPI** { #normal-fastapi } @@ -75,6 +75,6 @@ ### Проверьте { #check-it } -Перейдите на http://127.0.0.1:8000/redoc — вы увидите, что используется ваш кастомный логотип (в этом примере — логотип **FastAPI**): +Перейдите на [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) — вы увидите, что используется ваш кастомный логотип (в этом примере — логотип **FastAPI**): diff --git a/docs/ru/docs/how-to/general.md b/docs/ru/docs/how-to/general.md index 029ea1d274..886105eec4 100644 --- a/docs/ru/docs/how-to/general.md +++ b/docs/ru/docs/how-to/general.md @@ -4,36 +4,40 @@ ## Фильтрация данных — Безопасность { #filter-data-security } -Чтобы убедиться, что вы не возвращаете больше данных, чем следует, прочитайте документацию: [Руководство — Модель ответа — Возвращаемый тип](../tutorial/response-model.md){.internal-link target=_blank}. +Чтобы убедиться, что вы не возвращаете больше данных, чем следует, прочитайте документацию: [Руководство — Модель ответа — Возвращаемый тип](../tutorial/response-model.md). + +## Оптимизация производительности ответа — Модель ответа — Возвращаемый тип { #optimize-response-performance-response-model-return-type } + +Чтобы оптимизировать производительность при возврате JSON-данных, используйте возвращаемый тип или модель ответа; таким образом Pydantic выполнит сериализацию в JSON на стороне Rust, без прохождения через Python. Подробнее читайте в документации: [Руководство — Модель ответа — Возвращаемый тип](../tutorial/response-model.md). ## Теги в документации — OpenAPI { #documentation-tags-openapi } -Чтобы добавить теги к вашим *операциям пути* и группировать их в интерфейсе документации, прочитайте документацию: [Руководство — Конфигурации операций пути — Теги](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank}. +Чтобы добавить теги к вашим *операциям пути* и группировать их в интерфейсе документации, прочитайте документацию: [Руководство — Конфигурации операций пути — Теги](../tutorial/path-operation-configuration.md#tags). ## Краткое описание и описание в документации — OpenAPI { #documentation-summary-and-description-openapi } -Чтобы добавить краткое описание и описание к вашим *операциям пути* и отобразить их в интерфейсе документации, прочитайте документацию: [Руководство — Конфигурации операций пути — Краткое описание и описание](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank}. +Чтобы добавить краткое описание и описание к вашим *операциям пути* и отобразить их в интерфейсе документации, прочитайте документацию: [Руководство — Конфигурации операций пути — Краткое описание и описание](../tutorial/path-operation-configuration.md#summary-and-description). ## Описание ответа в документации — OpenAPI { #documentation-response-description-openapi } -Чтобы задать описание ответа, отображаемое в интерфейсе документации, прочитайте документацию: [Руководство — Конфигурации операций пути — Описание ответа](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank}. +Чтобы задать описание ответа, отображаемое в интерфейсе документации, прочитайте документацию: [Руководство — Конфигурации операций пути — Описание ответа](../tutorial/path-operation-configuration.md#response-description). ## Документация — пометить операцию пути устаревшей — OpenAPI { #documentation-deprecate-a-path-operation-openapi } -Чтобы пометить *операцию пути* как устаревшую и показать это в интерфейсе документации, прочитайте документацию: [Руководство — Конфигурации операций пути — Пометить операцию пути устаревшей](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank}. +Чтобы пометить *операцию пути* как устаревшую и показать это в интерфейсе документации, прочитайте документацию: [Руководство — Конфигурации операций пути — Пометить операцию пути устаревшей](../tutorial/path-operation-configuration.md#deprecate-a-path-operation). ## Преобразование любых данных к формату, совместимому с JSON { #convert-any-data-to-json-compatible } -Чтобы преобразовать любые данные к формату, совместимому с JSON, прочитайте документацию: [Руководство — JSON-совместимый кодировщик](../tutorial/encoder.md){.internal-link target=_blank}. +Чтобы преобразовать любые данные к формату, совместимому с JSON, прочитайте документацию: [Руководство — JSON-совместимый кодировщик](../tutorial/encoder.md). ## Метаданные OpenAPI — Документация { #openapi-metadata-docs } -Чтобы добавить метаданные в вашу схему OpenAPI, включая лицензию, версию, контакты и т.д., прочитайте документацию: [Руководство — Метаданные и URL документации](../tutorial/metadata.md){.internal-link target=_blank}. +Чтобы добавить метаданные в вашу схему OpenAPI, включая лицензию, версию, контакты и т.д., прочитайте документацию: [Руководство — Метаданные и URL документации](../tutorial/metadata.md). ## Пользовательский URL OpenAPI { #openapi-custom-url } -Чтобы настроить URL OpenAPI (или удалить его), прочитайте документацию: [Руководство — Метаданные и URL документации](../tutorial/metadata.md#openapi-url){.internal-link target=_blank}. +Чтобы настроить URL OpenAPI (или удалить его), прочитайте документацию: [Руководство — Метаданные и URL документации](../tutorial/metadata.md#openapi-url). ## URL документации OpenAPI { #openapi-docs-urls } -Чтобы изменить URL, используемые для автоматически сгенерированных пользовательских интерфейсов документации, прочитайте документацию: [Руководство — Метаданные и URL документации](../tutorial/metadata.md#docs-urls){.internal-link target=_blank}. +Чтобы изменить URL, используемые для автоматически сгенерированных пользовательских интерфейсов документации, прочитайте документацию: [Руководство — Метаданные и URL документации](../tutorial/metadata.md#docs-urls). diff --git a/docs/ru/docs/how-to/graphql.md b/docs/ru/docs/how-to/graphql.md index 9e28d61822..1829a211c1 100644 --- a/docs/ru/docs/how-to/graphql.md +++ b/docs/ru/docs/how-to/graphql.md @@ -18,18 +18,18 @@ Ниже приведены некоторые библиотеки **GraphQL** с поддержкой **ASGI**. Их можно использовать с **FastAPI**: -* Strawberry 🍓 - * С документацией для FastAPI -* Ariadne - * С документацией для FastAPI -* Tartiflette - * С Tartiflette ASGI для интеграции с ASGI -* Graphene - * С starlette-graphene3 +* [Strawberry](https://strawberry.rocks/) 🍓 + * С [документацией для FastAPI](https://strawberry.rocks/docs/integrations/fastapi) +* [Ariadne](https://ariadnegraphql.org/) + * С [документацией для FastAPI](https://ariadnegraphql.org/docs/fastapi-integration) +* [Tartiflette](https://tartiflette.io/) + * С [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) для интеграции с ASGI +* [Graphene](https://graphene-python.org/) + * С [starlette-graphene3](https://github.com/ciscorn/starlette-graphene3) ## GraphQL со Strawberry { #graphql-with-strawberry } -Если вам нужно или хочется работать с **GraphQL**, **Strawberry** — **рекомендуемая** библиотека, так как её дизайн ближе всего к дизайну **FastAPI**, всё основано на **аннотациях типов**. +Если вам нужно или хочется работать с **GraphQL**, [**Strawberry**](https://strawberry.rocks/) — **рекомендуемая** библиотека, так как её дизайн ближе всего к дизайну **FastAPI**, всё основано на **аннотациях типов**. В зависимости от вашего сценария использования вы можете предпочесть другую библиотеку, но если бы вы спросили меня, я, скорее всего, предложил бы попробовать **Strawberry**. @@ -37,24 +37,24 @@ {* ../../docs_src/graphql_/tutorial001_py310.py hl[3,22,25] *} -Подробнее о Strawberry можно узнать в документации Strawberry. +Подробнее о Strawberry можно узнать в [документации Strawberry](https://strawberry.rocks/). -А также в документации по интеграции Strawberry с FastAPI. +А также в документации по [интеграции Strawberry с FastAPI](https://strawberry.rocks/docs/integrations/fastapi). ## Устаревший `GraphQLApp` из Starlette { #older-graphqlapp-from-starlette } -В предыдущих версиях Starlette был класс `GraphQLApp` для интеграции с Graphene. +В предыдущих версиях Starlette был класс `GraphQLApp` для интеграции с [Graphene](https://graphene-python.org/). -Он был объявлен устаревшим в Starlette, но если у вас есть код, который его использовал, вы можете легко **мигрировать** на starlette-graphene3, который решает ту же задачу и имеет **почти идентичный интерфейс**. +Он был объявлен устаревшим в Starlette, но если у вас есть код, который его использовал, вы можете легко **мигрировать** на [starlette-graphene3](https://github.com/ciscorn/starlette-graphene3), который решает ту же задачу и имеет **почти идентичный интерфейс**. /// tip | Совет -Если вам нужен GraphQL, я всё же рекомендую посмотреть Strawberry, так как он основан на аннотациях типов, а не на пользовательских классах и типах. +Если вам нужен GraphQL, я всё же рекомендую посмотреть [Strawberry](https://strawberry.rocks/), так как он основан на аннотациях типов, а не на пользовательских классах и типах. /// ## Подробнее { #learn-more } -Подробнее о **GraphQL** вы можете узнать в официальной документации GraphQL. +Подробнее о **GraphQL** вы можете узнать в [официальной документации GraphQL](https://graphql.org/). Также можно почитать больше о каждой из указанных выше библиотек по приведённым ссылкам. diff --git a/docs/ru/docs/how-to/index.md b/docs/ru/docs/how-to/index.md index 75e7fff265..23d95ba04c 100644 --- a/docs/ru/docs/how-to/index.md +++ b/docs/ru/docs/how-to/index.md @@ -8,6 +8,6 @@ /// tip | Совет -Если вы хотите **изучить FastAPI** структурированно (рекомендуется), вместо этого читайте [Учебник — Руководство пользователя](../tutorial/index.md){.internal-link target=_blank} по главам. +Если вы хотите **изучить FastAPI** структурированно (рекомендуется), вместо этого читайте [Учебник - Руководство пользователя](../tutorial/index.md) по главам. /// diff --git a/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index 2b47c08f67..46b4071da8 100644 --- a/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -22,7 +22,7 @@ FastAPI 0.126.0 убрал поддержку Pydantic v1, при этом ещ ## Официальное руководство { #official-guide } -У Pydantic есть официальное руководство по миграции с v1 на v2. +У Pydantic есть официальное [руководство по миграции](https://docs.pydantic.dev/latest/migration/) с v1 на v2. Там также описано, что изменилось, как валидации стали более корректными и строгими, возможные нюансы и т.д. @@ -30,7 +30,7 @@ FastAPI 0.126.0 убрал поддержку Pydantic v1, при этом ещ ## Тесты { #tests } -Убедитесь, что у вас есть [тесты](../tutorial/testing.md){.internal-link target=_blank} для вашего приложения и что вы запускаете их в системе непрерывной интеграции (CI). +Убедитесь, что у вас есть [тесты](../tutorial/testing.md) для вашего приложения и что вы запускаете их в системе непрерывной интеграции (CI). Так вы сможете выполнить обновление и убедиться, что всё работает как ожидается. @@ -38,7 +38,7 @@ FastAPI 0.126.0 убрал поддержку Pydantic v1, при этом ещ Во многих случаях, когда вы используете обычные Pydantic‑модели без пользовательских настроек, вы сможете автоматизировать большую часть процесса миграции с Pydantic v1 на Pydantic v2. -Вы можете использовать `bump-pydantic` от той же команды Pydantic. +Вы можете использовать [`bump-pydantic`](https://github.com/pydantic/bump-pydantic) от той же команды Pydantic. Этот инструмент поможет автоматически изменить большую часть кода, который нужно изменить. diff --git a/docs/ru/docs/how-to/testing-database.md b/docs/ru/docs/how-to/testing-database.md index 18f4deeca5..09cd48fafd 100644 --- a/docs/ru/docs/how-to/testing-database.md +++ b/docs/ru/docs/how-to/testing-database.md @@ -1,7 +1,7 @@ # Тестирование базы данных { #testing-a-database } -Вы можете изучить базы данных, SQL и SQLModel в документации SQLModel. 🤓 +Вы можете изучить базы данных, SQL и SQLModel в [документации SQLModel](https://sqlmodel.tiangolo.com/). 🤓 -Есть мини-руководство по использованию SQLModel с FastAPI. ✨ +Есть мини-[руководство по использованию SQLModel с FastAPI](https://sqlmodel.tiangolo.com/tutorial/fastapi/). ✨ -В этом руководстве есть раздел о тестировании SQL-баз данных. 😎 +В этом руководстве есть раздел о [тестировании SQL-баз данных](https://sqlmodel.tiangolo.com/tutorial/fastapi/tests/). 😎