Регенерация и миграции¶
Описание процесса регенерации проекта и миграций между версиями.
Сохранение пользовательского кода¶
Уникальная возможность: Перегенерируйте весь проект без потери ваших изменений.
Как работают Disclaimer-маркеры¶
Каждый сгенерированный файл содержит маркер:
// ==========================================
// GENERATED CODE - DO NOT EDIT ABOVE THIS LINE
// Changes manually made below will not be overwritten by generator.
// ==========================================
Правила:
- Код выше маркера регенерируется при каждом запуске
- Код ниже маркера сохраняется навсегда
- Если нужно изменить сгенерированный код — переместите его ниже маркера
After-marker код как workaround¶
Код ниже маркера можно использовать, чтобы не ждать закрытия issue в go-project-starter. Например, если шаблон генерирует не тот код, который вам нужен — переопределите поведение ниже маркера.
Правило: каждый такой workaround обязательно должен содержать:
- Ссылку на issue в go-project-starter
- 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 самим генератором при прошлом прогоне:
Отсюда два следствия. Регенерация не требует предустановленного генератора — версия скачивается сама, как ogen и argen. И версия, которой собрано дерево, записана в репозитории: регенерация записанной версией обязана давать пустой дифф.
Поднять пин:
Новая версия перегенерирует проект и запишет себя в GPSVERSION. Руками эту строку править
не нужно — следующий прогон её перезапишет. Подробности, включая tools.starter_version для
окружений с несобираемой версией, — в секции tools.
Файлы, которые никогда не перезаписываются¶
.gitignorego.mod,go.sumLICENSE.txtREADME.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…}
Из этого следуют пять практических правил:
meta.yamlкоммитится вместе с проектом. Без него следующая регенерация не знает, какие файлы её, и возвращается к старому поведению — поиску маркера disclaimer по всему дереву. Файл меняется на каждом прогоне, который меняет вывод; конфликт при merge двух веток решается перегенерацией на смёрженном дереве.- Посторонние файлы в дереве генератор не трогает. Бэкап сгенерированного файла,
*_gen.go.origот merge-конфликта, индекс code-intelligence инструмента — всё, чего нет в манифесте, не читается, не удаляется и не ломает прогон, даже если внутри есть строка disclaimer. - Правки выше маркера видны. Если сгенерированная часть файла изменена руками, генератор печатает предупреждение с путём:
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.
Миграции между версиями¶
При обновлении генератора на новую версию может потребоваться миграция конфигурации.
Проверка версии¶
Запуск миграции¶
Что делает миграция¶
- Читает текущую конфигурацию
- Применяет изменения для устаревших полей:
- Переименование полей
- Изменение структуры
- Удаление deprecated-полей
- Сохраняет обновлённую конфигурацию
Пример миграции¶
# До миграции (старый формат)
rest:
- name: api
generator: ogen
# После миграции (новый формат)
rest:
- name: api
generator_type: ogen
Добавление новых компонентов¶
Добавление нового REST транспорта¶
- Добавьте в
config.yaml:
- Добавьте в application:
- Регенерируйте:
Добавление нового воркера¶
- Добавьте в
config.yaml:
- Добавьте в application:
- Регенерируйте проект.
Удаление компонентов¶
При удалении компонента из конфигурации и перегенерации проекта:
-
Сгенерированные файлы без user code — удаляются автоматически. Генератор определяет устаревшие файлы по наличию disclaimer-маркера и отсутствию в текущем наборе шаблонов.
-
Сгенерированные файлы с user code — генерация завершается ошибкой. Перенесите свой код в другое место и удалите файл вручную.
-
Пользовательские файлы (без disclaimer) — не затрагиваются.
При использовании --dry-run устаревшие файлы отображаются в выводе
как "Remove obsolete file".
Best Practices¶
Версионирование конфигурации¶
Храните config.yaml в Git:
Предпросмотр изменений¶
Используйте --dry-run перед регенерацией:
Регулярная регенерация¶
Регенерируйте проект после обновления генератора:
go install github.com/Educentr/go-project-starter/cmd/go-project-starter@latest
go-project-starter --config=config.yaml --target=.
Это обеспечит актуальность инфраструктурного кода.