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

Регенерация и миграции

Описание процесса регенерации проекта и миграций между версиями.

Сохранение пользовательского кода

Уникальная возможность: Перегенерируйте весь проект без потери ваших изменений.

Как работают Disclaimer-маркеры

Каждый сгенерированный файл содержит маркер:

// ==========================================
// GENERATED CODE - DO NOT EDIT ABOVE THIS LINE
// Changes manually made below will not be overwritten by generator.
// ==========================================

Правила:

  1. Код выше маркера регенерируется при каждом запуске
  2. Код ниже маркера сохраняется навсегда
  3. Если нужно изменить сгенерированный код — переместите его ниже маркера

After-marker код как workaround

Код ниже маркера можно использовать, чтобы не ждать закрытия issue в go-project-starter. Например, если шаблон генерирует не тот код, который вам нужен — переопределите поведение ниже маркера.

Правило: каждый такой workaround обязательно должен содержать:

  1. Ссылку на issue в go-project-starter
  2. TODO-комментарий для удаления после закрытия issue
// ==========================================
// GENERATED CODE - DO NOT EDIT ABOVE THIS LINE
// ==========================================

// TODO: удалить после закрытия https://github.com/Educentr/go-project-starter/issues/12
// Workaround: кастомная схема ошибки вместо ErrorDefault
func (h *ogenDefaultError) NewError(ctx context.Context, err error) *oas.ApiErrorStatusCode {
    // ...
}

Это позволяет:

  • Не блокировать разработку — проект работает с нужным поведением сразу
  • Не терять контекст — ссылка на issue объясняет, зачем этот код
  • Вовремя убирать workaround — по закрытии issue TODO напомнит удалить код и перегенерировать проект

Пример

package handler

import (
    "context"
    "net/http"
)

// ==========================================
// GENERATED CODE - DO NOT EDIT ABOVE THIS LINE
// ==========================================

func (h *Handler) CreateUser(ctx context.Context, req *CreateUserRequest) (*User, error) {
    // Ваш код здесь - переживёт регенерацию!

    user := &User{
        Email: req.Email,
        Name:  req.Name,
    }

    // Кастомная валидация
    if err := h.validateBusinessRules(user); err != nil {
        return nil, err
    }

    return h.repo.Create(ctx, user)
}

// Ваши вспомогательные функции
func (h *Handler) validateBusinessRules(user *User) error {
    // ...
}

Workflow регенерации

При изменении OpenAPI/Protobuf

Используйте make generate:

# 1. Изменить api/openapi.yaml
# 2. Регенерировать код
make generate

# Ваш код в handlers.go сохранится

make generate перегенерирует и моки, каркас которых пишет генератор (tests/{app}/mocks/{transport}/ — для приложений с goat_tests и транспортом ogen_client): мок отражает ogen-интерфейс, поэтому после изменения контракта он обязан перегенерироваться вместе с ним. Иначе мок остаётся ссылаться на типы, которых ogen больше не выдаёт, и тестовый пакет перестаёт компилироваться. Подробности и ограничения цели — Makefile Targets Reference.

При изменении config.yaml

Запустите генератор повторно:

# 1. Изменить config.yaml
# 2. Предпросмотр изменений (опционально)
go-project-starter --dry-run --config=config.yaml --target=.

# 3. Применить изменения
go-project-starter --config=config.yaml --target=.

Какой версией генератора регенерируется проект

make regenerate зовёт не тот go-project-starter, что стоит в окружении, а версию, записанную в Makefile самим генератором при прошлом прогоне:

GPSVERSION = v1.2.3

regenerate:
    go run $(GPSPKG)@$(GPSVERSION) --target ${PWD}

Отсюда два следствия. Регенерация не требует предустановленного генератора — версия скачивается сама, как ogen и argen. И версия, которой собрано дерево, записана в репозитории: регенерация записанной версией обязана давать пустой дифф.

Поднять пин:

make update-starter STARTER_VERSION=v1.3.0

Новая версия перегенерирует проект и запишет себя в GPSVERSION. Руками эту строку править не нужно — следующий прогон её перезапишет. Подробности, включая tools.starter_version для окружений с несобираемой версией, — в секции tools.

Файлы, которые никогда не перезаписываются

  • .gitignore
  • go.mod, go.sum
  • LICENSE.txt
  • README.md
  • .git/ директория

