Статьи в категории "Веб-технологии"

🧱 Фундаментальные принципы организации

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

• Разделение ответственности (Separation of Concerns): Код разбивается на слои с четкими задачами. Например, слой представления (UI) не должен знать, как работает слой доступа к данным (DB). Это делает систему гибкой и тестируемой.

• Feature-First (Предметно-ориентированная) vs. Type-First (Тип-ориентированная) структура: Вместо группировки файлов по их технической роли (components/, hooks/, utils/), feature-first подход группирует все файлы, относящиеся к одной бизнес-функции (например, profile/, checkout/), в одном месте. Это значительно упрощает навигацию и поддержку в больших проектах.

• Масштабируемость (Scalability): Структура должна легко позволять добавлять новые функции, не ломая старые, и быть понятной для новых членов команды.

📁 Структура для разных частей стека

1. Backend: Express.js, Hono, Fastify

Для серверной части (API) хорошо зарекомендовала себя многослойная архитектура. Вот как она выглядит на практике.

Общая идея (Layered Architecture):

src/
├── config/           # Конфигурации (env, БД, логирование)
├── modules/          # Фичи/модули (feature-first подход)
│   └── users/        # Пример модуля "Пользователи"
│       ├── controllers/   # Обработка HTTP запросов
│       ├── services/      # Бизнес-логика
│       ├── repositories/  # Работа с БД
│       ├── schemas/       # Валидация (Zod, TypeBox)
│       ├── types/         # TypeScript типы для модуля
│       └── index.ts       # Точка входа модуля
├── shared/           # Общие утилиты, middleware, ошибки
│   ├── middleware/
│   ├── errors/
│   └── utils/
├── app.ts            # Инициализация приложения (роуты, middleware)
└── server.ts         # Запуск сервера

• Express.js: Классический пример — server/ с src/, где лежат resolvers/, models/, prisma/. В более продвинутых шаблонах используют controllers/, services/, routes/.

• Hono: Так как Hono не навязывает структуру, в сообществе предлагают гибкие подходы. Можно использовать feature-first структуру с папкой features/, где каждый модуль содержит свои api/ (эндпоинты), services/ (бизнес-логику), repositories/ (доступ к данным) и validation/. Общие части выносятся в core/ и shared/.

• Fastify: Рекомендуется структура с routes/ (группировка по ресурсам), plugins/ (для регистрации функциональности), services/ и repositories/.

2. Frontend: React / Next.js

Здесь ключевой выбор — между App Router (рекомендуемый) и Pages Router.

Структура для Next.js (App Router):

my-nextjs-app/
├── app/                    # Маршруты и страницы (App Router)
│   ├── (auth)/             # Группа маршрутов для аутентификации
│   ├── (dashboard)/        # Группа для защищенных страниц
│   ├── api/                # API Routes (serverless функции)
│   ├── layout.tsx          # Корневой layout
│   └── page.tsx            # Домашняя страница
├── src/                    # Исходный код приложения (опционально)
│   ├── components/         # Переиспользуемые UI компоненты
│   │   ├── ui/             # Базовые (Button, Input)
│   │   └── layout/         # Структурные (Header, Sidebar)
│   ├── features/           # Фичи (самодостаточные модули)
│   │   └── profile/        # Пример фичи "Профиль"
│   │       ├── components/
│   │       ├── hooks/
│   │       ├── services/   # API вызовы для фичи
│   │       └── types/
│   ├── lib/                # Утилиты, конфигурация клиентов (API, React Query)
│   ├── hooks/              # Кастомные React хуки (глобальные)
│   ├── types/              # Общие TypeScript типы
│   └── context/            # React Context провайдеры
├── public/                 # Статические файлы
└── package.json

Ключевые моменты:

• Используйте app/ для новых проектов.

• Для изоляции кода применяйте Route Groups (groupName).

• Код, относящийся к одной функции, группируйте в features/.

• Общие компоненты храните в components/.

