Перейти к содержанию

Использование утилиты contract#

Поскольку мы разработали собственный формат контрактов данных, нам потребовался набор утилит и библиотек для работы с ним (pkg/).

Утилита contract позволяет генерировать Avro Schema, проверять контракты на соответствие спецификации и генерировать их заготовки из различных форматов (Go struct, Avro Schema, JSON Schema, Protobuf) для упрощения их написания.

Кроме того, утилита используется в наших CI-пайплайнах, для генерации моделей, используемых в рамках платформы, и для генерации синтетических данных при тестировании.

В статье примеры использования представлены только для той функциональности, которая непосредственно необходима издателям.

Также функциональность, аналогичная описанной в статье, доступна в веб-версии утилиты.

Установка#

Доступ к репозиторию с утилитой есть у всех авторизованных пользователей.

Также вам может понадобиться репозиторий с примерами контрактов.

Релизы#

Скачать последний релиз можно в репозитории data-contract-utils.

Сборка из исходников#

  1. Убедитесь, что установлен Go.
  2. Склонируйте репозиторий: git clone git@gitlab.kruma.ru:data-office/data-contract-utils.git.
  3. Перейдите в директорию проекта: cd data-contract-utils.
  4. Выполните сборку: make build.
  5. Используйте бинарный файл: build/contract.

Основные возможности#

contract валидирует и преобразует контракты данных. Основные команды:

  • validate: Проверяет контракты на соответствие спецификации.
  • avsc: Генерирует Avro Schema (.avsc) из контрактов.
  • template: Генерирует шаблоны контрактов из различных моделей данных: Avro Schema, Go struct, JSON Schema или Protobuf.

Примеры#

Валидация контракта#

Проверяет контракт на соответствие спецификации.

Команда:

contract validate contract.yaml

Входной файл (contract.yaml):

title: entity
specification: 1.4.0
type: object
description: "Сущность"
properties:
  id:
    type: int64
    description: "Идентификатор сущности в системе"
  name:
    type: string
    description: "Название сущности"
required:
  - id
  - name

Если валидация прошла успешно, утилита завершится с кодом 0. В противном случае, код завершения будет равен 1.

Также в случае ошибки вы увидите её в логе.

Генерация Avro Schema из контракта#

Команда:

contract avsc contract.yaml schema.avsc --namespace wb

* Параметр namespace представляет собой название домена данных, обычно оно соответствует названию репозитория с контрактами.

Входной файл (contract.yaml):

title: entity
specification: 1.4.0
type: object
description: "Сущность"
properties:
  id:
    type: int64
    description: "Идентификатор сущности в системе"
  name:
    type: string
    description: "Название сущности"
required:
  - id
  - name

Вывод (schema.avsc):

{
  "name": "wb.entity",
  "type": "record",
  "fields": [
    {
      "name": "id",
      "type": "long"
    },
    {
      "name": "name",
      "type": "string"
    }
  ]
}

Генерация контракта из Avro Schema, Go struct, JSON Schema или Protobuf#

Команда:

contract template model.go contract.yaml

* Тип исходной модели определяется автоматически по расширению файла.

В случае необходимости тип можно задать вручную параметром -s, --source. Доступные варианты: auto, go, avsc, json-schema, protobuf.

Входной файл (model.go):

package main

type Entity struct {
  ID   int64  `json:"id"` // Идентификатор сущности в системе
  Name string `json:"name"` // Название сущности
}

Вывод (contract.yaml):

title: entity
specification: 1.4.0
description: '' # TODO: заполнить description
type: object
properties:
    id:
        type: int64
        description: Идентификатор сущности в системе
    name:
        type: string
        description: Название сущности
required:
    - id
    - name
primaryKey: [] # TODO: заполнить массив primaryKey

* При генерации контрактов description заполняется из комментариев к структуре или к полям (при наличии оных). Если поле осталось пустым, его необходимо заполнить самостоятельно.

* Поле primaryKey может присутствовать в сгенерированных контрактах, однако его наличие будет ошибкой в будущих версиях тулинга (1.5+).

Полный список команд можно получить, вызвав contract help.

Для получения подсказки для каждой отдельной команды, выполните contract help <команда>.