Что генератор считает своим: .project-config/meta.yaml

В .project-config/meta.yaml после каждого прогона лежит манифест — список файлов, которые записал генератор, по одной записи на строку:

version: 5
manifest:
    - {path: cmd/publicApi/psg_main_gen.go, kind: generated, hash: 8fe15f…}
    - {path: api/rest/example/v1/example.swagger.yml, kind: copied, hash: 490da3…}

Из этого следуют пять практических правил:

  1. meta.yaml коммитится вместе с проектом. Без него следующая регенерация не знает, какие файлы её, и возвращается к старому поведению — поиску маркера disclaimer по всему дереву. Файл меняется на каждом прогоне, который меняет вывод; конфликт при merge двух веток решается перегенерацией на смёрженном дереве.
  2. Посторонние файлы в дереве генератор не трогает. Бэкап сгенерированного файла, *_gen.go.orig от merge-конфликта, индекс code-intelligence инструмента — всё, чего нет в манифесте, не читается, не удаляется и не ломает прогон, даже если внутри есть строка disclaimer.
  3. Правки выше маркера видны. Если сгенерированная часть файла изменена руками, генератор печатает предупреждение с путём:
warning: cmd/publicApi/psg_main_gen.go: generated part was changed after the last generation, the changes will be overwritten

Прогон при этом не останавливается — правки выше маркера перезаписываются, как и раньше. Если такой файл при этом выпал из набора шаблонов, он не удаляется: генератор оставит его на диске с отдельным предупреждением. 4. Ваш файл на пути, который генератор только начал занимать, не перезаписывается. Новая версия генератора может начать генерировать файл там, где у вас уже лежит свой. Такого файла нет в манифесте — значит генератор его не писал, и прогон останавливается до записи чего-либо, перечисляя все конфликтующие пути сразу:

conflict: 2 files exist and were not written by the generator — rename or remove them:
  - internal/app/constant/psg_constant_gen.go
  - api/rest/example/v1/example.swagger.yml

Это касается любых файлов — и с disclaimer-маркером, и без него (.json, .keep), и скопированных спек (kind: copied). Что делать: переименуйте или удалите свой файл (если содержимое нужно — перенесите его ниже маркера в сгенерированный файл после прогона) и запустите регенерацию снова. --dry-run показывает те же конфликты, не меняя дерево.

