Как записать JSON в файл в 1С: Пошаговое руководство для разработчиков

Современный обмен данными между различными информационными системами практически невозможен без использования формата JSON. В экосистеме 1С:Предприятие работа с этим легковесным форматом стала стандартом де-факто для интеграции с веб-сервисами, мобильными приложениями и внешними API. Однако, несмотря на простоту самой структуры данных, процесс физической записи полученного или сформированного массива в физический файл на диске часто вызывает трудности у начинающих разработчиков. Неправильная настройка кодировки или режима открытия файла может привести к нечитаемым символам или полной потере данных.

Рассмотрим детально алгоритм действий, необходимый для корректного сохранения JSON-структуры. Основной инструмент, который нам потребуется, — это встроенный объект ЗаписьJSON. Он предоставляет гибкие методы для управления процессом сериализации данных. Важно понимать, что запись в файл — это двухэтапный процесс: сначала мы создаем объект записи, привязанный к конкретному файлу, и только затем передаем в него структуру данных. Игнорирование порядка действий или параметров конструктора является частой причиной ошибок FileIsLocked или InvalidEncoding.

В данной статье мы разберем не только базовый синтаксис, но и тонкости работы с различными типами данных внутри JSON. Вы узнаете, как правильно обрабатывать специальные символы, избегать дублирования ключей и обеспечивать кроссплатформенную совместимость создаваемых файлов. Особое внимание уделим вопросам производительности при работе с большими объемами данных, так как некорректная реализация может привести к зависанию клиентского приложения или сервера 1С.

Инициализация объекта записи и выбор кодировки

Первым шагом в процессе сохранения данных является создание экземпляра объекта ЗаписьJSON. Этот объект выступает в роли посредника между структурой данных 1С (массивы, структуры, значения) и текстовым представлением в файле. Критически важным моментом здесь является выбор правильной кодировки текста. По умолчанию многие текстовые редакторы и операционные системы ожидают формат UTF-8, особенно если в данных присутствуют кириллические символы или спецзнаки.

Если вы проигнорируете параметр кодировки при конструировании объекта, система может использовать кодировку по умолчанию операционной системы, что часто приводит к появлению «кракозябр» вместо русского текста. Для гарантированной совместимости с веб-стандартами всегда явно указывайте кодировку КодировкаТекста.UTF8. Это обеспечит корректное отображение данных в браузерах, мобильных приложениях и на сторонних серверах.

⚠️ Внимание: При записи в сетевую папку убедитесь, что у пользователя, от имени которого запущен процесс 1С, есть права на создание файлов в целевой директории. Ошибка доступа к файлу прервет выполнение кода без сохранения части данных.

Синтаксис создания объекта довольно прост, но требует внимательности к порядку аргументов. Первый аргумент — это имя файла (строка или объект ИмяФайла), второй — режим использования (перезапись или добавление), и третий — кодировка. Для создания нового файла с нуля используется режим РежимИспользованияФайла.Перезаписать. Вот как это выглядит в коде:

ИмяФайлаДляЗаписи = "C:\Data\export.json";
Запись = Новый ЗаписьJSON(ИмяФайлаДляЗаписи, , КодировкаТекста.UTF8);

Обратите внимание на второй параметр в конструкторе — он оставлен пустым (запятая стоит, но значение не передано), что означает использование режима по умолчанию, однако явное указание режима повышает читаемость кода. После инициализации объект готов к приему данных, но файл на диске еще не создан физически до момента первой записи или закрытия объекта.

Формирование структуры данных перед записью

Прежде чем передать данные в объект записи, их необходимо корректно сформировать в памяти 1С. Формат JSON поддерживает несколько основных типов узлов: объекты (соответствуют Структура или Соответствие в 1С), массивы (Массив), строки, числа, булевы значения и null. Ошибки чаще всего возникают при попытке записать специфические типы 1С, такие как Дата или УникальныйИдентификатор, без предварительного преобразования.

Объект ЗаписьJSON умеет автоматически сериализовать многие типы, но для сложных случаев лучше подготовить данные вручную. Например, даты в JSON обычно представляются в строковом формате ISO 8601. Если вы передадите дату как есть, она может быть записана в локальном формате, который не поймет иностранный партнер. Рекомендуется явно конвертировать даты в строки перед добавлением в структуру.

Рассмотрим пример создания сложной вложенной структуры, которая часто требуется для отправки заказов или документов во внешние системы. Мы используем Структура для объектов и Массив для списков товаров.

Данные = Новый Структура();
Данные.Вставить("Версия", "1.0");
Данные.Вставить("ДатаСоздания", Формат(ТекущаяДата(), "ДФ='yyyy-MM-dd'T'HH:mm:ss'"));

