CI и поиск
breaking changes

§1Что такое сборка контракта

CI — непрерывная интеграция: набор проверок, который запускается сам при каждом изменении. В учебном проекте это один файл .github/workflows/ci.yml и две задачи внутри него.

name: API contract

on:
  push:
    branches: [main]
  pull_request:

Разница существенная: проверка после объединения сообщает, что контракт уже сломан, а проверка до объединения не даёт этого сделать.

§2Задача contract: четыре проверки

jobs:
  contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Contract and behaviour tests
        run: pytest

      - name: OpenAPI files match the code
        run: python scripts/export_openapi.py --check

      - uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Spectral lint
        run: npx --yes @stoplight/spectral-cli@6.16.3 lint openapi/openapi.yaml --fail-severity=warn

Порядок шагов выбран по времени выполнения: сначала быстрые тесты, потом сверка файла, и только затем установка Node.js для линтера. Если контракт сломан, сборка сообщит об этом через несколько секунд, не тратя время на установку лишнего.

§3Задача breaking-changes

Вторая задача сравнивает контракт из pull request с контрактом в основной ветке — тем самым oasdiff, который мы запускали вручную в главе 5.2.

  breaking-changes:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
      - run: git fetch --depth=1 origin ${{ github.base_ref }}

      - name: oasdiff breaking
        uses: oasdiff/oasdiff-action/breaking@v0.1.17
        with:
          base: "origin/${{ github.base_ref }}:openapi/openapi.yaml"
          revision: "HEAD:openapi/openapi.yaml"
          fail-on: ERR
          review: false

§4Как сравниваются две версии контракта

1. Разработчик меняет код и заново выгружает описание: python scripts/export_openapi.py.
2. Открывает pull request. В изменении видны и код, и новое описание — рядом, одним списком правок.
3. Сборка достаёт две версии файла openapi/openapi.yaml: из основной ветки и из изменения.
4. oasdiff сравнивает их по своему набору правил и печатает список несовместимых изменений.
5. Есть ошибки — задача красная, и объединить изменение нельзя, пока автор не вернёт совместимость или не выпустит новую мажорную версию.

Обратите внимание на шаг 2: описание попадает в pull request как обычный текстовый файл, и его правки видны так же, как правки кода. Ревьюер видит не изменение модели в коде, а строку описания: в ответе появилось поле priority типа string. Обсуждать при этом можно сам контракт.

§5Зелёная сборка

§6Красная сборка: настоящий случай

Проверим, что защита работает. В учебном репозитории открыто изменение demo/rename-updated-at: в схеме Ticket поле updated_at переименовано в modified_at. Тесты его не ловят — они переименованы вместе с кодом и проходят. Ловит сравнение описаний.

running oasdiff breaking...
  base: origin/main:openapi/openapi.yaml, revision: HEAD:openapi/openapi.yaml, fail_on: ERR

##[error] in API GET /api/v1/tickets
         removed the required property `items/items/updated_at` from the response with the `200` status
##[error] in API POST /api/v1/tickets
         removed the required property `updated_at` from the response with the `201` status
##[error] in API GET /api/v1/tickets/open
         removed the required property `items/items/updated_at` from the response with the `200` status
##[error] in API GET /api/v1/tickets/{ticket_id}
         removed the required property `updated_at` from the response with the `200` status
##[error] in API PATCH /api/v1/tickets/{ticket_id}
         removed the required property `updated_at` from the response with the `200` status

Пять ошибок на одно переименование — по числу операций, в ответе которых встречается схема Ticket. Формулировка везде одна: removed the required property. Для клиента переименование и есть удаление: код, который читал ticket["updated_at"], перестанет находить это поле, и появление рядом modified_at ему не поможет.

Разработчик видит этот вывод в самом pull request, до объединения. Дальше у него три пути: вернуть прежнее имя поля, признать изменение мажорным и выпускать /api/v2 или добавить новое поле рядом со старым и объявить старое устаревшим, как описано в главе 5.3. Варианта «объединить и посмотреть, что будет» среди них нет.

§7Защита ветки

Сборка сообщает о результате проверок, но ничего не запрещает. Запрет задаётся настройкой репозитория — защитой основной ветки.

Вместе эти четыре настройки дают требуемое свойство: изменить контракт, не пройдя проверок и не показав изменение человеку, невозможно. Без защиты ветки соблюдение всех предыдущих правил остаётся добровольным.

§8Сколько это стоит по времени

Больше всего времени занимает не выполнение проверок, а установка окружения. Поэтому тесты и сверку файла запускают локально перед отправкой изменения, а полный набор — в сборке. Чем раньше сработала проверка, тем меньше объём исправлений: замечание линтера в своём редакторе исправляют сразу, то же замечание после объединения затрагивает уже чужую работу.