Skip to content

От переводчика

Это машинный перевод (DeepSeek) статьи https://fastapi.tiangolo.com/tutorial/path-params

Версия от 03.09.2026

 

Перевод прочих разделов документации буду по мере сил делать.

Обо мне

Параметры пути

Вы можете объявлять параметры (или переменные) пути, используя тот же синтаксис, что и в форматированных строках Python:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id):
    return {"item_id": item_id}

Значение параметра пути item_id будет передано в вашу функцию как аргумент item_id.

Таким образом, если вы запустите этот пример и перейдете по адресу http://127.0.0.1:8000/items/foo, вы увидите ответ:

{"item_id":"foo"}

Параметры пути с типами

Вы можете объявить тип параметра пути в функции, используя стандартные аннотации типов Python:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

В этом случае item_id объявлен как int.

Совет

Это обеспечит поддержку редактора внутри вашей функции, включая проверки ошибок, автодополнение и т.д.

Преобразование данных

Если вы запустите этот пример и откроете браузер по адресу http://127.0.0.1:8000/items/3, вы увидите ответ:

{"item_id":3}

Совет

Обратите внимание, что значение, которое получила (и вернула) ваша функция, — это 3 как Python int, а не строка "3".

Таким образом, с помощью этого объявления типа FastAPI предоставляет автоматический "парсинг" запроса.

Валидация данных

Но если вы перейдете в браузере по адресу http://127.0.0.1:8000/items/foo, вы увидите понятную HTTP-ошибку:

{
  "detail": [
    {
      "type": "int_parsing",
      "loc": [
        "path",
        "item_id"
      ],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "foo"
    }
  ]
}

потому что параметр пути item_id имел значение "foo", которое не является int.

Та же ошибка появится, если вы передадите float вместо int, например: http://127.0.0.1:8000/items/4.2

Совет

Таким образом, с тем же объявлением типа Python FastAPI обеспечивает валидацию данных.

Обратите внимание, что ошибка также четко указывает, где именно валидация не прошла.

Это невероятно полезно при разработке и отладке кода, взаимодействующего с вашим API.

Документация

И когда вы откроете браузер по адресу http://127.0.0.1:8000/docs, вы увидите автоматическую интерактивную документацию API, подобную этой:

Совет

Опять же, просто с тем же объявлением типа Python FastAPI предоставляет автоматическую интерактивную документацию (интегрирующую Swagger UI).

Обратите внимание, что параметр пути объявлен как целое число.

Преимущества, основанные на стандартах, альтернативная документация

И поскольку сгенерированная схема основана на стандарте OpenAPI, существует множество совместимых инструментов.

Благодаря этому FastAPI сам предоставляет альтернативную документацию API (с использованием ReDoc), которую вы можете открыть по адресу http://127.0.0.1:8000/redoc:

Таким же образом существует множество совместимых инструментов, включая инструменты генерации кода для многих языков.

Pydantic

Вся валидация данных выполняется под капотом с помощью Pydantic, так что вы получаете все его преимущества. И вы знаете, что в надежных руках.

Вы можете использовать те же объявления типов с str, float, bool и многими другими сложными типами данных.

Некоторые из них будут рассмотрены в следующих главах руководства.

Порядок имеет значение

При создании операций пути вы можете столкнуться с ситуациями, когда у вас есть фиксированный путь.

Например, /users/me — допустим, это для получения данных о текущем пользователе.

И у вас также может быть путь /users/{user_id} для получения данных о конкретном пользователе по его ID.

Поскольку операции пути выполняются по порядку, необходимо убедиться, что путь /users/me объявлен раньше, чем /users/{user_id}:

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/me")
async def read_user_me():
    return {"user_id": "the current user"}


@app.get("/users/{user_id}")
async def read_user(user_id: str):
    return {"user_id": user_id}

В противном случае путь /users/{user_id} будет соответствовать и /users/me, "думая", что он получает параметр user_id со значением "me".

