API
Статус-коды: выпусти честный API
Читать про статус-коды — не то же, что выпустить API, который попадает в них верно, когда апстрим умирает, клиент тебя флудит, а два писателя гонят одну запись. Собери небольшой сервис, чья статус-строка говорит правду во всех трёх случаях, и докажи это набором тестов, который проверяет на проводе, а не твои намерения.
Превратить модель юнита в работающий контракт: выдавать корректный класс и под-код на каждый исход, прикреплять верные заголовки (Location, Retry-After, ETag), держать детали ошибки в теле честного статуса, делать ретраи безопасными через идемпотентность и проверять каждое правило чёрно-ящичным конформанс-тестом.
Собрать небольшой order/payment HTTP API (любой язык), чьи статус-коды корректны при создании, async-работе, по всему словарю 4xx, на 5xx с распределённой виной, при rate limiting и идемпотентных ретраях — затем написать чёрно-ящичный конформанс-тест, который прогоняет его через каждый сценарий и проверяет реальную статус-строку, заголовки и тело.
- Каждый эндпоинт возвращает корректный класс и под-код на каждый исход, что проверено конформанс-тестом по статус-строке (а не по флагу ok в теле) — 201+Location, 202+poll-URL, 204, 400/422/409/401/403, 500/502/504, 429/503.
- Ответы 429 и 503 всегда несут заголовок Retry-After; тест проверяет, что он присутствует и парсится.
- Повтор запроса с тем же Idempotency-Key порождает ровно один заказ/списание и возвращает исходный ответ; тест доказывает, что дубль не создаётся.
- Условный PUT с устаревшим If-Match возвращает 412 и не перезаписывает; со свежим If-Match проходит — оба случая проверены тестом.
- Ни один путь ошибки не возвращает 200; тест, проверяющий «статус 2xx подразумевает успех», проходит, то есть нигде нет отказа в форме успеха.
- Добавить тонкий client SDK с корректной политикой ретраев: ретраить только 5xx и 429, уважать Retry-After перед экспоненциальным бэкоффом с джиттером, никогда не ретраить неидемпотентный запрос без Idempotency-Key и сверять при неоднозначном 504.
- Добавить наблюдаемость: эмитить метрику с лейблом по классу статуса и проверять в тесте, что инжектированный отказ апстрима двигает счётчик 5xx (доказывая, что дашборд поймал бы сценарий инцидента шлюза).
- Добавить режим 404-вместо-403 для чувствительных ресурсов и задокументировать security-компромисс (скрытие существования vs REST-корректность), на который идёшь.
- Гонять конформанс-набор в CI как гейт и добавить снапшот контракта, чтобы будущее изменение, понижающее 422 обратно до общего 400, валило билд.
Это цикл за сервисом, чьим статус-кодам можно доверять в инциденте: спроектируй контракт так, чтобы класс и под-код говорили правду, прикрепи заголовки, заставляющие клиентов вести себя верно (Location, Retry-After, ETag), держи детали в теле честного статуса, сделай записи идемпотентными, чтобы ретраи не списывали дважды, и докажи каждое правило чёрно-ящичным тестом, проверяющим на проводе, а не твои намерения. Сделать это раз на игрушечном API — то, что делает продакшен-версию рефлексом.