Большая часть моей основной работы - TypeScript и PHP, но за этим стоит значительная часть инструментов Toolz.dev и маленькие сервисы, которые я пишу вокруг него, это Go, и каждый раз, когда я подключаю новый клиент API, я натыкаюсь на ту же стену. Перед вами ответ JSON, и вам нужна структура Go, которая json.Unmarshal расшифрует в. Написать эту структуру вручную утомительно очень специфическим образом: это не сложно, это просто скрипка, и скрипка биты именно там, где вы делаете ошибки. поэтому я построил конвертер в сайт, и это руководство к нему.
TL;DR: Инструмент Конвертер структур JSON в Go анализирует документ JSON и выдает описания типов Go, которые его описывают. Объекты становятся встроенными структурами, массивы объектов объединяются в одну структуру, и каждое поле получает a
json:"key"тег такencoding/jsonправильно отображает данные обратно.Имена полей следуют соглашениям Go, так чтоidстановитьсяIDаuser_urlстановитьсяUserURL. Переключить целые числа наint64, добавитьomitemptyи переименовать тип root. Он работает полностью на стороне клиента: нет загрузки, нет регистрации, работает в автономном режиме.
Что такое преобразователь структуры JSON в Go?
Преобразователь структуры JSON в Go превращает документ JSON в описания типов Go, которые его описывают, поэтому вы можете декодировать те же данные со стандартной библиотекой 's encoding/json пакет вместо ввода структуры вручную. Каждый объект JSON становится структурой Go, каждое поле несет a json:"key" тег, который отображает его обратно к исходному имени, и скалярные типы выводятся из значений. становится строка JSON string, становится целое число int, число с десятичной точкой становится float64, true а false стать bool, и null становиться interface{}, йо-
Причина, по которой это полезно, заключается в том, что объект JSON и структура Go описывают одну и ту же форму, набор именованных полей с типизированными значениями, но Go статически типизирован, а JSON - нет, поэтому структура должна заранее указать каждый тип. Получение этих типов из ответа образца - это чистая механика, а механика, выполняемая вручную с вложенной полезной нагрузкой, - это место, где живут ошибки. Конвертер выполняет вывод детерминированно и передает вам блок типов, который компилируется.
Стоит прояснить две половины проблемы, потому что это то, что наивный конвертер ошибается. Первый - это именование: Go кодирует только экспортированные поля, те, которые имеют первую заглавную букву, а правила сообщества хотят, чтобы общие инициализмы были полностью заглавными. Второй - тег: the json:"..." тег должен содержать точный оригинальный ключ или json.Unmarshal молча пропускает поле во время выполнения без ошибок Получите либо неправильно, и ваш декодирование возвращает структуру, полную нулевых значений, в то время как все выглядит нормально. инструмент обрабатывает оба для вас.
Почему бы не написать структуру от руки?
Это честный вопрос, потому что для плоского трехпольного объекта рукописный текст структуры быстрее, чем открытие инструмента Преобразователь зарабатывает свое место на ответах, которые не являются плоскими: полезная нагрузка с вложенными объектами, массивы объектов и двадцать полей, где половина ключей snake_case и некоторые из них представляют собой инициализмы типа id, url, и api_key, йо-
В таком ответе рукописная версия имеет три режима отказа, которые я нажимал неоднократно. Вы забываете экспортировать поле, поэтому оно остается строчным и encoding/json отказывается заселять его. Вы извлекаете выгоду из поля, но забываете тег, так что UserName ищет ключ JSON под названием UserName и никогда не находит user_name. Или вы неправильно вложено, объявляя поле простой структурой, когда JSON фактически заворачивает его в массив. Ничто из этого не является ошибкой компиляции. Это сюрпризы во время выполнения, которые отображаются как недостающие данные, и вы теряете больше времени на отладку одного из них, чем вы бы потратили на создание всей структуры.
Преобразователь удаляет все три. Он экспортирует каждое поле, он записывает тег из реального ключа, и он читает фактическую форму JSON, чтобы решить между структурой и срезом структур. то, что вы вставляете, это то, для чего вы получаете типы.
Вот решение в одной таблице.
| положение | обычай | почему |
|---|---|---|
| Плоский объект с двумя или тремя полями | Напишите это от руки | Быстрее, чем что-либо открывать |
| Вложенный ответ API со множеством полей | Конвертер структур JSON в Go | Именование и теги - это место, где нарушаются рукописные структуры |
| Вам нужна та же форма, что и TypeScript | Конвертер JSON в TypeScript | Тот же вывод, другой целевой язык |
| Вам нужна схема проверки, а не типы | Генератор схем JSON | Правила Draft-07, а не типы Go |
Почему имена полей Go отличаются от моих ключей JSON?
Это сбивает людей с первого раза, поэтому стоит объяснять, а не прятаться.Go's encoding/json упаковка только маршалов и маршалов экспортируется поля структуры, что означает поля, имя которых начинается с заглавной буквы Ключ JSON, как user_name не может сопоставить с неэкспортированным user_name поле, поэтому поле необходимо переименовать в что-то экспортируемое. Инструмент использует каждое слово с заглавной буквы, поворачивая user_name в UserName, йо-
Вдобавок ко всему, сообщество Go и инструмент для ворса №39;s - правила, с которых началось golint и жить дальше в таких инструментах, как staticcheckхочет, чтобы общие инициализмы были написаны заглавными буквами. Итак id становиться ID, не Id; user_url становиться UserURL, не UserUrl; и html_body становиться HTMLBody. Преобразователь знает стандартный набор инициализмов, ID, URL, API, HTTP, JSON, UUID, а остальное, и применяет их, поэтому выходные данные проходят через линты, которые, вероятно, запускает ваш CI.
Часть, которая делает переименование безопасным, это тег. Каждое поле получает a json:"user_name" тег точно удерживает исходную клавишу, то есть во время выполнения json.Unmarshal читает ключ JSON user_name и записывает это в UserName поле независимо от переименования.The Go blog's статья на JSON и Go документирует этот механизм тегов, и это причина, по которой переименованное поле все еще правильно декодируется. без тега переименованная структура незаметно не заполнилась бы.
Как обрабатываются номера и массивы объектов?
Две части вывода заслуживают более пристального внимания, поскольку именно в них преобразователи различаются по качеству.
Числа первыми. JSON имеет один тип числа, а Go - нет, поэтому инструменту приходится выбирать. Становится значение без дробной части int, или int64 если вы включите эту опцию, появится значение с десятичной точкой float64. Интересный случай - это массив, который их смешивает, например [9.5, 8, 7.2]. Если инструмент напечатал это как []int ему не удалось бы декодировать 9.5итак, он расширяет весь срез до []float64. Любой массив, в котором один элемент форсирует более широкий тип, получает более широкий тип для всех элементов, что является единственным выбором, который декодирует каждое значение.
Массивы объектов - это другое место, где реальная полезная нагрузка становится интересной. API почти никогда не дает вам массив, где каждый объект имеет одинаковый набор ключей; у одного элемента есть поле, которое другие опускают, или поле, которое можно свести на нет, присутствует здесь и отсутствует там. если инструмент сгенерировал структуру только из первого элемента, он сбросит ключи, которые появятся позже. Вместо этого он объединяет каждый объект в массиве в одну структуру, которая включает в себя каждый ключ, который есть у любого элемента. И если два элемента дают один и тот же ключ несовместимых типов, скажем, число в одном и строку в другом, это поле падает обратно на interface{} вместо того, чтобы инструмент угадывал неправильно или терпел неудачу сразу. результатом является один тип структуры, который может декодировать весь массив.
Как использовать конвертер?
Поток состоит из четырех шагов Вставьте объект или массив JSON во входное поле; если вы хотите сначала увидеть форму вывода, загрузите образец. дайте корневому типу имя, что-то вроде User или ApiResponse, и инструмент очищает его в действительный экспортированный идентификатор Go, чтобы он компилировался как записанный. Выбирать int или int64 для целых чисел и включите omitempty если вы хотите, чтобы поля с нулевым значением были исключены, когда структура позже будет закодирована обратно в JSON. Затем нажмите "Конвертировать" и скопируйте структуру в свой .go пилка
Если JSON недействителен, инструмент сообщает сообщение об ошибке парсера's, а не выходит из строя молча, поэтому быстро можно найти случайную конечную запятую или нецитируемый ключ. И поскольку все работает в вашем браузере, вы можете вставить реальный ответ API, в том числе с частными полями, не покидая свою машину. Эта модель на стороне клиента такая же, как и за остальной частью сайта, описанная в онлайн-инструменты конфиденциальности данных гид.
Как это сочетается с другими инструментами JSON?
Преобразователь структуры JSON в Go является одним из членов семейства трансформаторов JSON на сайте, и они имеют одно и то же ядро синтаксического анализа. Когда вы хотите сначала привести в порядок JSON, Форматтер JSON будет отступать и проверять его, что стоит сделать, прежде чем конвертировать, чтобы вы могли прочитать форму, которую собираетесь ввести. Когда ваш целевой язык TypeScript, а не Go, Конвертер JSON в TypeScript запускает тот же вывод и излучает интерфейсы. Когда вам нужен контракт проверки вместо типов языков, Генератор схем JSON создает схему Draft-07, а когда пунктом назначения является кодовая база PHP, Преобразователь массива JSON в PHP пишет массив литерал.
Нить, соединяющая их все, заключается в том, что они рассматривают JSON как источник структуры и переводят эту структуру во все, на чем говорит ваша кодовая база. Если вы работаете на нескольких языках, Набор инструментов для веб-разработчиков обзор показывает, как эти части складываются вместе и Руководство по инструментам кодирования охватывает более широкий набор форматировщиков и преобразователей.
Работающий пример из построения сервиса Go
Позвольте мне конкретизировать. некоторое время назад я писал небольшой сервис Go, который извлекал данные из стороннего API и повторно выставлял уменьшенную версию его.Ответом поставщика 's был вложенный объект: запись верхнего уровня с owner подпредмет, а tags массив строк и а scores массив, который, что раздражает, смешивал целые и десятичные числа в зависимости от поля. Ручная типизация структуры означала получение owner гнездо правильно, маркировка каждого snake_case ключ и решение, что делать с этим смешанным массивом.
Я вставил выборочный ответ в преобразователь, назвал корневой тип в честь ресурса и получил обратно структуру Owner как встроенная вложенная структура, Tags как []string, и Scores правильно расширен до []float64, йо- выше id филд вышел таким ID с json:"id" тег, так что он и прошел линтер и декодировал реальный ключ. я скопировал его прямо в пакет клиента и перешел к логике, где я действительно хотел провести свое время. структура не была интересной частью работы, и генерировать его означало, что он перестал быть какой-либо частью работы.
Причина, по которой я обращаюсь к конвертеру, а не к рукописной структуре в этих пятнах, не лень, это то, что механические части, экспортируя, маркируя и вложенные, являются именно теми частями, которые я ошибаюсь, когда я думаю о логике вместо этого. Разгрузка их на детерминированный инструмент означает, что структура правильна на первом компиляторе, и правильный декодирование на первом прогоне, который на вложенной полезной нагрузке экономит подлинный сеанс отладки. когда мне нужно, чтобы структура также выжила при повторном кодировании, я включаю omitempty таким образом, нулевые значения остаются вне выхода, а теги проходят как json:"key,omitempty" готов к тому путешествию туда и обратно.
О каких пределах стоит знать?
Несколько честных краев. Первый есть null. ДЖСОН null не несет никакой информации о типе самостоятельно, поэтому поле таково null в вашем образце напечатано как interface{}. Там нет ничего, что инструмент может сделать вывод; если вы знаете реальный тип, измените его в своем редакторе после вставки или подайте конвертеру образец, где это поле имеет реальное значение, чтобы можно было получить тип. Это свойство данных, а не недостаток инструмента.
Второй - это числовая точность, и это свойство анализа JSON в целом, а не этого преобразователя в частности. Инструмент анализирует ваш JSON с помощью анализатора JSON 's, который представляет числа как числа двойной точности плавают, поэтому целые числа, превышающие примерно 2 в 53-й степени, теряют точность во время анализа, прежде чем инструмент когда-либо увидит их. Сгенерированный int64 поле достаточно широкое, чтобы держать большой идентификатор, но если идентификатор поступает как голый номер JSON, который настолько велик, анализ уже округлил его. Для действительно больших целочисленных идентификаторов надежный ход - нести их в виде строк в JSON, что сохраняет их точность и позволяет вводить поле как string, йо-
Третий заключается в том, что вывод является отправной точкой, а не евангелием. инструмент дает вам типы, которые поддерживает выборка, но только вы знаете, что поле, которое в этом ответе оказывается целым числом, на самом деле является нулевым числом или что a float64 должен быть а json.Number чтобы избежать потери точности. Относитесь к выводу как к правильному первому черновику, который вы уточняете, а не к контракту, вырезанному в камне. Это верно для каждого генератора JSON-типа, на любом языке.
Наконец, конвертер производит встроенные вложенные структуры, которые сохраняют всю форму в одном объявлении вы можете вставить как блок. это наиболее распространенный и наиболее читаемый стиль для сгенерированной структуры, и это то, что инструменты в экосистеме Go популяризированы. Если вы предпочитаете иметь отдельные именованные типы для глубоко повторно используемых подобъектов, это рефактор, который вы делаете вручную, как только встроенная версия находится в вашем редакторе, и это обычно пятисекундный экстракт с вашей IDE.
Часто задаваемые вопросы
Что такое преобразователь структуры JSON в Go? Преобразователь структуры JSON в Go преобразует документ JSON в описания типа Go, которые его описывают Каждый объект становится структурой, каждое поле получает json:"key" тег, и типы значений выводятся, так что вы можете размаршировать те же данные с кодированием/json без записи структуры вручную.
Как конвертировать JSON в структуру Go? Вставьте JSON в поле ввода, введите имя для корневого типа, выберите параметры целого числа и тега, затем нажмите Convert. инструмент печатает определения структуры Go с тегами json, которые вы можете скопировать прямо в файл.go.
Почему имена полей Go отличаются от моих ключей JSON? Go кодирует только экспортированные поля, поэтому каждое имя поля пишется с заглавной буквы, а общие инициализмы создаются в верхнем регистре, чтобы соответствовать golint. Json:"..." тег на каждом поле сохраняет исходный ключ, поэтому json.Unmarshal по-прежнему правильно отображает данные, несмотря на переименованное поле.
Как номера JSON сопоставляются с типами Go? Целое число становится int, или int64, если включить эту опцию, и число с десятичной точкой становится float64. когда массив смешивает целые и десятичные числа для одной и той же позиции, тип расширяется до float64, чтобы каждое значение соответствовало.
Как обрабатываются массивы объектов? Массив объектов объединяется в единую структуру, которая включает в себя каждый ключ, который есть у любого элемента. Если два элемента дают один и тот же ключ несовместимых типов, это поле становится интерфейсом{}, поэтому структура по-прежнему покрывает весь массив.
Что происходит с нулевыми значениями? Нуль JSON не дает информации о типе сам по себе, поэтому поле набирается как интерфейс{}. Если вы знаете реальный тип, измените его в редакторе после вставки или предоставьте ненулевое значение примера в JSON, чтобы этот тип можно было вывести.
мой json где-нибудь загружен? Нет. Преобразование происходит полностью в вашем браузере с использованием JavaScript на вашем устройстве. Ваш JSON никогда не загружается, не регистрируется и не сохраняется, и инструмент продолжает работать с отключенной сетью после загрузки страницы.
Бесплатен ли преобразователь структуры JSON в Go? Да. Это совершенно бесплатно без регистрации, водяных знаков и ограничений использования. Преобразуйте столько документов JSON в структуры Go, сколько вам нужно для личных или коммерческих проектов.