СписокТоваров = Новый Массив;
Элемент1 = Новый Структура("Артикул, Название, Цена", "A001", "Ноутбук", 50000);
Элемент2 = Новый Структура("Артикул, Название, Цена", "B002", "Мышь", 1500);

СписокТоваров.Добавить(Элемент1);
СписокТоваров.Добавить(Элемент2);
Данные.Вставить("Товары", СписокТоваров);

Старайтесь использовать латиницу для имен полей, так как это общепринятый стандарт в веб-разработке. Использование кириллицы в именах ключей (Название вместо Name) допустимо технически, но может вызвать проблемы парсинга на стороне принимающей системы, если она не настроена на UTF-8 корректно.

Процесс записи и настройка форматирования

После того как объект ЗаписьJSON создан, а данные сформированы, наступает этап непосредственной записи. Метод ЗаписатьЗначение() является основным инструментом для этого. Он принимает значение любого типа, поддерживаемого платформой, и преобразует его в текстовое представление JSON. Однако, чтобы файл был читаемым человеком (не в одну длинную строку), необходимо настроить параметры форматирования.

Объект ЗаписьJSON имеет свойство Форматировать. Если установить его в значение Истина, то в файл будут добавляться отступы и переносы строк, что значительно упрощает отладку и визуальный анализ содержимого. Для продакшн-среды, где важен каждый байт трафика, иногда используют сжатый формат (без отступов), но для логов и промежуточных файлов лучше включать форматирование.

Процесс записи выглядит следующим образом:

Запись.Форматировать = Истина;
Запись.ЗаписатьЗначение(Данные);
Запись.Закрыть();

Крайне важно не забыть вызвать метод Закрыть() в конце работы. Пока объект записи открыт, файл остается заблокированным для других процессов. Вызов метода закрытия гарантирует, что все буферы сброшены на диск и файл освобожден. Если этого не сделать, попытка открыть этот же файл в другом месте (например, в блокноте или другой обработке) приведет к ошибке доступа.

⚠️ Внимание: Никогда не используйте один и тот же экземпляр ЗаписьJSON для записи нескольких независимых документов в один файл без разделителей. Это создаст невалидный JSON, который невозможно будет распарсить стандартными средствами.

Если вам нужно записать несколько объектов в один файл (например, поток данных NDJSON), каждый объект должен быть записан отдельным вызовом ЗаписатьЗначение, но тогда форматирование лучше отключить, чтобы каждый объект занимал одну строку. В стандартном же случае один вызов ЗаписатьЗначение соответствует одному корневому элементу JSON.

Обработка ошибок и исключительных ситуаций

Работа с файловой системой всегда сопряжена с рисками: диск может быть полон, файл может быть открыт другим процессом, путь может быть неверным. В языке 1С для обработки таких ситуаций используется конструкция Попытка..Исключение. Игнорирование потенциальных ошибок может привести к падению всего сеанса пользователя или фоновой задачи.

Особое внимание стоит уделить ситуации, когда путь к файлу содержит несуществующие директории. Объект ЗаписьJSON не создает папки автоматически. Если вы попытаетесь записать файл в C:\Reports\2026\file.json, а папка 2026 не существует, возникнет ошибка. Поэтому перед записью необходимо проверить существование пути и создать его при необходимости.

Пример надежной реализации с обработкой ошибок:

Попытка
ПутьКФайлу = "C:\Export\data.json";
// Проверка и создание папки, если нужно
Если Не ФайлСуществует(ПутьКФайлу) Тогда
СоздатьКаталог(ПолучитьИмяКаталога(ПутьКФайлу));
КонецЕсли;

Запись = Новый ЗаписьJSON(ПутьКФайлу, , КодировкаТекста.UTF8);
Запись.ЗаписатьЗначение(Данные);
Запись.Закрыть();
Сообщить("Файл успешно записан!");
Исключение
Сообщить("Ошибка записи: " + ОписаниеОшибки());
КонецПопытки;

В блоке Исключение можно не только вывести сообщение пользователю, но и записать информацию в журнал регистрации событий 1С. Это позволит администратору системы позже проанализировать причину сбоя, даже если пользователь просто закрыл окно с ошибкой. Использование ЖурналРегистрации является лучшей практикой для фоновых обработок.

Сравнение методов записи: ЗаписьJSON против КонвертерJSON

В платформе 1С существует несколько способов работы с JSON, и начинающие разработчики часто путаются в них. Основное различие заключается между низкоуровневым объектом ЗаписьJSON и высокоуровневым КонвертерJSON. Понимание разницы между ними критично для выбора правильного инструмента под конкретную задачу.

ЗаписьJSON работает по принципу потока (stream). Вы создаете объект, последовательно записываете в него данные и закрываете. Это дает полный контроль над процессом, позволяет записывать данные частями (что важно для огромных файлов) и минимизирует потребление памяти. КонвертерJSON, в свою очередь, работает с готовыми структурами: он берет всю структуру 1С, преобразует её в строку JSON в памяти, и только потом эту строку можно записать в файл.

