Design on kenji.blog

Настройка темы Hugo: Как внедрить Tailwind CSS

Sun, 13 Sep 2026 03:00:00 +0900

Введение: Мощная синергия генератора статических сайтов Hugo и Tailwind CSS

В современной веб-разработке фронтенда баланс между производительностью и удобством разработки (DX: Developer Experience) является одной из важнейших задач в любом проекте. Комбинация Hugo, который может похвастаться самой высокой скоростью сборки в мире среди генераторов статических сайтов (SSG), и Tailwind CSS, принесшего инновационную парадигму utility-first, является одним из идеальных решений этой проблемы.

Hugo написан на языке Go и обладает потрясающей производительностью, позволяющей завершить сборку даже для сайтов с тысячами страниц всего за несколько секунд или миллисекунд. С другой стороны, Tailwind CSS ускоряет процесс дизайна за счет прямого использования в HTML огромного количества предопределенных утилитарных классов (таких как flex, text-center, mt-4), что устраняет необходимость постоянно переключаться между CSS и HTML файлами.

В этой статье мы подробно и досконально рассмотрим процесс интеграции Tailwind CSS в тему Hugo, а также создание продвинутого конвейера ресурсов (Hugo Pipes) с использованием PostCSS — от основ архитектуры до математической оптимизации производительности.

1. Эволюция utility-first CSS и компонентно-ориентированного подхода

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

Ограничения традиционного дизайна CSS (BEM и OOCSS)

В прошлом в веб-разработке лучшей практикой считалось использование семантических имен классов. Например, при создании компонента карточки HTML и CSS разделялись следующим образом:

1
2
3
4
5
6
7


<div class="card">
 <img class="card__image" src="image.jpg" alt="thumbnail">
 <div class="card__content">
 <h2 class="card__title">Заголовок</h2>
 <p class="card__description">Здесь будет описание.</p>
 </div>
</div>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


.card {
 border-radius: 8px;
 box-shadow: 0 4px 6px rgba(0,0,0,0.1);
 background-color: #ffffff;
 overflow: hidden;
}
.card__title {
 font-size: 1.5rem;
 font-weight: bold;
 color: #333333;
}
/* Далее идут детальные стили */

Хотя такой подход на основе BEM (Block Element Modifier) работает на ранних стадиях небольших проектов, он часто приводит к следующим проблемам:

Истощение и усталость от именования: Каждый раз при создании похожего компонента приходится придумывать новые имена классов (например: card-news, card-featured).
Раздувание CSS: С каждой новой функцией количество строк CSS продолжает расти. Однажды написанный CSS редко удаляется из страха, что «непонятно, где он используется», что приводит к накоплению мертвого кода.
Переключение контекста: Поскольку структура HTML и стили CSS управляются в разных файлах, количество переключений между вкладками в редакторе растет в геометрической прогрессии.

Сдвиг парадигмы с Tailwind CSS

Tailwind CSS решает эти проблемы с помощью подхода «комбинирования утилитарных классов». Приведенный выше компонент карточки с использованием Tailwind CSS будет выглядеть так:

1
2
3
4
5
6
7


<div class="rounded-lg shadow-md bg-white overflow-hidden">
 <img class="w-full h-48 object-cover" src="image.jpg" alt="thumbnail">
 <div class="p-6">
 <h2 class="text-2xl font-bold text-gray-800">Заголовок</h2>
 <p class="mt-2 text-gray-600">Здесь будет описание.</p>
 </div>
</div>

Поскольку сами имена классов представляют конкретные значения стилей (например, p-6 означает padding: 1.5rem;), вы можете предсказать конечный результат рендеринга, просто посмотрев на HTML. Кроме того, благодаря компилятору JIT (Just-In-Time) Tailwind в продакшн CSS файл извлекаются только те классы, которые фактически используются, что сводит размер файла CSS к минимуму.

2. Архитектура Hugo Pipes и PostCSS

Чтобы интегрировать Tailwind CSS в Hugo, необходимо понять конвейер обработки ресурсов, называемый Hugo Pipes. Hugo Pipes — это мощная функция, которая позволяет Hugo выполнять всю обработку ресурсов внутри себя, включая компиляцию Sass/SCSS, сборку и минификацию JavaScript, а также выполнение PostCSS, который мы будем использовать.

PostCSS — это инструмент для преобразования CSS с помощью плагинов JavaScript. Сам Tailwind CSS фактически работает как плагин для PostCSS.

Механизм преобразования AST (Абстрактного синтаксического дерева) с помощью PostCSS

Понимание того, как PostCSS обрабатывает CSS, очень полезно при устранении неполадок. Следующая диаграмма Mermaid показывает конвейер, в котором PostCSS читает CSS-файл, преобразует его через плагины и выводит финальный CSS.

flowchart TD
A["Сырой CSS (styles.css)"] -->|Parser| B["AST (Абстрактное синтаксическое дерево)"]
B --> C["Плагин 1: Tailwind CSS"]
C --> D["Плагин 2: Autoprefixer"]
D --> E["Плагин N: cssnano"]
E -->|Stringifier| F["Скомпилированный и оптимизированный CSS"]

Parser (Парсер): Анализирует входящую необработанную строку CSS и преобразует ее в AST (абстрактное синтаксическое дерево), структуру данных, которой можно управлять программно.
Plugins (Плагины):
- Tailwind CSS: Сканирует файлы шаблонов (HTML или Markdown) и добавляет используемые утилитарные классы в качестве узлов в AST. Он также разворачивает директивы @tailwind.
- Autoprefixer: Обращается к базе данных Can I Use и при необходимости добавляет вендорные префиксы (например, -webkit-, -moz-) к свойствам AST.
Stringifier (Генератор строк): Преобразует готовое AST обратно в строку CSS, понятную браузеру, и выводит ее.

3. Настройка среды и предварительные условия

Давайте перейдем к фактическим шагам по установке. Сначала убедитесь, что у вас установлено необходимое программное обеспечение.

Обязательные требования

Hugo Extended Version: Обязательно нужна Extended версия, которая включает в себя возможности обработки Sass/SCSS и встроенную интеграцию PostCSS, а не обычный Hugo. Выполните следующую команду в терминале и убедитесь, что строка extended присутствует в информации о версии.
1 2 3

hugo version # Ожидаемый вывод: # hugo v0.121.2-4146... windows/amd64 BuildDate=... VendorInfo=gohugoio +extended
Node.js и npm: Зависимости, такие как Tailwind CSS и PostCSS, работают на Node.js. Убедитесь, что установлен Node.js (рекомендуется версия LTS).
1 2

node -v npm -v

Установка пакетов npm

Инициализируйте npm в корневом каталоге проекта (там, где находится файл конфигурации Hugo hugo.toml) и установите необходимые пакеты.

1
2
3
4
5


# Создание package.json
npm init -y

# Установка Tailwind CSS, PostCSS и Autoprefixer в качестве зависимостей для разработки
npm install -D tailwindcss postcss postcss-cli autoprefixer

[!IMPORTANT] Если postcss-cli не установлен, могут возникнуть ошибки при вызове PostCSS из Hugo. Обязательно установите его, так как Hugo Pipes внутренне использует postcss-cli.

