load-tester Все курсы

✻ Урок 2.2 · Тема 2: Как устроен веб-сервис

REST API, JSON и авторизация

⏱ 2.5 ч

Как работать с кодом и когда идти дальше

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

  • Запусти готовое. Код приложения и вспомогательных скриптов можно скопировать. Пойми, зачем они нужны, что запускают или меняют и как проверить результат. Разбирать каждую функцию внутри готового инструмента не требуется.
  • Измени по образцу. Разбери новые конструкции, объяснённые в уроке. Измени указанный параметр или часть кода, предскажи результат и проверь запуском.
  • Напиши сам. Собери свой вариант под условия задания. Образцы и справка разрешены: важно объяснить своё решение и проверить его работу.

Можно идти дальше, если ты выполнил практику, получил ожидаемый результат и понимаешь, что проверил. Если задание просит изменить код, проверь и своё изменение.

Непонятные детали готового инструмента можно оставить на потом. При ошибке запуска вернись к разбору вывода и типичным ошибкам в уроке.

Зачем это нужно

Допустим, в «Магазине» появилась жалоба: «после входа в личный кабинет всё тормозит». Каталог ты читать уже умеешь (урок 2.1), но жалуются не на него. Покупатель регистрируется, входит, кладёт товар в корзину и оформляет заказ. Нагрузочный тест должен ходить так же: запросами с данными в формате JSON (текст с полями) и с пропуском, токеном (строкой, которую сервер выдаёт после входа).

Частая ловушка первого теста: сотня виртуальных покупателей, красный график, сплошные ошибки. Час уходит на поиски поломки в магазине, а сломан тест: он не прикладывал пропуск, и сервер каждому отвечал кодом 401: «не знаю, кто ты». Вот как выглядит такой отказ, если спросить корзину без пропуска:

$ curl localhost:8000/api/cart
{"detail":"bearer token required"}

Сервер не показал корзину и ответил текстом «нужен токен». Для него это обычный отказ, а для графика теста ошибка, и таких ответов будет сотня. Поэтому любой новый сценарий сначала проходят руками, и этому ты научишься здесь.

Вход и заказ к тому же обычно самые тяжёлые операции (тема 11), и начать надо с умения выполнить эти запросы руками и прочитать ответ.

Шаг проекта: ты зарегистрируешь своего тестового пользователя student@shop.lab, войдёшь, положишь товар в корзину и оформишь заказ. Всю цепочку запишешь в скрипт ~/perf-lab/02-web/order-flow.sh: это прообраз сценария пользователя, который в теме 9 ты переложишь на Locust.

Что нужно знать

  • Запрос, ответ, метод, заголовок, код статуса: урок 2.1. Здесь мы много раз будем смотреть 200, 201, 401, 404, 422.
  • Стенд «Магазин» запущен (docker compose ps показывает четыре healthy). Если нет, вернись к практике 2.1: cd ~/learning/load-tester/project/shop && docker compose up -d --wait.
  • jq установлен в уроке 1.1: проверь jq --version.
  • Переменные терминала и подстановка $(...): урок 1.1.

Картина целиком

Ты приходишь в клуб. На входе охранник проверяет паспорт (логин и пароль), и если всё в порядке, выдаёт браслет. Дальше внутри никто не просит паспорт: бармен смотрит на браслет и обслуживает. Браслет действует до закрытия клуба, потом недействителен. Потерял браслет: снова к охраннику.

Так работает вход в «Магазин». Логин и пароль ты отправляешь один раз и получаешь токен (token, «жетон»): длинную случайную строку, которая выполняет роль браслета. Каждый следующий запрос несёт токен в заголовке. Магазин по токену узнаёт, кто ты, и работает с твоей корзиной и твоими заказами.

sequenceDiagram
    participant К as Клиент
    participant М as Магазин
    participant R as Redis
    К->>М: POST /api/login<br/>email и пароль
    М->>М: проверить пароль
    М->>R: записать токен на 1 час
    М-->>К: 200 и токен
    К->>М: GET /api/cart<br/>Authorization: Bearer токен
    М->>R: чей это токен?
    R-->>М: пользователь 1001
    М-->>К: 200 и корзина

На схеме видно: пароль участвует только в первом запросе. Токен Магазин хранит в Redis (быстрое хранилище «ключ → значение», подробно в уроке 2.3) и при каждом запросе заглядывает туда. Поэтому токен можно «отозвать»: достаточно удалить запись, и он перестаёт действовать.

Теория

JSON: как записывают данные в запросах и ответах

Клиент и сервер написаны на разных языках и работают на разных машинах. Как передать корзину с тремя товарами так, чтобы поняли оба? Они договариваются записывать данные как анкету с подписанными полями: «Имя: Иван, возраст: 30». Такая запись называется JSON (JavaScript Object Notation, читается «джейсон»). Правила строгие: перепутаешь кавычку, и анкету не примут.

Вот ответ каталога. В нём есть почти всё, что бывает в JSON:

{
  "items": [
    {"id": 1, "name": "Товар 1", "price": 137.0, "category_id": 1, "stock": 1000000},
    {"id": 2, "name": "Товар 2", "price": 174.0, "category_id": 2, "stock": 1000000}
  ],
  "page": 1,
  "size": 2,
  "total": 10000
}

Фигурные скобки {} это объект: набор пар «ключ: значение», как строки анкеты. Квадратные [] это список значений через запятую. Текст пишут в двойных кавычках, числа без кавычек. Ещё бывают true, false и null («пусто»).

Читаем: items это список из двух товаров, а total показывает, что всего их 10000.

Когда клиент сам отправляет данные (регистрация, вход), он кладёт JSON в тело запроса и добавляет заголовок Content-Type: application/json. По нему сервер понимает, как читать тело.

