Gson для Java: полное руководство с примерами

Что такое Gson и зачем он нужен?

Gson — это мощная библиотека для языка Java, разработанная компанией Google, которая позволяет преобразовывать объекты Java в их JSON-представление (сериализация) и, наоборот, восстанавливать Java-объекты из JSON-строк (десериализация). JSON (JavaScript Object Notation) — это легковесный формат обмена данными, который широко используется в веб-API, конфигурационных файлах и для хранения структурированных данных.

Зачем использовать Gson? В современной разработке Java-приложений практически ни один проект не обходится без работы с JSON. Будь то общение с REST API, чтение конфигураций или обмен данными между микросервисами — Gson предоставляет простой, быстрый и надежный способ конвертации. В отличие от стандартной библиотеки Java (org.json), Gson умеет работать напрямую с произвольными Java-объектами (POJO), автоматически сопоставляя поля класса с ключами JSON. Это избавляет разработчика от ручного парсинга и написания шаблонного кода.

Установка Gson

Gson — это Java-библиотека, поэтому она распространяется через системы управления зависимостями для JVM. Ниже приведены способы установки для самых популярных инструментов сборки.

Maven

Добавьте следующую зависимость в ваш файл pom.xml:

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version> <!-- Проверьте актуальную версию на Maven Central -->
</dependency>

Gradle

Добавьте в файл build.gradle:

implementation 'com.google.code.gson:gson:2.10.1'

Прямая загрузка JAR

Если вы не используете системы сборки, скачайте JAR-файл с Maven Central и добавьте его в classpath вашего проекта.

Важно: В отличие от Python (pip) или Node.js (npm), в Java нет единого менеджера пакетов. Maven и Gradle — это стандарт де-факто.

Быстрый старт: первый пример

Давайте создадим простой класс Person и сериализуем его в JSON, а затем десериализуем обратно.

import com.google.gson.Gson;

public class QuickStart {
    public static void main(String[] args) {
        // 1. Создаем объект
        Person person = new Person("Иван", 30, "ivan@example.com");

        // 2. Создаем экземпляр Gson
        Gson gson = new Gson();

        // 3. Сериализация (Java -> JSON)
        String json = gson.toJson(person);
        System.out.println("JSON: " + json);
        // Вывод: JSON: {"name":"Иван","age":30,"email":"ivan@example.com"}

        // 4. Десериализация (JSON -> Java)
        String jsonInput = "{\"name\":\"Мария\",\"age\":25,\"email\":\"maria@test.com\"}";
        Person personFromJson = gson.fromJson(jsonInput, Person.class);
        System.out.println("Имя: " + personFromJson.getName());
        // Вывод: Имя: Мария
    }
}

class Person {
    private String name;
    private int age;
    private String email;

    // Обязательно нужен конструктор по умолчанию (без аргументов) для десериализации!
    public Person() {}

    public Person(String name, int age, String email) {
        this.name = name;
        this.age = age;
        this.email = email;
    }

    public String getName() { return name; }
    public int getAge() { return age; }
    public String getEmail() { return email; }
}

Основные методы и функции Gson

Ниже представлены ключевые методы библиотеки Gson. Каждый метод сопровождается описанием и рабочим примером.

1. Gson.toJson(Object src)

Что делает: Сериализует переданный Java-объект в строку JSON. Это самый основной метод для преобразования объекта в JSON.

Параметры: src — объект для сериализации (может быть null).

Пример:

Gson gson = new Gson();
Map<String, Object> map = new HashMap<>();
map.put("key1", "value1");
map.put("key2", 123);
String json = gson.toJson(map);
System.out.println(json); // {"key1":"value1","key2":123}

2. Gson.fromJson(String json, Class<T> classOfT)

Что делает: Десериализует JSON-строку в объект указанного класса. Поля JSON автоматически сопоставляются с полями класса (по именам).

Параметры: json — строка JSON; classOfT — класс, в который нужно преобразовать JSON.

Пример:

Gson gson = new Gson();
String json = "{\"name\":\"Тест\",\"value\":42}";
Map map = gson.fromJson(json, Map.class);
System.out.println(map.get("name")); // Тест

3. Gson.toJson(Object src, Appendable writer)

Что делает: Сериализует объект и записывает результат напрямую в поток вывода (например, в файл или сетевой сокет). Это эффективнее, чем получать строку и потом записывать её.

Параметры: src — объект; writer — объект, реализующий интерфейс Appendable (например, FileWriter, StringWriter).

Пример:

