Различать описание и исполнение
Зафиксируйте поддерживаемую инструментами версию спецификации. Опишите параметры, тела, ответы и безопасность. Приложение и шлюз всё равно должны применять заявленные требования.
| Элемент | Что описывает | Дополнительная проверка |
|---|---|---|
| Схема | Структура и ограничения | Реальная валидация и бизнес-правила. |
| Описанный ответ | Ожидаемые статус и содержимое | Соответствие реальных ответов. |
| Требование безопасности | Заявленные механизм и права | Действующий контроль каждой операции. |
| Пример | Один иллюстративный случай | Согласованность, отсутствие секретов и крайние случаи. |
Проверить до публикации
- Проверьте обязательность полей, типы, диапазоны, пагинацию, ошибки и форматы. Используйте вымышленные согласованные примеры без секретов и клиентских данных.
- Сравните описание с запросами и ответами в контролируемой среде. Испытайте отсутствие учётных данных, нехватку прав и изоляцию аккаунтов.
- Проверьте внешние ссылки и обрабатывающие их инструменты. Очистите публичное описание и защитите частные среды и операции.
Поддерживать документацию
Проверяйте изменения и назначьте владельца. Сгенерированный клиент или пример может быть структурно верным, но упускать бизнес-правило. Интерактивным консолям нужны подходящая среда, ограниченные права и пометки изменяющих состояние операций.
Первоисточники
Сравнение OpenAPI с работающим сервисом.
Полезное описание OpenAPI включает ответы об ошибках, схемы и примеры, с которыми клиенты действительно сталкиваются. Когда документ и API расходятся, интеграция может пройти демонстрацию, но потерпеть неудачу в производственной среде.
- Сравнение случаев успеха и ошибок с описанием.
- Документирование необязательных значений, пагинации и ограничений операций.
- Тестирование репрезентативного клиента перед изменением контракта.
Первичный источник: IETF RFC 9457 — Problem Details for HTTP APIs. Связанный метод: прочитать практическое руководство.
ZIP и TAR: извлекать в пределах каталога и ресурсов
Проверять пути, ссылки и распакованные данные до публикации файлов.
- Извлекайте в новый непубличный каталог с минимальными правами. Отклоняйте абсолютные пути, выход вверх, ненужные ссылки и специальные файлы. Проверяйте разрешённые пути и коллизии по правилам целевой системы, включая регистр. Текстовый префикс не доказывает изоляцию.
- Задайте отдельные и суммарные пределы записанных байтов, записей, глубины, времени и ресурсов процесса. Сжатого или заявленного размера недостаточно. Запретите ненужные вложенные архивы; иначе используйте общий бюджет. Обновляйте библиотеку и фильтры.
- Проверьте ../, абсолютный путь, ссылку, дубликат и превышение бюджета. Сбой оставляет пакет неопубликованным и не заменяет существующие файлы. Проверьте типы и содержимое до публикации; при очистке подтвердите каталог назначения.
Воспроизводимый приёмочный случай
Вымышленный пример: данные не описывают клиента или наблюдаемый результат.
Посмотреть данные случая
{
"compressed_mb": 2,
"expanded_mb": 600,
"aggregate_budget_mb": 100,
"first_files_valid": true,
"expected": "stop_on_actual_overrun_and_do_not_promote"
}Ожидаемое решение
Вымышленный пример: 2 МБ сжатых данных дают 600 МБ при бюджете 100 МБ. Остановитесь при превышении записанных байтов и не публикуйте пакет, даже если первые файлы выглядят правильными.
Python — tarfile extraction filters and further verification
Гарантирует ли маленький архив или фильтр безопасность?
Нет. Он может сильно вырасти. Добавьте ограничения ресурсов, правила путей и проверку извлечённых файлов.
Первичный источник: Python — tarfile extraction filters and further verification. Связанный метод: прочитать практическое руководство.
Ошибки API: типы, статусы и доказательства
Подробные справочные заметки в этой версии доступны на английском.
Include errors in contract tests
A new type URI, removed extension or changed status may alter consumer behaviour. Failure examples are part of the contract alongside successful responses.
- Replay existing clients against representative refusals.
- Check tolerance of unknown extensions and localised text.
- Document migration of a problem identity and actually observed use.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5