Три ошибки ты сделаешь в первые полчаса: одинарные кавычки ({'email': 'a@b.c'}), запятая после последнего элемента ({"a": 1,}) и ключ без кавычек. Четвёртая ловушка в терминале: он «съест» двойные кавычки в curl -d {"a":1}, поэтому JSON оборачивай в одинарные: -d '{"a":1}'.

Осторожно: JSON похож на словарь Python, но в нём true и false пишутся строчными (в Python True и False). Подробнее: урок 4.4.

Прикинь сам: найди ошибку в {"email": "a@b.c", "password": 'secret1234'}.

Пароль в одинарных кавычках. В JSON строки только в двойных: "secret1234".

Главное: JSON это текст из объектов {}, списков [], строк в двойных кавычках, чисел и true, false, null; тело с JSON всегда сопровождает заголовок Content-Type: application/json.

Ответ сервера приходит одной длинной строкой. Как достать из неё токен, а не искать глазами?

jq: достать нужное поле из JSON

В скриптах из ответа на вход нужен токен, из ответа на заказ номер. Программа jq (ты встречал её в уроке 1.2) читает JSON и применяет к нему «фильтр», то есть описание того, что достать. Сохраним каталог из трёх товаров в файл (-s скрывает индикатор curl, > пишет ответ в файл):

curl -s 'http://localhost:8000/api/products?size=3' > /tmp/p.json
jq .total /tmp/p.json                          # 10000
jq '.items[0].name' /tmp/p.json                # "Товар 1"
jq -r '.items[0].name' /tmp/p.json             # Товар 1
jq -r '.items[] | select(.price > 150) | .name' /tmp/p.json   # Товар 2 и Товар 3

Разберём по шагам.

  1. Поле. Точка . значит «текущее значение», .total «поле total»: получим 10000.
  2. Элемент списка. .items[0] берёт первый элемент (счёт с нуля), .items[] каждый по очереди. Флаг -r (raw, «сырой») убирает кавычки вокруг строки, он нужен, когда результат идёт в переменную.
  3. Отбор. Вертикальная черта | передаёт результат слева в выражение справа, как в терминале. select(.price > 150) оставляет только товары дороже 150, а .name берёт у них название.

Позже понадобится ещё один приём: {id, status} собирает из объекта новый, только с этими полями (например, jq '{id, status}' на заказе покажет номер и статус).

Фильтр со скобками и чертой оборачивай в одинарные кавычки, иначе терминал поймёт их по-своему.

Прикинь сам: что напечатает jq '.items[1].price' /tmp/p.json?

Второй товар, потому что счёт с нуля: 174.0, цена видна в ответе каталога выше.

Осторожно: jq: error (at <stdin>:1): Cannot index array with string "items" значит, что на этом месте список, а не объект: из списка достают элемент по номеру или через []. А jq: parse error: Invalid numeric literal значит, что пришёл не JSON, почти всегда HTML-страница или другой текст ошибки. Сначала посмотри, что вернул curl.

Главное: jq достаёт поле по пути с точки, список разбирают через [0] или [], | передаёт результат дальше, а -r убирает кавычки.

Данные читать умеем. А по каким правилам устроены адреса API?

REST: адреса как существительные, методы как глаголы

Если адреса у каждого свои (/getProduct, /doOrder), к каждому API нужна своя инструкция. Негласное соглашение, которое это лечит, называется REST (Representational State Transfer): увидев адрес, ты примерно угадываешь, что он делает.

Первая идея: адрес называет ресурс, то есть предмет, с которым работает API. Это существительное: /api/products (все товары), /api/products/42 (один товар), /api/cart, /api/orders. Вторая идея: действие задаёт метод HTTP, глагол (урок 2.1). GET читает, POST создаёт, DELETE удаляет. Поэтому один адрес с разными методами делает разное: GET /api/orders покажет заказы, POST /api/orders создаст новый.

Третья идея: сервер не хранит состояние между запросами (по-английски stateless). Приложение не держит данные клиента в памяти своего процесса и не помнит, что «этот клиент недавно смотрел каталог»: каждый запрос несёт всё нужное, включая токен (его сверяют во внешнем хранилище, Redis, общем для всех экземпляров). Зато запросы можно развести по разным серверам.

Для нагрузки отсюда следует важное: GET ничего не меняет в данных, но мощность он тратит, поэтому на рабочем сервере и каталог нагружают по согласованию и с ограничением числа запросов в секунду. А POST /api/orders меняет склад и базу, и такой тест создаёт данные.

Врезка: токен «Магазина» и JWT. Здесь «stateless» относится к приложению: токен проверяется поиском в Redis, то есть это серверная сессия. Плюс: отозвать мгновенно (удалить запись). Минус: нужен Redis на каждый запрос. JWT (JSON Web Token) самодостаточен: внутри подписанные данные пользователя, хранилище не нужно, но отозвать токен до истечения сложно. Выбор зависит от задачи, на собеседовании спрашивают именно об этом.

Для любопытных: все адреса API «Магазина»

Общий префикс /api, {id} заменяется числом.

Метод и адрес Что делает Токен Ответ
POST /register зарегистрироваться нет 201
POST /login войти, получить токен нет 200
GET /categories список категорий нет 200
GET /products каталог (category_id, q, page, size) нет 200
GET /products/{id} один товар нет 200
GET /cart моя корзина да 200
POST /cart/items добавить товар в корзину да 201
DELETE /cart/items/{id} убрать товар из корзины да 204
POST /orders оформить заказ из корзины да 201
GET /orders мои последние заказы (до 20) да 200
GET /orders/{id} мой заказ по номеру да 200

Прикинь сам: как по правилам REST выглядит запрос, который убирает товар 5 из корзины, и какой код ждать?

Ресурс «позиция корзины» плюс глагол «удалить»: DELETE /api/cart/items/5 с токеном. Ждём 204: успех без тела.

