Как построить архитектуру фронтенда, чтобы проект не умер через год

Представьте: вы начинаете новый проект. Энтузиазм на максимуме, код пишется быстро. Через пару месяцев вы уже забыли, зачем нужна та странная функция в utils.js. Через полгода добавление новой фичи превращается в квест. Через год проект превращается в болото, где каждое изменение может сломать всё.

Знакомо? Это классический результат отсутствия продуманной архитектуры. Давайте разберёмся, как строить фронтенд-проекты, которые будут жить и развиваться годами.

Почему проекты умирают?

Перед тем как говорить о решениях, поймём главные причины смерти проектов:

Спагетти-код. Всё связано со всем. Изменение в одном месте ломает три других компонента.

Отсутствие структуры. Файлы разбросаны хаотично. Найти нужный компонент — это археологическая экспедиция.

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

Нет документации. Даже вы сами через месяц не помните, как работает ваш код.

Технический долг. "Потом исправлю" превращается в "никогда не исправлю".

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

Хорошая архитектура начинается с организации файлов. Вот проверенная структура для большинства проектов:

src/
├── components/          # Переиспользуемые компоненты
│   ├── ui/             # Базовые UI элементы (кнопки, инпуты)
│   ├── layout/         # Компоненты раскладки (хедер, футер)
│   └── features/       # Бизнес-компоненты
├── pages/              # Страницы приложения
├── services/           # Работа с API
├── store/              # Глобальное состояние (Vuex, Redux, Pinia)
├── utils/              # Вспомогательные функции
├── hooks/              # Кастомные хуки (для React)
├── composables/        # Композабельные функции (для Vue)
├── types/              # TypeScript типы
├── constants/          # Константы приложения
└── assets/             # Статические ресурсы

Принцип: каждая папка отвечает за одну область ответственности. Когда вам нужен UI-компонент, вы идёте в components/ui. Нужна функция для работы с API — в services.

Принцип единственной ответственности

Каждый модуль должен делать что-то одно, но делать это хорошо.

Плохо:

// UserCard.js - делает всё сразу
function UserCard({ userId }) {
  const [user, setUser] = useState(null);
  
  // Получение данных
  useEffect(() => {
    fetch(`/api/users/${userId}`)
      .then(res => res.json())
      .then(setUser);
  }, [userId]);
  
  // Валидация
  const isValid = user?.email && user?.name;
  
  // Форматирование
  const formattedDate = new Date(user?.created).toLocaleDateString();
  
  // И ещё рендеринг...
  return <div>...</div>;
}

Хорошо:

// services/userService.js
export const fetchUser = async (userId) => {
  const response = await fetch(`/api/users/${userId}`);
  return response.json();
};

// utils/validation.js
export const validateUser = (user) => {
  return user?.email && user?.name;
};

// utils/dateFormatter.js
export const formatDate = (date) => {
  return new Date(date).toLocaleDateString();
};

// components/UserCard.js - только отображение
function UserCard({ userId }) {
  const [user, setUser] = useState(null);
  
  useEffect(() => {
    fetchUser(userId).then(setUser);
  }, [userId]);
  
  if (!validateUser(user)) return null;
  
  return (
    <div>
      <h2>{user.name}</h2>
      <p>{user.email}</p>
      <span>{formatDate(user.created)}</span>
    </div>
  );
}

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

Слои абстракции: разделяй и властвуй

Хорошая архитектура строится слоями, как луковица:

1. Слой данных (Data Layer)

Отвечает за получение и отправку данных. Здесь живут все API-запросы.

// services/api/userApi.js
const API_BASE = 'https://api.example.com';

export const userApi = {
  getUser: (id) => fetch(`${API_BASE}/users/${id}`).then(r => r.json()),
  updateUser: (id, data) => fetch(`${API_BASE}/users/${id}`, {
    method: 'PUT',
    body: JSON.stringify(data)
  }),
  deleteUser: (id) => fetch(`${API_BASE}/users/${id}`, { method: 'DELETE' })
};

2. Слой бизнес-логики (Business Logic Layer)

Обрабатывает данные, применяет правила бизнес-логики.

// services/userService.js
import { userApi } from './api/userApi';

