Serde в Rust: как отсутствующее поле JSON незаметно отключало настройки приложения

В Rust есть немало способов выстрелить себе в ногу, даже когда компилятор доволен, тесты проходят, а приложение работает без ошибок. Иногда для этого достаточно одного атрибута, который делает ровно то, что написано в документации.

При разработке NetRuleRouter столкнулся с довольно странным поведением. Две настройки должны были быть включены по умолчанию, но после обмена данными между компонентами приложения оказывались выключенными. При этом JSON успешно обрабатывался, ошибок десериализации не возникало, а подозрительные значения выглядели совершенно допустимыми.

Причина оказалась не в Qt, не в IPC и даже не в ошибке библиотеки. Проблема скрывалась в том, как обычное отсутствие поля превращалось в конкретное значение.

Разобраться помог Serde — один из наиболее распространённых инструментов сериализации в экосистеме Rust. Причём позднее похожая ситуация обнаружилась уже при диагностике сетевых адаптеров, где цена неправильного значения могла быть значительно выше, чем просто сброшенная настройка.


Что такое Serde и где его используют

Serde — фреймворк сериализации и десериализации данных в Rust.

Сериализация преобразует данные программы в представление, которое можно записать в файл или передать другому процессу. Десериализация выполняет обратное преобразование.

Serde используется в самых разных задачах:

  • Чтение и запись конфигурационных файлов в JSON, TOML, YAML и других форматах.

  • Обработка запросов и ответов REST API.

  • Обмен данными между процессами через IPC.

  • Работа с сообщениями в сетевых протоколах.

  • Преобразование структур при хранении и передаче данных.

Простейший пример:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Preferences {
    auto_start: bool,
    language: String,
}

Такую структуру можно сериализовать в JSON:

let prefs = Preferences {
    auto_start: true,
    language: "ru".to_string(),
};

let json = serde_json::to_string(&prefs).unwrap();

Результат:

{"auto_start":true,"language":"ru"}

И восстановить обратно:

let restored: Preferences =
    serde_json::from_str(&json).unwrap();

Для примера потребуются две зависимости:

[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"

Одна из особенностей Serde — разделение описания данных и формата сериализации. Вместо JSON можно использовать другие поддерживаемые форматы, не переписывая структуру и реализации трейтов Serialize и Deserialize.

При этом Serde активно использует систему типов Rust и генерацию кода во время компиляции.

А как в других языках?

Сама задача универсальна. В других языках для сериализации используются свои инструменты.

Язык

Инструмент

Особенность

Rust

Serde + serde_json

Типизированные структуры, трейты и derive

Go

encoding/json

Структуры и нулевые значения типов

Python

json

Обычно словари и списки, без автоматического создания пользовательских объектов

Java

Jackson

Привязка JSON к объектам и настраиваемая обработка полей

Разница особенно заметна при чтении неполных данных.

Например, стандартный encoding/json в Go при декодировании JSON в новую структуру оставляет отсутствующие поля с нулевыми значениями соответствующих типов.

Serde по умолчанию ведёт себя строже: отсутствие обязательного поля обычно приводит к ошибке десериализации.

Чтобы разрешить отсутствие поля, можно использовать:

#[serde(default)]

Но здесь возникает вопрос: какое именно значение должно появиться вместо отсутствующего?

Почему Serde понадобился в NetRuleRouter

NetRuleRouter — открытая утилита для управления маршрутизацией сетевого трафика по правилам.

Основная логика приложения реализована на Rust, графический интерфейс — на Qt/QML. Между компонентами используется IPC, в том числе сообщения в формате JSON.

По мере развития программы в настройках появлялись новые поля, а разные компоненты не всегда одновременно знали обо всех изменениях формата сообщений.

Например, отправитель мог передать JSON старого формата, в котором ещё не существовало новой настройки.

Если поле обязательное, Serde вернёт ошибку. Атрибут #[serde(default)] позволяет обработать такое сообщение, подставив значение по умолчанию.

При этом важно различать две ситуации:

  • Поле отсутствует, хотя структура получателя его ожидает.

  • Поле присутствует, но получатель о нём не знает.

По умолчанию Serde при работе со структурами обычно игнорирует неизвестные поля JSON. При необходимости это поведение можно изменить с помощью deny_unknown_fields.

А вот для отсутствующих ожидаемых полей требуется отдельно определить поведение.

И именно здесь возникла ошибка.

Как отсутствующие поля отключали настройки

В структуре настроек появились два булевых поля:

#[derive(Deserialize)]
struct UiPreferences {
    #[serde(default)]
    auto_load_rules_on_launch: bool,

    #[serde(default)]
    export_include_comments: bool,
}

Первое отвечало за автоматическую загрузку правил при запуске. Второе — за включение комментариев при экспорте.

Оба параметра должны были быть включены по умолчанию.

Но отправитель, не знавший об этих полях, передавал JSON без них.

Получалась следующая последовательность:

Никакой ошибки десериализации не было. Значения успешно подставлялись, но пользовательские настройки фактически оказывались выключенными.

Почему именно false?

#[serde(default)] при отсутствии поля использует Default::default() для типа этого поля.

Для bool это false:

assert_eq!(bool::default(), false);

Для других распространённых типов результат выглядит так:

Тип

Значение Default::default()

bool

false

String

Пустая строка

u32, i32

0

Option<T>

None

Vec<T>

Пустой вектор

Serde не знает, что автоматическая загрузка правил должна быть включена. Для него false — совершенно корректное значение по умолчанию для типа bool.

Но для конкретной настройки приложения правильный дефолт — true.

Значение по умолчанию для типа и значение по умолчанию для настройки — не одно и то же.

Исправление: явные дефолты

Serde позволяет назначить функцию, возвращающую нужное значение при отсутствии поля.

В исправленном варианте это выглядит так:

use serde::Deserialize;

fn default_auto_load_rules() -> bool {
    true
}

fn default_export_comments() -> bool {
    true
}

#[derive(Debug, Deserialize)]
struct UiPreferences {
    #[serde(default = "default_auto_load_rules")]
    auto_load_rules_on_launch: bool,

    #[serde(default = "default_export_comments")]
    export_include_comments: bool,
}

Теперь, если поле отсутствует, используется значение, соответствующее требованиям приложения.

Технически оба случая можно было обработать одной функцией:

fn default_true() -> bool {
    true
}

Но именованные функции удобнее для сопровождения. Например, default_export_comments явно показывает, какая настройка получает значение по умолчанию.

Проверка тестами

Для начала проверяется сообщение, в котором новых полей вообще нет:

#[test]
fn missing_fields_use_expected_defaults() {
    let prefs: UiPreferences =
        serde_json::from_str("{}").unwrap();

    assert!(prefs.auto_load_rules_on_launch);
    assert!(prefs.export_include_comments);
}

Но одного такого теста недостаточно.

Если пользователь явно передал false, Serde должен сохранить это значение:

#[test]
fn explicit_false_is_preserved() {
    let json = r#"{
        "auto_load_rules_on_launch": false,
        "export_include_comments": false
    }"#;

    let prefs: UiPreferences =
        serde_json::from_str(json).unwrap();

    assert!(!prefs.auto_load_rules_on_launch);
    assert!(!prefs.export_include_comments);
}

Таким образом, отсутствующее поле получает нужный дефолт, а явно переданное значение не изменяется.

Стоит учитывать ещё одну особенность: #[serde(default)] влияет на десериализацию, а не на сериализацию. Сам по себе он не заставляет Serde пропускать поля, равные значению по умолчанию, при формировании JSON.

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

Позднее при работе над NetRuleRouter возникла похожая задача, но уже связанная с диагностикой сетевых адаптеров.

Понадобилось передавать из службы в графический интерфейс признак has_forwarding_path — есть ли через выбранный адаптер путь для передачи трафика.