Осторожно: REST это не «JSON поверх HTTP». REST про ресурсы и методы, а JSON лишь самый частый формат.

Главное: адрес называет ресурс, метод называет действие, сервер между запросами ничего о клиенте не помнит.

Многие адреса требуют токен. Кто и как его проверяет?

Аутентификация и авторизация

Покупатель вошёл в личный кабинет и видит чужие заказы. Какую проверку сервис пропустил? Их две. «Кто ты?» это аутентификация (authentication): проверка, что человек тот, за кого себя выдаёт. «Что тебе можно?» это авторизация (authorization): можно ли именно этому пользователю именно это действие. Без первой любой выдал бы себя за другого, без второй вошедший читал бы чужие заказы.

В «Магазине» аутентификация это POST /api/login: проверка пароля и выдача токена. Авторизация простая: у каждого пользователя свои корзина и заказы, и по токену Магазин берёт данные только этого пользователя. Если попросить чужой заказ, придёт 404 order not found: Магазин не раскрывает, что такой заказ вообще есть.

С кодами ошибок так. 401 значит «не удалось понять, кто ты»: нет токена, он неверный или просрочен, пароль не подошёл. 403 значит «тебя знаю, но этого тебе нельзя». В «Магазине» 403 не бывает: права у всех одинаковые.

Главное: аутентификация отвечает «кто ты» и кончается ошибкой 401, авторизация отвечает «что можно» и кончается 403 (или 404, если сервис прячет чужое).

Пароль проверяется один раз, а запросов за сессию десятки. Чем Магазин узнаёт тебя дальше?

Токен и заголовок Authorization

Проверять пароль дорого. Пароль хранят не как есть, а в виде хэша (hash): необратимого «отпечатка» пароля. Восстановить пароль из него нельзя, можно только проверить, совпадает ли отпечаток. Считается хэш сотни миллисекунд, и это специально: так подбирать пароли медленно. Делать такую проверку на каждый запрос было бы нереально, поэтому пароль проверяют один раз и меняют на токен, который проверяется мгновенно.

Токен в «Магазине» это случайная строка из 64 символов, например 7c1e9f...3ab2. Магазин пишет в Redis запись «токен → номер пользователя» на час: это время жизни записи (TTL, time to live), 3600 секунд, и поле expires_in: 3600 сообщает его клиенту.

Клиент прикладывает токен к каждому запросу в заголовке:

Authorization: Bearer 7c1e9f...3ab2

Слово Bearer («предъявитель») значит «обслужи того, кто предъявил этот токен». Кто знает токен, тот и считается пользователем, поэтому его хранят как пароль: не публикуют и не пишут в отчёты. Вот жизнь токена целиком:

stateDiagram-v2
    state "Без токена" as NoToken
    state "Токен действует" as Valid
    state "Токен истёк" as Expired
    [*] --> NoToken
    NoToken --> Valid: POST /login
    Valid --> Valid: запросы с токеном
    Valid --> Expired: прошёл час
    Expired --> NoToken: ответ 401, нужен новый вход
    NoToken --> NoToken: любой запрос, ответ 401

Без токена или с истёкшим Магазин отвечает 401, и клиенту нужно снова пройти login.

Прикинь сам: твой тест идёт 2,5 часа, а войти он успел один раз, в самом начале. Когда появятся 401?

Через час: токен истёк, и каждый следующий запрос получит 401. Скрипт, не умеющий входить заново, соберёт тысячи «ошибок» при исправном сервере (урок 9.3).

Осторожно: токен и пароль не одно и то же. Пароль знает только пользователь, а токен несут с каждым запросом.

Главное: пароль меняют на токен один раз, дальше токен идёт в заголовке Authorization: Bearer <токен> и живёт час.

Но что будет, если ответ на POST потеряется по дороге, а клиент отправит запрос ещё раз?

Идемпотентность: можно ли повторить запрос

В уроке 2.1 мы сказали, что POST не идемпотентен: два запроса дают два заказа, а GET и DELETE можно повторять. Сеть ненадёжна, ответ мог потеряться, и клиент не знает, выполнился запрос или нет. Здесь только то, что добавляется для нагрузки.

Кнопка лифта, нажатая пять раз, работает как одна, а кнопка «купить» может дать пять покупок. Для нагрузки это важно дважды. Первое: инструмент при ошибке может сам повторить запрос, и повтор POST исказит число заказов. Второе: оплата в «Магазине» при сбое повторяется три раза. На настоящем сервисе для такого POST придумывают ключ идемпотентности: клиент присылает уникальный ключ, и сервер по повтору с тем же ключом не списывает деньги второй раз (урок 11.5).

Осторожно: идемпотентный не значит безопасный. Безопасный метод ничего не меняет (GET), а идемпотентный может менять, но повтор ничего нового не даст (DELETE).

Главное: повтор идемпотентного запроса безвреден, повтор POST может создать вторую покупку, и нагрузочный инструмент не должен повторять такие запросы вслепую.

Осталось научиться читать ответ, когда запрос не удался.

Код и тело ответа: где искать причину

Причину ищут в двух местах по порядку. Сначала код: 4xx значит ошибку клиента, 5xx сервера. Потом тело: в «Магазине» там всегда JSON с полем detail. Для 4xx в нём подсказка, что поправить. Для 5xx там обычно короткое сообщение, а подробности лежат в логах сервера по request_id (он есть и в заголовке ответа).

У detail две формы. Первая: {"detail": "текст"}, так отвечает сам код магазина (invalid credentials, invalid or expired token, cart is empty, product not found, email already registered). Вторая: {"detail": [ {...}, ... ]} для ошибок проверки данных (код 422). Это список, потому что ошибок может быть несколько, и каждая описывает, где (loc), что не так (msg) и какого типа (type).

Выбери сценарии в виджете:

