✻ Урок 2.2 · Тема 2: Как устроен веб-сервис
REST API, JSON и авторизация
Содержание урока
Как работать с кодом и когда идти дальше
Команды не нужно писать по памяти. Пользуйся примерами из урока и справкой. Ориентируйся на цель задания:
- Запусти готовое. Код приложения и вспомогательных скриптов можно скопировать. Пойми, зачем они нужны, что запускают или меняют и как проверить результат. Разбирать каждую функцию внутри готового инструмента не требуется.
- Измени по образцу. Разбери новые конструкции, объяснённые в уроке. Измени указанный параметр или часть кода, предскажи результат и проверь запуском.
- Напиши сам. Собери свой вариант под условия задания. Образцы и справка разрешены: важно объяснить своё решение и проверить его работу.
Можно идти дальше, если ты выполнил практику, получил ожидаемый результат и понимаешь, что проверил. Если задание просит изменить код, проверь и своё изменение.
Непонятные детали готового инструмента можно оставить на потом. При ошибке запуска вернись к разбору вывода и типичным ошибкам в уроке.
Зачем это нужно
Допустим, в «Магазине» появилась жалоба: «после входа в личный кабинет всё тормозит». Каталог ты читать уже умеешь (урок 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
Разберём по шагам.
- Поле. Точка
.значит «текущее значение»,.total«полеtotal»: получим10000. - Элемент списка.
.items[0]берёт первый элемент (счёт с нуля),.items[]каждый по очереди. Флаг-r(raw, «сырой») убирает кавычки вокруг строки, он нужен, когда результат идёт в переменную. - Отбор. Вертикальная черта
|передаёт результат слева в выражение справа, как в терминале.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?
Ответ
- Форма запроса верная, но действие невозможно из-за текущего состояния (корзина пуста). 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.