4. Создание конфигурационных файлов (PostCSS и Tailwind CSS)

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

Создание tailwind.config.js

Выполните следующую команду в терминале, чтобы сгенерировать конфигурационный файл по умолчанию.

1

npx tailwindcss init

Откройте созданный tailwind.config.js в редакторе и настройте свойство content. Это очень важно. Tailwind анализирует файлы по указанным здесь путям и извлекает используемые классы. Точно укажите файлы макетов и контента в соответствии со структурой вашего проекта Hugo.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


/** @type {import('tailwindcss').Config} */
module.exports = {
 // Указание файлов для сканирования в соответствии со структурой каталогов Hugo
 content: [
 "./content/**/*.md",
 "./content/**/*.html",
 "./layouts/**/*.html",
 "./assets/**/*.js",
 // Если вы используете тему, необходимо включить и её каталоги
 // "./themes/my-theme/layouts/**/*.html",
 ],
 theme: {
 extend: {
 // Здесь можно расширить пользовательские цвета и шрифты
 colors: {
 'brand-primary': '#3490dc',
 'brand-secondary': '#ffed4a',
 },
 fontFamily: {
 'sans': ['Helvetica Neue', 'Arial', 'Hiragino Kaku Gothic ProN', 'Meiryo', 'sans-serif'],
 }
 },
 },
 plugins: [
 // При необходимости добавьте официальные плагины (например, плагин Typography)
 // require('@tailwindcss/typography'),
 ],
}

Создание postcss.config.js

Далее создайте в корне проекта файл postcss.config.js, который определяет, какие плагины и в каком порядке будет выполнять PostCSS.

1
2
3
4
5
6


module.exports = {
 plugins: {
 tailwindcss: {},
 autoprefixer: {},
 }
}

Благодаря этой настройке, когда Hugo вызывает PostCSS, сначала применяется Tailwind CSS, а затем Autoprefixer добавляет вендорные префиксы.

5. Создание конвейера ресурсов CSS в Hugo

После завершения настроек пришло время интегрировать Tailwind CSS в тему Hugo.

5-1. Создание CSS файла точки входа

Создайте CSS-файл, который послужит точкой входа, в каталоге assets/css/ (если его нет, создайте его). Назовем его main.css.

Путь к файлу: assets/css/main.css

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


/* Импорт базовых стилей Tailwind (сброс CSS и т.д.) */
@tailwind base;

/* Импорт классов компонентов */
@tailwind components;

/* Импорт утилитарных классов */
@tailwind utilities;

/* Пользовательский CSS можно добавить здесь, но
 рекомендуется использовать extend в tailwind.config.js по мере возможности */
@layer components {
 .btn-primary {
 @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded transition-colors duration-300;
 }
}

5-2. Редактирование файла макета (head.html)

Далее загрузите вышеуказанный CSS-файл из шаблона Hugo и напишите конвейер для его обработки с помощью PostCSS. Обычно редактируется частичный шаблон (например, layouts/partials/head.html), который определяет содержимое тега <head>.

Путь к файлу: layouts/partials/head.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


<head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>{{ .Title }} | {{ .Site.Title }}</title>

 <!-- Получение assets/css/main.css -->
 {{ $css := resources.Get "css/main.css" }}

 <!-- Определение опций PostCSS -->
 {{ $options := dict "inlineImports" true }}
 {{ $css = $css | resources.PostCSS $options }}

 <!-- Конвейер оптимизации ресурсов для продакшн-окружения (Production) -->
 {{ if hugo.IsProduction }}
 <!-- 1. Minify (сжатие) -->
 {{ $css = $css | minify }}
 <!-- 2. Fingerprint (добавление хеша для сброса кэша) -->
 {{ $css = $css | fingerprint "sha512" }}
 <!-- 3. Вывод тега с атрибутом SRI (Subresource Integrity) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
 {{ else }}
 <!-- В среде разработки (Development) выводится без сжатия (приоритет на скорость сборки) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}">
 {{ end }}
</head>

Объяснение конвейера и диаграмма Mermaid

Ниже представлена диаграмма, иллюстрирующая, как код шаблона Go обрабатывает CSS-файл через серию операций конвейера.

flowchart TD
A["assets/css/main.css"] -->|resources.Get| B["Пространство памяти Hugo"]
B -->|resources.PostCSS| C["Процесс PostCSS + Tailwind JIT"]
C --> D{"hugo.IsProduction ?"}
D -- Да (Продакшн) --> E["minify (удаление пробелов и переносов строк)"]
E --> F["fingerprint (вычисление хеша)"]
F --> G["public/css/main.[hash].css (с SRI)"]
D -- Нет (Разработка) --> H["public/css/main.css"]

resources.Get: Ищет указанный файл в каталоге assets и загружает его как объект ресурса в память.
resources.PostCSS: Применяет обработку Tailwind CSS и Autoprefixer к исходному коду CSS, ссылаясь на postcss.config.js в корне проекта. В среде разработки (hugo server) работает режим JIT, быстро генерирующий только необходимые классы при изменении файлов.
minify: При сборке для продакшна (например, hugo --environment production) удаляет ненужные пробелы и комментарии, сводя к минимуму размер файла.
fingerprint: Вычисляет SHA-хеш на основе содержимого файла и добавляет его к имени файла (например, main.ab12cd...css). Это позволяет использовать мощное кэширование браузера и одновременно обеспечивает «сброс кэша» — надежную загрузку нового файла при обновлении CSS.
integrity: Выводит атрибут SRI с использованием хеш-значения, вычисленного Fingerprint, для предотвращения подделки данных при доставке через CDN и т. д.

6. Математический анализ производительности при оптимизации CSS

Одним из самых больших преимуществ внедрения Tailwind CSS является минимизация размера доставляемого CSS-файла. Давайте с помощью математической модели количественно проанализируем, как это влияет на производительность веб-сайта (особенно на First Contentful Paint: FCP).

Модель уменьшения размера CSS файла

В традиционных CSS-фреймворках (например, Bootstrap) размер файла $S_{original}$ обычно велик (около 150-200 КБ), поскольку загружаются все стили, включая неиспользуемые. Если обозначить размер файла после удаления неиспользуемых классов (Purge) компилятором JIT Tailwind CSS как $S_{purged}$, и коэффициент уменьшения как $R_{purge}$, то это можно выразить следующей формулой:

$$ S_{purged} = S_{original} \times (1 - R_{purge}) $$

В типичном проекте $R_{purge}$ достигает почти $0.9$ (уменьшение на 90%), а $S_{purged}$ составляет всего лишь 10-20 КБ.

Кроме того, при доставке файлы сжимаются на стороне сервера с помощью Brotli или Gzip. Если коэффициент сжатия равен $R_{compress}$ (обычно около 0.7-0.8), конечный размер полезной нагрузки $S_{final}$, передаваемой по сети, вычисляется по следующей формуле:

$$ S_{final} = S_{purged} \times (1 - R_{compress}) $$

Критический путь рендеринга и сетевая задержка

Время до того момента, когда браузер отрисует первый контент на экране (FCP), можно приблизительно оценить как сумму времени загрузки HTML, времени загрузки CSS и времени рендеринга.

