Давай заключим контракт?

Принципы SOLID, DRY, KISS во фронтенде работают ровно так же, как в любой другой разработке. Но если открыть почти любой проект, всё равно натыкаешься на мешанину.

Причём дело обычно не в том, что код «грязный» — он как раз бывает аккуратно типизирован и проходит linter. Дело в том, что эти принципы отвечают на вопрос «как написать», а не «зачем мы вообще это пишем». А без ответа на «зачем» чистый код превращается в красиво оформленную путаницу.

Быстрее всего это бьёт по store. Причина проста: чаще всего плохо понимают, зачем стор вообще нужен. А с приходом Pinia на смену Vuex непонимание усугубилось — инструмент дал полную свободу и убрал ограничения, которые раньше хоть как-то держали разработчика в рамках.

С чего начнем?

В момент, когда мы себя спрашиваем: “А хороший ли у меня store?” в основном начинается проверка совсем не тех вещей. В основном мы смотрим на методы, их типизацию, нет ли дублирования, проходит ли linter… Это всё, разумеется, делать нужно. Только за этими проверками теряется основная сущность, зачем этот стор был вообще придуман.

Сама по себе концепция store – это идея того, что у нас существует сущность, при обращении к которой другие элементы проекта (вроде компонентов, composable и других сторов) получают определенную информацию. Store не вещь в себе, его единственная цель — обслуживать потребителей.

И можно сказать главная идея любого store – это некоторое обещание, контракт. Не просто список ref-ов, не просто данные, которые существуют внутри, а некоторая гарантия того, что именно и в какой форме другие элементы могут получить от этого store.

Хороший store не тот, у которого красивый и чистый код внутри (это всё про внутреннее устройство). Хороший store тот, на чей контракт можно опереться, не заглядывая вовнутрь и не изучая его поведение на реализации в разных местах.

Это абстрактное вступление, поэтому давайте сразу попробуем перейти в реалии кода.

Вот вам пример стора, который намеренно ухудшен, однако его проявления я в том или ином виде встречала в разных живых проектах:

export const useTokensStore = defineStore('tokens', () => {
  const router = useRouter()

  // тут лежит всё сразу: и то, что пришло с бэка, и то, что докрутили руками
  const items = ref<Record<string, any>>({})
  const isLoading = ref(false)
  const lastError = ref(null)          // вдруг где-нибудь пригодится
  const filters = ref({ name: null, is_static: null })

  // "реактивно" достаём активный тип... ага
  const activeType = computed(() => localStorage.getItem('activeType'))

  const currentToken = computed(() => {
    if (!activeType.value) return null
    return items.value[activeType.value]
  })

  // на каждый чих пишем в localStorage
  watch(items, (val) => {
    localStorage.setItem('items', JSON.stringify(val))
  }, { deep: true })

  async function load() {
    isLoading.value = true
    const { data } = await instance.get('access-tokens')
    // нормализуем прямо тут: часть полей сырые, часть — уже под таблицу
    items.value = data.data.reduce((acc, item) => {
      acc[item.type_id] = {
        ...item,                                  // сырьё с бэка как есть
        is_static: item.is_static ? 'Да' : 'Нет', // boolean → строка для UI
        label: item.name ?? 'Без названия',
      }
      return acc
    }, {})
    router.replace({ query: { type: activeType.value } }) // заодно перепишем URL
    isLoading.value = false
  }

  return { items, isLoading, lastError, filters, activeType, currentToken, load }
})

Как вы видите, в этом примере store – типизирован — items имеет некоторый тип, методы возвращают значения. Код наверняка пройдёт linter, потому что нет не используемых импортов/кривого форматирования. По формальным меркам “чистоты кода” – не докопаешься.

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

Store ничего не обещает

Давайте взглянем на тип: Record<string, any>. Формально можно сказать: “Ну тут лежит что угодно под любым ключом”.

Представьте себя на месте разработчика, которому нужно было подключить этот стор для чего угодно. Достать оттуда currentToken, например. У вас сразу понесутся мысли в голове:

Что за поля у этого токена? Какого они типа? label здесь вообще приходит? А типа он какого, если он вообще бывает? А может не быть? is_static – это вообще что и откуда оно приходит?

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

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

Главная ошибка – это наивно полагать, что типизация в целом является контрактом. Но это не так. Типизация описывает форму переменных и функций: “Здесь лежит объект, у него такие-то поля”.

А контракт описывает обязательства модуля: “Я обещаю отдавать токены вот в такой форме, и за это отвечаю”.

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

Я ж зиллениал, так что давайте на примере кофе

Вот пришли вы в кофейню, попить любимую капучинку на альтернативном. Выбираете себе из списка кофе, даже выбрали не арабику, а колумбию. Ждёте заказ. А бариста вам вместо желаемого напитка приносит вам раздельно зерна, стакан воды и молоко. Формально же вы кофе получили? Ну и что, что он в зёрнах!

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

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

Вам не надо думать, как это использовать

