Июнь 2019 — тройное ревью чернового пакета П16 «Контракт REST API»

Статус: принят в публикационный слой 31 июля 2026 года. Registry накладывает три ревизии по стабильным slug и сохраняет дату и автора базового архива:

editorial-2019-06-practice-rest-api;
editorial-2019-06-mechanism-rest-api;
editorial-2019-06-field-rest-api.

Созданы только:

web/scripts/upgrade-2019-06.mjs;
web/public/assets/editorial/2019/rest-api-contract-map-2019.svg;
web/public/assets/editorial/2019/rest-api-response-matrix-2019.svg;
web/public/assets/editorial/2019/rest-api-contract-fixture-2019.svg;
этот файл.

Модуль экспортирует ровно три ревизии. В ревизиях нет date и author: это исторические поля исходных публикаций, а не черновика. При вызове с --print-revisions stdout содержит только JSON. Отдельный --run-fixture запускает локальную проверку заранее заданных объектов ответа; он не делает HTTP-запрос, не запускает сервер и не является проверкой production.

Проход 1. Факты и техника — пройдено

Утверждение или решение	Первичный источник	Проверенная граница
HTTP-код и представление ответа — часть результата операции	IETF RFC 7231, раздел 6	В текст не введён флаг ошибки внутри 200 как замена HTTP-статуса
Problem detail содержит type, title, status, detail, instance; расширения принадлежат API	IETF RFC 7807	`errors` помечен как project extension, а не как универсальное поле стандарта
OpenAPI 3.0.2 описывает operation, responses, content и schema	OpenAPI 3.0.2	Версия существовала в 2019 году; не использованы более поздние возможности
required-property и nullable-value — разные условия	OpenAPI 3.0.2, Schema Object	`page.nextCursor` обязателен и допускает null; `customer` либо отсутствует, либо является объектом
HTTP не навязывает конкретную pagination форму	IETF RFC 8288	cursor и object page названы проектным выбором; Link header назван альтернативой, а не проигнорирован

Учебные snippets и fixture не ссылаются на настоящий сервис, токен, URL production или якобы выполненный сетевой сценарий. В CLI с --run-fixture есть три локальных case:

200 / JSON с последней страницей и явным nextCursor: null;
400 / problem+json с invalid_cursor;
отрицательный 200 / JSON без nextCursor, который обязан быть отклонён.

Итог первого прохода: технические утверждения привязаны к HTTP, RFC 7807 и исторически уместному OpenAPI 3.0.2; тест не объявлен серверным или production-доказательством.

Проход 2. Редактура и голос М2 — пройдено

Проверка	Практика	Механизм	Полевой разбор
Ранняя постановка симптома и цены	Падение, неверная страница и спор слоёв	Тихая поломка при семантически другом JSON	UI не знает, как трактовать распарсенный ответ
Рабочая цепочка	Симптом → причина → контракт → fixture → действие	Симптом → Operation/Responses/Schema → совместимость	Симптом → cases → fixture → запрос к стенду
Техническая речь	Статус, media type, cursor, optional field	HTTP, OpenAPI 3.0.2, required, nullable	Response objects, negative case, headers, body
Объём основного текста	Подтверждается draft gate	Подтверждается draft gate	Подтверждается draft gate

Голос соответствует М2 / 2019: автор уже связывает frontend, backend и HTTP, но не имитирует инструменты и практики 2027 года. Текст не обещает «универсальный REST», не называет обычный JSON доказательством успеха и не подменяет конкретные условия общими оценками. В каждой статье есть не менее пяти смысловых разделов, доступная таблица, код, порядок действий, визуал, источники и ограничения.

Итог второго прохода: три текста держат прагматичный формат «симптом → причина → проверка → действие» и не раздувают тему за счёт общих вступлений.

Проход 3. Визуал и выпускная дисциплина — пройдено для автономного пакета

Артефакт	Назначение	Проверка доступности и выпуска
`rest-api-contract-map-2019.svg`	Вход операции и развилка 200/400	Есть title, desc, содержательный alt, подпись; SVG без script
`rest-api-response-matrix-2019.svg`	Связь Operation, Responses и Schema	Есть title, desc, содержательный alt, подпись; SVG без script
`rest-api-contract-fixture-2019.svg`	Граница локальной fixture и сетевой проверки	Есть title, desc, содержательный alt, подпись; SVG без script

Выполненные проверки

node --check web/scripts/upgrade-2019-06.mjs
cd web && npm run audit:draft -- scripts/upgrade-2019-06.mjs
node web/scripts/upgrade-2019-06.mjs --run-fixture
xmllint --noout \
  web/public/assets/editorial/2019/rest-api-contract-map-2019.svg \
  web/public/assets/editorial/2019/rest-api-response-matrix-2019.svg \
  web/public/assets/editorial/2019/rest-api-contract-fixture-2019.svg

Результат 31 июля 2026 года:

node --check — код 0;
draft gate — три PASS: практика 9 266, механизм 10 792, полевой разбор 10 300 знаков основного текста;
--run-fixture — три PASS: финальная 200-страница с nextCursor: null, 400 problem detail с invalid_cursor и обязательное отклонение 200 без nextCursor;
xmllint --noout — код 0 для трёх SVG;
проверка завершающих пробелов не нашла совпадений.

SVG дополнительно прочитаны как выпускные артефакты: у каждого есть самодостаточные title и desc, все блоки, стрелки и подписи размещены внутри viewBox 900×760. У первой схемы длинная итоговая подпись разбита на две строки. CSS статьи выводит figure-image по ширине контейнера, а таблицы имеют горизонтальную прокрутку. Это статическая проверка разметки и геометрии; в журнал не приписывается вымышленный browser-render, server run или production build. Перед публикацией основной редактор должен отдельно подключить ревизии к registry, повторить strict audit вместе с архивом, построить production-сайт и проверить реальные страницы на широком и узком экране, сохранив исходные дату и автора.

После подключения registry основной редактор повторил strict audit: все три slug прошли объём 9 266 / 10 792 / 10 300 знаков, figure, таблицы, код, маршруты и источники. npm run build завершился с кодом 0 и сгенерировал 374 статические страницы.

Выпусковой вердикт: принят к публикации. articles.json не менялся; registry заменяет только редакционные поля по стабильному slug.

Независимый мобильный preflight

Основной редактор отдельно отрендерил все три SVG через Sharp на ширине 720 и 375 px. Первый вариант не обрезался, но его подписи были слишком мелкими при 375 px. Все три схемы заменены на вертикальные композиции с короткими подписями; повторный рендер подтвердил читаемые главные метки, отсутствие обрезания и горизонтального overflow. Это проверка SVG-артефактов, а не заявление о browser-render или сетевом production-тесте.

11 KiB Raw Permalink Blame History Unescape Escape