среда, 17 июня 2020 г.

Пакет bson для работы с MongoDB в Golang

Пакет bson (go.mongodb.org/mongo-driver/bson) - это библиотека для чтения, записи и управления BSON. BSON - это двоичный формат сериализации, используемый для хранения документов и выполнения удаленных вызовов процедур в MongoDB. Библиотека BSON обрабатывает маршалинг и демаршаллинг значений через настраиваемую систему кодеков.

Raw BSON

Семейство типов Raw используется для проверки и извлечения элементов из срезов байтов. Этот тип наиболее полезен, когда вы хотите выполнить поиск на байтах BSON, не демаршируя его в другой тип.

Пример:

var raw bson.Raw = ... // байты откуда-либо
err := raw.Validate()
if err != nil { return err }
val := raw.Lookup("foo")
i32, ok := val.Int32OK()
// делаем что-нибудь с i32...

Нативные Go типы

Типы D и M, определенные в этом пакете, могут использоваться для построения представлений BSON с использованием собственных типов Go. D - это срез, а M - это карта.

Пример:

bson.D{{"foo", "bar"}, {"hello", "world"}, {"pi", 3.14159}}
bson.M{"foo": "bar", "hello": "world", "pi": 3.14159}

При декодировании BSON в D или M применяются следующие сопоставления типов при демаршаллинге:

  1. BSON int32 демаршаллизируется в int32.
  2. BSON int64 демаршаллизируется в int64.
  3. BSON double демаршаллизируется в float64.
  4. BSON string демаршализируется в string.
  5. BSON boolean демаршализируется в bool.
  6. BSON embedded document демаршализируется в родительский тип (т.е. D для D, M для M).
  7. BSON array демаршализируется в bson.A.
  8. BSON ObjectId демаршализируется в primitive.ObjectID.
  9. BSON datetime демаршализируется в primitive.Datetime.
  10. BSON binary демаршализируется в primitive.Binary.
  11. BSON regular expression демаршализируется в primitive.Regex.
  12. BSON JavaScript демаршализируется в primitive.JavaScript.
  13. BSON code демаршализируется в primitive.CodeWithScope.
  14. BSON timestamp демаршализируется в primitive.Timestamp.
  15. BSON 128-bit decimal демаршализируется в primitive.Decimal128.
  16. BSON min key демаршализируется в primitive.MinKey.
  17. BSON max key демаршализируется в primitive.MaxKey.
  18. BSON undefined демаршализируется в primitive.Undefined.
  19. BSON null демаршализируется в primitive.Null.
  20. BSON DBPointer демаршализируется в primitive.DBPointer.
  21. BSON symbol демаршализируется в primitive.Symbol.

Вышеуказанные сопоставления также применяются при маршалинге D или M к BSON. Некоторые другие полезные сопоставления маршаллинга:

  1. time.Time маршализируется в BSON datetime.
  2. int8, int16, and int32 маршализируется в BSON int32.
  3. int маршалируется в BSON int32, если значение находится между math.MinInt32 и math.MaxInt32 включительно, и BSON int64 в противном случае.
  4. int64 маршалируется в BSON int64.
  5. uint8 и uint16 маршалируется в BSON int32.
  6. uint, uint32 и uint64 маршалируются в BSON int32, если значение находится между math.MinInt32 и math.MaxInt32, включительно, в BSON int64 в противном случае.
  7. BSON null значения будут разбиты на нулевое значение поля (например, демаршализирование BSON null в строку даст пустую строку.).

Структуры

Структуры можно маршалировать/демаршалировать в/из BSON. При преобразовании структур в/из BSON применяются следующие правила:

  1. Только экспортированные поля в структурах будут маршалированы или демаршалированы.
  2. При маршалинге структуры каждое поле будет в нижнем регистре генерировать ключ для соответствующего элемента BSON.
    Например, поле структуры с именем "Foo" будет генерировать ключ "foo". Это можно переопределить с помощью тега struct (например, `bson:"fooField"` для генерации ключа "fooField" вместо этого).
  3. Встроенное поле структуры маршалируется как вложенный документ. Ключом будет строчное имя типа поля.
  4. Поле указателя маршалируется как базовый тип, если указатель не nil. Если указатель равен nil, это маршалируется как BSON null значение.
  5. При отмене маршалинга поле типа interface{} будет соответствовать отображениям типа D/M, перечисленным выше. Документы BSON демаршалированные в поле interface{} будет демаршалированны как D.

Следующие теги структуры могут использоваться для настройки поведения:

  1. omitempty: если в поле указан тег структуры omitempty, поле не будет маршалироваться, если установлено нулевое значение. По умолчанию поле структуры считается пустым, только если тип поля реализует Zeroer интерфейс и метод IsZero возвращает true. Структурные поля типов, которые не реализуют Zeroer, всегда маршалируются как вложенные документы. Этот тег должен использоваться для всех значений среза и карты.
  2. minsize: если тег структуры minsize указан в поле типа int64, uint, uint32 или uint64 и значением поле может помещаться в int32 со знаком, поле будет сериализовано как BSON int32, а не BSON int64. Для других типов, этот тег игнорируется.
  3. truncate: если структурный тег truncate указан в поле с числовым типом, не являющимся float, BSON double демаршалированный в это поле будет окреглен к десятичной точке. Например, если 3.14 демаршалируется в поле типа int, он будет демаршалирован как 3. Если этот тег не указан, декодер выдаст ошибку, если значение не может быть декодировано без потери точности. Для float64 или нечисловых типов этот тег игнорируется.
  4. inline: если структурный тег inline указан для поля struct или map, поле будет "уплощено" при маршаллинге и "разуплощено" при демаршаллинге. Это означает, что все поля в этой структуре/карте будут поднято на один уровень и станет полями верхнего уровня, а не полями во вложенном документе. Например, если поле карты с именем "Map" со значением map map[string]interface{}{"foo": "bar"} является inline, результирующий документ будет {"foo": "bar"} вместо {"map": {"foo": "bar"}}. В структуре может быть только одно inline поле map. Если есть дублированные поля в результирующем документе, когда inline поле маршалируется, будет возвращена ошибка. Этот тег может использоваться с полями, которые являются указателями на структуры. Если поле встроенного указателя равно nil, оно не будет маршалировано. Для полей, которые не являются картами или структурами, этот тег игнорируется.

Маршаллинг и демаршаллинг

Маршаллинг и демаршаллинг можно выполнять вручную с помощью семейства функций Marshal и Unmarshal.

Читайте также:


Канал в Телеграм

Labels: ,

Комментариев нет:

Отправить комментарий