Это позволяет, например, отличать виртуальный host‑only адаптер от VPN‑туннеля, у которого нет обычного шлюза.

Первоначально напрашивался простой вариант:

#[serde(default)]
has_forwarding_path: bool,

Но возник вопрос: что произойдёт, если поле не пришло?

Предположим, используется старая версия компонента, которая ещё не передаёт этот признак. Или результат проверки маршрутов оказался недоступен.

Serde подставит false.

Графический интерфейс может интерпретировать его как подтверждение отсутствия пути и показать предупреждение о проблеме с адаптером.

Хотя на самом деле проверка могла вообще не выполняться.

Здесь выяснилось, что у признака не два, а три возможных состояния:

Значение

Смысл

Some(true)

Проверка подтвердила наличие пути

Some(false)

Проверка подтвердила отсутствие пути

None

Результат неизвестен

Поэтому вместо bool был выбран:

has_forwarding_path: Option<bool>,

Для Serde поле типа Option<bool> может отсутствовать в JSON — тогда оно получит None. Явное значение null тоже будет преобразовано в None.

Если приложению потребуется различать отсутствие поля и явный null, понадобится более подробная модель данных.

В данном случае достаточно трёх состояний: путь есть, пути нет, результат неизвестен.

Небольшой тест демонстрирует нужное поведение:

#[derive(Debug, serde::Deserialize)]
struct AdapterStatus {
    has_forwarding_path: Option<bool>,
}

#[test]
fn missing_path_is_not_a_negative_result() {
    let status: AdapterStatus =
        serde_json::from_str("{}").unwrap();

    assert_eq!(status.has_forwarding_path, None);
}

Теперь графический интерфейс может показывать предупреждение только при Some(false).

Если результат неизвестен, оснований утверждать, что маршрут отсутствует, нет.

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

Почему не использовать Option везде?

Казалось бы, можно просто заменить все булевы поля на Option<bool>.

Но это лишь перенесёт принятие решения в другое место.

Для настройки автоматической загрузки правил есть два состояния: включено и выключено. Если поле отсутствует в старом сообщении, приложение должно использовать заранее установленный дефолт.

А для результата диагностики отсутствие значения само по себе имеет смысл.

Поэтому правильный выбор зависит от предметной области.

Не всякое отсутствующее значение означает false, 0 или пустую строку. Иногда отсутствие данных — отдельное состояние, которое нужно явно сохранить.

Что в итоге

После первого случая я стал внимательнее относиться к значениям по умолчанию при десериализации.

Второй напомнил, что иногда проблему нужно исправлять не значением, а самим типом.

При добавлении новых полей в JSON‑контракт полезно проверять три вещи:

  1. Что произойдёт, если старый отправитель не передаст поле?

  2. Совпадает ли Default::default() с предполагаемым поведением приложения?

  3. Не теряется ли важное состояние при выборе типа данных?

Для таких случаев полезно иметь отдельные тесты на отсутствие новых полей и на сохранение явно переданных значений.

В конечном счёте #[serde(default)] выполнял свою работу правильно. Ошибка заключалась в предположении, что стандартное значение типа автоматически соответствует требованиям приложения.

Значение по умолчанию — часть контракта приложения, а не просто свойство типа.


А стоит ли продолжать?

В процессе разработки NetRuleRouter и других приложений на Rust накопилось немало подобных историй — от небольших ловушек типов и сериализации до взаимодействия с Windows API, Linux, IPC и сетевыми механизмами.

Думаю периодически делиться такими случаями: что не работало, почему, какие варианты решения рассматривались и что в итоге помогло.

Интересен ли такой формат практических заметок по Rust? И какие темы хотелось бы увидеть в первую очередь: особенности самого языка, разработку десктопных приложений или системное и сетевое программирование?

Будет интересно почитать и о похожем опыте других разработчиков.


Ссылки:

Комментарии (10)


  1. Dhwtj
    15.11.2026 15:13

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

    Лучше так

    fn parse(json: &str) -> Result<Preferences, serde_json::Error> {
        // v2 — текущая
        if let Ok(v) = serde_json::from_str::<PreferencesV2>(json) {
            return Ok(v.into());
        }
        // v1 — легаси
        serde_json::from_str::<PreferencesV1>(json).map(Preferences::from)
    }

    А ещё лучше в явном виде в JSON

    #[derive(Deserialize)]
    struct Envelope {
        version: u32,
        #[serde(flatten)]
        body: serde_json::Value,
    }

    И в итоге реализация станет такой

    use serde::{Deserialize, Serialize};
    use thiserror::Error;
    
    const CURRENT_VERSION: u32 = 3;
    const FIRST_SUPPORTED_VERSION: u32 = 1;
    
    #[derive(Error, Debug)]
    enum PrefsError {
        #[error("ожидался объект с полем `version`: {0}")]
        Envelope(#[from] serde_json::Error),
    
        #[error("тело формата v{version} не разобрано: {source}")]
        Body { version: u32, #[source] source: serde_json::Error },
    
        #[error("файл создан более новой версией (формат v{got}, поддерживается до v{known}); обновите приложение")]
        TooNew { got: u32, known: u32 },
    
        #[error("версия формата v{got} не поддерживается (минимальная: v{first})")]
        Unsupported { got: u32, first: u32 },
    }
    
    // --- версии формата --------------------------------------------------------
    
    /// v1: изначальный формат
    #[derive(Deserialize)]
    struct PrefsV1 { theme: String }
    
    /// v2: добавили язык
    #[derive(Deserialize)]
    struct PrefsV2 { theme: String, language: String }
    
    /// v3 (текущая): добавили акцентный цвет
    #[derive(Deserialize)]
    struct PrefsV3 { theme: String, language: String, accent: String }
    
    /// доменная структура — единственная, с которой живёт остальной код
    struct Preferences { theme: String, language: String, accent: String }
    
    // --- явные миграции: каждая имеет имя, комментарий и свой тест --------------
    
    impl PrefsV1 {
        /// v1 -> v2: язык отсутствовал, все считались англоязычными.
        fn into_v2(self) -> PrefsV2 {
            PrefsV2 { theme: self.theme, language: "en".into() }
        }
    }
    impl PrefsV2 {
        /// v2 -> v3: акцентного цвета не было — стандартный синий.
        fn into_v3(self) -> PrefsV3 {
            PrefsV3 { theme: self.theme, language: self.language, accent: "#0066cc".into() }
        }
    }
    impl From<PrefsV3> for Preferences {
        fn from(v: PrefsV3) -> Self {
            Self { theme: v.theme, language: v.language, accent: v.accent }
        }
    }
    
    // --- чтение ------------------------------------------------------------------
    
    #[derive(Deserialize)]
    struct Envelope {
        version: u32,
        #[serde(flatten)]
        body: serde_json::Value,
    }
    
    fn parse(json: &str) -> Result<Preferences, PrefsError> {
        let env: Envelope = serde_json::from_str(json)?; // нет `version` -> Envelope-ошибка
    
        match env.version {
            1 => Ok(serde_json::from_value::<PrefsV1>(env.body)
                .map_err(|e| PrefsError::Body { version: 1, source: e })?
                .into_v2().into_v3().into()),
            2 => Ok(serde_json::from_value::<PrefsV2>(env.body)
                .map_err(|e| PrefsError::Body { version: 2, source: e })?
                .into_v3().into()),
            CURRENT_VERSION => serde_json::from_value::<PrefsV3>(env.body)
                .map_err(|e| PrefsError::Body { version: CURRENT_VERSION, source: e })
                .map(Into::into),
            v if v > CURRENT_VERSION => Err(PrefsError::TooNew { got: v, known: CURRENT_VERSION }),
            v => Err(PrefsError::Unsupported { got: v, first: FIRST_SUPPORTED_VERSION }),
        }
    }


    1. krox Автор
      15.11.2026 15:13

      Согласен, отсутствие поля действительно может быть следствием различий между версиями контракта. Но не каждое добавление необязательного поля требует отдельной версии API и полноценной миграции.

      Если семантика отсутствующего поля заранее определена, дефолт вполне может быть частью контракта обратной совместимости. В описанном случае ошибка была именно в выборе значения: Default::default() для bool возвращал false, хотя по логике приложения требовался true.

      А во втором примере с Option<bool> как раз выяснилось, что никакой булевый дефолт не подходит, поскольку «не проверяли» и «проверили, результата нет» — разные состояния.

      Для более серьёзных изменений формата явное версионирование, конечно, предпочтительнее.


      1. Dhwtj
        15.11.2026 15:13

        Но не каждое добавление необязательного поля требует отдельной версии API и полноценной миграции.

        Кроилово ведёт к попадалову


  1. Free_ze
    15.11.2026 15:13

    В Rust есть немало способов выстрелить себе в ногу, даже когда компилятор доволен, тесты проходят, а приложение работает без ошибок.

    Serde кидался явными ошибками, но упорный программист незаметно написал #[serde(default)] и переменная получила дефолтное значение.

    мем про интеграцию палки в колесо


    1. krox Автор
      15.11.2026 15:13

      Справедливое замечание. Serde здесь действительно ни при чём — #[serde(default)] был добавлен сознательно, чтобы принимать сообщения без новых полей. Ошибка заключалась в том, что стандартное false не соответствовало ожидаемому поведению настроек.

      Пожалуй, во вступлении стоило точнее сформулировать проблему: не Serde незаметно сделал что-то неправильное, а я неверно определил контракт отсутствующих полей. Именно этот случай и хотел разобрать.


  1. MaximianQaAuto
    15.11.2026 15:13

    Тесты «пустой JSON» и «явный false» хорошие, но оба написаны по текущей структуре — их автор уже знает про новые поля. Ошибку из статьи надёжнее ловит набор настоящих сообщений, записанных от прошлых версий отправителя: положить пару JSON от каждой выпущенной версии в фикстуры и проверять, что новый получатель восстанавливает из них те же настройки, что видел пользователь. Тогда следующий #[serde(default)] с неудачным дефолтом упадёт в CI, даже если про новое поле забыли написать отдельный тест. Вы храните образцы сообщений старых версий или совместимость проверяется только руками при релизе?


    1. krox Автор
      15.11.2026 15:13

      Спасибо за предложение. Согласен, фикстуры с реальными сообщениями предыдущих релизов позволят надёжнее проверять обратную совместимость.

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

      В проекте уже есть автоматизированные тесты контрактов, но идея дополнить их историческими сообщениями с проверкой ожидаемого результата определённо заслуживает внимания. Особенно с учётом дальнейшего развития IPC и внешних API.


      1. MaximianQaAuto
        15.11.2026 15:13

        Да, именно значения, иначе тест подтвердит только то, что JSON распарсился. Я бы и ожидаемое брал не из головы, а из старой версии: один раз прогнать сообщение через получателя того релиза, сохранить, какие настройки он восстановил, и положить рядом с фикстурой. Тогда в ожидании нет знаний о новых полях, и неудачный дефолт его не обманет. Спасибо за статью и разговор!


        1. krox Автор
          15.11.2026 15:13

          Спасибо за идею! Сохранять не только исторические сообщения, но и результат их обработки старым получателем — действительно хороший подход.

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

          Думаю, оба подхода стоит сочетать. Как раз сейчас пересматриваю тестирование совместимости IPC в проекте с учётом обсуждения. Спасибо за конструктивную обратную связь!


          1. MaximianQaAuto
            15.11.2026 15:13

            Да, для новых полей ожидание пишет человек, и его как раз стоит сверять с решением о миграции, а не с тем, что код сейчас делает. Получается два слоя: старое восстанавливается как раньше, новое — как договорились. Удачи с пересмотром тестов.