Все неудачи возвращают detail. Сравни bad-login, no-token и bad-token (все 401, но текст разный), cart-422 (проверка данных) и empty-order (код 400).

Плохой запрос получает 400, 404 или 422, и тут легко запутаться. Помогает последовательность вопросов:

flowchart TD
    A{"Токен есть<br>и верный?"} -- нет --> B["401: не знаю, кто ты"]
    A -- да --> C{"Форма запроса<br>подходит?"}
    C -- нет --> D["422: нет поля,<br>не тот тип, вне границ"]
    C -- да --> E{"Нужный объект<br>существует?"}
    E -- нет --> F["404: например,<br>товара нет"]
    E -- да --> G{"Действие возможно<br>сейчас?"}
    G -- нет --> H["400: заказ из<br>пустой корзины"]
    G -- да --> I["Успех: 200, 201, 204"]

Сервер на нашем стенде проверяет пропуск, потом форму, потом существование объекта, потом состояние. Ещё одна строка вне схемы: 409 «конфликт», например email уже занят или на складе мало товара.

Осторожно: порядок «токен, потом форма» верен для корректного JSON. Сломанный JSON отклоняется ещё раньше, кодом 422 json_invalid, даже без токена. В других фреймворках порядок может быть иным. При росте ошибок в тесте смотри на код: 401 и 422 говорят об ошибке теста, 503 и 504 о перегрузке стенда.

Проверь понимание: запрос POST /api/cart/items с телом {"product_id": 5, "qty": 0} и верным токеном. Какой код вернётся?

Ответ

422: qty должно быть не меньше 1, это нарушение формы данных. Токен верный, товар существует, но тело не прошло проверку.

Главное: сначала смотри код (кто виноват), потом detail (что поправить); 401 и 422 чаще всего вина теста, 5xx вина сервера.

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

Практика

Все команды из каталога ~/perf-lab/02-web. Стенд работает на localhost:8000.

cd ~/perf-lab/02-web
curl -s localhost:8000/readyz

Должно вернуться {"status":"ready"}. Если нет, сначала подними стенд.

1. Регистрация

Ты регистрируешь своего тестового пользователя. Новая команда: curl с телом. Разбор: -X POST задаёт метод, -H 'Content-Type: application/json' добавляет заголовок, -d '...' (data) передаёт тело, и если есть -d, curl по умолчанию сам выберет POST. -i покажет код и заголовки.

curl -i -X POST localhost:8000/api/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"student@shop.lab","password":"learnload1"}'

Обратный слэш \ в конце строки переносит команду на следующую строку: терминал воспринимает её как одну.

HTTP/1.1 201 Created
date: Sat, 03 Oct 2026 10:30:01 GMT
server: uvicorn
content-length: 38
content-type: application/json
x-request-id: 6d0a3f1e8c2b4a77a9e5f0d1c2b3a495

{"id":1001,"email":"student@shop.lab"}

Как читать вывод: 201 значит «создано». В теле номер нового пользователя (1001: тысяча готовых пользователей user0001…user1000 уже есть) и email. Пароля в ответе нет, и это правильно. Регистрация заметно медленнее обычных запросов, потому что считается хэш пароля. Проверь: добавь -w '%{time_total}\n' -o /dev/null и увидишь около 0,25 с.

Повтори ту же команду:

HTTP/1.1 409 Conflict
...
{"detail":"email already registered"}

409 значит «конфликт»: такой email уже есть. Если ты по какой-то причине зарегистрирован раньше, пропусти шаг и переходи к входу.

Типичные ошибки:

  • 422 с "msg":"String should have at least 8 characters" и "loc":["body","password"]: пароль короче 8 символов.
  • 422 с "msg":"Value error, Нужен email": email без @ или точки.
  • 422 с "type":"json_invalid": сломан JSON, обычно кавычки. Проверь одинарные кавычки вокруг -d.
  • 422 с "type":"missing" и "loc":["body","email"]: опечатка в имени поля (или поля нет в теле).
  • 422 с "type":"model_attributes_type" и "loc":["body"]: забыл заголовок Content-Type: application/json, и сервер не стал читать тело как JSON.

2. Вход и токен

curl -s -X POST localhost:8000/api/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"student@shop.lab","password":"learnload1"}'
{"token":"7c1e9f0a4b6d28e5c3f71a90d4b8e2c6f5a3091b7d8e4c2a6f0b9d1e3a5c7f48","expires_in":3600}

Как читать вывод: token это твой пропуск (у тебя будет другой), expires_in сколько секунд он действует. Теперь сохрани токен в переменную терминала, чтобы не копировать его руками:

TOKEN=$(curl -s -X POST localhost:8000/api/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"student@shop.lab","password":"learnload1"}' | jq -r .token)
echo "${TOKEN:0:12}..."

Разбор: $( ... ) запускает команду и подставляет её вывод, | jq -r .token вытаскивает поле token без кавычек. ${TOKEN:0:12} показывает только первые 12 символов: полный токен в терминале и в записях лучше не светить.

7c1e9f0a4b6d...

Если вывод пустой, значит jq ничего не нашёл: проверь, что вход вернул 200, а не 401 (выполни команду без | jq -r .token и прочитай ответ).

Проверь ошибки входа:

curl -s -w '\n%{http_code}\n' -X POST localhost:8000/api/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"student@shop.lab","password":"неверный"}'
{"detail":"invalid credentials"}
401

-w '\n%{http_code}\n' печатает код после тела.

Типичные ошибки:

  • invalid credentials на верный пароль: ты не выполнил шаг 1 (пользователя student@shop.lab ещё нет) или опечатался в пароле.
  • Пустой TOKEN после jq -r .token: вход вернул не токен. Выполни команду без | jq -r .token и прочитай ответ.
  • 422 с json_invalid: в -d попали «умные» кавычки из скопированного текста. Набери прямые кавычки заново.