• Серверную логику (работа с БД, сервисы) выносите в папку server/ или lib/server/.

🏗️ Архитектура на уровне решения (Monorepo)

Если вы разрабатываете фронтенд и бэкенд в одном репозитории, используйте монорепозиторий (monorepo). Это стандарт для полного цикла разработки.

Пример структуры монорепозитория:

my-monorepo/
├── packages/ или apps/
│   ├── frontend/          # Next.js приложение
│   │   ├── app/
│   │   ├── components/
│   │   └── package.json
│   └── backend/           # Express / Hono / Fastify приложение
│       ├── src/
│       │   ├── modules/
│       │   ├── shared/
│       │   └── server.ts
│       └── package.json
├── docker-compose.yml
├── package.json           # Корневой package.json с workspaces
└── turbo.json или pnpm-workspace.yaml

Инструменты для управления: pnpm workspaces, npm workspaces, или Turborepo для более сложных сценариев.

🚀 Специфика для Bun

Bun — это не только рантайм, но и пакетный менеджер, и сборщик.

• Структура: Стандартный проект на Bun выглядит так:

  text

  my-bun-app/
  ├── src/           # Исходный код
  ├── index.ts       # Точка входа
  ├── package.json
  └── tsconfig.json

• Монорепозиторий: Bun отлично поддерживает workspaces в package.json для создания монорепозиториев.

📈 От простого к сложному: Эволюция структуры

Важно понимать, что структура растет вместе с проектом:

1. Начальный уровень (Small Project): app/, components/, lib/, types/. Просто и быстро.

2. Средний уровень (Medium Project): Добавляются features/ для логической группировки, server/ для серверной логики, ui/ для общих компонентов.

3. Продвинутый уровень (Enterprise): Внедряются Domain-Driven Design (DDD) с папкой entities/, четкое разделение на core/, modules/, shared/ и использование принципов Чистой архитектуры.

💎 Итог: Стратегия выбора

1. Начните с малого: Для нового проекта используйте простую, но логичную структуру (например, app/ + components/ + lib/ для Next.js).

2. Рефакторинг по мере роста: Как только проект начинает разрастаться, внедряйте feature-first подход, группируя код по функциям в папке features/.

3. Разделяйте backend и frontend: Даже в монорепозитории четко разделяйте код клиента и сервера по разным пакетам.

4. Следуйте соглашениям фреймворка: Используйте App Router в Next.js, роутинг по ресурсам в Fastify, и feature-based структуру в Hono.

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

В современной веб-разработке с использованием TypeScript, React, Next.js и Node.js сложился ряд отраслевых стандартов и лучших практик. Эти практики помогают создавать код, который легко поддерживать, масштабировать и развивать в команде.

Ниже представлен сводный обзор ключевых стандартов для каждого компонента вашего стека.

📝 Единые стандарты кода и TypeScript

• Стиль кода: Для обеспечения единообразия в команде принято использовать один из популярных стилевых гайдов, например Airbnb JavaScript Style Guide или Google Style Guide. Их легко внедрить с помощью соответствующих конфигураций для ESLint (eslint-config-airbnb-typescript, eslint-config-google).

• Строгий TypeScript: В файле tsconfig.json обязательно нужно устанавливать "strict": true. Это включает все строгие проверки типов, что является фундаментом надежности кода.

• Инструменты линтинга и форматирования: Используйте ESLint для поиска проблем в коде и Prettier для автоматического форматирования. Это обязательный минимум для любого современного проекта.

⚛️ Стандарты для React и Next.js

• Компоненты: Предпочтение отдается функциональным компонентам с четко описанными TypeScript-интерфейсами для props. По возможности используйте серверные компоненты (Server Components) по умолчанию.

• Производительность: Для оптимизации используйте встроенные хуки: useCallback для мемоизации функций, useMemo для дорогих вычислений и React.memo для предотвращения лишних перерисовок компонентов.

