Перейти к основному содержимому

Заголовки

Заголовки — это пары ключ-значение, отправляемые вместе с HTTP-запросом. Они несут метаданные о запросе — такие как тип контента, токены авторизации, информацию о клиенте и многое другое. Заголовки не являются частью URL или тела, но отправляются в отдельной секции между строкой запроса и телом.

Как выглядят параметры заголовков?​

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

GET /profile HTTP/1.1
Host: example.com
User-Agent: curl/8.5.0
Accept: application/json, text/plain, text/html

Каждый заголовок структурирован как пара ключ-значение, и согласно спецификации HTTP (RFC 7230), ключ заголовка может появляться несколько раз с различными значениями. Когда это происходит, значения либо:

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

Параметры заголовков vs другие параметры запроса​

  1. Расположение в запросе Параметры заголовков являются частью HTTP-заголовков, отправляемых отдельно от URL и тела. Например:

    GET /resource HTTP/1.1
    Host: example.com
    Authorization: Bearer abc123
    X-Custom-Header: value

  2. Формат кодирования Заголовки — это пары ключ-значение в виде обычного текста. В отличие от параметров запроса, они не кодируются URL, но значения должны соответствовать стандартам HTTP-заголовков.

  3. Типы данных Заголовки обычно несут строки, но могут быть разобраны в примитивные типы, такие как int, bool, или пользовательские типы по необходимости.

  4. Случаи использования Заголовки обычно используются для метаданных, таких как токены аутентификации, тип контента, информация о пользовательском агенте или пользовательские флаги управления. Они не предназначены для несения больших или сложных структур данных, как параметры тела.

Объявление параметров заголовков в lihil​

Вы можете легко объявлять параметры заголовков непосредственно в вашей конечной точке, используя Param("header").

from lihil import Route, Param
from typing import Annotated

route = Route("/greet")

@route.get
async def greet_user(
    user_agent: Annotated[str, Param("header")],  # Автоматически сопоставляется с "user-agent"
    accept: Annotated[list[str], Param("header")],  # Обрабатывает разделенный запятыми Accept
):
    return {"ua": user_agent, "accepts": accept}

Заголовки с множественными значениями​

Некоторые заголовки — такие как Accept, Accept-Language, Cache-Control естественно поддерживают множественные значения, разделенные запятыми.

lihil поддерживает это из коробки. Чтобы принять заголовок с множественными значениями, просто используйте аннотацию типа list[str]:

Чтобы принять заголовок с множественными значениями, просто используйте аннотацию типа list[str]:

accept: Annotated[list[str], Param("header")]

Это правильно разберет:

Accept: text/html, application/json

в:

["text/html", "application/json"]

Сопоставление ключей заголовков​

Имена HTTP-заголовков часто используют kebab-case (например, X-Request-ID), но переменные Python не могут содержать тире. lihil решает это двумя способами:

Автоматическое сопоставление: По умолчанию lihil преобразует my_token в my-token.

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

request_id: Annotated[str, Param("header", alias="x-request-id")]

Пользовательский декодер​

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

from lihil import Route, Param
from typing import Annotated

def custom_decoder(value: str) -> str:
    # Пользовательская логика декодирования
    return value.lower()

route = Route("/greet")

@route
async def create_user(
    user_agent: Annotated[str, Param("header")],
    custom_header: Annotated[str, Param("header", decoder=custom_decoder)],
):
    return {"ua": user_agent, "custom": custom_header}

Резюме​

  • Параметры заголовков являются частью HTTP-заголовков, несущих метаданные, такие как токены аутентификации или пользовательские флаги.
  • Это пары ключ-значение в виде обычного текста, не кодированные URL.
  • В lihil объявляйте заголовки явно, используя Annotated с Param(alias=...) для точных имен заголовков.
  • lihil автоматически обрабатывает конвертацию типов, валидацию и значения по умолчанию.
  • Отсутствующие или недействительные заголовки приводят к автоматическим ответам об ошибках для надежной обработки ввода.