11 KiB
Path-параметры и валидация числовых данных
Так же, как с помощью Query вы можете добавлять валидацию и метаданные для query-параметров, так и с помощью Path вы можете добавлять такую же валидацию и метаданные для path-параметров.
Импорт Path
Сначала импортируйте Path из fastapi, а также импортируйте Annotated:
{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
/// info | Информация
Поддержка Annotated была добавлена в FastAPI начиная с версии 0.95.0 (и с этой версии рекомендуется использовать этот подход).
Если вы используете более старую версию, вы столкнётесь с ошибками при попытке использовать Annotated.
Убедитесь, что вы обновили версию FastAPI{.internal-link target=_blank} как минимум до 0.95.1 перед тем, как использовать Annotated.
///
Определите метаданные
Вы можете указать все те же параметры, что и для Query.
Например, чтобы указать значение метаданных title для path-параметра item_id, вы можете написать:
{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *}
/// note | Примечание
Path-параметр всегда является обязательным, поскольку он должен быть частью пути. Даже если вы объявите его как None или зададите значение по умолчанию, это ни на что не повлияет — параметр всё равно будет обязательным.
///
Задайте нужный вам порядок параметров
/// tip | Подсказка
Это не имеет большого значения, если вы используете Annotated.
///
Допустим, вы хотите объявить query-параметр q как обязательный параметр типа str.
И если вам больше ничего не нужно указывать для этого параметра, то нет необходимости использовать Query.
Но вам по-прежнему нужно использовать Path для path-параметра item_id. И если по какой-либо причине вы не хотите использовать Annotated, то могут возникнуть небольшие сложности.
Если вы поместите параметр со значением по умолчанию перед другим параметром, у которого нет значения по умолчанию, то Python укажет на ошибку.
Но вы можете изменить порядок параметров, чтобы параметр без значения по умолчанию (query-параметр q) шёл первым.
Это не имеет значения для FastAPI. Он распознает параметры по их названиям, типам и значениям по умолчанию (Query, Path, и т.д.), ему не важен их порядок.
Поэтому вы можете определить функцию так:
{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
Но имейте в виду, что если вы используете Annotated, вы не столкнётесь с этой проблемой, так как вы не используете значения по умолчанию параметров функции для Query() или Path().
{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *}
Задайте нужный вам порядок параметров, полезные приёмы
/// tip | Подсказка
Это не имеет большого значения, если вы используете Annotated.
///
Здесь описан небольшой приём, который может оказаться удобным, хотя часто он вам не понадобится.
Если вы хотите:
- объявить query-параметр
qбезQueryи без значения по умолчанию - объявить path-параметр
item_idс помощьюPath - указать их в другом порядке
- не использовать
Annotated
...то вы можете использовать специальную возможность синтаксиса Python.
Передайте * в качестве первого параметра функции.
Python не будет ничего делать с *, но он будет знать, что все следующие параметры являются именованными аргументами (парами ключ-значение), также известными как kwargs, даже если у них нет значений по умолчанию.
{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
Лучше с Annotated
Имейте в виду, что если вы используете Annotated, то, поскольку вы не используете значений по умолчанию для параметров функции, у вас не возникнет подобной проблемы и вам, вероятно, не придётся использовать *.
{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *}
Валидация числовых данных: больше или равно
С помощью Query и Path (и других классов, которые мы разберём позже) вы можете добавлять ограничения для числовых данных.
В этом примере при указании ge=1, параметр item_id должен быть целым числом "greater than or equal" — больше или равно 1.
{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *}
Валидация числовых данных: больше и меньше или равно
То же самое применимо к:
gt: больше (greaterthan)le: меньше или равно (less than orequal)
{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *}
Валидация числовых данных: числа с плавающей точкой, больше и меньше
Валидация также применима к значениям типа float.
В этом случае становится важной возможность добавить ограничение gt, вместо ge, поскольку в таком случае вы можете, например, создать ограничение, чтобы значение было больше 0, даже если оно меньше 1.
Таким образом, 0.5 будет корректным значением. А 0.0 или 0 — нет.
То же самое справедливо и для lt.
{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *}
Резюме
С помощью Query, Path (и других классов, которые мы пока не затронули) вы можете добавлять метаданные и строковую валидацию тем же способом, как и в главе Query-параметры и валидация строк{.internal-link target=_blank}.
А также вы можете добавить валидацию числовых данных:
gt: больше (greaterthan)ge: больше или равно (greater than orequal)lt: меньше (lessthan)le: меньше или равно (less than orequal)
/// info | Информация
Query, Path и другие классы, которые вы разберёте позже, являются наследниками общего класса Param.
Все они используют те же параметры для дополнительной валидации и метаданных, которые вы видели ранее.
///
/// note | Технические детали
Query, Path и другие "классы", которые вы импортируете из fastapi, на самом деле являются функциями, которые при вызове возвращают экземпляры одноимённых классов.
Объект Query, который вы импортируете, является функцией. И при вызове она возвращает экземпляр одноимённого класса Query.
Использование функций (вместо использования классов напрямую) нужно для того, чтобы ваш редактор не подсвечивал ошибки, связанные с их типами.
Таким образом вы можете использовать привычный вам редактор и инструменты разработки, не добавляя дополнительных конфигураций для игнорирования подобных ошибок.
///