Магазин не говорит, что именно неверно, пароль или email. Это сделано намеренно: иначе можно подбирать существующие адреса. Но честности ради: регистрация на стенде отвечает 409 email already registered, то есть адреса всё же раскрывает. На рабочих системах это решают отдельно: подтверждением по почте или одним и тем же ответом на оба случая.

3. Кто я: корзина без токена и с токеном

Шаги 2-5 делай в одном окне терминала: переменная TOKEN живёт только в нём.

curl -s -w '\n%{http_code}\n' localhost:8000/api/cart
curl -s -w '\n%{http_code}\n' localhost:8000/api/cart -H 'Authorization: Bearer wrong-token'
curl -s -w '\n%{http_code}\n' localhost:8000/api/cart -H "Authorization: Bearer $TOKEN"
{"detail":"bearer token required"}
401
{"detail":"invalid or expired token"}
401
{"items":[],"total":0}
200

Как читать вывод: первая и вторая команды обе дают 401, но с разным текстом: в первом случае токена нет вовсе, во втором он есть, но Магазин его не знает. Третья команда: кавычки двойные, потому что внутри нужна подстановка $TOKEN (в одинарных кавычках терминал её не выполнит). Корзина пуста, total 0.

Типичные ошибки: bearer token required, хотя ты передал токен: заголовок написан неверно (Bearer и токен должны быть через пробел, в заголовке ровно два слова) или переменная TOKEN пуста (новое окно терминала не помнит переменных: выполни вход снова).

4. Положи товар в корзину

curl -s -X POST localhost:8000/api/cart/items \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"product_id":5,"qty":2}' | jq .
{
  "items": [
    {
      "product_id": 5,
      "name": "Товар 5",
      "price": 285.0,
      "qty": 2
    }
  ],
  "total": 570.0
}

Как читать вывод: в ответ приходит вся корзина после добавления. Товар 5 стоит 285, их два, итого 570. Если выполнишь команду ещё раз, qty вырастет до 4: повторное добавление не создаёт вторую строку, а увеличивает количество (поэтому POST /cart/items не идемпотентен: в 2.1 мы сказали это про POST вообще, здесь видно на деле).

Теперь три ошибки, каждая даёт свой код:

# 1. количество 0: нарушена форма, 422
curl -s -w '\n%{http_code}\n' -X POST localhost:8000/api/cart/items -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"product_id":5,"qty":0}'
# 2. такого товара нет: форма верна, объекта нет, 404
curl -s -w '\n%{http_code}\n' -X POST localhost:8000/api/cart/items -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"product_id":999999,"qty":1}'
# 3. DELETE товара 7: его в корзине нет, но ответ всё равно 204 и пустое тело
curl -s -w '%{http_code}\n' -X DELETE localhost:8000/api/cart/items/7 -H "Authorization: Bearer $TOKEN"
{"detail":[{"type":"greater_than_equal","loc":["body","qty"],"msg":"Input should be greater than or equal to 1","input":0,"ctx":{"ge":1}}]}
422
{"detail":"product not found"}
404
204

Как читать вывод: в 422 поле loc указывает на qty в теле, ctx показывает граничное значение. 204 печатается без тела, поэтому в выводе видна только цифра. В корзине лежит только товар 5, а мы удаляли товар 7: сервер всё равно отвечает 204, потому что цель «чтобы товара 7 в корзине не было» достигнута. Удалить то, чего нет, не ошибка (так и должен вести себя идемпотентный DELETE). Корзина при этом не изменилась, товар 5 на месте, и следующий шаг сработает. Строки с # это комментарии терминала: они ничего не делают, но объясняют, что происходит.

Типичные ошибки:

  • 401 с bearer token required: переменная TOKEN пуста (ты открыл новое окно терминала). Выполни вход из шага 2 снова.
  • 422 с json_invalid: перепутаны кавычки в -d (снаружи одинарные, внутри двойные).
  • 422 с model_attributes_type: забыт заголовок Content-Type: application/json.

5. Оформи заказ

curl -s -X POST localhost:8000/api/orders -H "Authorization: Bearer $TOKEN" | jq .
{
  "id": 200001,
  "status": "paid",
  "total": 570.0,
  "items": [
    {
      "product_id": 5,
      "name": "Товар 5",
      "price": 285.0,
      "qty": 2
    }
  ]
}

Номер заказа 200001: в базе уже есть 200 000 исторических заказов, твой стал первым новым.

Как читать вывод: 201, status: "paid" значит, что заказ оплачен (оплату выполнил сервис payment, подробности в уроке 2.3), total сумма, items что куплено. По времени заказ заметно медленнее каталога, потому что внутри идёт вызов оплаты, около 50 мс по умолчанию, плюс запись в базу.

Проверь, что корзина очищена, и повторный заказ невозможен:

curl -s -w '\n%{http_code}\n' -X POST localhost:8000/api/orders -H "Authorization: Bearer $TOKEN"
{"detail":"cart is empty"}
400

Теперь посмотри свои заказы и чужой заказ:

curl -s localhost:8000/api/orders -H "Authorization: Bearer $TOKEN" | jq '.[0] | {id, status, total}'   # {id, status, total}: новый объект только с тремя полями
curl -s -w '\n%{http_code}\n' localhost:8000/api/orders/1 -H "Authorization: Bearer $TOKEN"
{
  "id": 200001,
  "status": "paid",
  "total": 570.0
}
{"detail":"order not found"}
404

Как читать вывод: GET /api/orders возвращает список твоих заказов, свежие первыми, .[0] это самый новый. Заказ номер 1 существует, но принадлежит другому пользователю, и ты получаешь 404, а не 403: это и есть авторизация в действии.

