Инструменты разработчика · JSON форматировщик и валидатор
Почему последовательный отступ JSON делает ваши различия git читабельными
· Почему это важно
JSON рабочий процесс разработчика проверка
Если два инструмента расходятся во мнениях по поводу отступов, каждый файл JSON в репозитории отображается как измененный. В этом посте объясняется, почему согласованность отступов важна для проверки, как ее выбрать и как безопасно переформатировать.
Изменено четыреста строк, отредактировано одно значение.
Изменено четыреста строк, отредактировано одно значение — запрос на включение, который никто не может просмотреть, поскольку редактор переформатировал файл. При построчном дифференцировании изменения отступов рассматриваются как замены, поэтому предполагаемый выступ версии исчезает среди механически измененных строк. Рецензенты либо тратят время на фильтрацию шума, либо одобряют без уверенной проверки семантической правки.
ToolAcre может соответствовать двум, четырем или восьми пробелам или табуляции и может сортировать клавиши, если они выбраны намеренно. Исходные окончания строк не сохраняются, поскольку JSON.stringify выдает новый текст. Командам следует отделить нормализацию всего репозитория от семантического редактирования, если они хотят, чтобы разница при проверке оставалась понятной. Политику форматирования следует выбирать до масштабных переписываний.
Пробелы несущественны для JSON и очень важны для различий.
Пробелы несущественны для JSON и очень важны для diff — почему изменение отступа перезаписывает каждую строку. Синтаксические анализаторы игнорируют пробелы, табуляции и разрывы строк вне строк, но сравнение при управлении версиями начинается с текстовых строк. Изменение двух ведущих пробелов на четыре приводит к изменению почти каждой вложенной строки, хотя результирующая структура данных идентична.
Этот шум имеет последствия, выходящие за рамки эстетики. История обвинений перемещается в коммит нормализации, конфликты слияния увеличиваются в ветвях, использующих предыдущую компоновку, а проверка кода теряет нормальное соотношение сигнал/шум. Стабильное форматирование позволяет редактированию одного значения оставаться изменением в одну строку. Примените нормализацию один раз, сообщите об этом и избегайте смешивания с изменениями функциональной конфигурации. Согласованность на уровне всего репозитория также позволяет рецензентам немедленно распознавать неожиданные выходные данные форматтера и сохранять автоматические сводки изменений, ориентированные на фактические изменения поведения конфигурации.
Два пробела, четыре пробела или табуляция
Два пробела, четыре пробела или табуляция — что используют по умолчанию общие экосистемы и почему выбор имеет меньшее значение, чем его соблюдение. Два пробела сужают глубоко вложенные документы; четыре создают более сильное визуальное разделение; Вкладки позволяют настраивать ширину отображения, но могут плохо взаимодействовать с выравниванием и инструментами, которые автоматически преобразуют их.
Выберите соглашение, уже доминирующее в репозитории, и закодируйте его в Prettier, EditorConfig или инструменте создания, а не полагайтесь на память. Убедитесь, что участники и CI используют совместимые версии. Грамматика JSON принимает каждый вариант, поэтому аргументы об универсальной корректности упускают из виду рабочий момент: детерминированный вывод не позволяет редакторам, генераторам и форматировщикам по очереди перезаписывать один и тот же файл. Закрепление версий форматтера позволяет избежать смещения политики после обновлений.
Окончания строк и завершающие символы новой строки
Окончания строк и конечные символы новой строки — CRLF вместо LF и отсутствующий последний символ новой строки в качестве других источников различий во всем файле. Проверка, настроенная для CRLF, может заменять каждую строку, когда форматтер выдает LF. Разобранный JSON не изменяется, но интерфейсы Git и проверки могут отображать перезапись текста на уровне всего репозитория.
Намеренно установите политику завершения строк с помощью атрибутов репозитория и конфигурации форматера, а затем проверьте ее на платформах, которые используют участники. Сохраните обычную последнюю новую строку, чтобы инструменты командной строки и файлы различий не сообщали неловко последнюю строку. Поскольку инструменты анализа и повторной сериализации генерируют новый текст, сравните полученные соглашения на уровне байтов, прежде чем применять их ко многим файлам. Шестнадцатеричная проверка позволяет отличить изменение конца строки от изменения значения.
Рабочий пример: нормализация JSON репозитория.
Рабочий пример: нормализация JSON репозитория — строго инвентаризируйте файлы JSON, выберите существующее соглашение о двух пробелах и переформатируйте их в специальном изменении. Исключите сгенерированные артефакты, производители которых владеют сериализацией и диалектами, подобными JSON, которые строгий форматировщик не может проанализировать. Запустите тесты до и после, чтобы убедиться, что потребители по-прежнему читают эквивалентные значения.
Объедините или перебазируйте ветки активных функций вокруг окна нормализации, чтобы уменьшить конфликты, а затем задействуйте выбранный форматировщик в CI. Проверка нормализации не должна содержать сортировку ключей или редактирование значений, что упрощает установление структурной эквивалентности. Последующие запросы на включение могут отображать обновление версии зависимости или изменение флага именно в той строке, где это произошло.
Тщательный анализ изменения JSON
Тщательно просмотрите изменение JSON — перед сравнением форматируйте обе версии одинаково, чтобы выделялось только семантическое изменение. Проверьте, не изменился ли порядок массивов, не превратилось ли число в строку и не исчезла ли клавиша, а не переместилась. Кавычки и литеральные типы несут в себе значение, которое нельзя оценить только с помощью отступов.
Избегайте сортировки ключей, если репозиторий явно не считает порядок нерелевантным и не ожидает канонической сортировки. Хотя порядок членов объекта часто не имеет смысла для приложения, изменение порядка расширяет различия и может повлиять на инструменты, сохраняющие порядок вставки. Для политик или манифестов, чувствительных к безопасности, сочетайте текстовую проверку с проверкой схемы и проверкой для конкретного потребителя, а не одобряйте только потому, что форматированная разница невелика.
Что это не распространяется
Чего здесь не касается — упорядочивание ключей и семантическое различие, для которых нужны инструменты, понимающие структуру, а не строки. Два документа могут сериализоваться по-разному при создании эквивалентных объектов, а два одинаково выглядящих значения могут иметь разные последствия в схеме приложения. Форматирование стандартизирует представление, но не определяет семантическую эквивалентность.
Это также не гарантирует сохранение байтов. Повторная сериализация может нормализовать escape-символы и написание чисел, изменить окончания строк и округлить небезопасные целые числа JavaScript. Для сгенерированных файлов может потребоваться точная версия производителя, а подписанные документы нельзя случайно переписывать. Прежде чем применять форматирование для всего репозитория, определите, является ли артефакт исходным, сгенерированным выходным сигналом или данными с канонической подписью.
Вывод: один отступ, принудительное применение досрочно
Вывод: один отступ, принудительно введенный заранее — используйте настройку отступа средства форматирования в соответствии с проектом, а не навязывайте личные предпочтения. Одновременно выровняйте окончания строк и политику окончательного перевода строки, а затем автоматизируйте этот выбор, чтобы каждый редактор и запуск CI создавали стабильный текст. Последовательность защищает качество обзора больше, чем какая-либо конкретная ширина.
Если нормализация необходима, изолируйте ее от семантической работы и объявите об этом активным ветвям. Проверьте повторно сериализованный вывод на наличие больших целых чисел, экранирующих изменений и нежелательной сортировки ключей перед его фиксацией. Как только базовый уровень стабилен, обычные изменения JSON остаются узкими, обвинения остаются полезными, и рецензенты могут сосредоточиться на ценностях и структуре вместо того, чтобы реконструировать намерения из форматирующего шума.