Структуры и bson-теги

Правило по умолчанию стоит запомнить дословно: без тега кодек драйвера пишет имя поля строчными буквами целиком. Name станет name, HTTPCode — httpcode, CreatedAt — createdat. Поэтому первый и главный модификатор — имя в теге: bson:"name" переопределяет ключ документа. Соглашение, которое я встречаю в Go-проектах чаще всего: snake_case — bson:"created_at", bson:"sku"; оно совпадает с традициями MongoDB-мира и с удобством чтения в mongosh. Порядок полей в структуре — тоже контракт: кодек пишет поля в порядке объявления, и BSON порядок сохраняет — это важно для _id, который обязан быть первым полем, и для читаемости документа глазами. Неэкспортируемые поля кодек пропускает молча — их в документе не будет никогда. И отдельно: если поле структуры вообще не должно попадать в базу, ставьте тег bson:"-" — минус явно исключает поле из кодирования и декодирования. Тег разбирается по запятой: первая часть — имя (пустая при ,inline), дальше — модификаторы. Анонимные вложенные структуры без тега кодек вливает автоматически — как неявный inline, поэтому композиция моделей работает и без лишних тегов.

Модификатор omitempty — источник половины багов с тегами, поэтому разберём его буквально. Пустым кодек считает: false у bool, ноль у любых чисел, пустую строку, nil-указатель, nil-срез, nil-карту и пустую структуру времени. Не пустым — всё остальное: не-nil указатель на ноль, срез с элементами, false нельзя «сделать не пустым» без указателя. Отсюда практические следствия. Число-ноль как легитимное значение — цена со скидкой 0, количество 0 — нельзя декорировать omitempty: поле исчезнет, и при декодировании вернётся тот же ноль, а вот в фильтрах и валидации документ окажется «без цены». Для таких полей используйте указатель int64: nil — пусто, а указатель на ноль — осмысленный ноль, и omitempty сработает честно. Тот же приём спасает bool-флаги, где false и «поле не задано» — разные вещи. Вопрос «bson omitempty когда применять» решается одним тестом: может ли значение быть нулём легитимно? Может — указатель или без omitempty; ноль всегда означает «нет данных» — смело ставьте. Отдельная история — время: нулевое time.Time тоже считается пустым при omitempty, поэтому для полей вроде deleted_at используйте указатель time.Time: nil — метки нет, а не «первое января 1970 года».

Структуры — не единственный способ собрать документ, и в запросах вы постоянно будете видеть три типа из пакета bson. bson.E — пара {Key, Value}, кирпичик документа. bson.D — []E, упорядоченный документ: порядок полей именно такой, как вы написали; его выбирают для команд сервера и фильтров, где порядок операторов важен ($group с сортировкой, составные ключи). bson.M — map[string]any, неупорядоченный документ: короткая запись для быстрых фильтров, где порядок не играет роли. bson.A — слайс значений, массив внутри документа. Моё рабочее разделение: модели — структуры с bson-тегами; ad-hoc запросы и агрегации — bson.D, потому что конвейеры чувствительны к порядку этапов; разовые проверки в тестах — bson.M. Спорное мнение с условием: я не люблю bson.M в продовом коде — опечатка в ключе компилируется и всплывает только на рантайме, — но в тестах и одноразовых скриптах его компактность перевешивает, и там он у меня законен. Если сомневаетесь, какой тип выбрать, — вспомните, важен ли порядок: важен — D, не важен — M, а модели всегда структуры.

Пара типов, которые BSON-кодек откажется кодировать — лучше знать заранее, чем ловить в проде. Каналы, функции и комплексные числа не имеют BSON-представления: кодирование вернёт ошибку вида no encoder found for type, и вставка не состоится. Карты в документе должны быть со строковыми ключами: map[string]any кодируется, а map[int]string — ошибка, потому что ключ документа в BSON всегда строка. Время кодируется типом time.Time: число-миллисекунды вручную лучше не складывать в поле int64, если потом хочется читать его датой. Отсюда рабочее правило: поле модели — либо BSON-нативный тип, либо ваш тип с явной конверсией перед записью; магии «драйвер сам догадается» не существует, и это хорошо — явный код отлаживается быстрее.

Два модификатора встречаются реже, но знать их стоит. minsize работает с целыми: int64 в Go кодируется в BSON как int64 — восемь байт, даже если число помещается в int32. Тег bson:"qty,minsize" просит кодек писать значение как int32, когда оно влезает: экономия на размере документа, плюс совместимость, когда другой инструмент ожидает int32. Цена минимальна, и на больших коллекциях счётчик байт заметен. inline — совсем другой инструмент: он вливает поля вложенной структуры на верхний уровень документа, как мы видели в разборе — Specs.Color стал color. Работает со структурами и картами, требует, чтобы имена не конфликтовали с полями родителя. Зачем это нужно: композиция моделей без лишнего уровня вложенности — общий блок аудита, инлайнится во многие документы; при декодировании поля соберутся обратно в ту же структуру. Полезно и для миграций: документ уже плоский, а вы хотите работать с ним как с вложенной структурой — inline сделает это без переписывания данных. Пара ограничений: inline-структура должна быть экспортируемым типом, а имена её полей — не конфликтовать с полями родителя, иначе кодек вернёт ошибку ещё на этапе маршалинга, а не молча испортит документ.

Теги работают в обе стороны, и это стоит проговорить до того, как появится первый FindOne. Декодер берёт BSON-документ и заполняет структуру: имя поля в документе сверяется с bson-тегами, отсутствующие поля остаются нулевыми значениями Go, лишние в документе — игнорируются молча. Последние два факта — источник «тихих» багов: если в структуре нет поля amount, а в документе оно есть, драйвер не пожалуется — данные просто не доедут до кода. Обратное тоже верно: если типы несовместимы — строка в документе и int64 в структуре — Decode вернёт ошибку, и её нужно проверять так же честно, как ошибку запроса. Отсюда правило: структура-модель должна описывать документ целиком, а для гибкости есть поля bson.Raw и bson.M — их разберём по ходу курса. Обратный путь, кстати, доступен и без базы: bson.Unmarshal(data, &product) применяет те же теги к байтам — удобно для тестов кодека. А bson.Raw — это документ без декодирования: байты с ленивым доступом к полям через Lookup, когда нужен один ключ из большого документа и распаковывать всё расточительно. Проверять связку «структура — документ» удобно через MarshalExtJSON, как в этом уроке: он чистый Go без сети. Но полноценный круг вставки и чтения требует живого MongoDB — песочница сайта показывает тематическую программу на чистом Go, поэтому код уроков гоняйте локально: контейнер из второго урока и mongosh показывают всю картину.