• Маршрутизация: В новых проектах на Next.js используйте App Router, так как это современный и рекомендуемый подход.

⚙️ Стандарты для серверных фреймворков (Express.js, Hono, Fastify)

Выбор фреймворка зависит от контекста задачи:

Общие для всех бэкенд-фреймворков практики:

• Структура проекта (Layered Architecture): Следуйте четкому разделению ответственности, выделяя слои:

  • routes/ — определение эндпоинтов.

  • controllers/ — обработка HTTP-запросов и ответов.

  • services/ — бизнес-логика (не должна зависеть от HTTP).

  • repositories/ или models/ — работа с данными и базой данных.

  • middleware/ — кастомные middleware (аутентификация, валидация, логирование).

• Валидация: Всегда проверяйте входные данные на границе приложения (в контроллере или middleware). Для этого отлично подходят библиотеки вроде Zod или TypeBox.

• Обработка ошибок: Используйте централизованный обработчик ошибок и иерархию кастомных классов ошибок (например, ValidationError, NotFoundError).

🚀 Стандарты для рантаймов (Bun и Node.js)

• Node.js: Это стандарт де-факто для серверной разработки с огромной экосистемой.

• Bun: Позиционируется как более быстрая альтернатива. Его стоит рассматривать, если важна производительность, а встроенный бандлер и тест-раннер могут упростить тулинг.

  • Ключевая практика для Bun: Bun нативно поддерживает TypeScript, поэтому для запуска .ts файлов не нужны дополнительные инструменты вроде ts-node. Предпочтительно использовать встроенные Web API (fetch, fs, path) вместо Node.js-специфичных, где это возможно.

🏗️ Общие принципы архитектуры

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

• Single Responsibility (SRP): Каждый модуль, класс или функция должны иметь одну четкую зону ответственности.