export const userService = {
  async getActiveUsers() {
    const users = await userApi.getUsers();
    return users.filter(user => user.isActive);
  },
  
  async promoteToAdmin(userId) {
    const user = await userApi.getUser(userId);
    if (!user.email.endsWith('@company.com')) {
      throw new Error('Only company emails can be admins');
    }
    return userApi.updateUser(userId, { role: 'admin' });
  }
};

3. Слой состояния (State Layer)

Управляет глобальным состоянием приложения.

// store/userStore.js (Pinia/Vue)
export const useUserStore = defineStore('user', {
  state: () => ({
    currentUser: null,
    users: []
  }),
  
  actions: {
    async loadUser(id) {
      this.currentUser = await userService.getUser(id);
    }
  }
});

4. Слой представления (Presentation Layer)

Компоненты, которые отображают данные пользователю.

// components/UserProfile.vue
<script setup>
import { useUserStore } from '@/store/userStore';

const userStore = useUserStore();
const { currentUser } = storeToRefs(userStore);

onMounted(() => {
  userStore.loadUser(route.params.id);
});
</script>

<template>
  <div v-if="currentUser">
    <h1>{{ currentUser.name }}</h1>
    <p>{{ currentUser.email }}</p>
  </div>
</template>

Золотое правило: верхние слои могут использовать нижние, но не наоборот. Компоненты используют store, store использует services, но services никогда не импортируют компоненты.

Композиция вместо наследования

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

Пример с React хуками:

// hooks/useLocalStorage.js
export function useLocalStorage(key, initialValue) {
  const [value, setValue] = useState(() => {
    const stored = localStorage.getItem(key);
    return stored ? JSON.parse(stored) : initialValue;
  });
  
  useEffect(() => {
    localStorage.setItem(key, JSON.stringify(value));
  }, [key, value]);
  
  return [value, setValue];
}

// hooks/useDebounce.js
export function useDebounce(value, delay) {
  const [debouncedValue, setDebouncedValue] = useState(value);
  
  useEffect(() => {
    const handler = setTimeout(() => setDebouncedValue(value), delay);
    return () => clearTimeout(handler);
  }, [value, delay]);
  
  return debouncedValue;
}

// Использование
function SearchComponent() {
  const [query, setQuery] = useLocalStorage('searchQuery', '');
  const debouncedQuery = useDebounce(query, 500);
  
  // Теперь у вас есть поиск с дебаунсом и сохранением в localStorage
  useEffect(() => {
    if (debouncedQuery) {
      searchApi(debouncedQuery);
    }
  }, [debouncedQuery]);
}

Типизация — ваш лучший друг

TypeScript может показаться излишним для начинающих, но он спасёт проект от многих проблем.

// types/user.ts
export interface User {
  id: number;
  name: string;
  email: string;
  role: 'user' | 'admin' | 'moderator';
  createdAt: Date;
}

export interface ApiResponse<T> {
  data: T;
  error?: string;
  status: number;
}

// services/userService.ts
export async function getUser(id: number): Promise<ApiResponse<User>> {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}

Теперь IDE будет подсказывать доступные поля, а TypeScript поймает ошибки на этапе разработки, а не в продакшене.

Конфигурация и константы

Не разбрасывайте магические числа и строки по коду. Собирайте их в одном месте.

// constants/config.js
export const API_CONFIG = {
  BASE_URL: process.env.VITE_API_URL || 'https://api.example.com',
  TIMEOUT: 5000,
  RETRY_ATTEMPTS: 3
};

export const UI_CONSTANTS = {
  ITEMS_PER_PAGE: 20,
  DEBOUNCE_DELAY: 300,
  TOAST_DURATION: 3000
};

export const ROUTES = {
  HOME: '/',
  PROFILE: '/profile',
  SETTINGS: '/settings'
};

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

Обработка ошибок

Системный подход к ошибкам — признак зрелой архитектуры.

// utils/errorHandler.js
export class ApiError extends Error {
  constructor(message, status, data) {
    super(message);
    this.status = status;
    this.data = data;
  }
}

export async function handleApiCall(apiFunction) {
  try {
    return await apiFunction();
  } catch (error) {
    if (error instanceof ApiError) {
      // Показываем пользователю понятное сообщение
      toast.error(error.message);
      
      // Логируем для разработчиков
      console.error('API Error:', error.status, error.data);
    } else {
      // Неожиданная ошибка
      toast.error('Что-то пошло не так. Попробуйте позже.');
      console.error('Unexpected error:', error);
    }
    throw error;
  }
}

