Полиморфизм в JSON в Go

Полиморфная сериализация JSON — частая задача при проектировании API, UI-моделей или событийных структур. Пример структуры:

[   {"type": "text", "content": "hello"},   {"type": "image", "url": "pic.jpg"} ]

В Go такие данные принято представлять с помощью интерфейсов. Однако стандартный пакет encoding/json не умеет автоматически сериализовать и десериализовать структуры с полем-дискриминатором (например, "type"), которое определяет конкретный подтип. Приходится либо использовать громоздкие конструкции вроде map[string]any или json.RawMessage , либо вручную реализовывать интерфейсы json.Marshaler и json.Unmarshaler с разбором каждого варианта — такой подход быстро становится неудобным и слабо масштабируется.

Для решения этой задачи были разработаны две библиотеки:

• poly — обёртка с использованием дженериков;

• polygen — генератор кода, расширяющий возможности poly.

Библиотека poly

poly реализует сериализацию и десериализацию JSON на основе интерфейсов и дженериков. Подтипы регистрируются через poly.TypesN[...] и реализуют интерфейс poly.TypeName с методом TypeName() string, определяющим значение поля "type".

Объявление типов

type Item = poly.Poly[IsItem, poly.Types2[TextItem, ImageItem]]  type IsItem interface { poly.TypeName  // необязательно явно, но удобно isItem() }  type TextItem struct { Content string `json:"content"` }  func (TextItem) isItem() {} func (TextItem) TypeName() string { return "text" }  type ImageItem struct { URL string `json:"url"` }  func (ImageItem) isItem() {} func (ImageItem) TypeName() string { return "image" }

Десериализация

var item Item  _ = json.Unmarshal([]byte(`{"type":"text","content":"hello"}`), &item) // item.Value => TextItem{Content: "hello"}  _ = json.Unmarshal([]byte(`{"type":"image","url":"pic.jpg"}`), &item) // item.Value => ImageItem{URL: "pic.jpg"}  _ = json.Unmarshal([]byte(`{"url":"new.jpg"}`), &item) // item.Value => ImageItem{URL: "new.jpg"}

Сериализация

item = Item{Value: TextItem{Content: "Hi"}} data, _ := json.Marshal(item) // {"type":"text","content":"Hi"}  item = Item{Value: ImageItem{URL: "pic.jpg"}} data, _ = json.Marshal(item) // {"type":"image","url":"pic.jpg"} 

Зачем появился polygen

poly задумывался как лёгкое решение без генерации кода. Однако по мере развития стало ясно, что многие необходимые возможности не удаётся реализовать без усложнения API:

• настройка имени поля-дискриминатора;

• строгий режим (ошибка при неизвестном поле (DisallowUnknownFields));

• дефолтное поведение при отсутствии "type";

• масштабируемость при большом числе вариантов.

Чтобы не перегружать poly, был создан отдельный инструмент — polygen, который решает эти задачи через генерацию кода на основе файла конфигурации.

Объявление типов

type IsItem interface { isItem() }  type TextItem struct { Content string `json:"content"` }  func (TextItem) isItem() {}  type ImageItem struct { URL string `json:"url"` }  func (ImageItem) isItem() {}

Конфигурация .polygen.json

{   "$schema": "https://raw.githubusercontent.com/ykalchevskiy/polygen/refs/heads/main/schema.json",   "types": [     {       "type": "Item",       "interface": "IsItem",       "package": "main",       "subtypes": {         "TextItem": {           "name": "text"         },         "ImageItem": {           "name": "image"         }       }     }   ] }

Описание этих и остальных параметров можно посмотреть в README и в документации.

Генерация

$ go install github.com/ykalchevskiy/polygen@latest $ polygen

Генерируется файл item_polygen.go с типом Item, реализующим сериализацию/десериализацию по полю "type".

Десериализация

var item Item  _ = json.Unmarshal([]byte(`{"type": "text", "content": "hello"}`), &item) // item.IsItem => TextItem{Content: "hello"}  _ = json.Unmarshal([]byte(`{"type": "image", "url": "pic.jpg"}`), &item) // item.IsItem => ImageItem{URL: "pic.jpg"}  _ = json.Unmarshal([]byte(`{"url": "new.jpg"}`), &item) // item.IsItem => ImageItem{URL: "new.jpg"}

Сериализация

item = Item{IsItem: TextItem{Content: "Hi"}} data, _ := json.Marshal(item) // {"type":"text","content":"Hi"}  item = Item{IsItem: ImageItem{URL: "pic.jpg"}} data, _ = json.Marshal(item) // {"type":"image","url":"pic.jpg"}

Ссылки

• poly: https://github.com/ykalchevskiy/poly

• polygen: https://github.com/ykalchevskiy/polygen