@the-teacher/the-router/docs/Article.ru.md

Simple router for Express.js, making routes and actions easy to manage.

[Previous content remains the same...]

## Основные концепции

### Архитектура на основе действий

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

1. **Единственную ответственность**

   - Каждое действие обрабатывает один конкретный HTTP эндпоинт
   - Четкий контракт ввода/вывода
   - Легко понять и поддерживать

2. **Автоматическую загрузку**

   - Действия загружаются на основе определений маршрутов
   - Соглашения важнее конфигурации
   - Нет необходимости в ручной регистрации контроллеров

3. **Предсказуемую структуру**
   ```
   actions/
     posts/
       indexAction.ts  # GET /posts
       showAction.ts   # GET /posts/:id
       createAction.ts # POST /posts
   ```

### Философия маршрутизации

Система маршрутизации построена на трех ключевых принципах:

1. **Декларативные маршруты**

   ```ts
   // Ясно и самодокументированно
   root("pages/home");
   get("/about", "pages/about");
   resources("posts");
   ```

2. **Организация на основе областей**

   ```ts
   // Логическая группировка с общим middleware
   scope("admin", [authenticate], () => {
     resources("users");
     get("/stats", "dashboard/stats");
   });
   ```

3. **Отображение на основе соглашений**
   - Маршрут `"posts/show"` отображается в `actions/posts/showAction.ts`
   - Область `"admin"` добавляет префикс к URL и пути действия
   - Ресурсы создают стандартизированные RESTful маршруты

### Интеграция Middleware

Роутер предоставляет гибкую систему middleware, работающую на нескольких уровнях:

1. **Middleware уровня области**

   - Применяется ко всем маршрутам внутри области
   - Наследуется вложенными областями
   - Идеально подходит для аутентификации и логирования

2. **Middleware ресурсов**

   - Применяется ко всем действиям ресурса
   - Может комбинироваться с middleware области

   ```ts
   resources("posts", [validatePost]);
   ```

3. **Middleware конкретных маршрутов**
   - Применяется к отдельным маршрутам
   - Имеет наивысший приоритет
   ```ts
   get("/posts/:id", [cacheResponse], "posts/show");
   ```

### Типобезопасность

Роутер построен с использованием TypeScript и предоставляет:

1. **Определения типов**

   - Полная типизация определений маршрутов
   - Типизация параметров действий
   - Типизация middleware

2. **Преимущества разработки**
   - Поддержка автодополнения
   - Проверка ошибок на этапе компиляции
   - Улучшенная поддержка рефакторинга

### Подход к тестированию

Архитектура роутера делает тестирование простым:

1. **Изолированные действия**

   ```ts
   // Легко тестировать отдельные действия
   test("должен показать пост", async () => {
     const response = await request(app).get("/posts/1").expect(200);
   });
   ```

2. **Тестирование Middleware**

   ```ts
   // Легко тестировать цепочки middleware
   test("требует аутентификации", async () => {
     await request(app).get("/admin/posts").expect(401);
   });
   ```

3. **Тестирование организации маршрутов**
   - Проверка поведения областей
   - Тестирование ресурсной маршрутизации
   - Валидация цепочек middleware

[Rest of the article remains the same...]