Сериализация и десериализация параметров

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

Сериализация параметров

Сериализация — это процесс преобразования значений параметров маршрута в строку, пригодную для использования в URL. В TanStack Router это реализуется через объект serialize в конфигурации маршрута.

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

import { createRouter, createRouteConfig } from '@tanstack/router';

const routeConfig = createRouteConfig()
  .createRoute({
    path: '/products/:productId',
    serialize: {
      productId: (value) => value.toString(),
    },
  });

В данном примере параметр productId всегда преобразуется в строку перед вставкой в URL. Это важно, так как URL может содержать только текстовые данные, и любые другие типы (числа, объекты, массивы) должны быть приведены к строковому формату.

Особенности сериализации:

  • Числа преобразуются через toString().
  • Булевы значения часто сериализуются как 'true' или 'false'.
  • Сложные объекты рекомендуется сериализовать с помощью JSON.stringify, но с учетом длины URL.

Десериализация параметров

Десериализация — процесс обратный сериализации: строковые данные из URL преобразуются в исходный тип, используемый внутри приложения. Для этого в TanStack Router используется объект deserialize:

const routeConfig = createRouteConfig()
  .createRoute({
    path: '/products/:productId',
    deserialize: {
      productId: (value) => parseInt(value, 10),
    },
  });

Здесь значение productId из URL, которое приходит как строка, преобразуется обратно в число с помощью parseInt.

Рекомендации по десериализации:

  • Всегда проверять корректность данных. Например, parseInt('abc') вернёт NaN.
  • Для булевых параметров использовать явное сравнение: value === 'true'.
  • Для массивов и объектов использовать JSON.parse, но с обработкой исключений на случай некорректного формата.

Сложные типы параметров

TanStack Router поддерживает сериализацию и десериализацию сложных структур, включая объекты и массивы, но для этого необходимо явно описывать правила:

const routeConfig = createRouteConfig()
  .createRoute({
    path: '/filters/:filter',
    serialize: {
      filter: (value) => JSON.stringify(value),
    },
    deserialize: {
      filter: (value) => {
        try {
          return JSON.parse(value);
        } catch {
          return {};
        }
      },
    },
  });

Особенности работы с объектами и массивами:

  • JSON-сериализация позволяет передавать несколько значений через один параметр.
  • Ограничения URL: длина строки и кодировка символов. Символы вроде / и ? необходимо кодировать через encodeURIComponent.
  • Десериализация должна обрабатывать ошибки, чтобы маршрут не ломался при некорректных данных.

Динамические и необязательные параметры

TanStack Router позволяет работать с динамическими и необязательными параметрами. Для них сериализация и десериализация становятся критичными, так как отсутствующее значение не должно приводить к ошибкам:

const routeConfig = createRouteConfig()
  .createRoute({
    path: '/search/:query?',
    serialize: {
      query: (value) => value ?? '',
    },
    deserialize: {
      query: (value) => value || null,
    },
  });

Замечания:

  • Использование ?? и || обеспечивает безопасное преобразование пустых или отсутствующих параметров.
  • Десериализация должна возвращать тип, ожидаемый приложением, например null вместо пустой строки для необязательных параметров.

Универсальный подход к сериализации и десериализации

Для удобства можно создавать универсальные функции:

function serializeParam(value) {
  if (value === null || value === undefined) return '';
  if (typeof value === 'object') return encodeURIComponent(JSON.stringify(value));
  return encodeURIComponent(String(value));
}

function deserializeParam(value) {
  if (!value) return null;
  try {
    const decoded = decodeURIComponent(value);
    return JSON.parse(decoded);
  } catch {
    return decodeURIComponent(value);
  }
}
  • Универсальная сериализация кодирует строки и объекты, предотвращая проблемы с символами в URL.
  • Десериализация безопасно восстанавливает тип данных, даже если формат строки не является JSON.

Итоговые рекомендации

  • Явное определение serialize и deserialize для каждого маршрута повышает надежность приложения.
  • Обработка ошибок при десериализации критична для стабильной работы маршрутов.
  • Использование универсальных функций упрощает поддержку сложных и динамических параметров.
  • Правильная кодировка и декодировка предотвращает баги с символами, недопустимыми в URL.

Система сериализации и десериализации TanStack Router обеспечивает гибкое управление параметрами маршрутов, позволяя безопасно передавать данные различной структуры через URL без потери типизации и с минимальным риском ошибок.

Оглавление