Организация кода: queries и models

Туториал из третьего урока оставил вам плоскую папку: schema.sql, query.sql, один пакет. Для демо хватает, для продукта — нет: через полгода в одной папке встретятся схема на тысячу строк, сорок файлов запросов и попытка понять, что из этого актуально. Зрелая sqlc структура проекта опирается на три решения, и все три вы уже видели по кусочкам. Первое: схема живёт в папке миграций — шестнадцатый урок отвёл db/migrations под пары up/down у goose и golang-migrate, и sqlc читает эту же папку как источник DDL. Одна папка — один источник правды: запросы компилируются против того же SQL, который накатывается на базу. Второе: запросы живут отдельно, в пакетах queries — по домену на папку, как учил семнадцатый урок: db/queries/todos, db/queries/users. Третье: сгенерированный код уезжает в internal/store/<pkg> — не в корень, не в cmd, не рядом с обработчиками. Префикс internal работает на вас: за пределы модуля пакет импортировать нельзя, а значит, никто из чужих репозиториев случайно не начнёт зависеть от вашего генерата.

Отдельное слово про sqlc.yaml. По умолчанию команда ищет его в текущей папке, и для монорепозитория с несколькими сервисами это повод держать конфиг в корне — sqlc generate из корня соберёт все записи списка sql разом. Если сервисов много и генерация у каждого своя, конфиг можно положить рядом с сервисом и звать с флагом -f, но приберегите это для дня, когда одна запись действительно начнёт мешать другой; до того момента один файл в корне — самая читаемая организация кода sqlc, какая бывает.

Откройте internal/store/pgdb после генерации — и вы увидите ровно четыре сорта файлов, какие бы таблицы ни завели. Файл db.go — каркас: интерфейс DBTX с методами QueryContext, QueryRowContext, ExecContext (для database/sql ещё и PrepareContext), структура Queries, хранящая соединение, конструктор New(db DBTX) и метод WithTx, который одиннадцатый урок делал главной дверью в транзакции. Этот файл одинаков почти дословно у всех контуров курса — меняются только сигнатуры под pgx или database/sql, как видел девятнадцатый.

Файл models.go — словарь: по структуре на таблицу, имена превращает простое правило — таблица todos даёт структуру Todo, срез хвостового «s» снимается; ключ emit_exact_table_names со значением true отключает это и оставит Authors для таблицы authors. Типы полей приходят из карты типов вашего движка — та самая, что читали четвёртый, восемнадцатый и девятнадцатый уроки.

Файлы-однофамильцы запросов: todos.sql.go рядом с вашим todos/queries.sql — константа с SQL, Params-структура, если параметров больше лимита, Row-структура для выборок с джойнами из двенадцатого урока и сами методы CreateTodo, ListTodos. Имя .sql.go наследуется от имени исходного файла — вот почему нарезку по файлам стоит делать осмысленной, а не «всё в один dump.sql». Наконец, querier.go — интерфейс со всеми методами пакета, появляется при emit_interface: true; одиннадцатый урок уже читал его применительно к транзакциям.

Генератор настраивается не флагами командной строки, а ключами в gen.go записи — вторая серия их мелькала ещё во втором уроке, здесь самое время собрать карту целиком.emit_interface включает querier.go — интерфейс над всеми методами; для организации кода sqlc это главный шов: сервис будет зависеть от интерфейса, а не от структуры, и тесты из двадцать первого урока подменят реализацию без докера. emit_json_tags добавляет теги json к структурам моделей; удобно для маленьких сервисов, где модель таблицы сразу уезжает в ответ API, и спорно для больших, где слои стоит разводить. emit_pointers_for_null_types меняет представление nullable-колонок: вместо sql.NullString — *string; девятый урок разбирал эту развилку как вопрос вкуса и кодовой базы. emit_empty_slices заставляет методы :many возвращать пустой срез вместо nil — мелочь, которая убирает целый класс «if rows == nil» в обработчиках.

Дальше — ключи, управляющие именами и объёмом. emit_exact_table_names уже разобрали: имена структур без сингуляризации. omit_unused_structs режет из models.go структуры таблиц, на которые не ссылается ни один запрос — осмысленно в монорепозитории, где один конфиг собирает несколько пакетов, как в семнадцатом. query_parameter_limit задаёт порог: пока параметров не больше N (по умолчанию один), они идут в сигнатуру метода по отдельности, как только больше — sqlc упаковывает их в структуру <Query>Params. Ключ rename в gen.go переназначает имена колонок, конфликтующие с ключевыми словами или стилем: колонка order станет Order по вашему указанию, а не сломает генерацию.

Запросы — это единственный код, который вы пишете руками, поэтому вся дисциплина организации кода sqlc сходится к тому, как вы держите пакеты queries. Правило нарезки: папка — домен, файл — тема внутри домена. В todos лежат queries.sql с крудом и stats.sql с агрегациями из тринадцатого урока — и генерат раскладывается по файлам-близнецам, как вы уже знаете. Имена запросов делайте глагол+сущность: CreateTodo, ListUsers, CompleteTodo — они станут именами методов, и от этого зависит читаемость вызовов по всему проекту. Дубликат имени внутри одной записи sql — ошибка генерации: два CreateTodo в разных файлах одного пакета не соберутся, потому что в Go не может быть двух методов с одним именем на приёмнике.

Чего у sqlc нет — include-ов и макросов общего SQL: если пять запросов используют одно условие, придётся либо написать его пять раз, либо вынести его в базу как представление, либо собрать запрос на стороне Go из констант. Это осознанный минимализм: sqlc компилирует то, что видит, и не тащит препроцессор. Зато повторное использование параметров уже в языке запросов — восьмой урок показывал, как sqlc.arg(name) при повторном упоминании даёт один параметр, а не два. И не забывайте про sqlc.narg из девятого: nullable-параметры в UPDATE — половина «динамических» фильтров из пятнадцатого урока живёт именно на них, без всякой магии конкатенации.