$$ T_{FCP} \approx RTT + \frac{S_{HTML}}{BW} + RTT + \frac{S_{final}}{BW} + T_{render} $$

Где:

$RTT$ : Round Trip Time (время круговой задержки связи с сервером)
$BW$ : Пропускная способность сети (Bandwidth)

В средах, таких как мобильные сети, где $BW$ ограничена, а $RTT$ велико (высокая задержка), подход Tailwind CSS, позволяющий сократить $S_{final}$ до нескольких килобайт, сводит член $\frac{S_{final}}{BW}$ практически к нулю. Это является движущей силой для достижения потрясающих оценок (в Google PageSpeed Insights и т. д.).

7. Запуск сервера разработки и проверка горячей перезагрузки

После завершения всех настроек запустите сервер разработки Hugo и убедитесь, что Tailwind CSS работает корректно.

1

hugo server -D

Откройте браузер по адресу http://localhost:1313/ и проверьте, отображается ли сайт. Откройте файл контента Markdown или шаблон Hugo (файлы в каталоге layouts/) и попробуйте добавить класс.

1
2
3
4
5


<!-- Пример применения классов Tailwind для тестирования -->
<div class="bg-gradient-to-r from-blue-500 to-purple-600 text-white p-8 rounded-xl shadow-2xl text-center transform transition duration-500 hover:scale-105">
 <h1 class="text-4xl font-extrabold tracking-tight">Tailwind CSS + Hugo — это потрясающе!</h1>
 <p class="mt-4 text-lg font-medium">Убедитесь, что горячая перезагрузка применяется мгновенно.</p>
</div>

Как только вы сохраните файл, мощный наблюдатель файлов Hugo и компилятор JIT Tailwind будут работать вместе, чтобы за миллисекунды перестроить CSS. Вы должны ощутить удовольствие от автоматической перезагрузки браузера (горячей перезагрузки).

Устранение неполадок: если стили не применяются

Если изменения не отображаются, проверьте следующие пункты:

Настройка путей content в tailwind.config.js Если пути к сканируемым файлам указаны неверно, Tailwind не сможет обнаружить используемые в них классы и не выведет их в CSS. Особенно если вы используете тему, убедитесь, что пути к каталогу темы не пропущены.
Ошибки PostCSS Если в журнале сервера Hugo в терминале появляется ошибка типа Error: failed to transform resource: PostCSS not found, возможно, npm install не был выполнен корректно или отсутствует postcss-cli.
Очистка кэша Hugo В редких случаях кэш Hugo может стать причиной того, что останется старый CSS. Остановите сервер и запустите его с помощью hugo server --ignoreCache или попробуйте удалить временный каталог ОС (например, /tmp/hugo_cache/).

8. Сборка для продакшна и дальнейшие улучшения

При развертывании сайта на рабочем сервере (Netlify, Vercel, GitHub Pages, Cloudflare Pages и т. д.) необходимо настроить переменные окружения и запустить конвейер оптимизации для продакшна.

1
2


# Пример команды для продакшн сборки
NODE_ENV=production hugo --minify --environment production

Добавление флага --environment production приведет к выполнению блока {{ if hugo.IsProduction }} в head.html, где будет выполнена минификация CSS и добавление Fingerprint.

Стилизация Markdown с помощью плагина Typography

На сайтах блогов или документации, таких как Hugo, вы не можете напрямую добавлять классы к чистым HTML-элементам (таким как <h1>, <p>, <ul>), сгенерированным из Markdown. В таких случаях очень полезен официальный плагин Typography от Tailwind.

Установка плагина

1

npm install -D @tailwindcss/typography

Добавление в tailwind.config.js

1
2
3
4
5
6


module.exports = {
 // ...
 plugins: [
 require('@tailwindcss/typography'),
 ],
}

Применение в шаблонах Просто добавьте класс prose (и, по желанию, варианты цвета и размера) к элементу-контейнеру, который выводит текст статьи, и к нему будут применены красивые стили по умолчанию.
1 2 3

<article class="prose prose-lg prose-blue mx-auto mt-10"> {{ .Content }} </article>

Это избавляет от необходимости писать сложные CSS-селекторы (например, .article-content h2 { ... }) вручную, полностью сохраняя модульность компонентов.

9. Заключение: Создание высокоподдерживаемой экосистемы фронтенда

Отличная работа. Теперь у вас есть идеальный конвейер веб-ресурсов, сочетающий сверхбыстрый движок генерации статических сайтов Hugo, современные возможности стилизации Tailwind CSS и расширяемость PostCSS.

Преимущество этой архитектуры в том, что «настраивать нужно только один раз». Как только конвейер будет создан, разработчики смогут создавать сложные пользовательские интерфейсы с невероятной скоростью, просто прописывая интуитивно понятные утилитарные классы в шаблонах HTML или Markdown, даже не открывая CSS-файл.

Кроме того, поскольку размер выходного CSS всегда минимизирован, это напрямую улучшает оценки Core Web Vitals и очень выгодно с точки зрения SEO.

Комбинация Hugo и Tailwind CSS, несомненно, останется одним из «лучших выборов» для любого проекта, от личного технического блога до крупного корпоративного сайта. Обязательно воспользуйтесь этим мощным набором инструментов и наслаждайтесь комфортной веб-разработкой!

Ключевые моменты CSS-проектирования для поддержки темного режима в блоге

Sat, 12 Sep 2026 12:00:00 +0900

В современной веб-разработке поддержка темного режима (Dark Mode) превратилась из просто «приятного дополнения» (Nice to have) в «обязательное требование» (Must have) для улучшения пользовательского опыта (UX). В частности, для медиа, предполагающих длительное чтение текста, таких как блоги и сайты с документацией, важность поддержки темного режима крайне высока, поскольку он снижает нагрузку на глаза пользователей и уменьшает расход заряда батареи устройств.

В этой статье мы глубоко погрузимся в технические проблемы, которых не избежать при внедрении темного режима в блог, и ключевые моменты CSS-проектирования с высокой степенью поддерживаемости с точки зрения фронтенд-инженера. Мы охватим все аспекты реализации темного режима: использование CSS Custom Properties (CSS-переменных), продвинутое управление JavaScript и интеграцию с SSR для предотвращения FOUC (Flash of Unstyled Content), цветовой дизайн (RGB, HSL и новейший OKLCH) для обеспечения доступности (WCAG 2.1 AAA), а также практические примеры кода с использованием Tailwind CSS.

1. Основы проектирования тем с использованием CSS Custom Properties (CSS-переменных)

В настоящее время наиболее стандартным и мощным методом реализации темного режима является подход с использованием CSS Custom Properties (CSS-переменных). В отличие от переменных в CSS-препроцессорах, таких как Sass ($color), которые разрешаются статически во время компиляции, CSS-переменные разрешаются и переопределяются динамически во время выполнения в браузере. Это позволяет мгновенно изменить цветовую гамму всей страницы, просто переключая классы с помощью JavaScript.

1.1 Базовое определение цветовой темы

Во-первых, мы используем псевдокласс :root для определения цветовой палитры светлого режима (по умолчанию). Затем классический паттерн проектирования заключается в переопределении этих переменных при добавлении атрибута, такого как [data-theme='dark'] (или класса .dark).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