Аналогично, вы не можете переопределить операцию пути:

from fastapi import FastAPI

app = FastAPI()


@app.get("/users")
async def read_users():
    return ["Rick", "Morty"]


@app.get("/users")
async def read_users2():
    return ["Bean", "Elfo"]

Первый будет использоваться всегда, поскольку путь совпадает первым.

Предопределенные значения

Если у вас есть операция пути, которая принимает параметр пути, но вы хотите, чтобы возможные допустимые значения параметра пути были предопределены, вы можете использовать стандартный Python Enum.

Создание класса Enum

Импортируйте Enum и создайте подкласс, наследующий от str и Enum.

Наследуя от str, документация API сможет знать, что значения должны быть типа string, и сможет правильно их отображать.

Затем создайте атрибуты класса с фиксированными значениями, которые и будут допустимыми значениями:

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

Совет

Если вам интересно, "AlexNet", "ResNet" и "LeNet" — это просто названия архитектур моделей машинного обучения.

Объявление параметра пути

Затем создайте параметр пути с аннотацией типа, используя созданный вами класс перечисления (ModelName):

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

Проверьте документацию

Поскольку допустимые значения для параметра пути предопределены, интерактивная документация может отобразить их красиво:

Работа с Python перечислениями

Значение параметра пути будет элементом перечисления.

Сравнение элементов перечисления

Вы можете сравнивать его с элементом перечисления в созданном вами перечислении ModelName:

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

Получение значения перечисления

Вы можете получить фактическое значение (в данном случае str) с помощью model_name.value или, в общем случае, your_enum_member.value:

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

Совет

Вы также можете получить доступ к значению "lenet" с помощью ModelName.lenet.value.

Возврат элементов перечисления

Вы можете возвращать элементы перечисления из вашей операции пути, даже вложенные в JSON-тело (например, dict).

Они будут преобразованы в соответствующие значения (в данном случае строки) перед возвратом клиенту:

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

Ваш клиент получит JSON-ответ вида:

{
  "model_name": "alexnet",
  "message": "Deep Learning FTW!"
}

Параметры пути, содержащие пути

Допустим, у вас есть операция пути с путем /files/{file_path}.

Но вам нужно, чтобы file_path сам содержал путь, например home/johndoe/myfile.txt.

Таким образом, URL для этого файла будет выглядеть так: /files/home/johndoe/myfile.txt.

Поддержка OpenAPI

OpenAPI не поддерживает способ объявления параметра пути, содержащего внутри путь, так как это может привести к сценариям, которые сложно тестировать и определять.

Тем не менее, вы все равно можете сделать это в FastAPI, используя один из внутренних инструментов Starlette.

И документация будет работать, хотя и не будет добавлять никаких указаний на то, что параметр должен содержать путь.

Конвертер пути

Используя опцию непосредственно из Starlette, вы можете объявить параметр пути, содержащий путь, используя URL вида:

/files/{file_path:path}

В этом случае имя параметра — file_path, а последняя часть :path указывает, что параметр должен соответствовать любому пути.

Таким образом, вы можете использовать это так:

from fastapi import FastAPI

app = FastAPI()


@app.get("/files/{file_path:path}")
async def read_file(file_path: str):
    return {"file_path": file_path}

Совет

Возможно, вам понадобится, чтобы параметр содержал /home/johndoe/myfile.txt с ведущим слешем (/).

В этом случае URL будет таким: /files//home/johndoe/myfile.txt с двойным слешем (//) между files и home.

Резюме

С FastAPI, используя краткие, интуитивно понятные и стандартные объявления типов Python, вы получаете:

  • Поддержку редактора: проверки ошибок, автодополнение и т.д.
  • Преобразование (парсинг) данных
  • Валидацию данных
  • Аннотацию API и автоматическую документацию

И вам нужно объявить их только один раз.

Это, вероятно, главное заметное преимущество FastAPI по сравнению с альтернативными фреймворками (помимо высокой производительности).