Gson gson = new Gson();
try (FileWriter writer = new FileWriter("output.json")) {
    Person person = new Person("Петр", 28, "petr@mail.ru");
    gson.toJson(person, writer);
    System.out.println("JSON записан в файл.");
} catch (IOException e) {
    e.printStackTrace();
}

4. Gson.fromJson(Reader json, Class<T> classOfT)

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

Параметры: json — объект Reader (например, FileReader); classOfT — целевой класс.

Пример:

Gson gson = new Gson();
try (FileReader reader = new FileReader("input.json")) {
    Person person = gson.fromJson(reader, Person.class);
    System.out.println("Прочитан: " + person.getName());
} catch (IOException e) {
    e.printStackTrace();
}

5. GsonBuilder.setPrettyPrinting()

Что делает: Включает форматированный вывод JSON с отступами (pretty printing). По умолчанию Gson выводит JSON в одну строку.

Параметры: Нет. Возвращает GsonBuilder для цепочки вызовов.

Пример:

Gson gson = new GsonBuilder().setPrettyPrinting().create();
Person person = new Person("Анна", 22, "anna@test.com");
String prettyJson = gson.toJson(person);
System.out.println(prettyJson);
// Вывод:
// {
//   "name": "Анна",
//   "age": 22,
//   "email": "anna@test.com"
// }

6. GsonBuilder.excludeFieldsWithoutExposeAnnotation()

Что делает: Заставляет Gson сериализовать/десериализовать только те поля, которые помечены аннотацией @Expose. Это позволяет гибко управлять тем, какие поля попадают в JSON.

Параметры: Нет.

Пример:

import com.google.gson.annotations.Expose;

class User {
    @Expose
    private String username;
    @Expose
    private String password; // Внимание: так делать не стоит!
    private transient int internalId; // Не будет в JSON
}

Gson gson = new GsonBuilder()
    .excludeFieldsWithoutExposeAnnotation()
    .create();
User user = new User();
String json = gson.toJson(user); // Содержит только username и password

7. GsonBuilder.registerTypeAdapter(Class type, Object typeAdapter)

Что делает: Регистрирует пользовательский адаптер для сериализации/десериализации конкретного типа. Используется, когда нужно изменить стандартное поведение (например, для работы с датами в нестандартном формате).

Параметры: type — класс, для которого регистрируется адаптер; typeAdapter — экземпляр JsonSerializer<T>, JsonDeserializer<T> или TypeAdapter<T>.

Пример:

GsonBuilder builder = new GsonBuilder();
builder.registerTypeAdapter(Date.class, new JsonDeserializer<Date>() {
    @Override
    public Date deserialize(JsonElement json, Type typeOfT, JsonDeserializationContext context) throws JsonParseException {
        return new Date(json.getAsLong()); // Предполагаем, что дата в JSON — это timestamp
    }
});
Gson gson = builder.create();

8. GsonBuilder.setDateFormat(String pattern)

Что делает: Устанавливает глобальный формат даты для всех полей типа Date. Это гораздо проще, чем писать кастомный адаптер для стандартного случая.

Параметры: pattern — строка формата даты (например, "yyyy-MM-dd").

Пример:

Gson gson = new GsonBuilder()
    .setDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'")
    .create();
// Теперь все Date поля будут сериализоваться в ISO 8601 формат

9. GsonBuilder.serializeNulls()

Что делает: По умолчанию Gson пропускает поля со значением null при сериализации. Этот метод включает запись null в JSON.

Параметры: Нет.

Пример:

Gson gson = new GsonBuilder().serializeNulls().create();
String json = gson.toJson(null);
System.out.println(json); // Выведет: null (без этого метода было бы пусто)

10. GsonBuilder.setLenient()

Что делает: Включает "снисходительный" режим парсинга JSON. В этом режиме Gson будет пытаться игнорировать некоторые нестрогие ошибки формата (например, комментарии в JSON, что запрещено стандартом). Используйте с осторожностью.

Параметры: Нет.

Пример:

Gson gson = new GsonBuilder().setLenient().create();
// Позволяет парсить некорректный JSON, например с однострочными комментариями

Реальный практический пример: Работа с REST API

Предположим, мы пишем клиент для сервиса погоды. Сервер возвращает JSON в таком формате:

{
  "location": "Москва",
  "temperature": 22.5,
  "humidity": 65,
  "forecast": [
    {"day": "Пн", "temp": 20},
    {"day": "Вт", "temp": 23}
  ]
}

Создадим Java-классы, отражающие эту структуру, и используем Gson для десериализации.

import com.google.gson.G