Skip to content

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

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

Версия от 03.09.2026

Неочевидных моментов в уроке не обнаружено, но я рад сообщить, что дополнил базу инструмента для импорта модулей и классов в python классами, использующимися в уроке.

Подпишитесь на канал "Изучаем FastAPI", чтобы ссылки на инструмент работала.

 

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

Обо мне

Параметры заголовков

Вы можете определять параметры заголовков так же, как определяете параметры Query, Path и Cookie.

Импорт Header

Сначала импортируйте Header:

from typing import Annotated

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
    return {"User-Agent": user_agent}
🤓 Другие версии и варианты

Совет

По возможности предпочитайте версию с Annotated.

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: str | None = Header(default=None)):
    return {"User-Agent": user_agent}

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

Затем объявите параметры заголовков, используя ту же структуру, что и с Path, Query и Cookie.

Вы можете определить значение по умолчанию, а также все дополнительные параметры валидации или аннотации:

from typing import Annotated

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
    return {"User-Agent": user_agent}
🤓 Другие версии и варианты

Совет

По возможности предпочитайте версию с Annotated.

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(user_agent: str | None = Header(default=None)):
    return {"User-Agent": user_agent}

Технические детали

Header — это «сестринский» класс Path, Query и Cookie. Он также наследуется от того же общего класса Param.

Но помните, что когда вы импортируете Query, Path, Header и другие из fastapi, на самом деле это функции, возвращающие специальные классы.

Примечание

Чтобы объявить заголовки, вам нужно использовать Header, иначе параметры будут интерпретированы как параметры запроса.

Автоматическое преобразование

Header имеет небольшую дополнительную функциональность поверх того, что предоставляют Path, Query и Cookie.

Большинство стандартных заголовков разделены символом «дефис», также известным как «знак минус» (-).

Но переменная, такая как user-agent, недопустима в Python.

Поэтому по умолчанию Header преобразует символы имён параметров из подчёркивания (_) в дефис (-), чтобы извлекать и документировать заголовки.

Кроме того, заголовки HTTP нечувствительны к регистру, поэтому вы можете объявлять их в стандартном стиле Python (также известном как «snake_case»).

Таким образом, вы можете использовать user_agent, как обычно, в коде Python, вместо того чтобы делать первые буквы заглавными, как User_Agent или что-то подобное.

Если по какой-то причине вам нужно отключить автоматическое преобразование подчёркиваний в дефисы, установите параметр convert_underscores у Header в False:

from typing import Annotated

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(
    strange_header: Annotated[str | None, Header(convert_underscores=False)] = None,
):
    return {"strange_header": strange_header}
🤓 Другие версии и варианты

Совет

По возможности предпочитайте версию с Annotated.

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(
    strange_header: str | None = Header(default=None, convert_underscores=False),
):
    return {"strange_header": strange_header}

Предупреждение

Прежде чем устанавливать convert_underscores в False, имейте в виду, что некоторые HTTP-прокси и серверы запрещают использование заголовков с подчёркиваниями.

Дублирующиеся заголовки

Возможно получение дублирующихся заголовков. Это означает, что один и тот же заголовок имеет несколько значений.

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

Вы получите все значения из дублирующегося заголовка в виде Python list.

Например, чтобы объявить заголовок X-Token, который может появляться более одного раза, вы можете написать:

from typing import Annotated

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(x_token: Annotated[list[str] | None, Header()] = None):
    return {"X-Token values": x_token}
🤓 Другие версии и варианты

Совет

По возможности предпочитайте версию с Annotated.

from fastapi import FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(x_token: list[str] | None = Header(default=None)):
    return {"X-Token values": x_token}

Если вы взаимодействуете с этой операцией пути, отправляя два HTTP-заголовка, например:

X-Token: foo
X-Token: bar

Ответ будет таким:

{
    "X-Token values": [
        "bar",
        "foo"
    ]
}

Итог

Объявляйте заголовки с помощью Header, используя тот же общий шаблон, что и Query, Path и Cookie.

И не беспокойтесь о подчёркиваниях в ваших переменных, FastAPI позаботится об их преобразовании.