Типичные ошибки:

  • {"detail":"not enough stock"} с кодом 409: на складе меньше, чем в корзине. На свежем стенде остаток миллион, значит, ты случайно положил огромное qty.
  • 502 с payment failed или 504 с payment timeout: сервис оплаты сейчас недоступен или медленный. Проверь curl -s localhost:8001/healthz, при необходимости docker compose restart payment.

6. Собери всё в скрипт

Теперь соберём цепочку в один файл. В скриптах переменные хранят промежуточные результаты, а проверка set -e останавливает выполнение при первой ошибке. Подробности про скрипты: урок 1.5.

Первый вариант перенеси из образца. Проследи путь данных: реквизиты входа → токен → заголовок запроса → корзина → заказ. Достаточно уметь подставить свои реквизиты при запуске и по ответам проверить эту цепочку; синтаксис сборки JSON через jq -n можно пока брать из образца.

cat > ~/perf-lab/02-web/order-flow.sh <<'EOF'
#!/usr/bin/env bash
# Сценарий покупателя: вход, корзина, заказ. Использование: ./order-flow.sh [email] [пароль]
set -euo pipefail
BASE=${BASE:-http://localhost:8000}
EMAIL=${1:-student@shop.lab}
PASSWORD=${2:-learnload1}

curl -fsS "$BASE/healthz" > /dev/null || { echo 'стенд не запущен' >&2; exit 1; }

# JSON собираем через jq, а не подстановкой строк: кавычка в пароле не сломает тело
BODY=$(jq -n --arg e "$EMAIL" --arg p "$PASSWORD" '{email: $e, password: $p}')
TOKEN=$(curl -s -X POST "$BASE/api/login" -H 'Content-Type: application/json' \
  -d "$BODY" | jq -r .token)
if [ "$TOKEN" = "null" ] || [ -z "$TOKEN" ]; then
  echo "вход не удался" >&2
  exit 1
fi

AUTH="Authorization: Bearer $TOKEN"
JSON='Content-Type: application/json'

curl -fsS -X POST "$BASE/api/cart/items" -H "$AUTH" -H "$JSON" -d '{"product_id":10,"qty":1}' > /dev/null
curl -s -o /dev/null -w 'заказ: код %{http_code}, время %{time_total} с\n' \
  -X POST "$BASE/api/orders" -H "$AUTH"
EOF
chmod +x ~/perf-lab/02-web/order-flow.sh
~/perf-lab/02-web/order-flow.sh
заказ: код 201, время 0.081342 с

Как читать вывод: скрипт молчит, пока всё идёт хорошо, и печатает одну строку про заказ. Код 201 значит «заказ создан». Время около 0,08 с это только запрос заказа, без входа и корзины. Любое другое сообщение (стенд не запущен, вход не удался) пришло из проверок самого скрипта, и после него он остановился.

Типичные ошибки:

  • Permission denied при запуске: забыт chmod +x.
  • вход не удался: пользователя ещё нет (шаг 1) или неверный пароль в аргументах.
  • заказ: код 400: добавление в корзину прошло без ошибки, но заказ не создан: корзина пуста (например, в неё попал не тот товар). Сверь product_id в скрипте с каталогом.
  • curl: (22) The requested URL returned error: 401 или 422 на добавлении в корзину: -f остановил скрипт. 401 значит просроченный токен, 422 неверное тело запроса. До строки про заказ дело не дойдёт.
  • jq: command not found: jq не установлен, скрипт падает ещё на сборке тела входа. Поставь его по уроку 1.1 и проверь jq --version.
  • Bearer null в заголовке: скрипт не проверил вход. Наш скрипт проверяет, а в своих добавляй такую же проверку.
  • Скрипт копирован с потерянными переносами строк: после \ не должно быть пробелов.

Токен живёт только в переменной скрипта и на диск (например, в общий /tmp) не пишется: так его не прочтёт другой пользователь машины. jq -n --arg собирает JSON безопасно, curl -f заставляет команду упасть на коде 4xx и 5xx, а первая проверка сообщает, если стенд не запущен. Разбор: set -euo pipefail останавливает скрипт на ошибке, неизвестной переменной и сбое в середине труб. ${BASE:-...} берёт значение переменной или запасное, ${1:-...} аргумент скрипта или запасное. Ответ jq -r .token при неверном пароле даёт слово null, поэтому скрипт проверяет и его. chmod +x делает файл запускаемым. Запускай ./order-flow.sh user0001@shop.lab password: это один из тысячи готовых пользователей.

Этот скрипт ты потом превратишь в сценарий нагрузочного теста: последовательность «вход, корзина, заказ» и есть путь пользователя (урок 9.2). Дважды один скрипт для одного пользователя не страшно: заказ создаст ещё один заказ, а корзина каждый раз пополняется заново. Запуск скрипта создаёт ещё один заказ (для student@shop.lab это 200002): в уроке 2.4 выводы запросов учитывают это.

7. Открой описание API

Открой в браузере http://localhost:8000/docs. Это интерактивное описание API (Swagger): список адресов, у каждого метод, нужное тело запроса и возможные ответы. Раскрой POST /api/cart/items: увидишь поля product_id и qty и ответы 201 и 422. Так сверяют то, что предложила нейросеть, с тем, что умеет стенд.

Как читать вывод: страница показывает, какие адреса есть и какие коды у них возможны. Если ответ стенда расходится со страницей, верь ответу стенда и перепроверь запрос. Если страница не открылась, проверь curl -s localhost:8000/readyz и порт.

Получил ошибку, которой нет в «Типичных ошибках»? Скопируй команду и ответ целиком (токен замени на <токен>), спроси, что значит каждое поле. Ответ проверь повторным запросом на стенде.

Сломай и почини

Поломка 1. Токен «умер». Токен хранится в Redis, а значит, его можно удалить. Сделай это сам, как будто прошёл час:

docker compose -f ~/learning/load-tester/project/shop/compose.yaml exec redis redis-cli DEL "session:$TOKEN"
curl -s -w '\n%{http_code}\n' localhost:8000/api/cart -H "Authorization: Bearer $TOKEN"

Задача. Ответь заранее: что вернёт вторая команда и что теперь делать клиенту? Затем почини ситуацию.

Разбор
(integer) 1
{"detail":"invalid or expired token"}
401

(integer) 1 значит, что удалена одна запись. Токен остался у тебя в переменной, но Магазин его больше не знает: 401 invalid or expired token. Это то же, что происходит через час. Починка: войти заново и получить новый токен (повтори команду с TOKEN=$(...) из шага 2). Вывод для нагрузочника: скрипт, который долго работает, обязан обрабатывать 401 повторным входом.

Поломка 2. Пустой токен в скрипте. Выполни:

TOKEN=""
curl -s -w '\n%{http_code}\n' localhost:8000/api/cart -H "Authorization: Bearer $TOKEN"

Задача. Какой код и какой текст? Почему это ошибка скрипта, а не сервера?

Разбор
{"detail":"bearer token required"}
401

Пустая переменная превратилась в заголовок Authorization: Bearer без токена, и сервер видит не два слова, а одно. Виноват скрипт: он не проверил, что вход удался. Поэтому в order-flow.sh стоит проверка на пустую строку и null. Правило: до первого запроса «с токеном» убедись, что токен действительно получен.

Поломка 3. Сломанный JSON. Отправь вход с одинарными кавычками внутри:

curl -s -w '\n%{http_code}\n' -X POST localhost:8000/api/login -H 'Content-Type: application/json' \
  -d "{'email':'student@shop.lab','password':'learnload1'}"

Задача. Найди в ответе, в чём ошибка, и исправь. Подсказка: ответ не 500.

Разбор

Ответ имеет код 422 и "type":"json_invalid": сервер не смог прочитать тело как JSON, потому что кавычки одинарные. Исправление: внешние кавычки одинарные, внутренние двойные, как в шаге 2. Код 422, а не 500, потому что ошибка в данных клиента, сервер работает исправно.

ИИ в помощь

Нейросеть помогает собирать запросы к API и объяснять ответы 401, 403 и 422. Общие правила на странице ИИ-помощник.

Задача: собрать запрос curl для нового метода API.

Мой стенд «Магазин» на http://localhost:8000. Нужно: войти (POST /api/login, email и password в JSON), взять токен и положить товар в корзину (POST /api/cart/items). Напиши команды curl и jq, чтобы токен попал в переменную, и объясни каждый флаг. Токен передавай заголовком Authorization: Bearer.

Проверь ответ: запусти команды на стенде и прочитай корзину (GET /api/cart). Типичная ошибка: токен в адресе вместо заголовка, -d без Content-Type: application/json (получишь 422) и выдуманные поля тела: сверь их с /docs стенда.

Задача: понять, почему пришёл 401, 403 или 422.

Запрос (токен заменён на <токен>):
<вставь команду>
Ответ сервера целиком:
<вставь ответ>
Объясни код и текст ошибки и предложи, что проверить. Отдельно скажи, чем 401 отличается от 403.

Проверь ответ: подтверди причину по полю detail в ответе стенда. Типичная ошибка: совет «отключи проверку токена»: на сервере ты ничего не правишь, ты тестируешь.

Реальный токен, пароль и заголовок Authorization в чат не отправляй: замени на <токен> и <пароль>. Токены учебного стенда безобидны, но привычка нужна для работы.

Словарик урока

Термин Простыми словами
JSON Текстовый формат данных: объекты {}, списки [], строки, числа
Content-Type Заголовок, говорящий, в каком формате тело (application/json)
jq Программа, которая достаёт нужные поля из JSON
REST Стиль API: адреса это ресурсы, методы это действия
Ресурс (resource) Предмет, с которым работает API: товар, корзина, заказ
Stateless Сервер не держит данные клиента в памяти процесса, всё нужное есть в запросе, а общее состояние лежит во внешнем хранилище
Аутентификация Проверка «кто ты»
Авторизация Проверка «что тебе можно»
Токен (token) Случайная строка-пропуск, выдаётся после входа
Bearer Схема заголовка: «обслужи предъявителя токена»
Хэш пароля Необратимый «отпечаток» пароля; позволяет проверить совпадение, не храня пароль
TTL, expires_in Время жизни токена в секундах
401 Неизвестно, кто ты: нет токена, он неверный или просрочен
422 Форма данных не подходит: нет поля, не тот тип, число вне границ
detail Поле JSON с текстом ошибки в ответах «Магазина»

Вопросы с собеседований

Раздел для повторения: ответь вслух, потом открой ответ. Короткие вопросы тренируй на скорость: ответ за 30 секунд.

1. [junior] [часто] Чем аутентификация отличается от авторизации?

Ответ

Аутентификация отвечает на вопрос «кто ты» (проверка логина и пароля, выдача токена), авторизация на вопрос «что тебе можно» (проверка прав на конкретное действие). Первая заканчивается ошибкой 401, вторая 403 (или 404, если сервис прячет чужое).

Что хотят услышать: два разных вопроса и два разных кода.

Красный флаг: считает их синонимами.

2. [junior] [часто] Как токен попадает в запрос и зачем он нужен?

Ответ

Клиент входит один раз, получает токен и кладёт его в заголовок Authorization: Bearer <токен> каждого следующего запроса. Токен нужен, чтобы не проверять пароль на каждый запрос: это дорогая операция. Сервер находит по токену пользователя и работает с его данными.

Что хотят услышать: заголовок, одноразовый вход, срок жизни.

Красный флаг: «токен передаётся в адресе запроса» (он попадёт в логи).

3. [junior] [часто] Что такое REST и что из него нужно знать нагрузочнику?

Ответ

Стиль API, где адреса называют ресурсы (/orders, /products/42), а методы HTTP задают действие. Запросы независимы: сервер не держит состояние клиента в памяти между ними, всё нужное передаётся в запросе. Нагрузочнику важно, что GET безопасен и его можно повторять, а POST и DELETE меняют данные, и по тому, какие ресурсы тест трогает, видно, какие данные он создаст.

Что хотят услышать: ресурсы, методы, stateless и связь с тестами.

Красный флаг: «REST это JSON».

4. [junior] Как отличить 401 от 403 и 404 от 422?

Ответ

401: нет или неверный токен, не знаю, кто ты. 403: знаю, но нельзя. 404: форма запроса верная, но нужного объекта нет. 422: форма данных не подходит (нет поля, неверный тип, значение вне границ).

Что хотят услышать: по одной фразе на каждый код с примером.

Красный флаг: «все 4xx это просто ошибки клиента» без различий.

5. [junior] Что такое Content-Type: application/json и что будет без него?

Ответ

Заголовок, который сообщает серверу формат тела. Без него сервер может не распознать тело как JSON и вернуть ошибку проверки (в «Магазине» это 422 model_attributes_type: «ожидался объект»), хотя тело было правильным.

Что хотят услышать: формат тела и пример последствия.

Красный флаг: «заголовок необязателен, и сервер сам догадается».

6. [junior] Почему нельзя передавать пароль или токен в адресе запроса?

Ответ

Адрес целиком попадает в логи сервера и прокси, в историю браузера и в другие системы наблюдения. Секрет окажется в открытом виде в местах, куда есть доступ у многих. Пароль передают в теле запроса (по HTTPS), токен в заголовке.

Что хотят услышать: где остаются адреса и безопасная альтернатива.

Красный флаг: «в адресе удобнее».

7. [junior] Что делает jq -r '.items[0].name' и чем -r отличается от запуска без него?

Ответ

Достаёт название первого товара из списка items. Без -r строка выводится в кавычках как JSON-значение ("Товар 1"), с -r без кавычек (Товар 1). Для подстановки результата в переменную нужен -r.

Что хотят услышать: индекс с нуля и назначение -r.

Красный флаг: путает [0] и [].

8. [middle] Тест работает два часа, и в середине появляются 401. Что случилось и как исправить?

Ответ

Токены живут час (expires_in: 3600) и протухли. Исправление: обрабатывать 401 повторным входом и подменой токена, либо перед истечением обновлять токен. В отчёте такие 401 нужно отделять от настоящих ошибок сервиса и считать ошибкой теста.

Что хотят услышать: срок жизни токена, повторный вход, различие ошибок теста и сервиса.

Красный флаг: «сервис нестабилен, 401 пошли после часа».

9. [middle] Ты нагружаешь вход (/api/login). Что надо учесть?

Ответ

Вход сознательно дорогой: проверка хэша пароля занимает сотни миллисекунд процессорного времени. Если каждый виртуальный пользователь входит на каждой итерации, вход станет главной нагрузкой на процессор и скроет остальное. Нужно входить один раз и переиспользовать токен (как реальный пользователь), а отдельно нагружать вход, если это нужно. Тестовые пользователи должны быть заранее созданы, иначе регистрация со своим хэшем исказит тест.

Что хотят услышать: дороговизна хэширования, переиспользование токена, отдельный сценарий.

Красный флаг: «входить на каждой итерации проще всего».

10. [на скорость] Какой код вернёт заказ из пустой корзины и почему не 422?

Ответ
  1. Форма запроса верная, но действие невозможно из-за текущего состояния (корзина пуста). 422 это про неверные данные в запросе.

Что хотят услышать: 400 и различие с 422.

Красный флаг: «404» или «500».

11. [на скорость] Какой заголовок несёт токен?

Ответ

Authorization: Bearer <токен>.

Что хотят услышать: имя заголовка и слово Bearer.

Красный флаг: «Token: ...» или «в адресе».

12. [на скорость] Как устроено тело ошибки 422 и где в нём искать, что именно не так?

Ответ

В поле detail лежит список. У каждой записи есть loc (где ошибка: body или query, и имя поля) и msg (что не так). Достаточно прочитать loc и msg, чтобы понять, какое поле поправить.

Что хотят услышать: detail, loc, msg.

Красный флаг: «смотреть в логах сервера», хотя ответ уже всё объясняет.

Проверено на версиях

Ubuntu 24.04, curl 8.5, jq 1.7, стенд «Магазин» из project/shop (FastAPI 0.142, PostgreSQL 18.6, Redis 8.10). Октябрь 2026.

Итог урока: ты умеешь

  • Прочитать и написать JSON, найти типичные ошибки записи.
  • Достать нужное поле из ответа через jq и сохранить в переменную.
  • Объяснить REST и по адресу с методом понять, что сделает запрос.
  • Различить аутентификацию и авторизацию, объяснить, зачем токен.
  • Зарегистрироваться, войти, положить товар в корзину и оформить заказ запросами curl.
  • По коду и тексту detail различить 401, 404, 422 и 400.
  • Написать скрипт order-flow.sh, выполняющий путь покупателя.

Дальше: урок 2.3. Из чего состоит бэкенд, где мы заглянем за дверь «Магазина»: приложение, воркеры, база, Redis и пул соединений.

Проверь себя

Короткий тест по уроку: 5 вопросов из банка в 30. Засчитывается только полностью правильный ответ, порог 60%. Каждая новая попытка даёт другие вопросы, пока банк не закончится. Ответы видны после проверки.

Тест работает с включённым JavaScript.

тема 2 урок 2.2 2.5 ч курс 0/0 ← → уроки

Помоги улучшить курс

Что нужно изменить?