128 lines
11 KiB
Markdown
128 lines
11 KiB
Markdown
# Июнь 2019 — тройное ревью чернового пакета П16 «Контракт REST API»
|
||
|
||
Статус: **принят в публикационный слой 31 июля 2026 года**. Registry
|
||
накладывает три ревизии по стабильным slug и сохраняет дату и автора базового
|
||
архива:
|
||
|
||
- <code>editorial-2019-06-practice-rest-api</code>;
|
||
- <code>editorial-2019-06-mechanism-rest-api</code>;
|
||
- <code>editorial-2019-06-field-rest-api</code>.
|
||
|
||
Созданы только:
|
||
|
||
- <code>web/scripts/upgrade-2019-06.mjs</code>;
|
||
- <code>web/public/assets/editorial/2019/rest-api-contract-map-2019.svg</code>;
|
||
- <code>web/public/assets/editorial/2019/rest-api-response-matrix-2019.svg</code>;
|
||
- <code>web/public/assets/editorial/2019/rest-api-contract-fixture-2019.svg</code>;
|
||
- этот файл.
|
||
|
||
Модуль экспортирует ровно три ревизии. В ревизиях нет <code>date</code> и
|
||
<code>author</code>: это исторические поля исходных публикаций, а не черновика.
|
||
При вызове с <code>--print-revisions</code> stdout содержит только JSON.
|
||
Отдельный <code>--run-fixture</code> запускает локальную проверку заранее
|
||
заданных объектов ответа; он не делает HTTP-запрос, не запускает сервер и не
|
||
является проверкой production.
|
||
|
||
## Проход 1. Факты и техника — пройдено
|
||
|
||
| Утверждение или решение | Первичный источник | Проверенная граница |
|
||
| --- | --- | --- |
|
||
| HTTP-код и представление ответа — часть результата операции | [IETF RFC 7231, раздел 6](https://www.rfc-editor.org/rfc/rfc7231#section-6) | В текст не введён флаг ошибки внутри 200 как замена HTTP-статуса |
|
||
| Problem detail содержит type, title, status, detail, instance; расширения принадлежат API | [IETF RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) | <code>errors</code> помечен как project extension, а не как универсальное поле стандарта |
|
||
| OpenAPI 3.0.2 описывает operation, responses, content и schema | [OpenAPI 3.0.2](https://spec.openapis.org/oas/v3.0.2.html) | Версия существовала в 2019 году; не использованы более поздние возможности |
|
||
| required-property и nullable-value — разные условия | [OpenAPI 3.0.2, Schema Object](https://spec.openapis.org/oas/v3.0.2.html#schema-object) | <code>page.nextCursor</code> обязателен и допускает null; <code>customer</code> либо отсутствует, либо является объектом |
|
||
| HTTP не навязывает конкретную pagination форму | [IETF RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) | cursor и object page названы проектным выбором; Link header назван альтернативой, а не проигнорирован |
|
||
|
||
Учебные snippets и fixture не ссылаются на настоящий сервис, токен, URL
|
||
production или якобы выполненный сетевой сценарий. В CLI с
|
||
<code>--run-fixture</code> есть три локальных case:
|
||
|
||
1. 200 / JSON с последней страницей и явным <code>nextCursor: null</code>;
|
||
2. 400 / problem+json с <code>invalid_cursor</code>;
|
||
3. отрицательный 200 / JSON без <code>nextCursor</code>, который обязан быть
|
||
отклонён.
|
||
|
||
Итог первого прохода: технические утверждения привязаны к 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. Визуал и выпускная дисциплина — пройдено для автономного пакета
|
||
|
||
| Артефакт | Назначение | Проверка доступности и выпуска |
|
||
| --- | --- | --- |
|
||
| <code>rest-api-contract-map-2019.svg</code> | Вход операции и развилка 200/400 | Есть title, desc, содержательный alt, подпись; SVG без script |
|
||
| <code>rest-api-response-matrix-2019.svg</code> | Связь Operation, Responses и Schema | Есть title, desc, содержательный alt, подпись; SVG без script |
|
||
| <code>rest-api-contract-fixture-2019.svg</code> | Граница локальной fixture и сетевой проверки | Есть title, desc, содержательный alt, подпись; SVG без script |
|
||
|
||
### Выполненные проверки
|
||
|
||
~~~text
|
||
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 года:
|
||
|
||
- <code>node --check</code> — код 0;
|
||
- draft gate — три PASS: практика 9 266, механизм 10 792, полевой разбор
|
||
10 300 знаков основного текста;
|
||
- <code>--run-fixture</code> — три PASS: финальная 200-страница с
|
||
<code>nextCursor: null</code>, 400 problem detail с
|
||
<code>invalid_cursor</code> и обязательное отклонение 200 без
|
||
<code>nextCursor</code>;
|
||
- <code>xmllint --noout</code> — код 0 для трёх SVG;
|
||
- проверка завершающих пробелов не нашла совпадений.
|
||
|
||
SVG дополнительно прочитаны как выпускные артефакты: у каждого есть
|
||
самодостаточные <code>title</code> и <code>desc</code>, все блоки, стрелки и
|
||
подписи размещены внутри 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, таблицы, код,
|
||
маршруты и источники. <code>npm run build</code> завершился с кодом 0 и
|
||
сгенерировал 374 статические страницы.
|
||
|
||
Выпусковой вердикт: **принят к публикации**. <code>articles.json</code> не
|
||
менялся; registry заменяет только редакционные поля по стабильному slug.
|
||
|
||
### Независимый мобильный preflight
|
||
|
||
Основной редактор отдельно отрендерил все три SVG через Sharp на ширине 720 и
|
||
375 px. Первый вариант не обрезался, но его подписи были слишком мелкими при
|
||
375 px. Все три схемы заменены на вертикальные композиции с короткими
|
||
подписями; повторный рендер подтвердил читаемые главные метки, отсутствие
|
||
обрезания и горизонтального overflow. Это проверка SVG-артефактов, а не
|
||
заявление о browser-render или сетевом production-тесте.
|