Самый частый вопрос после анатомии — использовать ли сгенерированный пакет напрямую из обработчиков. Для маленького сервиса — да: pgdb.New(pool) в main, Queries в зависимостях хендлеров, и всё честно. Но в проекте, который растёт, есть две причины обернуть генерат в свой тонкий слой. Первая — транзакции: метод домена вроде «закрыть задачу и списать деньги» должен выполняться атомарно, и одиннадцатый урок строил для этого хелпер withTx; если каждый обработчик сам открывает транзакцию, правила расползаются. Вторая — тесты: сервис, зависящий от интерфейса, проверяется фейком без базы, а интеграционные тесты из двадцать первого урока достанутся только обёртке.

Классический паттерн — структура-обёртка, которая встраивает Queries и добавляет свою транзакционную дверь. Встраивание даёт красивую механику: все методы Queries становятся методами Store как есть, при этом Store может добавлять свои. Метод ExecTx у обёртки принимает функцию и передаёт ей Queries, привязанную к транзакции через WithTx, — тот самый контракт одиннадцатого урока, но спрятанный за одной точкой входа. Границу не переступайте: обёртка без логики, без кэшей, без «умных» конвертеров — иначе вы построите второй ORM поверх генератора, который от ORM как раз уходил. Правило: Store — это про время жизни соединений и транзакций, а не про бизнес-правила.

Девятнадцатый урок закончился обещанием: конфиг, где postgresql, mysql и sqlite живут по соседству. Теперь у вас есть все детали, чтобы его выполнить. Каждая запись списка sql — свой пакет со своим out, это механика семнадцатого. Схема у движков общая по смыслу, но не по синтаксису: SERIAL против INTEGER PRIMARY KEY, TIMESTAMPTZ против TEXT — поэтому схема разделяется на db/schema/pg, db/schema/my, db/schema/lite, и тут же встаёт вопрос о пакетах queries: дублировать ли SQL трижды?

Честный ответ зависит от того, насколько диалекты расходятся. Если запросы — фильтры, вставки, обновления на голом SQL без экзотики, один каталог db/queries обслуживает все три записи: массив queries может указывать на одну и ту же папку из разных записей, а плейсхолдеры ? и $1 останутся единственным расходящимся штрихом, и sqlc молча переварит оба стиля в своём парсере. Как только появляются массивы ANY($1::int[]), ON CONFLICT, RETURNING с особенностями — выносите специфичное в db/queries/pg и указывайте его только в PG-записи: общий каталог минус папка специфики. Помните и о картах типов из восемнадцатого и девятнадцатого уроков: DECIMAL в MySQL — string, в SQLite — float64, то есть одна и та же колонка даёт разные поля в соседних пакетах, и обёртка Store — правильное место, чтобы разницу проглотить. Трекер из курса живёт на PostgreSQL, а SQLite-пакет обслуживает тесты и CLI — это ровно та модель, где мультидвижковость не превращается в налог.

Последнее организационное решение — судьба сгенерированных файлов в git, и оно делит сообщество надвое. Аргументы за коммит: пакет собирается у любого, кто склонировал репозиторий, без установки sqlc; diff генерата в pull request показывает ровно то, что изменит запрос — ревьюер видит новые поля структур и новые методы; версии sqlc у всех команды и в деплое совпадают по умолчанию. Аргументы против: PR шумит сгенерированными строками, а если кто-то забудет перегенерировать, репозиторий уезжает в дрейф — источники говорят одно, генерат другое.

Дрейф лечится механикой, а не запретами:sqlc diff из двадцать второго урока сравнит генерат с тем, что выдал бы текущий конфиг, и уронит CI при расхождении. Практика, которая работает в большинстве команд: коммитим генерат, CI проверяет diff, версия sqlc зафиксирована. Фиксация делается прямо в go:generate-директиве: go run с явной версией модуля тянет именно её, и генерация перестаёт зависеть от того, что установлено у разработчика в PATH. Экономия на коммите генерата (репозиторий тоньше, diff чище) почти всегда оборачивается tax-ом на сборку: каждому потребителю нужен установленный sqlc, а откат релиза — это не revert-коммит, а повторная генерация на месте. Оставьте «генерим на месте» проектам, где слой данных меняется каждый день, и вернитесь к нему, когда CI из двадцать второго урока научится проверять всё сам.

Оглядитесь: раскладка стоит, пакет собран из четырёх сортов файлов, emit-карта настроила форму, Store закрыл транзакции, а мультидвижковый конфиг держит три мира в одном репозитории. Если запрос «sqlc организация кода» сворачивать в один ответ, ответом будет эта раскладка плюс договорённости вокруг генерата — всё остальное в курсе оказалось её следствиями. Главная причина, по которой всё это делалось именно так, а не «лишь бы компилировалось» — тесты. Интерфейс querier.go — это место, куда сервис может встать на учет и не звать базу в юнит-тестах; DBTX — шов, через который генерат равнодушен к тому, живая база перед ним, sqlite в памяти или мок; Store с ExecTx — единственная точка, которую нужно проверять на атомарность. Двадцать первый урок разложит это хозяйство по пирамиде: юнит-тесты на фейках репозитория, интеграционные на sqlite из девятнадцатого и на настоящем Postgres, sqlmock — и покажет, где моки врут, а где честнее самой базы. Если вы ещё не включили emit_interface — сделайте это сегодня: завтра будет поздно, потому что сервисы уже встанут на конкретную структуру, а не на интерфейс.