Работа С JSON В Delphi Через TJSONObject И TJSONArray
JSON давно стал стандартным форматом обмена данными между мобильными приложениями, серверными API и настольными программами. В Delphi для его обработки используется пространство имён System.JSON, включающее классы TJSONValue, TJSONObject, TJSONArray, TJSONPair, а также типы для строк, чисел, логических значений и null.
Объект JSON хранит пары «ключ — значение», поэтому в Delphi ему соответствует TJSONObject. Массив представляет упорядоченную коллекцию элементов и описывается классом TJSONArray. Эти классы подходят для REST-запросов, локальных настроек, сериализации моделей и обмена данными между приложением и веб-сервисом.
При работе с JSON важно учитывать управление памятью, проверку типов и возможное отсутствие полей. Аккуратный разбор входной строки защищает приложение от исключений и делает код одинаково пригодным для Android, iOS, Windows, macOS и Linux.
| Задача | Класс или метод Delphi | Назначение |
|---|---|---|
| Разобрать JSON-объект | TJSONObject.ParseJSONValue |
Преобразование строки в дерево JSON |
| Получить поле | GetValue<T> |
Чтение значения по имени ключа |
| Обработать массив | TJSONArray |
Перебор элементов по индексу |
| Создать объект | TJSONObject.Create |
Формирование JSON программно |
| Добавить свойство | AddPair |
Добавление строки, числа или вложенного значения |
| Преобразовать в строку | ToJSON или ToString |
Подготовка данных для отправки |
Подключение Модуля И Разбор Строки
Для использования стандартных JSON-классов обычно достаточно добавить System.JSON в секцию uses. Разбор выполняется методом TJSONObject.ParseJSONValue, который возвращает объект типа TJSONValue. Поскольку результат может быть объектом, массивом или простым значением, его нужно проверить перед дальнейшей обработкой.
uses
System.SysUtils, System.JSON;
var
Value: TJSONValue;
Root: TJSONObject;
begin
Value := TJSONObject.ParseJSONValue(
'{"name":"Ravil","active":true,"age":35}'
);
try
if Value is TJSONObject then
begin
Root := TJSONObject(Value);
Writeln(Root.GetValue<string>('name'));
end;
finally
Value.Free;
end;
end;
Если строка содержит синтаксическую ошибку, результат разбора может быть nil. Поэтому перед приведением типа желательно убедиться, что значение успешно создано. Для API, где формат ответа заранее известен, можно дополнительно проверять обязательные поля и типы.
Чтение Значений Из TJSONObject
Наиболее удобный способ получить данные — вызвать GetValue<T>. Например, GetValue<string>('name') возвращает строку, а GetValue<Integer>('age') преобразует JSON-число в целое значение. При отсутствии ключа или несовместимом типе такой вызов способен вызвать исключение, поэтому он лучше подходит для проверенных ответов сервера.
var
Name: string;
Age: Integer;
Active: Boolean;
begin
Name := Root.GetValue<string>('name');
Age := Root.GetValue<Integer>('age');
Active := Root.GetValue<Boolean>('active');
end;
Для необязательных параметров полезен вариант с указанием значения по умолчанию либо предварительная проверка через FindValue. В зависимости от версии Delphi доступны перегрузки TryGetValue<T>, позволяющие безопасно определить, найдено ли поле и удалось ли преобразование.
var
Email: string;
begin
if Root.TryGetValue<string>('email', Email) then
Writeln(Email)
else
Writeln('Email отсутствует');
end;
Если требуется получить вложенный объект, путь можно передать в FindValue, например profile.city. После этого результат нужно проверить на nil и привести к TJSONObject. Для значений null полезно учитывать, что JSON null не равен пустой строке и не должен автоматически трактоваться как обычный текст.
Создание JSON-Объекта Программно
Новый объект создаётся через TJSONObject.Create, а свойства добавляются методом AddPair. Для строк используется TJSONString, для чисел — TJSONNumber, для логических значений — TJSONBool. В простых случаях Delphi принимает обычные типы и автоматически формирует соответствующие JSON-узлы.
var
Request: TJSONObject;
begin
Request := TJSONObject.Create;
try
Request.AddPair('login', 'ravil');
Request.AddPair('count', TJSONNumber.Create(3));
Request.AddPair('enabled', TJSONBool.Create(True));
Writeln(Request.ToJSON);
finally
Request.Free;
end;
end;
После вызова AddPair объект обычно становится владельцем добавленного значения. Это особенно важно при создании вложенных структур: переданный TJSONArray или TJSONObject не нужно освобождать отдельно до уничтожения родительского объекта.
Для простых строковых, числовых и логических параметров перегрузки AddPair делают код компактным. Если значение может быть nil, следует явно определить, нужно ли добавить TJSONNull, пропустить поле или записать пустую строку. Такой выбор влияет на поведение серверной части.
Работа С TJSONArray И Вложенными Данными
Массив создаётся через TJSONArray.Create, после чего элементы добавляются методами Add. Элементами могут быть строки, числа, логические значения, объекты и другие массивы. Доступ выполняется по индексу, начиная с нуля, а количество элементов возвращает свойство Count.
var
Items: TJSONArray;
I: Integer;
begin
Items := TJSONArray.Create;
try
Items.Add('Delphi');
Items.Add('Kotlin');
Items.Add('Swift');
for I := 0 to Items.Count - 1 do
Writeln(Items.Items[I].Value);
finally
Items.Free;
end;
end;
Чаще массив содержит объекты, например список товаров или пользователей. В этом случае каждый элемент проверяется как TJSONObject, после чего из него извлекаются поля.
var
User: TJSONObject;
I: Integer;
begin
for I := 0 to Users.Count - 1 do
begin
if Users.Items[I] is TJSONObject then
begin
User := TJSONObject(Users.Items[I]);
Writeln(User.GetValue<string>('name'));
end;
end;
end;
Вложенный массив добавляется в объект под нужным ключом:
Request.AddPair('tags', Items);
После этого результат может выглядеть как {"tags":["Delphi","Kotlin","Swift"]}. Для больших ответов желательно проверять каждый элемент, поскольку один повреждённый или неожиданный узел не должен приводить к неконтролируемому падению приложения.
Формирование Вложенной Структуры Для API
Практический запрос к серверу часто содержит несколько уровней: сведения о клиенте, параметры фильтра и массив записей. Такая структура строится последовательно, начиная с внутренних объектов и массивов.
var
Root, Client: TJSONObject;
Filters, Product: TJSONArray;
begin
Root := TJSONObject.Create;
try
Client := TJSONObject.Create;
Client.AddPair('platform', 'Android');
Client.AddPair('version', '1.0');
Filters := TJSONArray.Create;
Filters.Add('active');
Filters.Add('featured');
Product := TJSONObject.Create;
Product.AddPair('id', TJSONNumber.Create(101));
Product.AddPair('title', 'Пример');
Root.AddPair('client', Client);
Root.AddPair('filters', Filters);
Root.AddPair('products', Product);
Writeln(Root.ToJSON);
finally
Root.Free;
end;
end;
В реальном коде названия полей лучше хранить в понятных константах или выделять построение JSON в отдельный метод. Это уменьшает количество опечаток и упрощает поддержку контрактов REST API. Для сетевых запросов результат ToJSON передаётся в тело HTTP-запроса с заголовком Content-Type: application/json.
Если JSON создаётся на основе классов предметной области, можно использовать сериализацию через REST.Json.Types, REST.JsonReflect или сторонние библиотеки. Однако ручное применение TJSONObject и TJSONArray остаётся удобным, когда структура небольшая, динамическая или должна точно соответствовать формату внешнего сервиса.
Ошибки, Память И Совместимость
Главная типичная ошибка — забыть освободить корневой объект после разбора или построения JSON. Обычно применяется конструкция try...finally, где освобождается именно владелец дерева. Если внутри объекта находятся вложенные элементы, их отдельно освобождать не следует, когда они были добавлены через AddPair или Add.
Нужно различать методы ToString и ToJSON с учётом версии Delphi. В большинстве современных проектов ToJSON явно показывает намерение получить корректное JSON-представление, тогда как ToString также используется для строкового отображения объекта. Перед интеграцией с конкретной версией RTL стоит проверить доступные перегрузки и поведение кодировки.
Для диагностики удобно сохранять исходный ответ сервера и оборачивать разбор в обработчик исключений:
try
Value := TJSONObject.ParseJSONValue(ResponseText);
if Value = nil then
raise Exception.Create('Некорректный JSON');
except
on E: Exception do
Log('Ошибка JSON: ' + E.Message);
end;
Не следует доверять внешним данным: проверяйте наличие полей, допустимые диапазоны чисел и ожидаемые типы. При разработке FireMonkey-приложений такой подход одинаково применим на мобильных и настольных платформах, поскольку System.JSON входит в кроссплатформенную библиотеку Delphi. правильное управление памятью и явная валидация делают обработку JSON предсказуемой при любом источнике данных.