NextNodeTemplate/docs/USAGE_GUIDE.md

Руководство по использованию улучшений шаблона

📋 Содержание

1. Переменные окружения
2. Логирование
3. Валидация запросов
4. Rate Limiting
5. Docker
6. CI/CD

🔐 Переменные окружения

Установка dotenv

cd backend
npm install

Использование

1. Скопируйте .env.example в .env:

Copy-Item backend\.env.example backend\.env

2. Заполните значения в backend/.env

3. Переменные автоматически загружаются при старте сервера

Доступные переменные

• PORT - порт сервера (по умолчанию 3001)
• NODE_ENV - окружение (development/production)
• LOG_LEVEL - уровень логирования (error/warn/info/debug)

📝 Логирование

Winston

Winston настроен для логирования в файлы и консоль.

Логи создаются в backend/logs/:

• error.log - только ошибки
• combined.log - все логи

Использование в коде:

const logger = require('./config/logger');

// Разные уровни логирования
logger.error('Error message');
logger.warn('Warning message');
logger.info('Info message');
logger.debug('Debug message');

// С контекстом
logger.info('User login', { userId: 123, ip: '192.168.1.1' });

Настройка уровня логирования

В .env файле:

LOG_LEVEL=debug  # error, warn, info, debug

✅ Валидация запросов

Express-Validator

Используется для валидации входящих данных.

Пример использования:

const { body } = require('express-validator');
const validate = require('../middleware/validate');

router.post(
  '/endpoint',
  [
    body('email')
      .isEmail()
      .withMessage('Invalid email'),
    body('password')
      .isLength({ min: 8 })
      .withMessage('Password must be at least 8 characters'),
  ],
  validate,
  (req, res) => {
    // Валидация прошла успешно
    // req.body содержит проверенные данные
  }
);

Доступные валидаторы:

• body() - валидация тела запроса
• param() - валидация параметров URL
• query() - валидация query параметров

Популярные методы:

body('field')
  .notEmpty()           // Не пустое
  .isEmail()            // Email формат
  .isLength({ min: 5 }) // Минимальная длина
  .isInt()              // Целое число
  .isFloat()            // Число с плавающей точкой
  .trim()               // Убрать пробелы
  .custom((value) => {  // Кастомная валидация
    // Ваша логика
    return true;
  })

🛡️ Rate Limiting

Защита от злоупотреблений

Два уровня защиты настроены:

1. Общий limiter (generalLimiter):

   • 100 запросов за 15 минут
   • Применяется ко всем маршрутам

2. Строгий limiter (strictLimiter):

   • 20 запросов за 15 минут
   • Для важных endpoints

Использование:

const { strictLimiter } = require('../middleware/rateLimiter');

router.post('/api/sensitive', strictLimiter, (req, res) => {
  // Защищенный endpoint
});

Настройка:

В .env (опционально):

RATE_LIMIT_WINDOW_MS=900000      # 15 минут в миллисекундах
RATE_LIMIT_MAX_REQUESTS=100      # Максимум запросов

🐳 Docker

Установка Docker

Убедитесь, что Docker установлен на вашей системе.

Структура:

• Dockerfile - для backend
• Dockerfile.frontend - для frontend
• docker-compose.yml - для разработки

Использование Docker Compose:

# Запустить все сервисы
docker-compose up -d

# Просмотр логов
docker-compose logs -f

# Остановить
docker-compose down

# Пересобрать
docker-compose up -d --build

Отдельная сборка:

# Backend
docker build -t my-app-backend -f Dockerfile .
docker run -p 3001:3001 my-app-backend

# Frontend
docker build -t my-app-frontend -f Dockerfile.frontend .
docker run -p 3000:3000 my-app-frontend

Переменные окружения в Docker:

Создайте .env файл или используйте env_file в docker-compose.yml.

🔄 CI/CD

GitHub Actions

Автоматическая проверка кода при push в репозиторий.

Что проверяется:

• ✅ Установка зависимостей
• ✅ ESLint проверка
• ✅ Prettier форматирование
• ✅ Сборка frontend
• ✅ Проверка синтаксиса backend

Файл: .github/workflows/ci.yml

Workflow автоматически запускается при:

• Push в ветки main или dev
• Pull Request в main

Просмотр результатов:

В GitHub репозитории: Actions → выберите workflow run

🔧 Интеграция всех улучшений

Пример полного endpoint:

const express = require('express');
const { body } = require('express-validator');
const validate = require('../middleware/validate');
const { strictLimiter } = require('../middleware/rateLimiter');
const logger = require('../config/logger');

router.post(
  '/api/users',
  strictLimiter,
  [
    body('name')
      .trim()
      .notEmpty()
      .withMessage('Name is required'),
    body('email')
      .isEmail()
      .withMessage('Invalid email'),
  ],
  validate,
  async (req, res) => {
    try {
      logger.info('Creating user', { email: req.body.email });
      
      // Ваша логика
      const user = { /* ... */ };
      
      logger.info('User created successfully', { userId: user.id });
      res.json({ success: true, data: user });
    } catch (err) {
      logger.error('Error creating user', { error: err.message });
      res.status(500).json({ success: false, error: err.message });
    }
  }
);

📚 Дополнительные ресурсы

• Express Validator документация
• Winston документация
• Express Rate Limit
• Docker документация