/* Определение переменных светлого режима (по умолчанию) */
:root {
 --color-bg-primary: #ffffff;
 --color-bg-secondary: #f3f4f6;
 --color-text-primary: #111827;
 --color-text-secondary: #4b5563;
 --color-accent: #3b82f6;
 --color-border: #e5e7eb;
}

/* Переопределение переменных для темного режима */
[data-theme='dark'] {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
}

/* Фактическое применение */
body {
 background-color: var(--color-bg-primary);
 color: var(--color-text-primary);
 transition: background-color 0.3s ease, color 0.3s ease;
}

a {
 color: var(--color-accent);
}

Таким образом, полностью разделяя определение макета/типографики и цвета (темы), поддерживаемость CSS значительно повышается.

1.2 Использование @media (prefers-color-scheme: dark)

Если темный режим установлен на уровне ОС, с точки зрения UX желательно автоматически применять темную тему с момента первого посещения веб-сайта. Это достигается с помощью медиа-запроса @media (prefers-color-scheme: dark).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* Фолбэк, если в настройках ОС выбран темный режим */
@media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
 }
}

При таком написании переменные переопределяются с учетом настроек темного режима ОС, если только пользователь явно не выбрал светлый режим (data-theme='light').

2. Понимание цветового пространства и доступность (WCAG 2.1 AAA)

При цветовом проектировании для темного режима недостаточно просто «сделать фон черным, а текст белым». Если контраст слишком сильный, это вызовет ореол и усложнит чтение, а если контраст слишком низкий, пострадает видимость. В Web Content Accessibility Guidelines (WCAG) строго определен коэффициент контрастности для обеспечения видимости.

2.1 Формула расчета коэффициента контрастности WCAG

Коэффициент контрастности (Contrast Ratio) $CR$ в WCAG определяется следующим образом с использованием относительной яркости (Relative Luminance) цвета фона и цвета переднего плана.

$$CR = \frac{L_{lighter} + 0.05}{L_{darker} + 0.05}$$

Здесь $L_{lighter}$ — относительная яркость более светлого цвета, а $L_{darker}$ — относительная яркость более темного цвета (диапазон значений от 0.0 до 1.0). Для достижения уровня AAA по стандарту WCAG 2.1 требуется коэффициент контрастности не менее 7:1 для обычного текста и не менее 4.5:1 для крупного текста.

Относительная яркость $L$ рассчитывается по следующей сложной формуле из значений RGB в цветовом пространстве sRGB.

$$L = 0.2126 \times R + 0.7152 \times G + 0.0722 \times B$$

Каждый компонент ($R, G, B$) использует нормализованное значение исходного 8-битного значения ($R_{sRGB}$), деленное на 255, и выполняет следующее преобразование для снятия гамма-коррекции.

$$ R, G, B = \begin{cases} \frac{C_{sRGB}}{12.92} & \text{if } C_{sRGB} \le 0.03928 \\ \left( \frac{C_{sRGB} + 0.055}{1.055} \right)^{2.4} & \text{otherwise} \end{cases} $$

Выполнять этот расчет вручную сложно, но, используя инструменты цветового проектирования, можно механически подобрать цвета, которые удовлетворяют коэффициенту контрастности 7:1 ($CR \ge 7.0$).

2.2 HSL vs RGB vs OKLCH

При создании цветовой палитры раньше доминировали RGB и HSL. Однако они имеют серьезный недостаток с точки зрения «перцептивной однородности» (perceptual uniformity).

RGB: Это механические три основных цвета света, и людям сложно интуитивно вносить коррективы вроде «сделать светлее» или «сделать темнее».
HSL: Использует оттенок (Hue), насыщенность (Saturation) и светлоту (Lightness), но «светлота (L)» в HSL не совпадает с воспринимаемой яркостью человеческим глазом. Например, чистый желтый и чистый синий со светлотой 50% в HSL численно имеют одинаковую яркость, но человеческому глазу желтый кажется значительно ярче.
OKLCH: Это новейшее цветовое пространство, введенное в CSS Color Module Level 4. Оно состоит из светлоты (Lightness — перцептивной яркости), насыщенности (Chroma) и оттенка (Hue), и полностью соответствует зрительным характеристикам человека (перцептивно однородно).

Используя OKLCH, вы можете сохранять ту же перцептивную яркость (Lightness) даже при изменении оттенка (Hue), что делает создание цветовой палитры для темного режима чрезвычайно предсказуемым и безопасным.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


/* Пример определения CSS-переменных с использованием OKLCH */
:root {
 /* Светлый режим: высокая базовая яркость, умеренная насыщенность */
 --bg-base: oklch(0.98 0.01 250);
 --text-base: oklch(0.25 0.02 250);
 --primary-brand: oklch(0.65 0.15 250);
}

[data-theme="dark"] {
 /* В темном режиме просто инвертируем яркость, легче поддерживать перцептивный контраст */
 --bg-base: oklch(0.20 0.02 250);
 --text-base: oklch(0.95 0.01 250);
 --primary-brand: oklch(0.75 0.15 250); /* Слегка осветляем для темного режима для обеспечения видимости */
}

Приняв OKLCH таким образом, можно просто построить логику, гарантирующую согласованный коэффициент контрастности (уровень WCAG AAA) в нескольких темах.

3. Предотвращение FOUC (Flash of Unstyled Content) и SSR гидратация

Наиболее раздражающей проблемой для разработчиков при реализации темного режима является мерцание экрана, известное как FOUC (Flash of Unstyled Content).

3.1 Ловушка переключения тем с помощью клиентского JS

В SPA, таких как React или Vue (или статических сайтах с помощью SSG), распространена практика сохранения пользовательских настроек в localStorage и их чтения с помощью JavaScript для переключения темы. Однако если этот процесс выполняется в useEffect в React или аналогичном хуке, возникают следующие проблемы:

Браузер отрисовывает HTML/CSS светлого режима.
Загружается и выполняется JS-бандл.
Из localStorage считывается настройка dark.
В HTML добавляется класс dark, и экран внезапно темнеет (мерцание).

Лучшая практика для полного предотвращения FOUC и предотвращения ошибок гидратации — это сохранение пользовательских настроек темы в document.cookie и возврат HTML с соответствующими классами, добавленными на этапе серверного рендеринга (SSR).

Следующая диаграмма последовательности иллюстрирует идеальный процесс инициализации темы с использованием Cookie.

sequenceDiagram
participant User as "Пользователь"
participant Browser as "Браузер ОС"
participant Server as "Сервер SSR"
participant DOM as "Клиентский DOM"
User->>Browser: "Запрос страницы"
Browser->>Server: "GET-запрос с Cookie (theme=dark)"
Server-->>Browser: "Возврат HTML с <html data-theme='dark'>"
Browser->>DOM: "Рендеринг начального HTML (Без FOUC)"
DOM->>DOM: "Выполнение скрипта гидратации"
alt "Cookie отсутствует (Первый визит)"
DOM->>Browser: "Проверка OS prefers-color-scheme"
Browser-->>DOM: "Результат matchMedia (например, dark)"
DOM->>DOM: "Установка data-theme='dark' через блокирующий инлайн-скрипт"
end