Исключения: файлы из списка «никогда не перезаписываются» (go.mod, .gitignore, README.md, static/**) и переименования, которые делает сам генератор при миграции версий. Если прогон упал на полпути (например, не нашлась спека) и успел записать новые файлы до обновления meta.yaml, следующий прогон сообщит о них как о конфликте — удалите их, это вывод генератора. 5. Скопированные спеки править внутри проекта нельзя — в отличие от правок выше маркера это не предупреждение, а ошибка. См. следующий раздел.

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

Спеки правятся в контрактном репозитории, не в проекте

Файлы с kind: copied — спеки REST (api/rest/<svc>/<ver>/), gRPC (api/grpc/<svc>/) и JSON Schema (api/schema/<name>/) — генератор копирует в проект из источника, указанного в path:. Править их внутри проекта нечего: правка не доедет до контракта и будет перезаписана следующей регенерацией. Поэтому генератор отказывается работать с таким деревом:

$ make regenerate
failed to generate: a file copied by the generator was edited inside the project tree:
  api/rest/example/v1/example.swagger.yml (source: ./example.swagger.yml)
files copied by the generator are not an edit point: change them at the source (the contract
repository the path points to) and re-run the generator. To drop the local edits, restore the
files from version control.

Что с этим делать:

  • правка не нужна — git restore <путь> и перегенерируйте. Без git достаточно удалить файл: отсутствующий файл дрейфом не считается, генератор скопирует его заново из источника;
  • правка нужна, источник локальный (source: ./…) — два шага: скопируйте файл из проекта поверх источника, затем удалите (или верните из git) файл в проекте и перегенерируйте. Одного копирования в источник мало: проверка сравнивает файл в проекте с хешем из meta.yaml, а не с источником, и упадёт снова;
  • правка нужна, источник — контрактный репозиторий (source: git+…) — закоммитьте правку в ветку контрактного репозитория, верните файл в проекте и перегенерируйте против этой ветки: make regenerate SOURCE_REF="<репозиторий>:<ветка>" (см. «Сборка против другой ветки контрактов» ниже). Ждать merge в контракт не нужно.

Флага «перезаписать несмотря на правку» нет намеренно: он делал бы то же, что удаление файлов, но для всех сразу и без разбора — правка терялась бы молча, ровно то, от чего защищает проверка.

Проверка выполняется до того, как генератор что-либо записал, поэтому дерево проекта остаётся нетронутым: правку ещё можно скопировать. --dry-run на таком дереве тоже завершится ошибкой — он показывает, что сделает реальный прогон, а реальный прогон остановится.

Сравнивается содержимое файла в проекте с хешем из meta.yaml, а не с источником. Если контракт изменился в своём репозитории, а файл в проекте не трогали, — это обычное обновление, оно пройдёт молча. Если записи о файле в манифесте нет (проект старше манифеста, канал только что добавлен в project.yaml), сравнивать не с чем — прогон тоже проходит.

Удалённые спеки

Если в path: указан URI (git+ssh://, git+https://, https://), при make regenerate соответствующий файл скачивается и кладётся в api/{rest|grpc|schema}/... — так же, как если бы он был локальным. Между регенерациями файлы лежат в репо проекта, и сборка не требует доступа в интернет. См. Удалённые спеки.

Сборка против другой ветки контрактов

Чтобы собрать дерево из контрактов релизной ветки или ветки задачи, не правя project.yaml:

# все репозитории контрактов — из одной ветки
make regenerate SOURCE_REF=release/2026.10

# у каждого репозитория своя ветка (список — через пробел или запятую)
make regenerate SOURCE_REF="github.com/org/specs:release/2026.10 github.com/org/proto:main"

Ref применяется к git-источникам, у которых ref не указан в строке; записи с @<ref> — это пин, он остаётся как есть. Форма <репозиторий>:<ref> нужна, когда контракты лежат в нескольких репозиториях и в релиз попадает своя ветка каждого. См. Переопределение ref.

Миграции между версиями

При обновлении генератора на новую версию может потребоваться миграция конфигурации.

Проверка версии

go-project-starter --version

Запуск миграции

go-project-starter migrate --configDir=.project-config

Что делает миграция

  1. Читает текущую конфигурацию
  2. Применяет изменения для устаревших полей:
  3. Переименование полей
  4. Изменение структуры
  5. Удаление deprecated-полей
  6. Сохраняет обновлённую конфигурацию

Пример миграции

# До миграции (старый формат)
rest:
  - name: api
    generator: ogen

# После миграции (новый формат)
rest:
  - name: api
    generator_type: ogen

Добавление новых компонентов

Добавление нового REST транспорта

  1. Добавьте в config.yaml:
rest:
  - name: admin
    path: [./api/admin.yaml]
    generator_type: ogen
    port: 8081
    version: v1
  1. Добавьте в application:
applications:
  - name: api
    transport: [api, admin, sys]
  1. Регенерируйте:
go-project-starter --config=config.yaml

Добавление нового воркера

  1. Добавьте в config.yaml:
workers:
  - name: email_sender
    generator_type: daemon
  1. Добавьте в application:
applications:
  - name: workers
    workers: [telegram_bot, email_sender]
  1. Регенерируйте проект.

Удаление компонентов

При удалении компонента из конфигурации и перегенерации проекта:

  1. Сгенерированные файлы без user code — удаляются автоматически. Генератор определяет устаревшие файлы по наличию disclaimer-маркера и отсутствию в текущем наборе шаблонов.

  2. Сгенерированные файлы с user code — генерация завершается ошибкой. Перенесите свой код в другое место и удалите файл вручную.

  3. Пользовательские файлы (без disclaimer) — не затрагиваются.

При использовании --dry-run устаревшие файлы отображаются в выводе как "Remove obsolete file".

Best Practices

Версионирование конфигурации

Храните config.yaml в Git:

git add config.yaml
git commit -m "Add admin API transport"

Предпросмотр изменений

Используйте --dry-run перед регенерацией:

go-project-starter --dry-run --config=config.yaml --target=.

Регулярная регенерация

Регенерируйте проект после обновления генератора:

go install github.com/Educentr/go-project-starter/cmd/go-project-starter@latest
go-project-starter --config=config.yaml --target=.

Это обеспечит актуальность инфраструктурного кода.