// Использование
async function loadUserData(userId) {
  await handleApiCall(async () => {
    const user = await userApi.getUser(userId);
    if (!user) {
      throw new ApiError('Пользователь не найден', 404);
    }
    return user;
  });
}

Документируйте архитектурные решения

Создайте файл ARCHITECTURE.md в корне проекта:

# Архитектура проекта

## Структура
- `/components` - переиспользуемые компоненты
- `/pages` - страницы приложения
- `/services` - бизнес-логика и API

## Соглашения
- Компоненты именуются в PascalCase
- Утилиты и сервисы в camelCase
- Константы в SCREAMING_SNAKE_CASE

## Слои
1. API Layer (services/api/)
2. Business Logic (services/)
3. State Management (store/)
4. UI Components (components/)

## Важные решения
- Используем Pinia для состояния
- Axios для HTTP запросов
- День.js для работы с датами

Код-ревью и линтинг

Настройте ESLint и Prettier сразу. Это предотвратит 90% проблем с читаемостью кода.

// .eslintrc.js
module.exports = {
  rules: {
    'no-console': 'warn',
    'no-unused-vars': 'error',
    'complexity': ['error', 10], // Предупреждает о сложных функциях
    'max-lines-per-function': ['warn', 50]
  }
};

Тестирование архитектуры

Хорошая архитектура легко тестируется.

// userService.test.js
import { userService } from './userService';
import { userApi } from './api/userApi';

jest.mock('./api/userApi');

test('promoteToAdmin отклоняет внешние email', async () => {
  userApi.getUser.mockResolvedValue({
    id: 1,
    email: 'external@gmail.com'
  });
  
  await expect(
    userService.promoteToAdmin(1)
  ).rejects.toThrow('Only company emails');
});

Если ваши функции сложно тестировать — это сигнал, что архитектура хромает.

Масштабирование: Feature-Based Structure

Когда проект растёт, группируйте код по фичам, а не по типам файлов:

src/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   ├── services/
│   │   ├── store/
│   │   └── types/
│   ├── products/
│   │   ├── components/
│   │   ├── services/
│   │   └── store/
│   └── cart/
│       ├── components/
│       └── store/
└── shared/              # Общие компоненты и утилиты

Теперь всё, связанное с авторизацией, в одной папке. Легко найти, легко удалить, легко передать другому разработчику.

Частые ошибки начинающих!

Преждевременная оптимизация

Не нужно сразу строить архитектуру на миллион пользователей. Начните с простого, но расширяемого решения.

Избыточная абстракция

Если у вас есть только одна кнопка, не нужно создавать систему из пяти базовых классов для неё.

Игнорирование конвенций

Используйте общепринятые практики вашего фреймворка. Не изобретайте велосипед.

Отсутствие рефакторинга

Закладывайте время на улучшение архитектуры. Технический долг накапливается незаметно.

Практические советы.

Начинайте с README. Опишите, как устроен проект, прежде чем писать код. Это заставит думать об архитектуре.

Регулярно рефакторьте. Выделите час в неделю на улучшение существующего кода.

Учитесь у других. Изучайте open-source проекты, смотрите, как они организованы.

Не бойтесь переделывать. Если структура не работает, лучше исправить её сейчас, чем жить с ней годами.

Инструменты в помощь.

• ESLint/Prettier — автоматическое форматирование кода

• Husky — проверка кода перед коммитом

• TypeScript — типизация для крупных проектов

• Storybook — разработка компонентов изолированно

• Jest/Vitest — тестирование логики

Заключение

Хорошая архитектура — это не идеальный код с первого раза. Это системный подход, который позволяет проекту эволюционировать. Начните с простой, но логичной структуры. Следуйте принципу единственной ответственности. Документируйте важные решения. И главное — регулярно пересматривайте и улучшайте свой код.

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

Это и многое другое можно изучить в Кодике — разобрать всё подробно и закрепить практикой с заданиями. Мы учим не просто писать код, а строить правильные, масштабируемые приложения, которые проживут долгие годы.

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

Присоединяйся к комьюнити, где растут настоящие профессионалы! 🚀