Для блогов, которые используют только SSG (генерацию статических сайтов) и где SSR невозможен (например, Hugo, Gatsby, статический экспорт Astro), необходимо разместить блокирующий инлайн-скрипт JavaScript внутри тега <head> для добавления класса непосредственно перед отрисовкой DOM.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- Размещается в конце тега <head> -->
<script>
 (function() {
 try {
 var localTheme = localStorage.getItem('theme');
 var osTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 var theme = localTheme || osTheme;
 document.documentElement.setAttribute('data-theme', theme);
 } catch (e) {}
 })();
</script>

Поскольку этот небольшой скрипт блокирует рендеринг браузера и выполняется немедленно, атрибут data-theme уже установлен к моменту отрисовки экрана, что полностью предотвращает мерцание экрана (FOUC).

4. Подходы к реализации с использованием Tailwind CSS и чистого SCSS/CSS

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

4.1 Темный режим в Tailwind CSS

Tailwind CSS предоставляет вариант dark: по умолчанию, что делает реализацию темного режима чрезвычайно простой. Вы настраиваете свойство darkMode в конфигурационном файле (tailwind.config.js).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// tailwind.config.js
module.exports = {
 // 'media' (зависит от настроек ОС) или 'class' (переключается вручную)
 darkMode: 'class',
 theme: {
 extend: {
 colors: {
 /* Расширение цветовой палитры Tailwind с использованием CSS-переменных */
 primary: 'rgb(var(--color-primary) / <alpha-value>)',
 background: 'rgb(var(--color-background) / <alpha-value>)',
 }
 }
 }
}

На стороне HTML вы просто добавляете классы следующим образом:

1
2
3
4


<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
 <h1 class="text-2xl font-bold">Hello World</h1>
 <p class="mt-2">Tailwind makes dark mode incredibly easy.</p>
</div>

Однако, написание dark:bg-xxx для каждого элемента может привести к раздуванию компонентов. В крупных блогах или приложениях рекомендуется гибридный подход (семантический цветовой дизайн), где CSS-переменные служат основой, а Tailwind ссылается на эти CSS-переменные.

Ниже представлена диаграмма классов, показывающая наследование CSS-переменных и уровни применения.

classDiagram
class GlobalCSSVariables {
"--color-brand-500"
"--color-gray-900"
}
class SemanticVariables {
"--bg-primary"
"--text-base"
"--accent"
}
class TailwindConfig {
"theme.colors.background"
"theme.colors.primary"
}
class UIComponents {
"class='bg-background text-primary'"
}
GlobalCSSVariables <|-- SemanticVariables : ":root & .dark"
SemanticVariables <|-- TailwindConfig : "tailwind.config.js"
TailwindConfig <.. UIComponents : "Применяет утилитарные классы"

4.2 Реализация на чистом SCSS/CSS (Использование примесей/Mixin)

В проектах, которые не используют Tailwind, а пишут собственные SCSS, стили темного режима инкапсулируются с помощью @mixin.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


/* Определение SCSS Mixin */
@mixin dark-mode {
 /* Поддерживает как атрибут [data-theme='dark'], так и настройки ОС */
 [data-theme='dark'] & {
 @content;
 }
 @media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) & {
 @content;
 }
 }
}

/* Пример использования */
.card {
 background-color: #ffffff;
 color: #333333;
 border: 1px solid #eeeeee;

 @include dark-mode {
 background-color: #1a202c;
 color: #e2e8f0;
 border-color: #2d3748;
 }
}

Хотя этот метод интуитивно понятен, скомпилированный файл CSS имеет тенденцию раздуваться (поскольку медиа-запросы дублируются для каждого селектора), поэтому современным трендом является переход к дизайну, ориентированному на CSS-переменные (Custom Properties).

5. Оптимизация изображений (Image) и SVG для темного режима

Даже если цветовой дизайн текста и фона завершен, если изображения и иконки (SVG), размещенные в качестве контента, останутся в светлом режиме, они будут выглядеть слишком яркими и неуместными в темном режиме. Оптимизация этих элементов также имеет важное значение.

5.1 CSS-фильтры для снижения яркости изображений

Растровые изображения, такие как фотографии, могут быть слишком яркими, если они отображаются как есть в темном режиме. Используя свойство CSS filter для незначительного снижения яркости (brightness) и контрастности (contrast) изображений, вы можете заставить их естественным образом сливаться с пользовательским интерфейсом темной темы.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[data-theme='dark'] img:not([src*=".svg"]) {
 /* Уменьшаем яркость, немного увеличиваем контраст */
 filter: brightness(0.8) contrast(1.1);
 transition: filter 0.3s ease;
}

[data-theme='dark'] img:hover {
 /* Возвращаем исходную яркость при наведении (если пользователь хочет рассмотреть детали) */
 filter: brightness(1) contrast(1);
}

5.2 Переключение изображений с помощью тега `<picture>`

Изображения логотипов и пояснительные схемы (например, JPEG с фиксированным белым фоном) не могут быть адаптированы только с помощью фильтров. В этом случае правильным подходом будет использование элемента HTML <picture> и медиа-запросов для предоставления отдельного файла изображения для темного режима.

1
2
3
4
5
6


<picture>
 <!-- Показывать это пользователям с настройками ОС в темном режиме -->
 <source srcset="/img/logo-dark.png" media="(prefers-color-scheme: dark)">
 <!-- По умолчанию (светлый режим) -->
 <img src="/img/logo-light.png" alt="Логотип сайта">
</picture>

※ Однако этот метод не связан с ручным переключением через localStorage и т.д. (он зависит только от настроек ОС). Поэтому, если вы реализуете ручное переключение, вам нужно либо динамически переписывать атрибут src изображений с помощью JS, либо переключать display: none с помощью CSS-классов.

5.3 Использование `currentColor` для SVG-иконок

Самый элегантный способ работы с инлайн-SVG, используемыми для иконок, — это связать цвет заливки с цветом текста родительского элемента. Задайте currentColor для атрибутов fill или stroke в SVG.

1
2
3
4


<!-- Значение свойства CSS color (например, var(--text-primary)) применяется автоматически -->
<svg viewBox="0 0 24 24" fill="currentColor">
 <path d="M12 2L2 22h20L12 2z" />
</svg>

Благодаря этому, когда включается темный режим и цвет текста родительского элемента становится светлым/белым, SVG-иконка также автоматически меняется на светлый/белый.

6. Заключение: К устойчивому проектированию темного режима

Чтобы реализовать качественный темный режим в блоге или веб-приложении, необходимо CSS-проектирование, охватывающее следующие ключевые моменты:

Использование CSS Custom Properties: Избегайте жесткого кодирования (хардкода) цветов и абстрагируйте их в семантические имена переменных (например, --bg-primary).
Принятие цветового пространства OKLCH: Логическое проектирование высокодоступного коэффициента контрастности (7:1 или выше), соответствующего WCAG 2.1 AAA, в перцептивно однородном цветовом пространстве.
Строгие меры предотвращения FOUC: Полное устранение мерцания экрана при начальной загрузке путем связывания SSR и Cookie или блокирующего инлайн-скрипта в <head>.
Оптимизация медиа и ассетов: Использование filter: brightness(), currentColor и тегов <picture>, чтобы нетекстовые элементы гармонировали с темной темой.