Ниже приведена таблица, сравнивающая основные характеристики этих подходов:

Характеристика	ЗаписьJSON	КонвертерJSON + ЗаписьТекста
Потребление памяти	Минимальное (потоковая запись)	Высокое (хранение всей строки в памяти)
Скорость работы	Высокая для больших объемов	Средняя (затраты на сборку строки)
Гибкость настройки	Высокая (можно писать частями)	Низкая (все или ничего)
Сложность кода	Средняя (нужно управлять объектом)	Низкая (одна функция)

Для большинства задач интеграции, где объем данных не превышает нескольких мегабайт, разница в производительности незаметна. Однако, если вы выгружаете справочник номенклатуры в 100 000 позиций, использование КонвертерJSON может привести к исчерпанию оперативной памяти сервера. В таких случаях ЗаписьJSON является безальтернативным выбором.

Секрет оптимизации

Если вы используете ЗаписьJSON, старайтесь не создавать временные структуры данных для каждого элемента цикла. Записывайте значения напрямую, если это возможно, чтобы снизить нагрузку на сборщик мусора.

Специфика работы в веб-клиенте и тонком клиенте

Архитектура 1С накладывает определенные ограничения на работу с файловой системой в зависимости от типа клиента. В толстом клиенте код выполняется на локальной машине пользователя, и путь C:\Temp\file.json указывает на локальный диск этого пользователя. В веб-клиенте (браузере) ситуация кардинально иная: код выполняется на сервере 1С.

Если вы запустите код записи файла в веб-клиенте, указав локальный путь, файл будет создан на сервере 1С в папке профиля сервера или в специальной директории временных файлов, а не на компьютере пользователя. Пользователь не увидит этот файл в своем проводнике. Для передачи файла пользователю в веб-клиенте необходимо использовать механизм ПомощникЗагрузкиФайлов или формировать HTTP-ответ, если это веб-сервис.

Для скачивания файла пользователем в браузере алгоритм меняется: сначала мы записываем JSON во временный файл на сервере (или в двоичные данные в памяти), а затем передаем эти данные клиенту для скачивания.

// Пример для веб-клиента: сохранение во временный файл сервера
ИмяВремФайла = ПолучитьИмяВременногоФайла("json");
Запись = Новый ЗаписьJSON(ИмяВремФайла, , КодировкаТекста.UTF8);
Запись.ЗаписатьЗначение(Данные);
Запись.Закрыть();

// Далее файл можно прочитать в ДвоичныеДанные и отдать пользователю
ДвоичныеДанные = Новый ДвоичныеДанные(ИмяВремФайла);
ПомощникЗагрузкиФайлов.ЗагрузитьФайл(ДвоичныеДанные, "export.json");

Такое разделение логики необходимо учитывать при разработке универсальных обработок, которые должны работать и в файловом варианте, и в клиент-серверном. Всегда проверяйте свойство ВебКлиент глобального контекста, чтобы выбрать правильный путь сохранения.

⚠️ Внимание: В облачных версиях 1С (1С:Фреш) доступ к файловой системе сервера строго ограничен. Запись файлов возможна только во временную директорию, которая очищается после завершения сеанса. Не рассчитывайте на сохранение файлов на сервере в облаке.

Часто задаваемые вопросы (FAQ)

Как записать JSON в файл, чтобы он открывался в Excel?

Excel не открывает «чистый» JSON напрямую как таблицу при двойном клике. Вам нужно либо использовать Power Query внутри Excel для импорта JSON файла, либо сохранить данные в формате CSV. Если нужен именно JSON, сохраните его с расширением.json, а в Excel выберите: Данные -> Получить данные -> Из файла -> Из JSON.

Можно ли дописывать данные в существующий JSON файл?

Технически можно открыть файл в режиме добавления, но это нарушит структуру JSON, так как в файле окажется два корневых объекта подряд. Валидный JSON должен иметь только один корневой элемент. Правильный подход: прочитать файл, объединить данные в памяти и перезаписать файл целиком.

Почему русские буквы превращаются в вопросительные знаки?

Это проблема кодировки. Скорее всего, файл сохраняется в ANSI или Windows-1251, а открывается в редакторе, ожидающем UTF-8 (или наоборот). Всегда явно указывайте КодировкаТекста.UTF8 при создании объекта ЗаписьJSON.

Как записать очень большой JSON файл (несколько ГБ)?

Не загружайте все данные в память в одну Структуру. Используйте потоковую запись: создайте ЗаписьJSON, начните запись массива, и в цикле обрабатывайте данные порциями (например, по 1000 строк из БД), записывая каждый элемент массива по очереди, не храня весь массив в переменной 1С.