Хороший стор работает по принципу хорошей кофейни. Вы пришли, назвали напиток и получили именно то, что ожидали. Компонент "заказывает" currentToken и получает его в понятной, обещанной форме. Как стор его собрал, откуда достал, что нормализовал – компонента вообще не касается.

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

Пишем обещание

Начинается самое интересное, потому что всякий контракт можно сформулировать с разной степенью честности. Давайте пройдем разные этапы — от "я вообще ни за что не отвечаю", до "Вот как я работаю и я прослежу, чтобы оно так было и дальше".

Первое, за что нужно взяться, это any. У нас сейчас это выглядит так:

const items = ref<Record<string, any>>({})

const token = items.value['abc']
token.lable.toUpperCase()   // опечатка в 'label'? ничего не произойдет
token.whatever.foo.bar      // выдуманные поля? то же самое — упадёт в рантайме

Если вы используете TypeScript то про any вам следует вообще забыть (ну или использовать там, где нет продуктового кода). если вы пишете ref<...> , то получается так, что компилятор в целом не будет проверять, что там лежит, хотя формально типизацию вы описали. Любая опечатка или несуществующее поле дойдут до пользователя и сломают работу только на проде.

Мы пробуем избавиться от этого и пишем Record<string, unknown>. Уже лучше:

const items = ref<Record<string, unknown>>({})

const token = items.value['abc']
token.label   // ❌ Object is of type 'unknown' — компилятор не даёт трогать поля

unknown в отличие от any по крайней мере заставляет сузить тип прежде, чем что-то с ним сделать. То есть компилятор больше молчать не будет – он вам прямо скажет, что "Я не знаю что это". Полумера вроде бы, но она полезная: по крайней мере не врёт. Правда, обещания формы тут всё ещё нет.

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

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

// Это и есть контракт стора, записанный на языке типов:
// «токен — это объект ровно с такими полями и такими типами»
interface Token {
  typeId: string
  label: string
  isStatic: boolean
}

const items = ref<Record<string, Token>>({})

const token = items.value['abc']
token.lable      // ❌ опечатка ловится сразу: нет поля 'lable', есть 'label'
token.isStatic   // ✅ boolean — ровно то, что обещано, без сюрпризов

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

1. Ошибка при неправильном использовании появится не в продакшене, а на этапе сборки.
   Такой формат можно сверху еще и тестированием покрыть, так что в случае неправильного использования у вас еще и CI/CD упадёт.

2. Мы убираем форматирование на уровне стора. (речь о UI форматировании)
   Стор вообще не должен знать, что там в итоге должно выводиться, это должны решать компоненты (а ещё лучше – утилиты). Мы не решаем на уровне стора, что должно выводиться, у него не должно быть на это полномочий.

Так что если вдруг вы попытаетесь протащить что-то такое:

items.value[item.type_id] = {
  typeId: item.type_id,
  label: item.name ?? 'Без названия',
  isStatic: item.is_static ? 'Да' : 'Нет', // ❌ Type 'string' is not assignable to type 'boolean'
}

То на 4 строке компилятор тут же упадёт. Потому что isStatic обещан как boolean, иначе нельзя. Интерфейс не будет физически пропускать такое форматирование внутрь хранилища.

Проблема интерфейсов

Если вы поняли основную мысль, то на моменте, когда вы попытаетесь описать interface Token вы можете столкнуться с неприятным моментом: вы попросту не можете его описать. Вы не знаете, какие поля могут быть обязательными, а какие – нет. Не знаете, label должен с бэка прийти или вы его выдумали под конкретную задачу. Путаетесь, что будет boolean, а что – string.

Но это не проблема типизации.

На самом деле это сигнал к тому, что граница в вашем проекте (или в конкретном нашем примере) не проведена вовсе: вы попросту не знаете, где кончается "сырьё с бэка" и начинается ваша "доменная модель". Решается это введением двух разных типов с границей между ними. Сырье с бэка – это RawToken (там может быть свой формат полей, даже разный case, и опциональные поля). А наша доменная модель – это Token.

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

interface RawToken { type_id: string, name?: string, is_static: boolean }
interface Token { typeId: string, label: string, isStatic: boolean }

function normalizeToken(raw: RawToken): Token {
  return {
    typeId: raw.type_id,
    label: raw.name ?? 'Без названия',
    isStatic: raw.is_static
  }
}

Вот теперь контракт будет закрыт. Однако о том, куда положить этот нормализатор и почему бизнес-логике не место внутри методов стора – поговорим во второй части (ссылку на которую я вставлю в эту статью, когде она появится).

А оно того стоит?

Кто-то дочитал досюда и думает:

Ну и зачем это академическое занудство? У меня дедлайн, а не диссертация. Окупится ли вообще возня с интерфейсами?

Мой ответ вам прозвучит примерно так:

Любая система, которая общается с внешним миром, рано или поздно поймает изменение этого мира — и поймает не по своим правилам и не в своём темпе. Бэк переименует поле, добавит новое, поменяет тип, выкатит это в пятницу вечером и забудет предупредить. Вопрос тут не «если», а «когда».

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

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

Хороший store — это не тот, у которого красивый код внутри. Это тот, чьему слову можно верить, не открывая его.