Можно сказать, что эти тщательные соображения, выходящие за рамки простого «инвертирования цветов», являются отличительной чертой современного блога, который обеспечивает превосходный опыт чтения, любим пользователями в течение долгого времени и меньше утомляет глаза. Разработчикам, которые собираются внедрять темный режим, обязательно стоит использовать паттерны проектирования из этой статьи в качестве справочного материала.

Основы архитектуры программного обеспечения: что такое Чистая архитектура?

Sat, 12 Sep 2026 12:00:00 +0900

В современной разработке программного обеспечения создание “устойчивых к изменениям систем” является вечной проблемой. Изменение бизнес-требований, появление новых фреймворков, обновление UI, миграция баз данных. Для всех этих изменений требуется архитектура, которая может гибко адаптироваться без перестройки всей системы. Одним из ответов на этот вызов является Чистая архитектура (Clean Architecture), предложенная Робертом С. Мартином (известным как Дядя Боб, Uncle Bob).

В этой статье мы раскроем суть Чистой архитектуры через её историю, цели, детали четырех слоев, правило зависимостей и конкретные примеры реализации. Мы проведем очень глубокий и подробный технический разбор.

1. Проблемы традиционных архитектур и история Чистой архитектуры

Исторически архитектура программного обеспечения претерпела различные смены парадигм. В ранних системах бизнес-логика, пользовательский интерфейс и код доступа к данным были тесно связаны (так называемый спагетти-код). Позже, с целью разделения ответственности (Separation of Concerns), получила распространение трехзвенная архитектура (слой представления, слой бизнес-логики, слой доступа к данным).

Однако традиционная трехзвенная архитектура имела серьезную проблему. Она заключалась в том, что “домен (бизнес-логика) зависел от базы данных и фреймворков”.

Например, если слой бизнес-логики напрямую вызывает слой доступа к данным (такой как ORM), то изменения в схеме базы данных или изменения в ORM распространяются на бизнес-логику. Иными словами, возникало противоречие, при котором наиболее важные “бизнес-правила”, которые не должны изменяться, зависели от “инфраструктуры”, которая наиболее подвержена техническим изменениям.

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

Гексагональная архитектура (Ports and Adapters) - Alistair Cockburn
Луковая архитектура (Onion Architecture) - Jeffrey Palermo
DCI (Data, Context and Interaction) - James Coplien, Trygve Reenskaug
BCE (Boundary-Control-Entity) - Ivar Jacobson

Все эти архитектуры преследуют одну и ту же цель. И это “разделение ответственности”. Оно заключается в разделении программного обеспечения на слои, каждый из которых можно тестировать независимо, создавая состояние, в котором они независимы от внешних агентов (UI, БД, фреймворки).

Роберт С. Мартин интегрировал концепции этих выдающихся архитектур и объединил их в одно практическое правило, назвав его “Чистой архитектурой”.

2. Цели и характеристики Чистой архитектуры

Системы, использующие Чистую архитектуру, обладают следующими характеристиками:

Независимость от фреймворков (Independent of Frameworks): Архитектура не зависит от существования многофункциональных библиотек программного обеспечения. Это позволяет использовать фреймворки как “инструменты”, и нет необходимости втискивать систему в их ограничения.
Тестируемость (Testable): Бизнес-правила могут тестироваться без UI, базы данных, веб-сервера или других внешних элементов.
Независимость от UI (Independent of UI): Пользовательский интерфейс можно легко изменить без изменения остальной части системы. Например, веб-интерфейс можно заменить консольным интерфейсом без изменения бизнес-правил.
Независимость от базы данных (Independent of Database): Oracle или SQL Server можно заменить на Mongo, BigTable, CouchDB и так далее. Бизнес-правила не привязаны к базе данных.
Независимость от любых внешних агентов (Independent of any external agency): Фактически, бизнес-правила ничего не знают о внешнем мире.

3. Четыре слоя Чистой архитектуры (Layers)

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

graph TD
subgraph "Внешние интерфейсы (Фреймворки и Драйверы)"
A["Web"]
B["UI"]
C["База данных"]
D["Внешние API"]
end
subgraph "Адаптеры интерфейсов"
E["Контроллеры"]
F["Шлюзы"]
G["Презентеры"]
end
subgraph "Бизнес-правила приложения (Варианты использования)"
H["Интеракторы вариантов использования"]
end
subgraph "Корпоративные бизнес-правила (Сущности)"
I["Сущности"]
end
A --> E
B --> E
C --> F
D --> F
E --> H
F --> H
G --> H
H --> I

3.1. Сущности (Entities)

Сущности инкапсулируют корпоративные бизнес-правила (Enterprise Business Rules). Сущность может быть объектом с методами или набором структур данных и функций. Это самые общие и высокоуровневые правила, которые можно повторно использовать во множестве различных приложений компании. Даже если вы создаете только одно приложение, сущности являются бизнес-объектами этого приложения. Сущности никогда не подвергаются влиянию внешних изменений (таких как изменение навигации по страницам или изменения в безопасности).

3.2. Варианты использования (Use Cases)

Слой вариантов использования содержит специфичные для приложения бизнес-правила (Application Business Rules). Здесь инкапсулируются и реализуются все варианты использования системы. Варианты использования управляют потоком данных к сущностям и от них, а также предписывают сущностям достигать целей системы. Изменения в этом слое не должны влиять на сущности. Аналогично, внешние изменения, такие как изменения в базе данных, UI или фреймворках, не влияют на этот слой. Варианты использования полностью изолированы от этих аспектов.

3.3. Адаптеры интерфейсов (Interface Adapters)

Слой адаптеров интерфейсов представляет собой набор адаптеров, которые преобразуют данные из форматов, наиболее удобных для вариантов использования и сущностей, в форматы, удобные для внешних агентов, таких как базы данных или веб. Например, элементы архитектуры MVC (Model-View-Controller) для графических интерфейсов в веб-среде принадлежат именно этому слою. Контроллеры принимают пользовательский ввод, передают его в варианты использования, а презентеры получают вывод от вариантов использования и форматируют его для представления (UI). Кроме того, задачей этого слоя является преобразование данных в формат, понятный базе данных (например, SQL). Код внутри этого слоя не должен ничего знать о базе данных.

3.4. Фреймворки и драйверы (Frameworks & Drivers)

Самый внешний слой состоит из таких инструментов, как базы данных и веб-фреймворки. Обычно здесь пишется не так много кода, кроме “связующего кода” (glue code) для взаимодействия со внутренними кругами. В этом слое хранятся все детали. Веб — это деталь. База данных — это деталь. Чтобы минимизировать ущерб, мы располагаем эти детали снаружи.

4. Правило зависимостей (The Dependency Rule)

Существует самое важное правило, которое делает Чистую архитектуру возможной и которое ни в коем случае нельзя нарушать. Это “Правило зависимостей (The Dependency Rule)”.

Зависимости в исходном коде должны быть направлены только внутрь (к политикам более высокого уровня).