• DRY (Don't Repeat Yourself): Избегайте дублирования кода, выносите повторяющуюся логику в утилиты или переиспользуемые хуки/компоненты.

🛠️ Рекомендованный инструментарий

• Линтер: eslint с плагинами для TypeScript, React и Next.js.

• Форматтер: prettier.

• Типы: typescript (строгий режим).

• Валидация: zod (отлично работает с TypeScript для вывода типов).

• Управление состояниями (React): Redux Toolkit или Zustand (более легковесный).

В целом, ключ к успеху — это строгая типизация, четкая структура проекта и автоматизированные инструменты для поддержания качества кода. Выбор между конкретными фреймворками (Express vs Fastify vs Hono) и рантаймами (Node vs Bun) зависит от конкретных требований вашего проекта к производительности, среде запуска и опыту команды.

Этаж 1: Фундамент (Рантаймы — Где код выполняется)

Аналогия: Это марка операционной системы вашего сервера (как Windows, Linux или macOS). Вы выбираете один фундамент, на котором будет крутиться проект. В 2026 году чаще всего выбирают проверенный Node.js или ультрабыстрый Bun.

Этаж 2: Стены (Классические Бэкенд-фреймворки)

Аналогия: Это каркас вашего здания. Вы выбираете один бэкенд-фреймворк. Для простых вещей берете Hono/Fastify, для огромного корпоративного банка — NestJS.

Этаж 3: Крыша и Фасад (Fullstack-фреймворк)

🗺 Карта «Что с чем дружит» (Как собрать свой первый конструктор)

Сценарий А: Простой современный сайт (интернет-магазин, блог)

Сценарий Б: Современное мощное API (например, для мобильного приложения)

Сценарий В: Крупный и сложный IT-продукт (онлайн-банк, огромная соцсеть)

1. Настройка ESLint (для React + TS)

Шаг 1: Установка зависимостей

npm install -D eslint @eslint/js typescript-eslint eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-react-refresh

Шаг 2: Создание файла eslint.config.js

import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import reactPlugin from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';
import reactRefresh from 'eslint-plugin-react-refresh';

export default tseslint.config(
  // Игнорируемые папки (замена старого .eslintignore)
  { ignores: ['dist', 'node_modules', 'build'] },
  
  // Базовые настройки для JavaScript и TypeScript
  js.configs.recommended,
  ...tseslint.configs.recommended,
  
  // Настройки для React-компонентов
  {
    files: ['**/*.{ts,tsx}'],
    plugins: {
      'react': reactPlugin,
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh,
    },
    languageOptions: {
      parserOptions: {
        ecmaFeatures: { jsx: true },
      },
    },
    settings: {
      react: { version: 'detect' }, // Автоопределение версии React
    },
    rules: {
      // Правила React Hooks
      ...reactHooks.configs.recommended.rules,
      
      // Специфичные правила для React
      'react/react-in-jsx-scope': 'off', // Отключено для React 17+
      'react/jsx-no-target-blank': 'warn',
      
      // Правила для React Fast Refresh (полезно для Vite)
      'react-refresh/only-export-components': [
        'warn',
        { allowConstantExport: true },
      ],
      
      // Кастомные правила TypeScript
      '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
      '@typescript-eslint/no-explicit-any': 'warn',
    },
  }
);

2. Структура папок по стандарту Feature-Sliced Design (FSD)

src/
├── 1_app/                  # Слои (Layers) пишутся строчными буквами, цифры — для визуального порядка
│   ├── providers/          # Провайдеры (Redux Store, RouterProvider, ThemeProvider)
│   ├── styles/             # Глобальные стили (index.css, variables.scss)
│   └── App.tsx             # Инициализация приложения
│
├── 2_pages/                # Страницы приложения
│   ├── home/               # Слайс страницы (Slice)
│   │   ├── ui/             # Сегменты (Segments): UI-компоненты страницы
│   │   └── index.ts        # Публичное API (только отсюда можно делать импорт наружу!)
│   └── profile/
│       ├── ui/
│       └── index.ts
│
├── 3_widgets/              # Крупные самостоятельные блоки (из фич и сущностей)
│   ├── header/
│   │   ├── ui/             # Header.tsx
│   │   └── index.ts
│   └── sidebar/
│
├── 4_features/             # Действия пользователя, несущие бизнес-ценность
│   ├── auth-by-username/   # Авторизация
│   │   ├── model/          # Стейт, экшены, селекторы (Redux/Zustand)
│   │   ├── ui/             # Форма логина, кнопка
│   │   └── index.ts
│   └── add-to-cart/        # Добавление в корзину
│
├── 5_entities/             # Бизнес-сущности (без привязки к конкретным действиям)
│   ├── user/
│   │   ├── model/          # Типы пользователя, стейт авторизации
│   │   └── index.ts
│   └── product/
│       ├── ui/             # Карточка продукта (ProductCard)
│       └── index.ts
│
└── 6_shared/               # Переиспользуемый код (инфраструктура, утилиты)
    ├── api/                # Базовые запросы (axios, fetch)
    ├── assets/             # Иконки, картинки, шрифты
    ├── lib/                # Хелперы, кастомные хуки (useDebounce и др.)
    └── ui/                 # Атомарные UI-компоненты (Button, Input, Modal)
        ├── button/
        │   ├── Button.tsx
        │   └── index.ts
        └── input/

Важные правила FSD для вашей команды:

npm install -D eslint-plugin-boundaries

import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import reactPlugin from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';
import reactRefresh from 'eslint-plugin-react-refresh';
// 1. Импортируем плагин границ
import boundaries from 'eslint-plugin-boundaries';

export default tseslint.config(
  { ignores: ['dist', 'node_modules', 'build'] },
  js.configs.recommended,
  ...tseslint.configs.recommended,
  
  {
    files: ['**/*.{ts,tsx,js,jsx}'],
    plugins: {
      'react': reactPlugin,
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh,
      // 2. Регистрируем плагин
      'boundaries': boundaries,
    },
    languageOptions: {
      parserOptions: {
        ecmaFeatures: { jsx: true },
      },
    },
    settings: {
      react: { version: 'detect' },
      // 3. Настраиваем распознавание путей (поддерживает относительные импорты и алиасы вроде @/*)
      'boundaries/elements': [
        { type: 'app', pattern: 'src/1_app/**/*' },
        { type: 'pages', pattern: 'src/2_pages/**/*' },
        { type: 'widgets', pattern: 'src/3_widgets/**/*' },
        { type: 'features', pattern: 'src/4_features/**/*' },
        { type: 'entities', pattern: 'src/5_entities/**/*' },
        { type: 'shared', pattern: 'src/6_shared/**/*' },
      ],
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      'react/react-in-jsx-scope': 'off',
      
      // 4. Включаем правила FSD
      'boundaries/entry-point': 'error', // Запрещает глубокие импорты в обход index.ts
      'boundaries/element-types': [
        'error',
        {
          default: 'disallow', // По умолчанию всё запрещено, кроме явных разрешений ниже
          message: 'Архитектурная ошибка FSD: импорт из слоев выше или чужих слайсов запрещен (${file.type} <- ${dependency.type})',
          rules: [
            // Слою App доступно всё
            { from: 'app', allow: ['pages', 'widgets', 'features', 'entities', 'shared'] },
            // Слою Pages доступны все нижележащие слои
            { from: 'pages', allow: ['widgets', 'features', 'entities', 'shared'] },
            // Слою Widgets доступны фичи, сущности и shared
            { from: 'widgets', allow: ['features', 'entities', 'shared'] },
            // Слою Features доступны сущности и shared
            { from: 'features', allow: ['entities', 'shared'] },
            // Слою Entities доступен только shared
            { from: 'entities', allow: ['shared'] },
            // Слою Shared запрещено импортировать из любых других слоев FSD
            { from: 'shared', allow: [] },
          ],
        },
      ],
    },
  }
);

{
  "compilerOptions": {
    // ... ваши текущие настройки
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

// ... ваши импорты

export default tseslint.config(
  { ignores: ['dist', 'node_modules', 'build'] },
  js.configs.recommended,
  ...tseslint.configs.recommended,
  
  {
    files: ['**/*.{ts,tsx,js,jsx}'],
    plugins: {
      'react': reactPlugin,
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh,
      'boundaries': boundaries,
    },
    // ОБНОВЛЕННАЯ СЕКЦИЯ SETTINGS
    settings: {
      react: { version: 'detect' },
      
      // Настройка для распознавания алиаса @/* парсером ESLint
      'import/resolver': {
        typescript: {}, 
      },
      
      // Шаблоны теперь учитывают как относительные пути, так и алиас @/
      'boundaries/elements': [
        { type: 'app', pattern: ['src/1_app/**/*', '@/1_app/**/*'] },
        { type: 'pages', pattern: ['src/2_pages/**/*', '@/2_pages/**/*'] },
        { type: 'widgets', pattern: ['src/3_widgets/**/*', '@/3_widgets/**/*'] },
        { type: 'features', pattern: ['src/4_features/**/*', '@/4_features/**/*'] },
        { type: 'entities', pattern: ['src/5_entities/**/*', '@/5_entities/**/*'] },
        { type: 'shared', pattern: ['src/6_shared/**/*', '@/6_shared/**/*'] },
      ],
    },
    rules: {
      // ... правила, которые мы настроили на прошлом шаге
    }
  }
);

// Внутри src/2_pages/home/ui/HomePage.tsx

// Отлично: импорт виджета через красивый алиас
import { Header } from '@/3_widgets/header'; 

// Отлично: импорт кнопки из shared
import { Button } from '@/6_shared/ui/button'; 

// ESLint выдаст ошибку ❌ (импорт сверху вниз):
// import { ProfilePage } from '@/2_pages/profile';