Код, принадлежащий внутренним кругам, не должен ничего знать о коде, принадлежащем внешним кругам. Имена (функции, классы, переменные и т.д.), объявленные во внешних кругах, не должны упоминаться во внутренних кругах. Аналогично, форматы данных, используемые во внешних кругах, не должны использоваться во внутренних. Особенно это касается случаев, когда такие форматы генерируются фреймворком из внешнего круга.

graph LR
A["Фреймворки и Драйверы"] -->| Зависит | B["Адаптеры интерфейсов"]
B -->| Зависит | C["Варианты использования"]
C -->| Зависит | D["Сущности"]
style A fill:#f9f9f9,stroke:#333,stroke-width:2px
style B fill:#e6f7ff,stroke:#333,stroke-width:2px
style C fill:#fff0f6,stroke:#333,stroke-width:2px
style D fill:#f6ffed,stroke:#333,stroke-width:2px

Выражаясь математически, если индекс слоя обозначить как $L_i$, где $i=0$ — это сущности (самый внутренний слой), а $i=3$ — фреймворки (самый внешний слой), то в случае существования зависимости от слоя $L_m$ к $L_n$ обязательно должно выполняться следующее неравенство:

$$ m > n $$

Иными словами, вектор зависимости $\vec{D}$ всегда направлен к центру.

5. Пересечение границ: Принцип инверсии зависимостей (DIP)

При попытке соблюсти правило зависимостей мы быстро сталкиваемся с одной серьезной проблемой: “Что делать, если варианту использования необходимо получить данные из базы данных?”

Если слой вариантов использования (внутренний) напрямую вызывает слой адаптеров интерфейсов (внешняя реализация Repository), то зависимость будет направлена наружу, что является нарушением правила зависимостей.

Для решения этой проблемы используется принцип “D” из принципов SOLID (Dependency Inversion Principle: Принцип инверсии зависимостей).

Определение принципа инверсии зависимостей (DIP)

Модули верхних уровней не должны зависеть от модулей нижних уровней. Оба типа модулей должны зависеть от абстракций.
Абстракции не должны зависеть от деталей. Детали должны зависеть от абстракций.

Чтобы реализовать это, мы определяем интерфейс (абстракцию) в слое вариантов использования и реализуем этот интерфейс во внешнем слое (адаптерах интерфейсов). Слой вариантов использования зависит только от интерфейса, который он сам определил, и не зависит от конкретных реализаций во внешних слоях.

classDiagram
class UseCaseInteractor {
- UserRepository repository
+ execute()
}
class UserRepository {
<<Interface>>
+ findById(id)
+ save(user)
}
class UserRepositoryImpl {
+ findById(id)
+ save(user)
}
UseCaseInteractor --> UserRepository : "Зависит от"
UserRepositoryImpl ..|> UserRepository : "Реализует"
note for UseCaseInteractor "Внутренний слой (Варианты использования)"
note for UserRepository "Внутренний слой (Варианты использования)"
note for UserRepositoryImpl "Внешний слой (Адаптеры интерфейсов)"

На приведенной выше диаграмме поток управления (Control Flow) во время выполнения идет от UseCaseInteractor $\rightarrow$ UserRepositoryImpl. Однако зависимость в исходном коде (Source Code Dependency) идет от UserRepositoryImpl $\rightarrow$ UserRepository (внутрь). Используя полиморфизм, мы смогли направить зависимость в исходном коде в сторону, противоположную потоку управления. Именно поэтому это называется “инверсией зависимостей”.

6. Конкретный пример реализации на TypeScript

Здесь мы покажем простой пример реализации Чистой архитектуры (функция регистрации пользователя) с использованием TypeScript.

6.1. Сущности (Entities)

Это самые центральные бизнес-правила.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// src/domain/entities/User.ts
export class User {
 constructor(
 public readonly id: string,
 public readonly name: string,
 public readonly email: string,
 public readonly createdAt: Date
 ) {}

 // Специфичные бизнес-правила сущности (например: проверка длины имени и т.д.)
 public isValid(): boolean {
 return this.name.length >= 3 && this.email.includes('@');
 }
}

6.2. Варианты использования (Use Cases)

В слое вариантов использования мы определяем структуры данных ввода и вывода (DTO), а также интерфейс репозитория для инверсии зависимостей.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


// src/application/repositories/UserRepository.ts
import { User } from '../../domain/entities/User';

// Интерфейс, определяемый слоем вариантов использования
export interface UserRepository {
 findByEmail(email: string): Promise<User | null>;
 save(user: User): Promise<void>;
}

// src/application/usecases/RegisterUser/RegisterUserDTO.ts
export interface RegisterUserInputDTO {
 name: string;
 email: string;
}

export interface RegisterUserOutputDTO {
 id: string;
 name: string;
 email: string;
 createdAt: Date;
}

// src/application/usecases/RegisterUser/RegisterUserUseCase.ts
import { User } from '../../domain/entities/User';
import { UserRepository } from '../../repositories/UserRepository';
import { RegisterUserInputDTO, RegisterUserOutputDTO } from './RegisterUserDTO';

export class RegisterUserUseCase {
 // Зависит от абстракции (интерфейса). Не зависит от конкретной реализации.
 constructor(private readonly userRepository: UserRepository) {}

 public async execute(input: RegisterUserInputDTO): Promise<RegisterUserOutputDTO> {
 const existingUser = await this.userRepository.findByEmail(input.email);
 if (existingUser) {
 throw new Error('User already exists');
 }

 const newUser = new User(
 crypto.randomUUID(),
 input.name,
 input.email,
 new Date()
 );

 if (!newUser.isValid()) {
 throw new Error('Invalid user data');
 }

 // Вызываем процесс сохранения в БД во внешнем слое, но зависимость направлена внутрь (на интерфейс)
 await this.userRepository.save(newUser);

 return {
 id: newUser.id,
 name: newUser.name,
 email: newUser.email,
 createdAt: newUser.createdAt
 };
 }
}

6.3. Адаптеры интерфейсов (Interface Adapters)

Здесь мы создаем конкретную обработку доступа к базе данных (реализация Repository) и контроллер для обработки HTTP-запросов.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


// src/adapters/repositories/PostgresUserRepository.ts
import { UserRepository } from '../../application/repositories/UserRepository';
import { User } from '../../domain/entities/User';
// Предполагается клиент БД, являющийся внешним слоем (Driver)
import { DatabaseClient } from '../../infrastructure/database/DatabaseClient';

export class PostgresUserRepository implements UserRepository {
 constructor(private readonly dbClient: DatabaseClient) {}

 public async findByEmail(email: string): Promise<User | null> {
 const record = await this.dbClient.query('SELECT * FROM users WHERE email = $1', [email]);
 if (!record) return null;
 return new User(record.id, record.name, record.email, record.created_at);
 }

 public async save(user: User): Promise<void> {
 await this.dbClient.query(
 'INSERT INTO users (id, name, email, created_at) VALUES ($1, $2, $3, $4)',
 [user.id, user.name, user.email, user.createdAt]
 );
 }
}

// src/adapters/controllers/UserController.ts
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';

export class UserController {
 constructor(private readonly registerUserUseCase: RegisterUserUseCase) {}

 public async register(req: any, res: any): Promise<void> {
 try {
 const input = {
 name: req.body.name,
 email: req.body.email
 };
 const output = await this.registerUserUseCase.execute(input);
 res.status(201).json(output);
 } catch (error: any) {
 res.status(400).json({ message: error.message });
 }
 }
}

6.4. Главный компонент (Внедрение зависимостей: DI)

При запуске приложения мы собираем (связываем) все зависимости. Это называется Корень композиции (Composition Root).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


// src/infrastructure/web/server.ts
import express from 'express';
import { DatabaseClient } from '../database/DatabaseClient';
import { PostgresUserRepository } from '../../adapters/repositories/PostgresUserRepository';
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';
import { UserController } from '../../adapters/controllers/UserController';

const app = express();
app.use(express.json());

// 1. Инициализация драйвера
const dbClient = new DatabaseClient(/* Данные для подключения */);

// 2. Инициализация адаптера (создание экземпляра конкретного класса)
const userRepository = new PostgresUserRepository(dbClient);

// 3. Инициализация варианта использования (внедрение конкретной реализации в интерфейс = DI)
const registerUserUseCase = new RegisterUserUseCase(userRepository);

// 4. Инициализация контроллера
const userController = new UserController(registerUserUseCase);

// Маршрутизация
app.post('/users', (req, res) => userController.register(req, res));

app.listen(3000, () => {
 console.log('Server is running on port 3000');
});

Таким образом, создавая структуру, в которой самый внешний “скрипт запуска” берет на себя грязные детали (создание экземпляров конкретных классов) и передает во внутренние слои только чистые интерфейсы, мы полностью изолируем бизнес-логику от внешнего мира.

7. Математическое рассмотрение связности и сцепления

В программной инженерии в качестве метрик оценки качества архитектуры используются связность (Coupling) и сцепление (Cohesion).

Связность $C$ представляет собой силу зависимости между модулями. Если модуль $A$ зависит от модуля $B$, то, обозначив общее количество зависимостей в системе как $N_{dep}$ и количество модулей как $N_{mod}$, один из показателей сложности можно выразить следующим образом:

$$ Complexity \propto \frac{N_{dep}}{N_{mod}} $$

В Чистой архитектуре применение DIP позволяет направить стрелки физических зависимостей в сторону абстракций. Абстракции (интерфейсы) проектируются так, чтобы частота их изменений (Нестабильность: $I$) была крайне низкой.

Нестабильность (Instability) $I$ вычисляется по следующей формуле (определение Роберта С. Мартина):

$C_e$ (Efferent Coupling): Исходящая связность (количество сущностей, от которых зависим мы)
$C_a$ (Afferent Coupling): Входящая связность (количество сущностей, которые зависят от нас)

$$ I = \frac{C_e}{C_e + C_a} $$

В случае $I = 0$, компонент абсолютно стабилен (ни от кого не зависит, но от него зависят другие).
В случае $I = 1$, компонент абсолютно нестабилен (от него никто не зависит, но он зависит от других).

В Чистой архитектуре “слой сущностей” имеет $C_e = 0$ (не зависит от внешнего мира), поэтому $I = 0$. То есть это самый стабильный слой. И наоборот, “слой UI” или “слой БД” имеют $C_a \approx 0$ и $C_e > 0$, поэтому их $I \approx 1$, что делает их легко изменяемыми (нестабильными слоями).

Важный принцип архитектуры SDP (Stable Dependencies Principle: Принцип стабильных зависимостей) гласит, что “зависимости должны быть направлены в сторону более стабильных компонентов (компонентов с меньшим значением $I$)”. Концентрические круги Чистой архитектуры — это как раз визуализация данного SDP; они спроектированы так, чтобы зависимости были направлены снаружи ($I=1$) внутрь ($I=0$).

8. Стратегия тестирования и Чистая архитектура

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

8.1. Тестирование сущностей (Модульное тестирование / Unit Test)

Поскольку это чистая логика без каких-либо внешних зависимостей, не нужны ни база данных, ни моки (mocks). Это самые быстрые и надежные тесты.

8.2. Тестирование вариантов использования (Unit Test with Mocks)

Поскольку все внешние зависимости, такие как репозитории, определены как интерфейсы, при тестировании достаточно внедрить (через DI) моки для тестирования или реализации в памяти (Fake). Нет необходимости запускать реальную базу данных. Это позволяет быстро тестировать сложные ветвления и обработку исключений в бизнес-логике.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// Пример тестирования варианта использования (предполагается Jest)
test('Возвращает ошибку при попытке регистрации с существующим адресом электронной почты', async () => {
 // Создание Fake репозитория
 const mockRepo: UserRepository = {
 findByEmail: async (email) => new User('1', 'Test', email, new Date()), // Возвращает существующего пользователя
 save: async (user) => {}
 };

 const useCase = new RegisterUserUseCase(mockRepo);

 // Выполнение варианта использования и проверка на ошибку
 await expect(useCase.execute({ name: 'Bob', email: 'test@example.com' }))
 .rejects
 .toThrow('User already exists');
});

8.3. Тестирование адаптеров (Интеграционное тестирование / Integration Test)

Классы реализации репозиториев фактически подключаются к базе данных для тестирования правильности SQL. Тесты контроллеров проверяют получение HTTP-запросов и возврат JSON. Здесь не проводится детальная проверка бизнес-логики; подтверждается лишь корректность “преобразования” и “коммуникации”.

9. Недостатки Чистой архитектуры и когда её следует применять

Хотя Чистая архитектура кажется универсальной, она не является серебряной пулей. Существуют следующие недостатки (компромиссы):

Увеличение первоначальных затрат на обучение и разработку: Значительно увеличивается количество файлов и интерфейсов (абстракций). Появляется много “шаблонного кода” (boilerplate code), такого как перекладывание данных из одних DTO в другие.
Избыточность для небольших проектов (Overkill): Применение этой архитектуры в прототипах, которые создаются за несколько дней, или в разовых инструментах, где почти не бывает изменений, часто является пустой тратой ресурсов. Она также не подходит для простых API, состоящих только из CRUD-операций.

Когда следует применять:

Продукты, которые планируется поддерживать и эксплуатировать в течение длительного периода (несколько лет и более).
Системы со сложными бизнес-правилами и частыми изменениями спецификаций.
Когда необходимо разделить работу (фронтенд, бэкенд, инфраструктура и т.д.) в большой команде разработчиков.
При необходимости моделирования сложных бизнес-областей в сочетании с предметно-ориентированным проектированием (DDD: Domain-Driven Design).

10. Заключение

Чистая архитектура — это философия проектирования, предназначенная для защиты ядра системы, то есть “бизнес-правил”, от таких “деталей”, как UI, базы данных и фреймворки.

В её основе лежат Правило зависимостей и Принцип инверсии зависимостей (DIP). При правильном применении этих правил программное обеспечение становится гибким к изменениям, легко тестируемым и способным сохранять свою ценность на протяжении длительного времени.

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

Источник: “Clean Architecture: A Craftsman’s Guide to Software Structure and Design”, Robert C. Martin