Tune IT

Strapi в эпоху AI-coding: почему dev-first CMS выигрывает

2026-06-10T09:31:36Z

Состояние рынка

Headless CMS перестал быть нишевой темой. Рынок оценивается в $3,94 млрд в 2026 году и прогнозируется к росту до $22 млрд к 2034-му (CAGR >21%). Для большинства команд это уже инфраструктурное, а не инструментальное решение.

Рынок сложился в два лагеря:

Enterprise-Grade Orchestrators — Contentful, Sanity, Kontent.ai. Проприетарные SaaS-платформы с высоким ценовым порогом, позиционирующие себя как «Composable DXP» или «Content Operating System». Высокий уровень managed-сервисов, global CDN из коробки, но данные живут у провайдера.

Developer-Owned Backends — Strapi, Payload CMS. Open-source, self-hosted, максимальный контроль над инфраструктурой. Strapi — самый популярный headless CMS с открытым исходным кодом по числу GitHub-звёзд и задокументированных enterprise-деплойментов.

Что такое Strapi

Strapi — headless CMS на Node.js с MIT-лицензией. Self-hosted Community Edition полностью бесплатен.

Ключевые параметры платформы:

API: REST и GraphQL генерируются автоматически для каждого content type. OpenAPI v3 spec с v5.20
База данных: PostgreSQL (рекомендован для production), MySQL/MariaDB, SQLite. Только SQL — намеренный выбор под реляционную enterprise-инфраструктуру
TypeScript: 100% кодовая база с Strapi 5, сборка через Vite
i18n, Draft/Publish, версионирование контента — из коробки

Архитектура: схема как код

Главное архитектурное решение Strapi — content type как файл в репозитории. Каждый тип — это schema.json, который версионируется в git, открыт для диффа в PR и читаем любым инструментом.

// src/api/article/content-types/article/schema.json
{
  "kind": "collectionType",
  "options": { "draftAndPublish": true },
  "attributes": {
    "title":   { "type": "string", "required": true },
    "slug":    { "type": "uid", "targetField": "title" },
    "content": { "type": "richtext" },
    "author":  { "type": "relation", "relation": "manyToOne", "target": "plugin::users-permissions.user" }
  }
}

Из этой схемы Strapi автоматически генерирует полный CRUD-слой. REST-эндпоинт поддерживает фильтрацию, сортировку, пагинацию и populate для связей:

GET /api/articles?filters[author][username][$eq]=john&populate[author][fields][0]=username&sort=createdAt:desc&pagination[pageSize]=10

Тот же запрос через GraphQL — через /graphql, который подключается одним плагином.

Кастомная бизнес-логика

Lifecycle hooks перехватывают события без написания отдельных эндпоинтов:

// src/api/article/content-types/article/lifecycles.ts
export default {
  async beforeCreate(event) {
    const { data } = event.params;
    if (!data.slug && data.title) {
      data.slug = slugify(data.title, { lower: true });
    }
  },
};

Кастомные роуты добавляются декларативно:

// src/api/article/routes/custom-article.ts
export default {
  routes: [
    { method: 'GET', path: '/articles/trending', handler: 'article.findTrending',
      config: { policies: ['global::is-authenticated'] } },
  ],
};

Официальный @strapi/sdk-js генерирует типизированные клиентские методы из OpenAPI-спецификации инстанса — IntelliSense и type narrowing без ручных деклараций.

Почему dev-first архитектура выигрывает у AI-агентов

Это принципиальный момент для современного рабочего процесса.

AI-агенты (Claude Code, Cursor, Copilot Workspace) работают с файловой системой и документацией. Когда схема контента существует как JSON-файл в репозитории, агент может прочитать её, добавить поле, написать lifecycle hook и сгенерировать seed-скрипт — всё в рамках одного PR без выхода в браузер.

В CMS с UI-first архитектурой (Contentful и подобных) схема живёт только в базе данных провайдера. Агент вынужден делать аутентифицированные API-вызовы к Management API, не имея статического контекста. Это не техническое ограничение — это архитектурное.

Задача	Strapi	UI-first SaaS
Прочитать схему	JSON из репозитория	API-вызов к провайдеру
Добавить поле	Редактирование файла	POST к Management API
Добавить логику	Lifecycle hook в TS	Отдельная Lambda/Function
Ревью изменений	git diff в PR	Только в UI провайдера

Strapi AI и MCP

В 2025 году Strapi выпустил Strapi AI — генерацию content models из текстового промпта или Figma-дизайна. Параллельно разрабатывается нативный MCP-сервер, который позволяет AI-ассистентам управлять схемой через Model Context Protocol. Пока он в разработке, доступен community-плагин @sensinum/strapi-plugin-mcp.

Документация публикует специальные файлы: llms.txt, llms-full.txt, llms-code.txt — структурированный, токен-экономный контекст для RAG-систем и IDE-агентов.

Сравнение с конкурентами

	Strapi	Contentful	Sanity	Payload
Лицензия	MIT	Проприетарный	Проприетарный	MIT
Self-hosting	Да	Нет	Да	Да
Schema as code	JSON в git	API-only	TypeScript	TypeScript
MCP-поддержка	plugin + roadmap	Нет	Нативный	Да
DB freedom	SQL (PG/MySQL)	Vendor	Vendor	PG/MongoDB/SQLite
Цена (managed)	Бесплатно / $18+	$300+/мес	$15+/мес	Бесплатно
Admin UI зрелость	Высокая	Высокая	Высокая (Studio)	Базовая

Payload CMS — ближайший конкурент в open-source нише. Устанавливается прямо в Next.js-приложение и работает внутри App Router. Figma приобрела Payload в июне 2025 года, MIT-лицензия сохранена. Если проект Next.js-first и минимальный network overhead важен — Payload стоит рассматривать наравне со Strapi.

Contentful — правильный выбор для global enterprise с требованиями к SLA, managed CDN и zero-ops. Ценовой порог отражает реальную стоимость этих гарантий.

Sanity выигрывает на real-time collaboration и кастомизации редактора через Portable Text.

Self-hosting: что нужно учесть

Strapi в production стандартно деплоится за reverse proxy (Cloudflare, nginx) с frontend на Vercel/Netlify. Для медиа нужен отдельный CDN (S3 + CloudFront или аналог) — Strapi не предоставляет его из коробки.

Для multi-region деплоймента придётся самостоятельно проектировать топологию репликации и кэширования. Именно это managed-платформы берут на себя за деньги.

Честно про миграции: upgrade между major-версиями Strapi исторически требует значительных усилий. Переход v4 → v5 не исключение. Это нужно учитывать при оценке long-term стоимости ownership.

Когда выбирать Strapi

Сценарий	Вывод
Data sovereignty, GDPR/HIPAA compliance, self-hosted	Strapi
Code-first команда, схема в git, CI/CD пайплайн	Strapi
AI-агенты работают с кодовой базой	Strapi
Ограниченный бюджет, нужен production-ready CMS	Strapi (MIT)
Next.js-monorepo, минимальный инфраструктурный overhead	→ Payload
Global CDN, 99.99% SLA, zero-ops	→ Contentful
Real-time collaboration редакторов	→ Sanity

Dev-first архитектура была преимуществом удобства. В мире, где AI-агенты читают, пишут и изменяют кодовую базу напрямую, она стала архитектурным преимуществом: инструменты работают с кодом, а не с UI провайдера.

Именованное деструктурирование в Kotlin

2026-06-10T07:30:12Z

Доброго дня! Сегодня поговорим об одной из экспериментальных фич Kotlin, а именно о деструктурировании.

Проблема

Деструктурирование в Kotlin - удобная вещь. Всё работает через сгенерированные методы componentN(), и синтаксис получается приятным:

data class User(val name: String, val age: Int)
 
val user = User("Max", 23)
val (name, age) = user
println("$name is $age years old")

Но за этим удобством скрывается ловушка. Деструктурирование позиционное - значит, name получает значение component1(), age - component2(). И если кто-то решит переставить поля местами или добавить новое поле в начало класса:

data class User(val id: Long, val name: String, val age: Int)

Компилятор не выдаст ошибку, код соберётся - просто name теперь будет содержать id, а age - name. Ещё хуже ситуация с интерфейсами: деструктурировать объект через интерфейс нельзя, потому что componentN() объявляется только в data class.

В Kotlin 2.3.20 появилась экспериментальная поддержка именованного деструктурирования. Идея простая: вместо позиций используем имена свойств, а синтаксис разделяется на два вида.

Именованное деструктурирование - круглые скобки:

val (val name, val age) = user

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

val (val years = age, val theName = name) = user
println("$theName is $years years old")

Позиционное деструктурирование - квадратные скобки:

val [x, y] = point

Таким образом разработчики чётко разделили намерение: если хочешь по именам, то используй (), но если хочешь по позициям - то будь добр, используй [].

Деструктурирование через интерфейс

Это пожалуй самое интересное. Теперь можно деструктурировать через интерфейс, если свойства в нём объявлены:

interface Named {
    val name: String
    val age: Int
}
 
data class User(override val name: String, override val age: Int) : Named
 
fun printInfo(entity: Named) {
    val (val name, val age) = entity
    println("$name is $age")
}

Раньше такой код просто не компилировался. Теперь компилятор ищет свойство по имени и находит его в интерфейсе.

Поддержка экспериментальная, поэтому включается флагом компилятора:

-Xname-based-destructuring=only-syntax

Для Gradle:

kotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xname-based-destructuring=only-syntax")
    }
}

Итог

Именованное деструктурирование - небольшое, но важное изменение. Оно убирает целый класс тихих ошибок, которые легко допустить при рефакторинге, и открывает деструктурирование для интерфейсов. Синтаксис с () и [] хорошо передаёт намерение.

Если вы активно используете деструктурирование в data-классах - стоит уже сейчас попробовать новый синтаксис и пробежаться по коду.

Микроанимация в интерфейсах: Как сделать цифровой продукт живым, понятным и комфортным

2026-06-08T21:09:03Z

Представьте, что вы нажимаете на кнопку в приложении, и... ничего не происходит. Тишина. Кнопка даже не меняет цвет. Возникло ли ощущение, что вы сделали что-то не так? Или что приложение «зависло»?

А теперь вспомните, как приятно, когда кнопка слегка «вдавливается» под пальцем, когда переключатель плавно скользит из положения «выкл» в «вкл», когда сердечко лайка пульсирует после нажатия. Это и есть микроанимация — маленькая деталь, которая превращает холодный цифровой интерфейс в теплый, отзывчивый и понятный диалог между пользователем и системой.

Часть 1. Что такое микроанимация и зачем она нужна?

Микроанимация (или микровзаимодействие) — это небольшие, целенаправленные анимации, которые происходят в ответ на действие пользователя или изменение состояния интерфейса. Они длятся доли секунды (обычно 200–400 мс) и не привлекают к себе излишнего внимания, но именно они делают интерфейс «живым» и интуитивно понятным.

Важно понимать разницу: микроанимация — это не декоративная заставка и не полноценный видеоролик. Это функциональный инструмент, который помогает пользователю понять, что происходит.

«Микроанимации — это как специи в еде. Без них — пресно. Слишком много — несъедобно. Правильная дозировка — шедевр».

Сам термин был введен дизайнером Дэном Саффером, который определил четыре ключевых компонента любого микровзаимодействия:

Почему микроанимации так эффективны?

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

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

Исследования подтверждают: 70% пользователей чувствуют себя более вовлеченными при работе с интерфейсами, которые используют продуманные микровзаимодействия. А люди распознают анимированные элементы на 60% быстрее, чем статичные.

Однако есть и обратная сторона. Те же исследования показывают: 73% пользователей раздражаются от излишних анимаций и ищут способ их отключить. Google, например, выяснил, что каждые 100 мс задержки в интерфейсе снижают конверсию на 1%. Медленные анимации — это не «красиво», это дорого.

Часть 2. Типы микроанимаций: что, где и когда уместно?

Микроанимации решают разные задачи. Условно их можно разделить на несколько категорий:

1. Обратная связь (Feedback)

Это самый базовый и важный тип. Пользователь совершил действие — интерфейс подтвердил, что заметил это.

Где использовать: кнопки, переключатели, чекбоксы, поля ввода.
Как выглядит: кнопка слегка «вдавливается» при нажатии (scale: 0.98), чекбокс плавно заполняется галочкой, поле ввода подсвечивается зеленым при правильном заполнении или красным при ошибке.
Зачем: устраняет тревогу «а сработало ли?». Исследование Якоба Нильсена показало: 82% пользователей нажимают кнопку повторно, если нет видимой реакции в первые 200 мс.

2. Статус системы (Status)

Информирует о процессе, который происходит в данный момент.

Где использовать: загрузка страниц, отправка форм, синхронизация данных.
Как выглядит: спиннеры (крутящиеся индикаторы), прогресс-бары, skeleton screens (пульсирующие каркасы страницы).
Зачем: показывает, что система «жива» и работает, даже если процесс занимает время. Skeleton screens, в частности, создают иллюзию быстрой загрузки и снижают воспринимаемое время ожидания.

3. Навигация и переходы (Transition)

Объясняют, как изменилась структура интерфейса и куда «переместился» пользователь.

Где использовать: переключение между экранами, открытие/закрытие меню, модальные окна, аккордеоны.
Как выглядит: новый экран въезжает справа, старый уезжает влево (как в мобильных приложениях); меню выезжает сверху; аккордеон плавно раскрывается, показывая скрытый контент.
Зачем: помогает пользователю не потерять контекст. Исследования показывают, что анимированные переходы снижают время поиска элементов на 30–40%.

4. Направление внимания (Guidance)

Подсказывают пользователю, куда смотреть или что делать дальше.

Где использовать: онбординг (обучение), сложные формы, важные призывы к действию.
Как выглядит: кнопка «Далее» мягко пульсирует; поле ввода подсвечивается; появляется подсказка со стрелкой, указывающей на нужный элемент.
Зачем: снижает когнитивную нагрузку в процессе обучения и помогает пользователю не «застревать» на сложных этапах.

5. Эмоциональная связь (Delight)

Самый «необязательный», но самый запоминающийся тип. Создает вау-эффект и укрепляет бренд.

Где использовать: лайки, достижения, поздравления, пустые состояния.
Как выглядит: сердечко лайка не просто закрашивается, а пульсирует или превращается в стаю бабочек; при завершении задачи вылетает анимированное конфетти; в «пустой корзине» грустная корзинка вздыхает.
Зачем: вызывает положительные эмоции, делает продукт «человечным» и запоминающимся. Классический пример — анимированный единорог, пролетающий по экрану в Asana после завершения сложной задачи.

Часть 3. Принципы хорошей микроанимации: как не навредить?

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

1. Функциональность прежде всего

Каждая анимация должна решать конкретную задачу, а не просто «быть красивой». Прежде чем добавить эффект, спросите себя: «Помогает ли эта анимация пользователю понять, что происходит?» Если нет — откажитесь от нее.

2. Скорость и тайминг

Микроанимация должна быть быстрой. Пользователь не должен ждать.

Базовые интеракции (наведение, нажатие): 100–200 мс.
Переходы между экранами, раскрытие элементов: 300–400 мс.
Сложные, кастомные анимации: максимум 500–600 мс.

Всё, что длится дольше 600 мс, — это уже не «микро», а полноценная анимация, которая начинает раздражать и тормозить работу.

3. Скорость и «характер движения» (Easing)

Не менее важно, как движется объект. Линейное движение (с постоянной скоростью) выглядит неестественно и роботизированно. Используйте easing-функции, которые имитируют физику реального мира:

ease-out — для появления элементов (быстро вначале, плавно замедляется в конце). Создает ощущение мягкого прибытия.
ease-in-out — для переходов между состояниями (плавно ускоряется и плавно замедляется). Выглядит органично.

4. Консистентность (единообразие)

Анимации должны быть предсказуемыми и соответствовать друг другу на всем протяжении продукта. Если кнопка «Сохранить» при нажатии слегка увеличивается на одной странице, она должна делать то же самое и на всех остальных. Единый «характер» анимации создает у пользователя ощущение целостности и мастерства продукта.

5. Ненавязчивость (Subtlety)

Хорошая микроанимация — это фон, а не главный герой. Она не должна отвлекать от основной задачи. Анимация должна быть заметна ровно настолько, чтобы быть полезной, и не более того.

6. Доступность (Accessibility)

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

Всегда используйте CSS-медиа-функцию prefers-reduced-motion.
Предусматривайте возможность отключить «тяжелую» (декоративную) анимацию в настройках, оставив только функциональную.
Дублируйте визуальную обратную связь тактильной (вибрация) или звуковой, где это уместно, но не делайте ни один из каналов единственным источником информации.

Часть 4. Лучшие примеры микроанимаций

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

Поиск Google

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

Google Assistant

Когда вы говорите «Окей, Google», на экране появляются четыре цветные точки, которые начинают двигаться, показывая, что ассистент «слушает». Когда вы замолкаете, анимация меняется, сигнализируя о готовности к ответу. Это идеальный пример того, как анимация делает невидимый процесс (обработку голоса) понятным и прозрачным.

Анимация на сайте Apple

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

Завершение задач в Asana

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

Часть 5. Инструменты и технологии

Внедрить микроанимацию можно разными способами — от простых CSS-стилей до сложных библиотек.

CSS-анимации — идеальны для простых эффектов при наведении (hover), изменении цвета, размера, прозрачности. Легко реализуются, отлично поддерживаются всеми браузерами.
GreenSock Animation Platform (GSAP) — мощнейшая JavaScript-библиотека для создания сложных, высокопроизводительных анимаций с точным контролем тайминга и последовательности. Выбор профессионалов для нестандартных задач.
Lottie — библиотека от Airbnb, которая позволяет встраивать сложные векторные анимации (созданные в Adobe After Effects) в веб и мобильные приложения. Файлы Lottie (в формате JSON) легковесны и масштабируются без потери качества. Идеально для иконок, иллюстраций, заставок.
Framer Motion, React Spring — для тех, кто работает в экосистеме React. Позволяют декларативно описывать анимации прямо в компонентах.
Конструкторы сайтов (Tilda, Webflow, Readymag) — имеют встроенные инструменты для создания микроанимаций (эффекты при наведении, появление при скролле) без единой строки кода.

Часть 6. Заключение

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

Она решает конкретные задачи:

Убирает неопределенность, давая мгновенную обратную связь.
Снижает когнитивную нагрузку, делая навигацию интуитивной.
Создает положительные эмоции, формируя лояльность к бренду.

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

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

Gitlab CI: запуск пайплайна при обновлении upstream-репозитория

2026-06-04T13:22:57Z

Сегодня в этой небольшой заметке мы покажем пример файла .gitlab-ci.yml, который описывает пайплайн, осуществляющий какие-либо действия с нашим репозиторием в момент, когда в другом проекте выходит новая версия. Типичный сценарий, при котором подобное может пригодиться – это необходимость вызова скрипта для обновления локальной копии репозитория, представляющего собой форк другого проекта (назовем его upstream), когда в оригинальном репозитории появляются изменения.

В первую очередь, необходимо решить, каким образом мы будем определять наиболее актуальную версию upstream. Чтобы не скачивать репозиторий целиком, удобнее будет воспользоваться командой git ls-remote, которая показывает список всех ссылок (веток, тегов и HEAD) в удаленном репозитории вместе с их ID коммитов (SHA-1). Так мы узнаем, появились ли новые коммиты. В нашем случае будем искать по тегам, так как это весьма удобный способ получить список готовых к использованию версий с номерами, чтобы по ним фильтровать и отслеживать, как далеко ушли изменения.

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

b9a2c14f7...1a2b3c4d    HEAD
b9a2c14f7...1a2b3c4d    refs/heads/main
a1b2c3d4e...5f6g7h8i    refs/tags/v1.0.0

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

git ls-remote --tags "$UPSTREAM_URL" | awk -F'/' '{print $3}' | grep -v '\^{}' | grep -E '^v?[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1

Здесь мы последовательно указываем, что берем лишь теги; очищаем строки от хэшей коммитов и части с refs/..; оставляем только числа и точки, чтобы вычленить версию; сортируем и берем только последний (самый актуальный) тег. В итоге будет лишь строка с версией, которая соответствует тегу.

Чтобы понять, есть ли в нашем репозитории самая актуальная версия upstream, можно проверить, существует ли ветка, содержащая в названии номер версии (хотя это сильно зависит от специфики проекта, но вариант кажется логичным). Для этого также вполне подойдет git ls-remote, но уже с флагом --heads. Так мы сможем получить ветку нашего репозитория, которая содержит в себе тег (точки заменили на дефис)

git ls-remote --heads "${YOUR_REPO}" | grep "${LATEST_TAG//./-}"

Переходя же непосредственно к пайплайну, предположим, что исходным у нас является базовый питоновский докер образ (например python:3.10-slim), в который через Dockerfile добавили произвольный python скрипт, призванный обновить локальный репозиторий правками из upstream. Его логику рассматривать не будем, поскольку она своя для кажого конкретного случая. Но что может понадобиться, так это определить ту ветку в нашем проекте, где лежат самые актуальные изменения (например, чтобы перенести их оттуда в ветку для новой версии). Для этого придется использовать уже git branch -r --sort=-committerdate | grep "origin/.*-main$", чтобы отсортировать ветки репозитория по дате последнего коммита.

В итоге получим вот такой файл .gitlab-ci.yml (с поясняющими комментариями):

image:
  name: dr.example.ru/your-script:latest
  entrypoint: [""]

variables:
  UPSTREAM_URL: "https://github.com/something.git"
  YOUR_APPLICATION_REPO_URL: "${CI_SERVER_HOST}/your-application.git"
  YOUR_APPLICATION_REPO_PATH: "${CI_PROJECT_DIR}/your-application"
  
stages:
  - check-version
  - update-repo


# проверка, есть ли новая версия upstream репозитория
check_new_version:
  stage: check-version
  rules:
    # Запускаем по планировщику, а после коммита - только при ручном действии
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: always
    - if: $CI_PIPELINE_SOURCE == "web"
      when: always
    - if: $CI_PIPELINE_SOURCE == "push"
      when: manual
  script:
    - YOUR_REPO="https://oauth2:${PROJECT_PUSH_TOKEN}@${YOUR_APPLICATION_REPO_URL}"
    # самый актуальный тег версии из upstream, как описывали
    - LATEST_TAG=$(git ls-remote --tags "$UPSTREAM_URL" | awk -F'/' '{print $3}' | grep -v '\^{}' | grep -E '^v?[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1)
    # проверка на наличие ветки с таким тегом в названии уже в нашем репозитории
    - IF_CORRESPONDING_BRANCH_EXISTS=$(git ls-remote --heads "${YOUR_REPO}" | grep "${LATEST_TAG//./-}" || true)
    # если есть века - все обновлено, выставляем флаг, если нет - то нужно какое-то действие
    - |
      if [ -n "$IF_CORRESPONDING_BRANCH_EXISTS" ]; then
        echo "Состояние актуально. Новой версии upstream не обнаружено"
        echo "NEEDS_UPDATE=false" >> check.env
      else 
        echo "Обнаружена новая версия ($LATEST_TAG)"
        echo "NEEDS_UPDATE=true" >> check.env
        echo "NEW_UPSTREAM_VERSION=$LATEST_TAG" >> check.env
      fi
  artifacts:
    # сохраняем переменные окружения для следующего этапа
    reports:
      dotenv: check.env


# полезная работа при обновлении upstream
do_on_update:
  stage: update-repo
  before_script:
    # проверяем переменную, если обновление не нужно, то выходим, не вызывая ошибку 
    - |
      if [ "$NEEDS_UPDATE" != "true" ]; then
        echo "Состояние актуально. Ничего не требуется"
        exit 0
      fi
  script:
    # клонируем наш репозиторий с фильтром blob:none, чтобы он не занимал много места, а хранил лишь саму структуру репозитория (что надо подгрузится лениво) 
    - git clone --filter=blob:none --no-checkout https://oauth2:${PROJECT_PUSH_TOKEN}@${YOUR_APPLICATION_REPO_URL} ${YOUR_APPLICATION_REPO_PATH}
    - cd ${YOUR_APPLICATION_REPO_PATH}
    # получаем по регулярному выражению самую свежую ветку в локальном репозитории (например, забрать оттуда наши правки)
    - REQUIRED_BRANCH=$(git branch -r --sort=-committerdate | grep "origin/.*-main$" | head -n 1 | awk '{$1=$1; print $1}')
    # запустить скрипт, который нужно запустить при новой версии upstream
    - python /app/your_script.py --branch ${REQUIRED_BRANCH}

Для настройки запуска по планировщику стандартно надо перейти в интерфейс Gitlab, выбрать там Build -> Pipeline schedules и задать нужные параметры.

В конечном итоге мы получим пайплайн, который запускается в указанный промежуток времени, проверяет upstream. Если там появляется новый тег (в нашем репозитории еще нет ветки для такой версии), то запускается скрипт для обновления, который обрабатывает самую новую ветку из локального репозитория. Если такой тег у нас уже есть (то есть нет обновлений в upstream), то пайплайн просто покажет все стадии успешно выполненными.

Эволюция инженера: как перейти в AI Engineering, не бросая всё, что вы умеете

2026-06-01T08:56:46Z

Введение: почему этот разговор важен именно сейчас

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

Речь идёт не об очередной волне хайпа, которую можно переждать. Это структурное изменение в том, как строятся программные продукты. И здесь возникает закономерный вопрос: что делать опытному разработчику, который строил надёжные системы на протяжении многих лет, но никогда не обучал нейронные сети и не работал с векторными базами данных?

Ответ, как это ни парадоксально, гораздо менее пугающий, чем кажется на первый взгляд. AI Engineering - это не новая профессия с нуля. Это расширение классической инженерной практики новым инструментальным слоем. Большая часть того, что вы уже умеете - проектирование API, работа с базами данных, управление состоянием, асинхронная обработка, паттерны проектирования - остаётся не просто релевантной, а критически важной.

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

Часть первая: Деконструкция иллюзий

Почему опытные разработчики избегают AI-тематики

Парадокс состоит в следующем: именно те инженеры, которым проще всего войти в AI Engineering, нередко сопротивляются этому дольше всех.

Причин несколько, и они вполне понятны:

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

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

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

"Это просто автодополнение текста в промышленных масштабах".

Это отчасти верно с технической точки зрения, но совершенно не отменяет практической ценности инструмента.

Ни одна из этих причин не является достаточным основанием для того, чтобы игнорировать происходящие изменения.

Часть вторая: Технические основы - архитектурный взгляд

Шаг 1. Понимание механики генеративного ИИ

Первый шаг - избавиться от ощущения "магии". Большая языковая модель (LLM) - это не разум и не оракул. Это вероятностная математическая функция, которая принимает последовательность токенов на входе и возвращает распределение вероятностей для следующего токена. Из этого простого механизма, повторённого миллиарды раз на огромных данных, возникает то, что мы воспринимаем как "понимание текста".

Для практикующего бэкенд-инженера взаимодействие с LLM через API - это, по существу, вызов внешнего микросервиса. Разница в одном: этот сервис не детерминирован. На один и тот же запрос он может вернуть разные ответы. Это не баг - это фундаментальное свойство, которым нужно научиться управлять.

Несколько концепций, которые необходимо понять на базовом уровне:

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

Эмбеддинги. Представьте, что любой текст - слово, предложение, абзац - можно описать точкой в многомерном пространстве так, что семантически близкие тексты окажутся рядом друг с другом. Именно это делают эмбеддинги. Если вы работали с индексами в базах данных или с алгоритмами хеширования, думайте об эмбеддингах как о семантическом индексе смысла. Расстояние между двумя векторами - это мера смысловой близости двух текстов.

Температура. Этот параметр управляет тем, насколько предсказуемы ответы модели. При температуре, близкой к нулю, модель будет воспроизводить наиболее статистически вероятный ответ - это полезно для задач, где требуется точность и повторяемость. При высокой температуре модель "рискует" и выбирает менее очевидные токены - это нужно для творческих задач. Выбор температуры - это инженерное решение, которое зависит от конкретной задачи.

Контекстное окно. Это максимальный объём информации, который модель может обработать за один вызов. Современные модели имеют контекстные окна от нескольких десятков тысяч до нескольких миллионов токенов. Управление контекстом - одна из ключевых инженерных задач при построении AI-приложений.

Вот базовый пример взаимодействия с языковой моделью через API:

import openai
 
client = openai.Client(api_key="your_api_key")
 
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "system",
            "content": (
                "Ты — старший инженер-программист. "
                "Отвечай точно и по существу, без лишних слов."
            )
        },
        {
            "role": "user",
            "content": "Объясни разницу между эмбеддингами и хэш-функциями."
        }
    ],
    temperature=0.0,   # Нулевая температура для точных, воспроизводимых ответов
    max_tokens=500
)
 
print(response.choices[0].message.content)
 
# Не забывайте обрабатывать метаданные вызова:
usage = response.usage
print(f"Использовано токенов: {usage.total_tokens} "
      f"(запрос: {usage.prompt_tokens}, ответ: {usage.completion_tokens})")

Обратите внимание на параметр temperature=0.0. Когда вы строите систему, которая должна анализировать логи, парсить документы или генерировать структурированные данные, детерминированность важнее разнообразия. Это инженерное решение, а не "магический" параметр.

Шаг 2. Структурирование хаоса: от текста к типизированным объектам

Одна из главных болей при интеграции языковых моделей в классический бэкенд - это работа с неструктурированным выводом. Ваша база данных ожидает конкретные типы, фронтенд - строгий JSON-контракт, а оркестрирующий код - предсказуемые объекты с известными полями. Языковая модель по умолчанию возвращает свободный текст.

Решение этой проблемы - принудительная типизация вывода через валидационные схемы. Концептуально это аналог паттерна DTO (Data Transfer Object) в классической архитектуре, только применённый к вероятностному компоненту системы.

В экосистеме Python стандартом де-факто стал Pydantic в связке с соответствующими инструментами LangChain.

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

from pydantic import BaseModel, Field
from typing import Literal
from langchain_openai import ChatOpenAI
from langchain.output_parsers import PydanticOutputParser
from langchain.prompts import PromptTemplate
 
# Описываем схему так же, как описывали бы DTO или схему базы данных
class LogAnalysis(BaseModel):
    severity: Literal["INFO", "WARNING", "ERROR", "FATAL"] = Field(
        description="Уровень критичности события"
    )
    affected_service: str = Field(
        description="Название микросервиса, в котором произошла ошибка"
    )
    root_cause: str = Field(
        description="Краткое описание предполагаемой причины проблемы"
    )
    recommended_action: str = Field(
        description="Рекомендуемое первоочередное действие для устранения проблемы"
    )
    is_production_affecting: bool = Field(
        description="True, если ошибка влияет на продакшен прямо сейчас"
    )
 
parser = PydanticOutputParser(pydantic_object=LogAnalysis)
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
 
prompt = PromptTemplate(
    template=(
        "Ты — старший SRE-инженер. "
        "Проанализируй следующую строку лога и верни структурированный анализ.\n\n"
        "{format_instructions}\n\n"
        "Строка лога:\n{log_entry}\n"
    ),
    input_variables=["log_entry"],
    partial_variables={"format_instructions": parser.get_format_instructions()},
)
 
chain = prompt | llm | parser
 
log_line = "[2024-01-15 03:47:22] FATAL: Connection pool exhausted in payment-gateway-service. Active connections: 512/512. Queue depth: 847."
 
result: LogAnalysis = chain.invoke({"log_entry": log_line})
 
# Теперь result — это строго типизированный объект, а не свободный текст
print(f"Сервис: {result.affected_service}")
print(f"Критичность: {result.severity}")
print(f"Влияет на продакшен: {result.is_production_affecting}")
print(f"Рекомендация: {result.recommended_action}")

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

Важно учитывать, что Pydantic-парсер внутри себя делает дополнительный вызов модели при ошибке формата. Если надёжность важнее скорости, используйте with_structured_output напрямую через OpenAI - это использует нативную поддержку JSON Schema на уровне API и более устойчиво к ошибкам:

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
 
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
structured_llm = llm.with_structured_output(LogAnalysis)
 
prompt = ChatPromptTemplate.from_messages([
    ("system", "Ты — старший SRE-инженер. Проанализируй строку лога."),
    ("user", "{log_entry}")
])
 
chain = prompt | structured_llm
result = chain.invoke({"log_entry": log_line})

Шаг 3. От простых вызовов к агентам

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

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

С точки зрения классической архитектуры это напоминает паттерн Strategy: у вас есть интерфейс "инструмент", конкретные реализации (поиск в базе данных, вызов внешнего API, расчёт), и оркестратор, который выбирает нужную стратегию. Только в данном случае оркестратором выступает языковая модель.

from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.tools import tool
from langchain_core.prompts import ChatPromptTemplate
import requests
 
# Определяем инструменты как обычные Python-функции
@tool
def get_service_metrics(service_name: str) -> dict:
    """
    Возвращает текущие метрики сервиса: CPU, память, количество запросов в секунду.
    Используй этот инструмент, когда нужно проверить состояние конкретного сервиса.
    """
    # В реальном коде здесь был бы запрос к Prometheus или DataDog
    return {
        "service": service_name,
        "cpu_usage": 87.3,
        "memory_mb": 1842,
        "rps": 1243,
        "error_rate": 0.023,
        "p99_latency_ms": 342
    }
 
@tool
def create_incident(severity: str, title: str, description: str) -> str:
    """
    Создаёт инцидент в системе управления инцидентами (например, PagerDuty или Opsgenie).
    Используй только при severity ERROR или FATAL.
    """
    # В реальном коде здесь был бы вызов API системы инцидентов
    incident_id = f"INC-{hash(title) % 10000:04d}"
    return f"Инцидент создан: {incident_id}"
 
@tool
def get_recent_deployments(service_name: str, hours: int = 24) -> list:
    """
    Возвращает список деплойментов сервиса за последние N часов.
    Полезно для корреляции проблем с недавними изменениями в коде.
    """
    return [
        {"time": "2024-01-15 02:30:00", "version": "v2.4.1", "author": "deploy-bot"},
        {"time": "2024-01-15 00:15:00", "version": "v2.4.0", "author": "deploy-bot"}
    ]
 
tools = [get_service_metrics, create_incident, get_recent_deployments]
 
llm = ChatOpenAI(model="gpt-4o", temperature=0)
 
prompt = ChatPromptTemplate.from_messages([
    ("system", (
        "Ты — автоматизированный SRE-ассистент. "
        "Анализируй проблемы, собирай метрики и при необходимости создавай инциденты. "
        "Всегда проверяй метрики перед созданием инцидента."
    )),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])
 
agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
 
response = executor.invoke({
    "input": "Получили алерт: payment-gateway-service начал возвращать 503 ошибки. "
             "Проверь метрики, посмотри недавние деплойменты и реши, нужно ли создавать инцидент."
})
 
print(response["output"])

В этом примере агент самостоятельно решает, в каком порядке вызывать инструменты: сначала собирает метрики, затем проверяет деплойменты, и только после этого принимает решение о создании инцидента. Вы не пишете эту логику явно - модель выводит её из описаний инструментов и контекста задачи.

Шаг 4. Управление состоянием сложных агентных систем

Когда число шагов в агентном пайплайне растёт, а логика ветвления становится нетривиальной, код на базе простого AgentExecutor начинает деградировать в запутанный клубок условных операторов. Это знакомая проблема: достаточно вспомнить любой крупный сервис, где бизнес-логика постепенно превратилась в лабиринт if-else.

Индустрия решает эту проблему с помощью LangGraph - библиотеки для построения агентных систем на основе ориентированных графов. С архитектурной точки зрения LangGraph реализует конечный автомат (Finite State Machine), где узлы - это функции или сервисы обработки, а рёбра - это правила переходов между ними.

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

from typing import TypedDict, Annotated, Optional
from langgraph.graph import StateGraph, END
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, AIMessage
import operator
 
# Состояние, которое передаётся между узлами графа
class SupportTicketState(TypedDict):
    ticket_id: str
    user_message: str
    category: Optional[str]           # Категория обращения (billing, technical, general)
    sentiment: Optional[str]          # Тональность (positive, neutral, negative, angry)
    response: Optional[str]           # Сгенерированный ответ
    needs_human: bool                 # Флаг эскалации на живого оператора
    history: Annotated[list, operator.add]  # Лог обработки
 
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
 
# Узел 1: классификация обращения
def classify_ticket(state: SupportTicketState) -> SupportTicketState:
    classification_prompt = f"""
    Классифицируй обращение пользователя. Верни ТОЛЬКО JSON с двумя ключами:
    - "category": одно из ["billing", "technical", "general", "complaint"]
    - "sentiment": одно из ["positive", "neutral", "negative", "angry"]
    
    Обращение: {state['user_message']}
    """
    response = llm.invoke([HumanMessage(content=classification_prompt)])
    
    import json, re
    data = json.loads(re.search(r'\{.*\}', response.content, re.DOTALL).group())
    
    return {
        "category": data["category"],
        "sentiment": data["sentiment"],
        "history": [f"Классифицировано: {data['category']}, тональность: {data['sentiment']}"]
    }
 
# Узел 2: генерация ответа
def generate_response(state: SupportTicketState) -> SupportTicketState:
    system_context = {
        "billing": "Ты — специалист по биллингу. Будь чётким и предоставь конкретные цифры.",
        "technical": "Ты — технический специалист поддержки. Давай пошаговые инструкции.",
        "general": "Ты — специалист общей поддержки. Будь дружелюбным и полезным.",
        "complaint": "Ты — менеджер по работе с клиентами. Проявляй эмпатию и предлагай решения."
    }
    
    context = system_context.get(state["category"], system_context["general"])
    response = llm.invoke([
        HumanMessage(content=f"Системный контекст: {context}\n\nОбращение: {state['user_message']}")
    ])
    
    return {
        "response": response.content,
        "history": ["Ответ сгенерирован"]
    }
 
# Узел 3: эскалация на человека
def escalate_to_human(state: SupportTicketState) -> SupportTicketState:
    return {
        "needs_human": True,
        "response": "Ваше обращение передано старшему специалисту. Ожидайте ответа в течение 2 часов.",
        "history": ["Эскалировано на живого оператора"]
    }
 
# Маршрутизатор: определяет, нужна ли эскалация
def route_after_classification(state: SupportTicketState) -> str:
    # Гневные обращения или жалобы сразу идут к живому оператору
    if state["sentiment"] == "angry" or state["category"] == "complaint":
        return "escalate"
    return "generate_response"
 
# Сборка графа
workflow = StateGraph(SupportTicketState)
 
workflow.add_node("classify", classify_ticket)
workflow.add_node("generate_response", generate_response)
workflow.add_node("escalate", escalate_to_human)
 
workflow.set_entry_point("classify")
 
workflow.add_conditional_edges(
    "classify",
    route_after_classification,
    {
        "escalate": "escalate",
        "generate_response": "generate_response"
    }
)
 
workflow.add_edge("generate_response", END)
workflow.add_edge("escalate", END)
 
app = workflow.compile()
 
# Запуск
result = app.invoke({
    "ticket_id": "TKT-001",
    "user_message": "Вы списали деньги дважды! Это уже второй раз за месяц!",
    "category": None,
    "sentiment": None,
    "response": None,
    "needs_human": False,
    "history": []
})
 
print(f"Нужен оператор: {result['needs_human']}")
print(f"Ответ: {result['response']}")
print(f"Лог обработки: {result['history']}")

Граф явно описывает все возможные пути обработки. Любой инженер, пришедший в проект после вас, может за несколько минут понять, какие состояния существуют и как осуществляются переходы между ними. Это и есть инженерная культура, применённая к AI-системам.

Шаг 5. Архитектура RAG: дать модели доступ к вашим данным

У любой языковой модели есть фундаментальное ограничение: она знает только то, на чём была обучена. Ваша внутренняя документация, база знаний, архивы тикетов, технические спецификации - всё это для неё terra incognita. Паттерн RAG (Retrieval-Augmented Generation) решает именно эту проблему.

Для опытного инженера RAG - это хорошо известная архитектурная связка: поисковый индекс плюс кэш контента плюс сервис обработки запросов. Новизна заключается в том, что поиск осуществляется не по ключевым словам, а по семантической близости - с использованием эмбеддингов.

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

from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_community.vectorstores import FAISS
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser
from langchain.schema import Document
 
# --- Этап 1: Подготовка индекса (выполняется один раз при инициализации) ---
 
# Ваша документация или база знаний
documents = [
    Document(
        page_content="""
        API аутентификации использует JWT-токены с временем жизни 15 минут.
        Refresh-токены хранятся в Redis с TTL 30 дней.
        При истечении access-токена клиент должен вызвать endpoint /auth/refresh.
        Endpoint /auth/refresh принимает только HTTP POST запросы.
        При невалидном refresh-токене возвращается 401 с кодом ошибки TOKEN_EXPIRED.
        """,
        metadata={"source": "auth-service-docs.md", "section": "authentication"}
    ),
    Document(
        page_content="""
        Сервис платежей поддерживает следующие провайдеры: Stripe, PayPal, YooKassa.
        Все транзакции логируются в таблицу payment_transactions с retention 7 лет.
        При сумме транзакции свыше 100 000 рублей требуется дополнительная верификация.
        Верификация осуществляется через SMS-код или подтверждение по email.
        Максимальное число попыток верификации — 3, после чего транзакция блокируется.
        """,
        metadata={"source": "payment-service-docs.md", "section": "payments"}
    ),
    Document(
        page_content="""
        Деплойменты в продакшен осуществляются через GitLab CI/CD.
        Каждый деплоймент проходит 4 стадии: test, build, staging, production.
        Стадия production требует ручного подтверждения от tech lead или CTO.
        Rollback выполняется командой: kubectl rollout undo deployment/<service-name>.
        Среднее время полного деплоймента — 12 минут при отсутствии проблем.
        """,
        metadata={"source": "deployment-runbook.md", "section": "deployments"}
    )
]
 
# Разбиваем на чанки с перекрытием для сохранения контекста
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=500,        # Символов в одном фрагменте
    chunk_overlap=50,      # Перекрытие между фрагментами — важно для сохранения контекста
    separators=["\n\n", "\n", ". ", " "]
)
 
split_docs = text_splitter.split_documents(documents)
 
# Создаём векторный индекс
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
vectorstore = FAISS.from_documents(split_docs, embeddings)
 
# --- Этап 2: Построение цепочки RAG ---
 
retriever = vectorstore.as_retriever(
    search_type="similarity",
    search_kwargs={"k": 3}  # Возвращаем 3 наиболее релевантных фрагмента
)
 
def format_docs(docs):
    """Форматируем найденные документы для передачи в промпт"""
    return "\n\n---\n\n".join(
        f"Источник: {doc.metadata.get('source', 'неизвестен')}\n{doc.page_content}"
        for doc in docs
    )
 
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
 
prompt = ChatPromptTemplate.from_messages([
    ("system", (
        "Ты — внутренний технический ассистент компании. "
        "Отвечай ТОЛЬКО на основе предоставленной документации. "
        "Если ответ не содержится в документации, прямо скажи об этом. "
        "Всегда указывай источник информации.\n\n"
        "Документация:\n{context}"
    )),
    ("human", "{question}")
])
 
rag_chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)
 
# --- Этап 3: Использование ---
 
questions = [
    "Как долго живёт refresh-токен?",
    "Что происходит при попытке перевести 150 000 рублей?",
    "Сколько длится деплоймент в продакшен?"
]
 
for question in questions:
    print(f"\nВопрос: {question}")
    print(f"Ответ: {rag_chain.invoke(question)}")
    print("-" * 60)

Здесь важно понять одну вещь: 80% качества RAG-системы определяется не выбором языковой модели, а качеством инженерии вокруг неё. Как вы разбиваете документы на фрагменты? Насколько правильно структурированы метаданные? Как настроены параметры поиска? Это классические инженерные вопросы, а не задачи машинного обучения.

Ключевые решения при построении RAG:

Размер чанка определяет компромисс между точностью поиска и полнотой контекста. Слишком маленькие чанки - модель не получает достаточного контекста; слишком большие - снижается точность семантического поиска. Хорошая отправная точка для технической документации: 400-600 символов с перекрытием 10-15%.
Метаданные критически важны для фильтрации. Добавляйте к каждому фрагменту источник, дату обновления, раздел, тип документа. Это позволяет строить гибридный поиск: сначала фильтрация по метаданным, затем семантический поиск внутри отфильтрованного подмножества.
Оценка качества - это инженерная задача. Стройте набор тестовых пар "вопрос - ожидаемый ответ" и измеряйте качество системы автоматически при каждом изменении параметров.

Шаг 6. Потоковая передача и асинхронность

Вызов языковой модели - это долгая операция. Типичный ответ на сложный запрос занимает от 3 до 30 секунд. Если вы строите API, которое синхронно ждёт полного ответа модели, прежде чем вернуть что-либо клиенту, пользовательский опыт будет неприемлемым.

Решения те же, что и в классическом бэкенде: стриминг и асинхронность.

import asyncio
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
 
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.3, streaming=True)
 
prompt = ChatPromptTemplate.from_messages([
    ("system", "Ты — технический писатель. Пиши чётко и структурированно."),
    ("human", "{topic}")
])
 
chain = prompt | llm | StrOutputParser()
 
# Асинхронный стриминг — идеально для API на FastAPI
async def stream_response(topic: str):
    async for chunk in chain.astream({"topic": topic}):
        print(chunk, end="", flush=True)
        # В реальном API здесь был бы yield chunk для SSE или WebSocket
    print()  # Новая строка в конце
 
# Параллельная обработка нескольких запросов
async def process_multiple_queries(queries: list[str]) -> list[str]:
    tasks = [chain.ainvoke({"topic": q}) for q in queries]
    return await asyncio.gather(*tasks)
 
# Запуск
asyncio.run(stream_response(
    "Объясни разницу между RAG и fine-tuning языковых моделей"
))
```
 
Пример интеграции со стримингом в FastAPI:
 
```python
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
import asyncio
 
app = FastAPI()
llm = ChatOpenAI(model="gpt-4o-mini", streaming=True)
 
@app.get("/generate")
async def generate_stream(query: str):
    prompt = ChatPromptTemplate.from_messages([
        ("system", "Ты — полезный технический ассистент."),
        ("human", "{query}")
    ])
    chain = prompt | llm | StrOutputParser()
    
    async def event_generator():
        async for chunk in chain.astream({"query": query}):
            yield f"data: {chunk}\n\n"
        yield "data: [DONE]\n\n"
    
    return StreamingResponse(
        event_generator(),
        media_type="text/event-stream"
    )

Обратите внимание: astream не просто ускоряет ответ - он фундаментально меняет пользовательский опыт. Первые токены появляются уже через 200-500 миллисекунд, и пользователь видит, что система работает, даже если полный ответ формируется ещё несколько секунд.

Часть третья: Инженерный фундамент как конкурентное преимущество

Почему опыт классической разработки - это преимущество, а не балласт

Здесь возникает парадокс, который многие не сразу замечают. Рынок AI-инженеров сегодня переполнен людьми, которые умеют вызывать API языковых моделей и получать ответы. Но построить из этого надёжную, масштабируемую, поддерживаемую систему - совсем другая история.

Разработчик с десятью годами опыта проектирования распределённых систем принесёт в AI Engineering то, чего у энтузиастов-самоучек нет: понимание того, как системы ломаются, как они масштабируются, как ими управляют в продакшене.

Observability.

Классический бэкенд-инженер знает, что без нормального логирования, трейсинга и метрик система неуправляема. В AI-системах это особенно важно, потому что вероятностный компонент делает отладку значительно сложнее. Трассировка LLM-вызовов с захватом промптов, токенов и времени ответа - это не опциональная функция, это базовая good-practice.

import time
import logging
from functools import wraps
from dataclasses import dataclass
from typing import Any
 
logger = logging.getLogger(__name__)
 
@dataclass
class LLMCallMetrics:
    model: str
    prompt_tokens: int
    completion_tokens: int
    latency_ms: float
    success: bool
    error: str | None = None
 
def track_llm_call(func):
    """Декоратор для автоматического трекинга вызовов LLM"""
    @wraps(func)
    async def wrapper(*args, **kwargs):
        start = time.time()
        try:
            result = await func(*args, **kwargs)
            latency = (time.time() - start) * 1000
            
            # В реальной системе здесь — отправка в Prometheus/DataDog
            logger.info(
                "LLM call completed",
                extra={
                    "latency_ms": latency,
                    "function": func.__name__,
                }
            )
            return result
        except Exception as e:
            latency = (time.time() - start) * 1000
            logger.error(
                "LLM call failed",
                extra={
                    "latency_ms": latency,
                    "error": str(e),
                    "function": func.__name__,
                }
            )
            raise
    return wrapper

Управление стоимостью.

Каждый вызов языковой модели стоит денег. Классический инженер немедленно задаётся вопросами кэширования: какие запросы повторяются? Какой TTL у кэша разумен для данного типа запросов? Можно ли батчевать вызовы?

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

LLM API возвращает ошибки: rate limits, timeout, временная недоступность сервиса. Стратегия retry с экспоненциальным backoff, circuit breaker, fallback на альтернативную модель - всё это стандартная практика надёжного бэкенда, перенесённая в новый контекст.

import asyncio
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
from openai import RateLimitError, APITimeoutError
 
@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=4, max=10),
    retry=retry_if_exception_type((RateLimitError, APITimeoutError))
)
async def resilient_llm_call(messages: list, model: str = "gpt-4o-mini"):
    """Вызов LLM с автоматическим retry при временных ошибках"""
    response = await client.chat.completions.acreate(
        model=model,
        messages=messages,
        timeout=30
    )
    return response

Тестирование.

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

Инструментальный стек AI-инженера в 2026 году

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

Оркестрация и цепочки: LangChain остаётся наиболее распространённым фреймворком для построения LLM-приложений. LangGraph - его расширение для сложных агентных систем. Для более лаконичного кода существует LlamaIndex, особенно популярный в RAG-сценариях.

Векторные базы данных: Chroma подходит для прототипов и небольших объёмов данных; Pinecone - для облачных продакшен-решений; Qdrant и Weaviate - для самостоятельного развёртывания с расширенными возможностями фильтрации; pgvector - если вы уже используете PostgreSQL и не хотите вводить дополнительную инфраструктуру.

Observability: LangSmith (от команды LangChain) - специализированный инструмент для трассировки LLM-вызовов; Weights & Biases - для более глубокого мониторинга и экспериментов; Phoenix от Arize - для оценки качества RAG-систем.

Оценка качества: RAGAS - фреймворк для автоматической оценки RAG-систем по метрикам faithfulness (верность источнику), answer relevancy (релевантность ответа) и context precision (точность контекста).

Заключение: правильный взгляд на трансформацию

Переход в AI Engineering - это не смена профессии. Это расширение профессионального контекста. Если переформулировать это в инженерных терминах: вы не мигрируете на новую платформу, вы добавляете новый слой абстракции поверх существующего стека.

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

Несколько практических рекомендаций для тех, кто готов начать:

Начните с задачи, которую вы хорошо понимаете. Возьмите реальную проблему из своей области: анализ логов, автоматизация code review, обработка технической документации, и решите её с помощью языковой модели. Знание предметной области поможет вам объективно оценить качество результата.

Измеряйте всё с самого начала. Добавляйте логирование LLM-вызовов до того, как система уйдёт в продакшен. Стоимость, задержка, частота ошибок - эти данные необходимы для принятия архитектурных решений.

Читайте исходный код инструментов, которыми пользуетесь. LangChain, LangGraph - это Python-библиотеки с открытым кодом. Понимание того, что происходит под капотом, помогает избежать многих неожиданных проблем в продакшене.

Не переоценивайте роль модели. Подавляющее большинство проблем в AI-приложениях - это инженерные проблемы: качество данных, архитектура системы, обработка ошибок, управление состоянием. Смена модели к примеру с GPT-4o на Claude или наоборот редко кардинально меняет ситуацию. Инженерные решения - меняют.

Искусственный интеллект не заменит инженеров-программистов. Но инженеры, которые поняли, как встроить AI в архитектуру систем, как управлять его нестабильностью, масштабировать его вызовы, тестировать его поведение и обеспечивать его надёжность, станут теми, кто будет проектировать следующее поколение программных систем.

У вас уже есть для этого фундамент. Теперь есть и карта.

UX-тексты для новичков: Как писать интерфейсы, которые говорят на языке пользователя

2026-05-06T17:33:50Z

Представьте: вы открываете приложение, чтобы удалить давно надоевшую подписку. Вы находите нужную кнопку... а на ней написано: «Деактивировать рекуррентный платёжный мандат». Что вы сделаете? Скорее всего, закроете приложение и подумаете: «Я слишком стар для этого».

Это не ваша проблема. Это проблема UX-письма (UX Writing).

UX-письмо — это проектирование слов в интерфейсе. Технически это написание текстов для кнопок, ошибок, подсказок, уведомлений — всего, с чем взаимодействует пользователь. По сути — это создание диалога между продуктом и человеком.

В этой статье разберём основы, на которые должен обратить внимание новичок, и главное — как не облажаться в первые же дни.

Что такое UX-тексты и чем они отличаются от копирайтинга?

Частая ошибка новичка: думать, что UX-тексты— это просто «покороче и подушевнее».

Золотое правило UX-текста:

Пользователь не должен думать о словах. Он должен смотреть на интерфейс и уже знать, что делать.

Пример:

Плохо (копирайтинг в интерфейсе): «Нажмите на эту волшебную кнопку, чтобы отправиться в захватывающее путешествие по миру скидок!»
Хорошо (UX-письмо): «Получить скидку»

На что обратить внимание новичку

1. Ясность превыше всего (Clarity > Cleverness)

Самый частый грех новичков — пытаться быть остроумным. Запомните: пользователь не ищет в вашем интерфейсе юмор. Он ищет способ закончить дело и уйти.

❌Остроумно, но непонятно: «Ой, что-то пошло не так с нашим магическим шаром...» (ошибка 500)
✅Понятно и полезно: «Не удалось загрузить данные. Проверьте соединение и попробуйте снова.»

Как проверить себя:
Прочитайте текст вслух. Если кто-то за стеной не поймёт, о чём речь, — переписывайте.

2. Действие в кнопке — глагол

Кнопка — это самый важный микротекст в интерфейсе. Пользователь должен мгновенно понимать, что случится после нажатия.

❌ Окей, но расплывчато: «Подтвердить», «Отправить», «Далее»
✅ Конкретно и честно: «Оплатить 590 ₽», «Удалить профиль», «Перейти к загрузке»

Правило «Да/Нет — это зло»: Если вы спрашиваете «Вы уверены?», не давайте ответы «Да» и «Нет». Дайте ответы, которые повторяют действие:

❌ «Вы уверены?» [Да] [Нет]
✅ «Удалить навсегда?» [Удалить] [Отменить]

3. Ошибки — не конец света, а подсказка

Пользователь и так расстроен, что у него что-то не получилось. Ваша задача — не добить его, а помочь.

Что должна содержать хорошая ошибка:

Информацию о том, что произошло
Объяснение почему это произошло
Ответ на вопрос «Что делать?»

❌ Бесполезная ошибка: «Ошибка валидации формы. Код: 0x000A12»
✅ Полезная ошибка: «Пароль слишком короткий. Используйте минимум 8 символов.»

4. Пустые состояния (Empty States) — это не мусорка

Пустое состояние — это когда в списке нет задач, корзина пуста, поиск не дал результатов. Новички часто оставляют там просто «Нет данных».

Пустое состояние должно:

Объяснить почему здесь пусто («У вас пока нет сохранённых адресов»).
Предложить действие («Добавить адрес»).
(Опционально) Показать пример или успокоить.

❌ Плохо: «Список наблюдения пуст»
✅ Хорошо: «Вы ещё не добавили ни одного товара в избранное. Самое время найти что-то особенное! [Перейти в каталог]»

5. Последовательность (их консистенция)

Ваши тексты должны быть предсказуемыми. Если на одной странице кнопка называется «Купить», а на следующей «Оформить заказ» — это разные действия в голове пользователя.

Создайте глоссарий для себя:

«Войти» — всегда «Войти», а не «Логин» или «Sign in».
«Товар» — всегда «Товар», а не «Продукт» или «Позиция».
Обращение на «ты» или «вы» — выберите одно и придерживайтесь везде. (Для массовых B2C-сервисов чаще «ты», для B2B и госуслуг — «вы»).

Как не облажаться: Типичные ошибки новичков и как их избежать

Ошибка №1: «Сейчас я им объясню...»

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

Как избежать: Напишите текст. Затем сократите его вдвое. Затем ещё раз вдвое. Если осталось 2-3 слова — идеально.

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

Ошибка №2: Копирование «крутых» фраз из чужих интерфейсов

Увидели в Telegram при регистрации «Ваш код — как секретная подушка для объятий: никому не показывайте». Скопировали текст к себе в банковское приложение — получился абсурд.

Как избежать: Голос продукта должен соответствовать его контексту. Банк — строго, лаконично, надёжно. Игровое приложение — игриво. Медицинский сервис — заботливо и спокойно.

Ошибка №3: Смешение «я» и «ты» (мы/вы/я)

В одном сообщении писать «Мы не смогли обработать вашу карту», а в следующем — «Я удалю этот платёж» (от лица робота). Это сбивает с толку.

Лучшая практика:

От лица системы = мы. «Мы обновили политику конфиденциальности.»
От лица пользователя = вы/твой. «Вы сохранили файл.», «Ваша подписка активна.»
Смешивать без нужды — не надо.

Ошибка №4: Игнорирование негативных сценариев

Вы продумали идеальный путь «вход > оплата > спасибо». Но забыли про «забыл пароль», «карта отклонена», «соединение потеряно». В результате, когда случается проблема, пользователь выпадает в осадок.

Как избежать: Составьте карту всех возможных ошибок в вашем интерфейсе и напишите для каждой короткий, полезный текст с инструкцией. Сначала плохие сценарии, потом — хорошие.

Чек-лист для проверки: 15 вопросов перед публикацией

Перед тем как отдать текст разработчикам или выкатить в прод, пройдитесь по списку:

Ясность: Поймёт ли мой текст человек, который видит интерфейс впервые?
Лаконичность: Можно ли удалить из этого текста хотя бы одно слово без потери смысла?
Действие: Понятно ли, что произойдёт после нажатия на кнопку?
Ошибка: Помогает ли она решить проблему, а не просто констатирует факт?
Единообразие: Так же ли я называю эту кнопку/объект в других местах?
Тон: Соответствует ли стиль текста задачам продукта (банк, игра, доставка еды)?
Призыв: Есть ли у пользователя понятное следующее действие после прочтения текста?
Пустые состояния: Не оставлены ли они без внимания?
Тревога: Не пугаю ли я пользователя без нужды («Вы уверены?» там, где достаточно «Отменить»)?
Орфография: Есть ли опечатки? (Это убивает доверие мгновенно).
Капитализация: Не пишу ли я целыми предложениями ЗАГЛАВНЫМИ БУКВАМИ? (Не кричите на пользователя).
Обращение: Везде ли выбрано единое «ты» или «вы»?
Негативные сценарии: Написал ли я текст для случая, когда пошло не так?
Адаптив: Помещается ли текст в кнопку на мобильном телефоне? (Проверьте!)
Тест: Показал ли я эти тексты хотя бы одному коллеге/другу, который не в теме?

UX-текст — это уважение

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

Ваша задача как UX-писателя — убрать себя из интерфейса. Убрать остроты, сложные конструкции, гордость за удачную фразу. Оставить только то, что нужно пользователю здесь и сейчас, чтобы он сделал своё дело и почувствовал себя умным и успешным.

Помните:
Пользователь не пришёл к вам восхищаться вашим слогом. Он пришёл удалить подписку, заказать пиццу или перевести деньги. Помогите ему сделать это быстро и без головной боли. И тогда ваш продукт полюбят. А хороший UX-текст останется незамеченным — это и есть высшая оценка.

Неоднозначные отношения Kotlin с Hibernate

2026-05-06T13:34:09Z

Kotlin позиционируется как язык, который призван сделать жизнь Java разработчика счастливее. Код становится лаконичнее, Null-safety спасает от NPE, а стандартная библиотека - удовольствие. Но когда мы подключаем к этому котлу JPA-провайдер (например Hibernate), начинаются интересные сюрпризы.

Хотя Kotlin и Java отлично совместимы, их парадигмы иногда конфликтуют. Hibernate изначально проектировался под Java-бины, а Kotlin привносит свои концепции: immutable data classes, свойства вместо геттеров/сеттеров и строгую типизацию.

Ловушка `data class` и `equals`/`hashCode`

Это, пожалуй, самая популярная ошибка. Все мы любим data class, но сущности помеченные @Entity - это не просто DTO.

@Entity

data class User(
 @Id 
 @GeneratedValue
 val id: Long? = null,
 val username: String
)

Так в чем же проблема? Первое - это Lazy Loading: Hibernate создает прокси-объекты, наследующие сущность. Если в equals используется == или ===, вы можете получить некорректные сравнения. Второе это - изменение ID: Когда вы сохраняете новую сущность, Hibernate присваивает ей ID. Если equals/hashCode опираются на ID (как генерирует data class), хеш-код объекта изменяется прямо в момент сохранения. Если этот объект лежал в HashSet, он «потеряется», так как хеш изменился после добавления.

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

Проблема `final` и отсутствие `open`

В Kotlin все классы и методы по умолчанию final. Hibernate же требует наследоваться от класса сущности для создания прокси (например, для Lazy Loading). Без дополнительных настроек вы получите ошибку при попытке подгрузить данные лениво.

Самый простой способ - использовать магию плагинов в build.gradle. Плагин kotlin-spring (или all-open) делает все классы, помеченные аннотациями (в т.ч. @Entity), открытыми, а плагин kotlin-jpa еще и open-ит методы, имеющие аннотации @Entity и т.д.

Конструкторы без аргументов

JPA-провайдеру нужен конструктор по умолчанию (без аргументов), чтобы создать экземпляр класса через рефлексию, а затем заполнить его поля данными из ResultSet. В Kotlin, если вы напишете primary конструктор с параметрами, конструктора по умолчанию не будет.

Здесь на помощь приходит тот же плагин kotlin-jpa. Он сгенерирует для вас невидимый конструктор без аргументов, если вы пометите класс аннотацией @Entity.

Проблема Default values

Допустим, у нас есть такое поле:

@Entity

class Task(

   val status: String = "NEW"

)

Разработчик ожидает, что если он сохранит объект, не задавая статус, то в БД будет "NEW". Но Hibernate при построении SQL-запроса (INSERT) смотрит на значение поля. Если мы создали объект через new Task(), в памяти статус "NEW". Но если мы мапим результат из базы, Hibernate использует конструктор без аргументов (о котором говорили выше) и сеттеры.

Если в БД колонка не имеет DEFAULT, а вы передаете null (или Hibrenate решит не вставлять это поле), возникнет ошибка. И наоборот, значение по умолчанию в Kotlin не синхронизируется со схемой БД.

Всегда дублируйте дефолтные значения на уровне бд и инициализируйте поле в классе. Либо, что более надежно в Enterprise-разработке, используйте @PrePersist.

В итоге получается, что Kotlin и Hibernate - отличная связка, но она требует понимания того, что происходит «под капотом». Плагины kotlin-jpa и kotlin-allopen решают 90% проблем с магией байт-кода, а остальные 10% решаются внимательным отношением к equals, hashCode и контрактам JPA.

Немного о porcelain и plumbing командах, а также о типах объектов в git

2026-05-06T13:06:31Z

Каждому разработчику практически ежедневно приходится сталкиваться с системой контроля версий git, выполняя набор привычных операций вроде git add, git fetch, git commit, git log и им подобных. Обычно для работы над прикладным проектом знания базового набора команд git оказывается вполне достаточно, однако важно понимать, что большинство всем известных команд представляют собой высокоуровневый инструментарий git (т.н. "porcelain" команды), которым возможности git не исчерпываются.

Porcelain - это команды, которые предназначены в первую очередь для удобства конечного пользователя (программиста), у них обычно довольно подробный вывод информации в консоль, который представлен в виде, удобном для чтения. Кроме того, вывод таких команд не регламентирован и теоретически может незначительно меняться от версии к версии. Подобные команды делают работу с git быстрее и доступнее, освобождая программиста от лишней работы, осуществляя множество операций "под капотом". У такого подхода есть очевидный недостаток - отсутствие гибкости и возможности контролировать каждый отдельный этап процесса выполнения команд. Впрочем, для большинства повседневных задач это и не нужно. Однако проблемы могут возникнуть, например, при необходимости автоматизировать какой-либо процесс, связанный с git. Если мы пишем скрипт, который полагается на вывод porcelain команд, то с выходом новой версии git код может сломаться (не говоря уже о необходимости в принципе парсить текстовый вывод). Примерами porcelain команд можно обозначить add, commit, status, push, pull, fetch, branch, checkout, merge, rebase, log, diff, stash, show, reset и др.

Другой категорией команд выступает низкроуровневый инструментарий - plumbing команды. В повседневной работе они редко нужны, однако позволяют работать с внутренностями git напрямую, обеспечивая максимальную гибкость. Иногда такие команды экономят время в повседневной разработке, заменяя длинные цепочки визуальных действий или помогая «вылечить» репозиторий, когда обычные команды выдают ошибки. Также они могут оказаться крайне полезны для использования в скриптах, поскольку они стабильны, их вывод не меняется и содержит минимум необходимых данных в хорошо структурированном формате, упрощая автоматическую обработку. По сути каждая porcelain команда, написанная программистом, самостоятельно исполняет набор более мелких низкоуровневых plumbing команд, манипулирующих различными объектами git.

Для общего понимания ситуации отметим, что в файловой системе git в принципе есть 4 типа объектов, о которых мы часто не задумываемся, но к работе с которыми сводится процесс исполнения любой команды:

blob - просто голое содержимое файла; в нем нет имени файла или даты, только сами данные (код, текст, картинка); если создать несколько файлов с идентичным содержанием, то все они будут ссылаться на один и тот же объект;
tree - своего рода директория, объект-дерево, содержащее список имен файлов (блобов) и других директорий (деревьев), а также права доступа к ним;
commit - это "снимок" проекта, который ссылается на конкретное дерево (корень проекта в этот момент) и содержит метаданные: автора, дату, сообщение и ссылку на предыдущий коммит (родителя);
tag - ссылка на конкретный коммит, содержащая имя тега, автора и сообщение.

Именно с ними работают plumbing команды как "атомарные" операции. В качестве примера приблизительно покажем, какие plumbing команды нужно вызвать, чтобы добиться результата аналогичного работе высокоуровневой обертке git commit:

git hash-object -w file.txt - взять содержимое файла и превратить его в объект blob, высчитать хеш и сохранить в директорию .git/objects
git update-index --add file.txt - привязать имя к хешу в индексе, связать содержимое (блоб) с именем файла
git write-tree - создать из текущего состояния индекса новый объект типа tree, вернуть хеш этого дерева
echo "commit message" | git commit-tree <хеш_дерева> -p <хеш_предыдущего_коммита> - создать объект commit из созданного ранее дерева; идет указание на tree как на внутреннее состояние репозитория и на parent как на прошлый коммит (нужно, чтобы связать в историю все коммиты); на выходе получаем хеш самого коммита
git update-ref refs/heads/main <хеш_коммита> - передвинуть указатель ветки на новый хеш, чтобы HEAD теперь указывал на новый созданный нами коммит

На примере выше мы показали, как plumbing команды позволяют лучше понимать внутреннее устройство git и при необходимости гибко им управлять, в том числе и внутри скриптов. Сам список таких команд весьма обширен и может быть найден в документации. Сейчас же, в дополнение к plumbling командам уже указанным выше, отдельно выделим еще несколько, заслуживающих внимание:

git rev-parse - одна из самых полезных команд в принципе, которая принимает строку (название ветки, тег, ссылка в стиле HEAD~4) и отдает хеш соответсвтующего коммита (либо последнего на указанной ветке); оказывается весьма нужно в скриптах;
git cat-file <хеш> - показывает сырое содержимое объекта по его хешу, позволяя узнать тип, размер любого из типов объектов;
git ls-tree - вывод содержимого дерева, показывается как список файлов и папок внутри конкретного коммита;
git ls-files - вывод информации о содержимом индекса.

Итак, подводя итог, еще раз отметим, что даже если использовать большинство из plumbing команд оказывается избыточно в случае повседневной разработки, все равно знать об их существовании достаточно важно. В этом небольшом обзоре, который не является исчерпывающим, я постарался сформулировать азы, которые позволят понимать git чуть глубже и расширить свой арсенал команд.

Astro.js: современный фреймворк для контент-ориентированных сайтов

2026-05-06T09:50:23Z

Astro.js: современный фреймворк для контент-ориентированных сайтов

Что такое Astro и зачем он нужен

Astro — это фреймворк для сайтов и веб-приложений, который по умолчанию рендерит большую часть страницы в статический HTML на сервере, а JavaScript подключает только там, где он действительно нужен. Такой подход называется islands architecture: основная часть страницы остается «легкой», а интерактивность добавляется небольшими изолированными фрагментами.

Astro поддерживает несколько UI-фреймворков одновременно: React, Preact, Vue, Svelte, Solid и веб-компоненты. Это делает его удобным, когда нужно сочетать контентные страницы, маркетинговые лендинги, документацию и отдельные интерактивные блоки в одном проекте.

Ключевые преимущества

Производительность «из коробки»

Astro проектировался как server-first решение, поэтому большинство страниц может отдаваться без необходимости тащить на клиент целый фреймворк runtime. В документации прямо отмечено, что это снижает сложность по сравнению с другими UI-фреймворками, потому что на сервере нет необходимости управлять реактивностью, хуками, stale closures и похожими механизмами.

UI-агностичность

Astro имеет систему интеграций и renderer-ов, через которую подключаются UI-фреймворки, адаптеры для серверного рендеринга и дополнительные возможности вроде MDX или sitemap. Для обычного проекта подключение официальной интеграции делается в несколько строк.

React — для компонентов с богатым состоянием,
Preact — там, где нужен React-подобный синтаксис с минимальным весом,
Svelte — для компактных и производительных виджетов,
Vue — если команда привыкла к его экосистеме,
Lit — для веб-компонентов.

На практике это особенно ценно при миграции старых проектов: вы можете постепенно переписывать компоненты, не ломая всё сразу.

Гибкая модель интерактивности

Astro использует компонентный подход, но интерактивность включается точечно через hydration directives: client:load, client:idle, client:visible, client:media и client:only. Это позволяет запускать JavaScript только для конкретных элементов интерфейса и выбирать момент загрузки в зависимости от приоритета UI.

Content Collections

Начиная с версии 2.0, Astro предлагает типизированные коллекции контента — встроенную систему для работы с Markdown, MDX и другими форматами с полной поддержкой TypeScript.

Технические основы: как это работает

Этапы сборки

Когда вы запускаете astro build, происходит следующее:

Парсинг компонентов — Astro читает все .astro-файлы и компоненты UI-фреймворков.
Статическая генерация — выполняется JavaScript в frontmatter (часть между ---), которая может делать запросы к API, читать файлы и т.д.
Рендеринг в HTML — вся разметка превращается в чистый HTML.
Выделение «островов» — компоненты с клиентскими директивами (client:load, client:idle и т.д.) упаковываются отдельно.
Гидратация — при загрузке страницы браузер загружает только нужные острова, причём строго по заданной стратегии.

Клиентские директивы

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

Директива	Поведение
`client:load`	Немедленно при загрузке страницы
`client:idle`	Когда браузер освободился (через `requestIdleCallback`)
`client:visible`	Когда компонент попадает в область видимости (Intersection Observer)
`client:media="(max-width: 768px)"`	При совпадении медиазапроса
`client:only="preact"`	Только на клиенте, без серверного рендеринга

Синтаксис `.astro`-файлов

.astro-файл делится на две части: frontmatter (серверный JavaScript) и шаблон (HTML-подобная разметка).

---
// Всё здесь выполняется ТОЛЬКО на сервере/в момент сборки.
// Этот код никогда не попадёт в браузер.

import Header from '../components/Header.astro';
import ProductCard from '../components/ProductCard.jsx'; // React-компонент
import { getCollection } from 'astro:content';

const products = await fetch('https://api.example.com/products')
  .then(res => res.json());

const { title = 'Каталог товаров' } = Astro.props;
---

<html lang="ru">
  <head>
    <meta charset="UTF-8" />
    <title>{title}</title>
  </head>
  <body>
    <!-- Статический Astro-компонент -->
    <Header />

    <main>
      <h1>{title}</h1>

      <ul class="product-grid">
        {products.map(product => (
          <!-- ProductCard — React-компонент -->
          <ProductCard client:visible name={product.name}/>
        ))}
      </ul>
    </main>
  </body>
</html>

<style>...</style>

Astro автоматически изолирует CSS-стили — каждый .astro-файл получает уникальный хэш-атрибут.

Layouts — переиспользуемые макеты

В Astro макеты — это просто компоненты со слотом <slot />:

---
// src/layouts/BaseLayout.astro
interface Props {
  title: string;
  description?: string;
}

const { title, description = 'Мой Astro-сайт' } = Astro.props;
---

<!doctype html>
<html lang="ru">
  <head>
    ...
  </head>
  <body>
    <nav class="site-nav"> ... </nav>

    <!-- Содержимое страницы подставляется сюда -->
    <slot />

    <footer>© 2024 Мой сайт</footer>
  </body>
</html>

Маршрутизация и работа с данными

Файловая маршрутизация

Astro использует файловую систему для маршрутизации — принцип, знакомый по Next.js:

src/pages/
├── index.astro          → /
├── about.astro          → /about
├── blog/
│   ├── index.astro      → /blog
│   └── [slug].astro     → /blog/любой-slug
└── api/
    └── products.ts      → /api/products  (API-эндпоинт)

Динамические маршруты и `getStaticPaths`

Для генерации динамических страниц используется функция getStaticPaths:

---
// src/pages/blog/[slug].astro
import { getCollection } from 'astro:content';
import BlogLayout from '../../layouts/BlogLayout.astro';

// Эта функция говорит Astro: "вот все возможные URL, которые нужно сгенерировать"
export async function getStaticPaths() {
  const posts = await getCollection('blog'); // читаем коллекцию из src/content/blog/

  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },              // передаём данные в компонент
  }));
}

const { post } = Astro.props;
const { Content } = await post.render(); // превращаем Markdown в компонент
---

<BlogLayout title={post.data.title} description={post.data.description}>
  <article>
    <h1>{post.data.title}</h1>
    <time>{post.data.publishedAt.toLocaleDateString('ru-RU')}</time>
    <!-- Content — это готовый к рендерингу HTML из Markdown-файла -->
    <Content />
  </article>
</BlogLayout>

Content Collections с типизацией

Система коллекций позволяет описать схему frontmatter и получить полную автодополнение в редакторе:

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blogCollection = defineCollection({
  type: 'content', // 'content' для Markdown, 'data' для JSON/YAML
  schema: z.object({
    title: z.string(),
    description: z.string(),
    publishedAt: z.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
    // Если поля нет — TypeScript немедленно об этом сообщит
    coverImage: z.string().optional(),
  }),
});

export const collections = {
  blog: blogCollection,
};

После этого getCollection('blog') вернёт типизированный массив, и вы не сможете случайно обратиться к несуществующему полю.

API-эндпоинты

Astro позволяет создавать серверные API прямо внутри проекта:

// src/pages/api/newsletter.ts
import type { APIRoute } from 'astro';

export const POST: APIRoute = async ({ request }) => {
  const body = await request.json();
  const { email } = body;

  if (!email || !email.includes('@')) {
    return new Response(
      JSON.stringify({ error: 'Некорректный email' }),
      { status: 400, headers: { 'Content-Type': 'application/json' } }
    );
  }

  // Здесь можно вызвать любой сервис: Mailchimp, Resend, собственную БД...
  await subscribeToNewsletter(email);

  return new Response(
    JSON.stringify({ success: true }),
    { status: 200, headers: { 'Content-Type': 'application/json' } }
  );
};

Сравнение с другими фреймворками

Понять место Astro в экосистеме проще всего через сравнение с конкурентами. Но важно понимать: это не «Astro против Next.js», а «разные инструменты для разных задач».

Сводная таблица

Критерий	Astro	Next.js	SvelteKit	Nuxt
JS по умолчанию	✅ Нет	❌ Да	⚠️ Минимум	❌ Да
Смешение фреймворков	✅ Да	❌ Нет	❌ Нет	❌ Нет
SSR	✅ Да	✅ Да	✅ Да	✅ Да
Встроенный роутер	✅ Файловый	✅ Файловый	✅ Файловый	✅ Файловый
Лучший случай	Контент-сайты	Rich SPA	Svelte-приложения	Vue-приложения
Порог входа	Низкий	Средний	Средний	Средний

Интеграция с UI-фреймворками на практике: Preact

Preact — это компактная библиотека компонентов, совместимая с React-экосистемой через preact/compat. В официальных материалах Preact подчеркивается, что compatibility layer позволяет использовать React-компоненты как drop-in replacement в ряде случаев, а сам Preact отличается более близким к DOM поведением и меньшим runtime-overhead, в том числе без synthetic event system.

В Astro интеграция с Preact подключается официальным пакетом @astrojs/preact. Для обычного использования достаточно команды astro add preact; после этого Astro умеет рендерить Preact-компоненты и гидрировать их через client:* директивы.

Установка и конфигурация

# Добавляем интеграцию одной командой
npx astro add preact

# Или вручную через npm
npm install @astrojs/preact preact

После этого обновляем конфиг:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';

export default defineConfig({
  integrations: [
    preact({
      // compat: true — включает слой совместимости с React,
      // что позволяет использовать некоторые React-библиотеки с Preact
      compat: true,
    }),
  ],
});

Особенности и тонкости при работе с Preact в Astro

Атрибуты class vs className. В Astro-компонентах (.astro) всегда используется class. В Preact-компонентах (.jsx) тоже рекомендуется class, а не className — это одно из отличий Preact от React.

Серверный рендеринг Preact-компонентов. Даже без клиентской директивы Preact-компоненты рендерятся на сервере в HTML. Директива лишь добавляет гидратацию. Это значит, что поисковик увидит контент компонента, даже если JavaScript в браузере отключён.

client:only="preact" нужен в редких случаях — когда компонент использует браузерные API (localStorage, window) и не может быть отрендерен на сервере. В таком случае Astro пропускает серверный рендеринг полностью.

// Компонент, который читает из localStorage — не может работать на сервере
export default function ThemeToggle() {
  const [theme, setTheme] = useState(
    // localStorage доступен только в браузере
    () => localStorage.getItem('theme') ?? 'light'
  );

  // ...
}

<!-- Правильно: client:only пропускает SSR -->
<ThemeToggle client:only="preact" />

Итог

Astro полезен там, где важны скорость первой отрисовки, небольшой клиентский бандл и гибкая интеграция с несколькими UI-фреймворками. Preact в этой экосистеме хорошо подходит для компактных интерактивных компонентов и для проектов, где нужна совместимость с частью React-экосистемы, но без полного веса React runtime.

Введение в архитектуру ПО. Часть 1: Истинная ценность структуры и цена спешки

2026-05-01T13:23:55Z

Введение

Вы когда-нибудь сталкивались с ситуацией, когда добавление «одной небольшой кнопки» на сайт превращается в задачу на несколько дней? Или когда каждый новый запрос от бизнеса оказывается сложнее предыдущего, хотя на первый взгляд всё выглядит просто? Как правило, причина кроется не в уровне команды и не в сложности самих задач - а в том, на каком фундаменте выполнен проект.

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

Что на самом деле означает хорошая архитектура

Распространённое заблуждение - считать, что хорошая архитектура обязательно предполагает сложные паттерны, многоуровневые абстракции или модные технологические решения. На практике всё значительно проще.

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

Именно это и является единственным значимым критерием.

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

Для тех, кто только начинает путь в разработке: представьте конструктор. Если детали рассортированы по типам и размерам, собирать новые уровни легко. Если всё свалено в одну кучу, а нижние уровни собраны кое-как - каждый новый этаж будет даваться труднее предыдущего, потому что прежде всего придётся укреплять то, что уже есть.

Для специалистов с опытом: в терминологии бизнеса это совокупная стоимость владения продуктом. Слабая архитектура делает кривую стоимости изменений экспоненциальной. Когда вы обосновываете необходимость рефакторинга перед заинтересованными сторонами - говорите именно об этом, а не об абстрактном «качестве кода».

Синдром быстрого старта и иллюзия «разберёмся потом»

Представьте строительную бригаду, которой поставили задачу возвести жилой дом в сжатые сроки. Чтобы уложиться в дедлайн, они принимают решение не тратить время на проектирование фундамента по всем нормам - заливают его быстро, приблизительно, «и так сойдёт». Первый этаж встаёт быстро. Второй - тоже. Заказчик доволен, темп впечатляет.

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

В разработке программного обеспечения происходит ровно то же самое.

Команды работают в условиях постоянного давления: сроки поджимают, рынок не ждёт. В такой обстановке легко поддаться соблазну сделать «как-нибудь сейчас, а разберёмся потом». Это, пожалуй, одно из самых распространённых и дорогостоящих заблуждений в индустрии.

Проблема в том, что это «потом» почти никогда не наступает. После первой задачи приходит вторая, за ней третья - давление не ослабевает, а технический долг неуклонно накапливается. До тех пор, пока рутинная задача вдруг не начинает занимать неделю вместо дня.

Именно тогда возникает идея: «Давайте перепишем всё с нуля». Но если подход к проектированию не меняется по существу, новая система через несколько лет придёт ровно к тому же результату - как если бы та же бригада построила рядом новый дом, но снова без нормального фундамента.

Здесь работает простая закономерность: поддерживать порядок в коде с самого начала - быстрее и дешевле, чем разгребать последствия накопленного беспорядка. На любой дистанции и при любом масштабе проекта.

Технический долг: когда метафора становится реальностью

Понятие технического долга - одно из наиболее точных в профессиональном лексиконе разработчиков. Оно появилось не случайно: его автор, программист Уорд Каннингем, намеренно использовал финансовую аналогию, чтобы сделать проблему понятной для бизнеса.

Суть аналогии такова. Когда компания берёт кредит, она получает деньги сейчас, но обязуется выплачивать проценты в будущем. Чем дольше она тянет с погашением - тем больше итоговая переплата. Технический долг работает по той же логике: принимая решение срезать углы сегодня, команда как бы берёт кредит у будущего. Расплата приходит в виде всё возрастающих затрат на поддержку и развитие системы.

Важно понимать: технический долг сам по себе не всегда является ошибкой. Иногда это осознанное и обоснованное решение. Например, стартап на ранней стадии может намеренно выбрать более простое техническое решение, чтобы быстро проверить гипотезу на рынке. Это разумно - при условии, что долг фиксируется явно и план по его погашению существует.

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

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

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

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

Две составляющие любого программного продукта

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

Поведение - это то, что система делает: считает, отображает, сохраняет, отправляет. Именно это видит бизнес и чувствуют пользователи. Многие считают, что если код работает - задача решена. Однако это лишь первая половина дела.

Структура - это то, насколько легко систему можно изменить.

Само английское слово software содержит в себе это значение: soft - мягкий, податливый. Программное обеспечение изначально задумано как то, что легко поддаётся изменениям. Сложность добавления новой возможности должна определяться только масштабом самой этой возможности - но никак не состоянием кодовой базы.

Наглядный пример: система формирует отчёты в формате PDF. Бизнес просит добавить выгрузку в Excel. Если архитектура продумана - это задача на несколько дней. Если логика формирования отчёта жёстко связана с логикой генерации PDF - команда переписывает модуль несколько недель.

Что важнее - поведение или структура? Ответ неочевиден, но принципиален.

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

Связанность и согласованность: два понятия, которые стоит знать

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

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

Хорошо спроектированная система стремится к низкой связанности. Модули взаимодействуют друг с другом через чётко определённые интерфейсы и не «знают» о внутреннем устройстве соседних компонентов. Это позволяет изменять, тестировать и заменять отдельные части системы независимо друг от друга.

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

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

Матрица Эйзенхауэра: почему архитектура всегда проигрывает в приоритетах

Президент Дуайт Эйзенхауэр сформулировал это так: «У меня есть два вида дел - срочные и важные. Срочные, как правило, не самые важные, а важные - не самые срочные».

В разработке эта закономерность проявляется особенно отчётливо.

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

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

Вывод здесь прост: если команда никогда не выделяет время на важное, потому что всегда находится что-то срочное - рано или поздно срочным становится всё.

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

Как архитектура влияет на команду: человеческое измерение

Разговор об архитектуре нередко сводится к техническим и экономическим аргументам. Однако есть ещё одно измерение, которое упускают из виду - человеческое.

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

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

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

Когда система организована логично, новый член команды способен разобраться в ней значительно быстрее. Когда модули изолированы и независимы, над разными частями продукта можно работать параллельно, не мешая друг другу. Всё это - не абстрактные преимущества, а вполне конкретные факторы, влияющие на скорость и качество разработки.

Как обосновывать важность архитектуры в диалоге с руководством

Разработчик - это не просто исполнитель, реализующий поставленные задачи. Это профессионал со своей зоной ответственности. И защита качества системы - неотъемлемая часть этой ответственности.

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

Несколько практических принципов:

Избегайте субъективных формулировок: «код стал некрасивым» или «это технически неправильно» не убеждают никого, кто не занимается разработкой.
Говорите на языке конкретных последствий: «Если мы выделим три дня на оптимизацию этого модуля сейчас, следующий этап займёт неделю, а не месяц».
Фиксируйте технический долг явно. Если ваша команда принимает осознанное решение сделать что-то упрощённо ради скорости - запишите это. Создайте задачу, опишите, что именно было сделано не так, как следовало бы, и почему. Это переводит технический долг из категории неосознанного накопления в категорию управляемого инструмента. Руководство видит, что команда отдаёт себе отчёт в принятых решениях, а не просто пишет «как получается».
Внедрите принцип постепенного улучшения: каждый раз, работая с определённым участком кода, оставляйте его в немного лучшем состоянии, чем он был до вашего вмешательства. Это не требует отдельного времени - это профессиональная привычка, которая со временем существенно меняет общее состояние системы.
Предлагайте компромиссы, а не ультиматумы. Вместо «нам нужна неделя на рефакторинг, иначе ничего не выйдет» попробуйте «давайте заложим в план двадцать процентов времени на улучшение структуры параллельно с основной работой». Это звучит управляемо и вызывает значительно меньше сопротивления.

Заключение

Если сформулировать главное из этого материала, получится следующее.

Качество архитектуры измеряется не технической изощрённостью решений, а тем, насколько легко и предсказуемо в систему вносятся изменения спустя месяцы и годы после запуска.

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

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

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

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

И наконец: умение объяснить всё это руководству на понятном бизнесу языке - такой же профессиональный навык, как и умение проектировать надёжные системы.

Спасибо, что прочитали материал до конца.

Данная статья является вводной и представляет собой лишь первый шаг в изучении архитектуры программного обеспечения. Тема значительно глубже, чем можно охватить в одном материале, и впереди ещё много интересного.

Следите за продолжением.

Анатомия письма: почему email-дизайн — это машина времени в 1999 год

2026-04-08T17:34:56Z

Вы когда-нибудь пробовали применить display: flex или grid в коде письма? Если да, то вы знаете чувство глубокого разочарования, когда Gmail, Outlook или Yahoo решают, что ваш современный красивый макет должен выглядеть как стена текста, набранная на печатной машинке.

Добро пожаловать в мир email-дизайна — уникальной дисциплины, где правила веб-разработки не работают, а стандарты де-факто застыли в эпохе Netscape Navigator. Здесь дизайнер и верстальщик вынуждены использовать табличную вёрстку, писать инлайновые стили и воевать с условными комментариями для Outlook. И тем не менее, именно здесь рождаются письма, которые читают, по которым кликают и которые приносят миллионы.

Эта статья — глубокое погружение в специфику создания адаптивных писем. Мы разберем, почему таблицы до сих пор правят бал, как сделать письмо красивым на iPhone и при этом не сломать его на древней версии Microsoft Outlook.

Часть 1. Великий парадокс: Почему email живет в прошлом?

В отличие от сайтов, которые вы открываете в одном-двух браузерах (Chrome, Safari), email-клиентов — сотни. Каждый из них использует свой движок для рендеринга HTML:

Gmail (веб и приложение) использует свой собственный, сильно урезанный HTML-парсер.
Outlook (десктоп) печально известен тем, что использует движок Microsoft Word (!) для отображения HTML.
Apple Mail — один из самых «продвинутых», поддерживает современные CSS.
Яндекс.Почта, Mail.ru — имеют свои особенности.

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

Часть 2. Табличная вёрстка: Скелет вашего письма

Забудьте про <div> с display: flex. В мире email главный строительный блок — это <table>.

2.1. Почему таблицы?

Предсказуемость: Таблицы были созданы для отображения структурированных данных. Их алгоритм рендеринга (как ячейки растягиваются и выравниваются) одинаков во всех клиентах.
Надёжность: Они устойчивы к «съеданию» тегов и стилей. Если какой-то CSS не сработает, таблица всё равно останется таблицей.
Вложенность: Вся вёрстка письма — это матрёшка из вложенных друг в друга таблиц.

2.2. Базовая структура «резинового» письма

Современное адаптивное письмо строится по следующему шаблону:

<center>
    <table role="presentation" width="100%" border="0" cellpadding="0" cellspacing="0">
        <tr>
            <td align="center">
                <!-- Основной контейнер письма (ширина 600px) -->
                <table role="presentation" width="600" border="0" cellpadding="0" cellspacing="0">
                    <!-- ШАПКА -->
                    <tr>
                        <td> ... </td>
                    </tr>
                    <!-- ГЕРОЙ (Баннер) -->
                    <tr>
                        <td> ... </td>
                    </tr>
                    <!-- ТЕЛО С КОЛОНКАМИ -->
                    <tr>
                        <td>
                            <table role="presentation" width="100%" border="0" cellpadding="0" cellspacing="0">
                                <tr>
                                    <td class="stack" width="280"> Левая колонка </td>
                                    <td class="stack" width="20"> Отступ </td>
                                    <td class="stack" width="280"> Правая колонка </td>
                                </tr>
                            </table>
                        </td>
                    </tr>
                    <!-- ФУТЕР -->
                    <tr>
                        <td> ... </td>
                    </tr>
                </table>
            </td>
        </tr>
    </table>
</center>

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

role="presentation" — говорит скрин-ридерам, что это таблица для вёрстки, а не для данных.
width="100%" — делает внешнюю таблицу «резиновой».
align="center" — центрирует всё письмо.

Часть 3. Адаптивность: Как превратить две колонки в одну

На десктопе мы видим две колонки текста. На мобильном телефоне они должны встать друг под друга. Это достигается с помощью медиа-запросов и трюка с display: block !important.

3.1. Медиа-запросы

Мы задаём правило: если ширина экрана меньше 600px, то заставляем наши колонки (с классом .stack) стать блочными и растянуться на 100%.

@media only screen and (max-width: 600px) {
    .stack {
        display: block !important;
        width: 100% !important;
    }
}

В нашем примере выше, у колонок ширина 280px и отступа 20px. На мобильном они получат width: 100% и выстроятся вертикально, а отступ превратится в пустую строку.

3.2. Проблема кнопок

Кнопки в письмах — это главная головная боль. <button> работает плохо. Ссылка <a> с padding тоже часто ломается в Outlook.
Надёжный способ (Bulletproof Button):
Сделать кнопку через границы ячейки таблицы.

<table role="presentation" border="0" cellpadding="0" cellspacing="0">
    <tr>
        <td align="center" bgcolor="#007bff" style="border-radius: 4px;">
            <a href="https://example.com" style="display: inline-block; padding: 12px 24px; color: #fff; text-decoration: none; font-weight: bold;">Купить сейчас</a>
        </td>
    </tr>
</table>

Почему это работает? Фон задаётся ячейке (td), а ссылка внутри просто растягивается. Outlook не любит фон у ссылок, но любит фон у ячеек.

Часть 4. Тонкая настройка: Инлайновые стили и условные комментарии

4.1. Инлайн — король

Никогда не полагайтесь на то, что стили, прописанные в <head> или внешнем CSS, сработают. Gmail, например, вырезает <style> при определённых условиях. Правило: все стили, касающиеся отступов, цветов, границ, шрифтов, должны быть прописаны в атрибуте style каждого тега.

<td style="padding: 20px; font-family: Arial, sans-serif; color: #333;">

4.2. Условные комментарии для Microsoft Outlook

Outlook (особенно 2007, 2010, 2013) — это темная лошадка. Чтобы задать стили только для Outlook, используют условные комментарии, которые никто, кроме Outlook, не видит.

<!--[if mso]>
    <style type="text/css">
        /* Стили, которые увидит только Outlook */
        .outlook-button { background: #000; }
    </style>
<![endif]-->

А для обратной ситуации (спрятать что-то от Outlook):

<!--[if !mso]><!-->
    <div style="display: none;">Это увидят все, кроме Outlook</div>
<!--<![endif]-->

Часть 5. Изображения: Смертельный номер

В email-дизайне изображения — это источник проблем. Многие почтовые клиенты по умолчанию блокируют загрузку картинок (пользователь должен нажать «Показать изображения»). Если ваше письмо — одна большая картинка, пользователь увидит пустоту.

Правила работы с изображениями:

Не кладите текст на картинки. Если картинка не загрузится, текст не увидят.
Всегда прописывайте ALT-текст. И делайте его полезным: не «логотип», а «Купите iPhone со скидкой 20%».
Используйте атрибуты ширины и высоты. Без них Outlook может отобразить картинку размером 1x1 пиксель.

<img src="..." alt="Описание" width="600" height="200" style="display: block; width: 100%; height: auto;">

Спрайты и адаптивность: Чтобы картинка сжималась на мобильном, дайте ей style="width: 100%; height: auto;".

Часть 6. Инструменты и тестирование

Спроектировать письмо «на глаз» невозможно. Вы обязательно что-то сломаете в Outlook или Gmail.

Современный подход к созданию писем:

Дизайн в Figma: Рисуйте макет, помня, что ширина письма редко превышает 600px (оптимально для чтения).

Фреймворк MJML: Это спасение. Вы пишете простой, понятный код на MJML, а компилятор превращает его в идеально работающую табличную вёрстку. Это стандарт индустрии.

Тестирование (важно!):

Litmus / Email on Acid: Платные сервисы, которые прогоняют ваше письмо через 90+ клиентов и показывают скриншоты.
PutsMail: Бесплатный инструмент для отправки тестовых писем.
Реальная отправка: Заведите себе аккаунты в Gmail, Яндекс.Почте, Outlook.com, Mail.ru и отправляйте письма себе.

Заключение: Это не баг, это фича

Дизайн для email-рассылок раздражает веб-разработчиков своей архаичностью. Но это осознанный выбор, продиктованный средой. Умение создать надёжное, красивое и конвертирующее письмо, которое работает даже в Outlook 2007, — это признак высокой квалификации.

В следующий раз, когда вы откроете красивую рассылку от Apple или Amazon, знайте: внутри неё — десятки вложенных таблиц, условные комментарии и надежда, что пользователь включил отображение картинок. Это и есть магия email-дизайна.

Нативная поддержка gRPC в Spring

2026-04-07T16:08:06Z

Не так давно в релиз был выкачена первая мажорная версия библиотеки Spring gRPC - для встроенной поддержки gRPC-сервисов в приложении Spring Boot. Она развивается внутри экосистемы Spring, а значит версионирование и интеграция с Boot - это теперь не вызывает проблем. У меня появился интерес протестить это in action.

Начнем с того, что подключим необходимые зависимости в build.gradle.kts:

implementation("org.springframework.grpc:spring-grpc-spring-boot-starter")
implementation("com.google.protobuf:protobuf-java")

Допустим, у нас есть такой proto-файл:

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

Реализация сервиса на kotlin будет выглядить следующим образом:

@GrpcService 
class GreeterService : GreeterGrpc.GreeterImplBase() {

    override fun sayHello(
        request: HelloRequest,
        responseObserver: StreamObserver<HelloReply>
    ) {
        val reply = HelloReply.newBuilder()
            .setMessage("Hello, ${request.name}!")
            .build()

        responseObserver.onNext(reply)
        responseObserver.onCompleted()
    }
}
// можно использовать и аннотацию @Service, но на личный вкус @GrpcService выглядит нагляднее

Spring gRPC автоматически обнаружит все бины, которые реализуют BindableService (это интерфейс, от которого наследует ImplBase), и зарегистрирует их на gRPC-сервере.

Дело за малым - осталось всё собрать и протестировать. Делать я это буду с помощью cli тулзы grpcurl, которая как раз предназначена для протыкивания grpc сервисов.

Подводя итог, можно сказать, что Spring gRPC успешно решает главную задачу - делает интеграцию gRPC в Spring Boot максимально бесшовной и нативной. Как показал тест, весь процесс настройки сводится к подключению стартера и созданию класса с аннотацией @Service. Автоматическое обнаружение сервисов и привычная работа через DI позволяют сосредоточиться на бизнес-логике, не отвлекаясь на инфраструктурные сложности.

Кэширование пользовательских ролей из стороннего сервиса при Stateless-аутентификации (Spring)

2026-04-06T13:47:44Z

Представим не столь редкую ситуацию, когда у нас есть некоторый сервис на базе Spring, к которому шлет запросы клиентское приложение. Фронтэнд взаимодействует с Keycloak (или другим сервером аутентификации, не столь важно), определяет пользователя, делающего запросы, и при обращении к нашему сервису подкладывает в заголовок "Authorization" Bearer-токен в виде JWT, на основании которого в сервисе должны происходить идентификация пользователя и определение прав доступа.

Схема обычная и соответствует стандарту авторизации OAuth 2.0, однако проблемы возникают, если нам необходимо непосредственно в процессе авторизации выдать те или иные права, основываясь на данных из другого сервиса, либо в целом приходится использовать какие-либо данные извне. Несмотря на все преимущества stateless-аутентификации, среди которых масштабируемость и производительность, в данном случае она будет проблемой, потому что при данном подходе сервер не использует сессии и не хранит никакой информации о клиенте между запросами. Таким образом, информация из стороннего сервиса будет запрашиваться заново при каждом запросе, что может сильно ударить по производительности системы. Конечно подобные проблемы лучше решать еще на этапе проектирования архитектуры всей системы, но если ситуация уже возникла, то решение есть.

Чтобы не запрашивать данные из стороннего сервиса каждый раз, можно прибегнуть к кэшированию данных, сохраняя их по идентификатору пользователя. Для этого есть несколько решений, но мы рассмотрим вариант, оптимальный по сложности реализации и скорости выполнения. Это будет стандартная поддержка кэширования Spring и библиотека Caffeine, которая де-факто уже также стала частью стандарта кэширования в Spring. Это будет быстрее, чем читать и обновлять значения из Redis, поднимать который имеет смысл лишь в случае множества распределенных сервисов, поскольку в данном случае кэш будет храниться прямо в памяти приложения. В дополнение к этому мы также напишем конвертер для аутентификации, который при входе будет объединять роли из Keycloak и роли, приходящие из стороннего сервиса, чтобы в нашем сервисе можно было единообразно их использовать.

Шаг 1. Зависимости и конфигурация приложения

Добавить зависимости:

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'
    implementation 'org.springframework.boot:spring-boot-starter-cache'
    implementation 'com.github.ben-manes.caffeine:caffeine'
}

В главный класс надо добавить аннотацию @EnableCaching, которая включит кэширвание в Spring
Добавить в application.yml нужные настройки:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://your-keycloak.com/realms/test
  cache:
    cache-names: infoFromOtherService
    caffeine:
      spec: expireAfterWrite=60s,maximumSize=1000

Здесь под issuer-uri мы указываем адрес Keycloak для проверки валидности токена, который пришел с клиентского приложения. В разделе cache указываем название для кэша, где мы будем хранить информацию о пользователе, приходящую из стороннего сервиса. В spec мы указываем настройки caffeine, которые помогут не очищать кэш самостоятельно, а задать ему срок жизни (в данном случае 60 секунд), после которого данные будут запрашиваться снова. В maximumSize пишется максимальный размер кэша, чтобы он не мог занять слишком много места.

Шаг 2. Сервис, который запрашивает данные о пользователе из стороннего сервиса


import org.springframework.cache.annotation.Cacheable;
import org.springframework.stereotype.Service;

@Service
public class ExternalSourceService {

    // sync = true защищает от повторной отправки застрявших в очереди запросов при истечении кэша
    @Cacheable(value = "infoFromOtherService", key = "#username", sync = true)
    public List<String> getInfoFromExternalSource(String username) {
        // Вызов API
        return externalSourceClient.findExternalInfoByUsername(username); 
    }
}

Это самый обычный сервис, который делает необходимый запрос по указанному API. Не будем приводить его реализацию, поскольку это сильно зависит от конкретного случая, отметим только необходимость добавить аннотацию Cacheable, value которой совпадает с названием кэша из настроек. С помощью этой аннотации мы отмечаем, что результаты именно этого метода необходимо кэшировать.

Шаг 3. Конвертер, преобразующий JWT-токен

import org.springframework.stereotype.Component;
import org.springframework.beans.factory.annotation.Autowired;

@Component
@RequiredArgsConstructor
public class AuthenticationConverter implements Converter<Jwt, AbstractAuthenticationToken> {

    @Autowired
    private final ExternalSourceService externalSourceService;

    @Override
    public AbstractAuthenticationToken convert(Jwt jwt) {
        UUID userId = UUID.fromString(jwt.getSubject()); // UUID пользователя
        String username = jwt.getClaimAsString("preferred_username"); // имя пользователя
        Collection<GrantedAuthority> roles = extractKeycloakRoles(jwt); // получаем роли из Keycloak
        // получаем информацию о пользователе из стороннего источника (что кэшируется)
        String externalSourceUserInfo = externalSourceService.getInfoFromExternalSource(username);
        try {
            // пытаемся добавить роли пользователя из стороннего источника
            Collection<GrantedAuthority> rolesFromExternalSource = extractExternalRoles(externalSourceUserInfo);
            roles.addAll(rolesFromExternalSource);
        } catch (JsonProcessingException e) {
            log.error("Cannot parse user info ", e);
        }
        return new JwtAuthenticationToken(jwt, roles, username);
    }

    private Collection<GrantedAuthority> extractKeycloakRoles(Jwt jwt) {
        Map<String, Object> realmAccess = jwt.getClaim("realm_access");
        if (realmAccess == null || realmAccess.isEmpty()) return Collections.emptyList();
        Collection<String> roles = (Collection<String>) realmAccess.get("roles");
        return roles.stream()
                .map(role -> new SimpleGrantedAuthority("ROLE_" + role))
                .collect(Collectors.toList());
    }

    private Collection<GrantedAuthority> extractExternalRoles(String externalSourceUserInfo) throws JsonProcessingException {
        ObjectMapper objectMapper = new ObjectMapper();
        JsonNode rootNode = objectMapper.readTree(externalSourceUserInfo);
        // достаем нужный кусок JSON, но парсинг ответа от стороннего сервиса зависит от особенностей конкретной системы
        JsonNode globalRoles = rootNode.get("roles");
        return objectMapper.convertValue(globalRoles, new TypeReference<List<String>>() {
                }).stream().map(role -> new SimpleGrantedAuthority("ROLE_" + role))
                .collect(Collectors.toList());
    }

Шаг 4. Конфигурация Spring Security

import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Autowired
    private AuthenticationConverter authenticationConverter;

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
                .csrf().disable()
                .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
                .and().authorizeRequests()
                    .antMatchers("/api/v1/example/**").authenticated()
                    .anyRequest().hasAnyRole("EXTERNAL_SOURCE_ADMIN")
                .and().oauth2ResourceServer().jwt().jwtAuthenticationConverter(authenticationConverter);

    }
}

Здесь мы уже можем в правилах проверки прав использовать те роли, которые мы получили из стороннего сервиса (вместе с кейклоковскими). И главное, что получение этих ролей не будет отрабатывать при каждом запросе к нашему сервису, а будет происходить лишь по истечении кэша, настройки которого, с использованием Caffeine, можно регулировать в application.yml.

REST API: 5 паттернов формирования ответов, которые используют опытные разработчики

2026-04-01T10:44:07Z

Введение

Представьте: вы только что запустили новый сервис. Первые эндпоинты работают, данные приходят, фронтенд доволен. Но спустя полгода приходит задача — переименовать колонку в базе данных. Вы меняете одно поле, и внезапно ломаются три мобильных клиента, два фронтенд-приложения и интеграция с партнёром. Почему? Потому что ваш API с самого начала возвращал сырые сущности напрямую из базы данных.

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

Возвращать необработанные JPA-сущности из REST-контроллеров — это один из тех паттернов, который кажется безобидным в начале, но затем превращается в системную проблему в production. Он не просто нарушает принцип разделения ответственности — он создаёт три взаимосвязанных риска одновременно: утечку чувствительных данных, жёсткую связанность API со схемой БД и потерю контроля над публичным контрактом.

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

Проблема прямого возврата сущностей

Прежде чем переходить к решениям, важно понять, в чем именно состоит проблема.

Рассмотрим типичную JPA-сущность:

@Entity
@Table(name = "users")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String firstName;
    private String lastName;
    private String email;

    // Никогда не должно покидать сервер
    private String passwordHash;

    // Внутренние поля, не нужные клиентам
    private String internalNotes;
    private String resetToken;
    private LocalDateTime resetTokenExpiry;

    // Технические поля аудита
    @CreatedDate
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime updatedAt;

    @Version
    private Long version;
}

А теперь — типичный контроллер новичка:

@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
    return userRepository.findById(id).orElseThrow();
    // В ответе окажется: passwordHash, internalNotes,
    // resetToken, resetTokenExpiry, version...
}

Этот код порождает три серьёзные проблемы.

Проблема 1: Утечка чувствительных данных. Поле `passwordHash` попадёт в JSON-ответ. Даже если там не открытый пароль, а хеш — это уже вектор для атак. Поле `resetToken` тоже не должно быть видно никому, кроме системы сброса пароля. Можно добавить `@JsonIgnore` на отдельные поля, но это ненадёжно: забудете об одном поле при добавлении — и утечка неизбежна.

Проблема 2: Жёсткая связанность с базой данных. Ваш API-контракт теперь является точным отражением вашей схемы БД. Переименовали `firstName` в `first_name` для соответствия coding style? Поздравляем — вы сломали всех клиентов. Разделили таблицу `users` на `users` и `user_profiles`? Теперь нужно менять не только схему, но и весь публичный API.

Проблема 3: Отсутствие контроля над контрактом. API должен выражать бизнес-понятия, а не структуру хранилища. Клиент хочет получить `fullName` вместо `firstName` + `lastName`? С сырыми сущностями это невозможно без изменения схемы БД.

Для решения этих проблем, на помощь приходят проверенные паттерны. Рассмотрим их по порядку.

Паттерн 1: Record-классы для формирования ответа

Проблема

Традиционные DTO-классы на Java требуют написания конструкторов, геттеров, сеттеров, `equals`, `hashCode` и `toString`. Это десятки строк шаблонного кода на каждую форму ответа. Даже с Lombok это всё равно дополнительные аннотации и косвенность.

Решение

Java Records (доступны с Java 16) дают вам неизменяемый объект передачи данных в несколько строк — без Lombok, без шаблонного кода, без сюрпризов.

public record UserResponse(
    Long id,
    String firstName,
    String lastName,
    String email
) {}

Вот и всё. Java автоматически генерирует конструктор, геттеры, `equals`, `hashCode` и `toString`. Объект неизменяем по умолчанию — никаких сеттеров, никаких случайных мутаций.

Полный пример

// Сервисный слой
@Service
@RequiredArgsConstructor
public class UserService {

    private final UserRepository userRepository;

    public User findById(Long id) {
        return userRepository.findById(id)
            .orElseThrow(() -> new EntityNotFoundException("User not found: " + id));
    }
}

// Контроллер
@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    @GetMapping("/{id}")
    public UserResponse getUser(@PathVariable Long id) {
        User user = userService.findById(id);
        return new UserResponse(
            user.getId(),
            user.getFirstName(),
            user.getLastName(),
            user.getEmail()
        );
    }
}

Важные детали

Вложенные Record-классы хорошо работают для составных ответов:

public record AddressResponse(
    String street,
    String city,
    String country
) {}

public record UserDetailResponse(
    Long id,
    String firstName,
    String lastName,
    String email,
    AddressResponse address,        // вложенный record
    List<String> roles              // коллекции тоже поддерживаются
) {}

Кастомная сериализация настраивается через стандартные Jackson-аннотации:

public record UserResponse(
    Long id,
    String firstName,
    String lastName,
    String email,

    @JsonFormat(pattern = "dd.MM.yyyy")
    LocalDate birthDate,

    @JsonProperty("isVerified")
    boolean verified
) {}

Почему опытные разработчики это ценят: Record-классы самодокументируемы — любой член команды, открыв файл, немедленно видит полный контракт эндпоинта. Не нужно читать маппер, искать аннотации `@JsonIgnore` или гадать, какие поля попадут в ответ.

Паттерн 2: MapStruct для конвертации без шаблонного кода

Проблема

Ручное маппирование — серьёзная проблема при масштабировании. Когда у вас десять сущностей, каждая с двадцатью полями, написание маппинга вручную превращается в рутину, которая к тому же молча ломается. Добавили новое обязательное поле в `UserResponse`, но забыли обновить маппер? Компилятор промолчит, тесты не поймают — и вы получите `null` в production.

Решение

MapStruct генерирует код конвертации на этапе компиляции через annotation processing. Вы объявляете только интерфейс — всё остальное делает библиотека.

<!-- pom.xml -->
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.5.5.Final</version>
</dependency>
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct-processor</artifactId>
    <version>1.5.5.Final</version>
    <scope>provided</scope>
</dependency>

Полный пример

// Базовый маппер
@Mapper(componentModel = "spring")
public interface UserMapper {

    // Простое маппирование: поля с одинаковыми именами — автоматически
    UserResponse toResponse(User user);

    // Маппирование коллекций — бесплатно
    List<UserResponse> toResponseList(List<User> users);

    // Кастомное маппирование полей с разными именами
    @Mapping(source = "passwordHash", target = "hasPassword",
             qualifiedByName = "passwordToBoolean")
    UserAdminResponse toAdminResponse(User user);

    @Named("passwordToBoolean")
    default boolean mapPassword(String passwordHash) {
        return passwordHash != null && !passwordHash.isEmpty();
    }

    // Игнорирование поля в целевом объекте
    @Mapping(target = "sensitiveData", ignore = true)
    UserPublicResponse toPublicResponse(User user);

    // Вычисляемые поля
    @Mapping(target = "fullName",
             expression = "java(user.getFirstName() + \" \" + user.getLastName())")
    UserSummaryResponse toSummaryResponse(User user);
}

// Использование в контроллере
@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;
    private final UserMapper userMapper;

    @GetMapping("/{id}")
    public UserResponse getUser(@PathVariable Long id) {
        return userMapper.toResponse(userService.findById(id));
    }

    @GetMapping
    public List<UserResponse> getAllUsers() {
        return userMapper.toResponseList(userService.findAll());
    }
}

Важные детали

Что происходит при несовпадении полей: MapStruct по умолчанию выдаёт предупреждение компилятора, если у целевого объекта есть поле, которое не замаппировано. Это можно настроить:

// Превратить предупреждение в ошибку компиляции — рекомендуется для production
@Mapper(
    componentModel = "spring",
    unmappedTargetPolicy = ReportingPolicy.ERROR  // жёсткий режим
)
public interface UserMapper { ... }

Маппинг между вложенными объектами работает автоматически, если зарегистрировать вспомогательные маппинги:

@Mapper(componentModel = "spring", uses = {AddressMapper.class})
public interface UserMapper {
    // Address внутри User будет смаппирован через AddressMapper автоматически
    UserDetailResponse toDetailResponse(User user);
}

Почему опытные разработчики это ценят: MapStruct — это отраслевой стандарт в крупных компаниях. Один интерфейс заменяет десятки строк ручного маппинга, при этом ошибки обнаруживаются на этапе компиляции, а не в production в три часа ночи.

Паттерн 3: Проекции Spring Data для эндпоинтов чтения

Проблема

Типичный сценарий: страница со списком пользователей отображает только имя и email. Но ваш репозиторий загружает из базы данных всю сущность — включая `bio`, `avatarUrl`, `preferences`, `notificationSettings` и ещё пятнадцать полей, которые на этой странице просто не нужны. Это избыточный SELECT, лишний трафик и бесполезная нагрузка на сериализатор.

Решение

Spring Data поддерживает проекции — интерфейсы, которые указывают репозиторию: «загрузи только эти поля». На уровне SQL это выражается в `SELECT id, first_name, email FROM users` вместо `SELECT * FROM users`.

Полный пример

// Объявление проекции — просто интерфейс
public interface UserSummary {
    Long getId();
    String getFirstName();
    String getEmail();
}

// Проекция для вложенных объектов
public interface UserWithAddress {
    Long getId();
    String getEmail();
    AddressSummary getAddress();  // вложенная проекция

    interface AddressSummary {
        String getCity();
        String getCountry();
    }
}

// Репозиторий
public interface UserRepository extends JpaRepository<User, Long> {

    // Возвращает только нужные поля
    List<UserSummary> findAllBy();

    // С фильтрацией
    List<UserSummary> findByActiveTrue();

    // Динамическая проекция — тип выбирается вызывающим кодом
    <T> List<T> findByDepartmentId(Long departmentId, Class<T> type);
}

// Контроллер
@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor
public class UserController {

    private final UserRepository userRepository;

    @GetMapping
    public List<UserSummary> getUsers() {
        return userRepository.findAllBy();
        // SQL: SELECT u.id, u.first_name, u.email FROM users u
    }

    @GetMapping("/list")
    public List<UserListItem> getUserList() {
        // Динамическая проекция
        return userRepository.findByDepartmentId(1L, UserListItem.class);
    }
}

Важные детали

Существуют два типа проекций, и важно понимать разницу:

Closed projection — интерфейс, где геттеры точно соответствуют полям сущности. Hibernate оптимизирует SQL: `SELECT id, first_name, email FROM users`. Это обеспечивает максимальную производительность.

Open projection — интерфейс с аннотацией `@Value` и SpEL-выражениями. Hibernate вынужден загружать всю сущность в память, а потом вычислять поле. Производительность хуже, но гибкость выше.

// Closed — оптимальный SQL
public interface UserSummary {
    Long getId();
    String getEmail(); // точное соответствие полям сущности
}

// Open — полная загрузка сущности, потом вычисление

// Расширенная проекция с вычисляемым полем через SpEL
public interface UserSummaryOpen {
    Long getId();
    String getEmail();
    String getFirstName();
    String getLastName();

    // Вычисляемое поле — склеивается на уровне Java, не SQL
    @Value("#{target.firstName + ' ' + target.lastName}")
    String getFullName(); // Hibernate загружает ВСЕ поля
}

Почему опытные разработчики это ценят: Проекции — это одновременно паттерн безопасности и инструмент оптимизации. Одно объявление интерфейса устраняет и DTO-класс, и лишний трафик к базе данных.

Паттерн 4: Конвертные ответы для единообразных контрактов API

Проблема

Клиент вашего API делает десять запросов к десяти разным эндпоинтам. У каждого своя структура: один возвращает объект напрямую, другой оборачивает в `{ "data": ... }`, третий при ошибке отдаёт строку, четвёртый — объект с полем `error`. Frontend-разработчики пишут десять разных обработчиков. Новые члены команды не знают, что ожидать. Интеграция с партнёрами превращается в квест по документации.

Решение

Единый конверт ответа (Envelope Pattern) — универсальная обёртка, которая делает каждый эндпоинт предсказуемым.

//  Универсальный конверт ответа
public record ApiResponse<T>(
    boolean success,
    String message,
    T data,
    List<String> errors,
    Map<String, Object> meta
) {
    // Успешный ответ с данными
    public static <T> ApiResponse<T> ok(T data) {
        return new ApiResponse<>(true, "OK", data, null, null);
    }

    // Успешный ответ с данными и пагинацией
    public static <T> ApiResponse<T> ok(T data, Map<String, Object> meta) {
        return new ApiResponse<>(true, "OK", data, null, meta);
    }

    // Ответ об ошибке
    public static <T> ApiResponse<T> error(String message) {
        return new ApiResponse<>(false, message, null, null, null);
    }

    // Ответ с несколькими ошибками (например, ошибки валидации)
    public static <T> ApiResponse<T> validationError(List<String> errors) {
        return new ApiResponse<>(false, "Validation failed", null, errors, null);
    }
}

Полный пример с пагинацией и обработкой ошибок

// Контроллер
@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;
    private final UserMapper userMapper;

    // Обычный запрос
    @GetMapping("/{id}")
    public ResponseEntity<ApiResponse<UserResponse>> getUser(@PathVariable Long id) {
        UserResponse user = userMapper.toResponse(userService.findById(id));
        return ResponseEntity.ok(ApiResponse.ok(user));
    }

    // Запрос с пагинацией — мета-информация передаётся в конверте
    @GetMapping
    public ResponseEntity<ApiResponse<List<UserResponse>>> getUsers(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {

        Page<User> usersPage = userService.findAll(PageRequest.of(page, size));

        Map<String, Object> meta = Map.of(
            "page", usersPage.getNumber(),
            "size", usersPage.getSize(),
            "totalElements", usersPage.getTotalElements(),
            "totalPages", usersPage.getTotalPages(),
            "last", usersPage.isLast()
        );

        return ResponseEntity.ok(
            ApiResponse.ok(userMapper.toResponseList(usersPage.getContent()), meta)
        );
    }
}

// Глобальный обработчик ошибок — ключевая часть паттерна
@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(EntityNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ApiResponse<Void> handleNotFound(EntityNotFoundException ex) {
        return ApiResponse.error(ex.getMessage());
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ApiResponse<Void> handleValidation(MethodArgumentNotValidException ex) {
        List<String> errors = ex.getBindingResult()
            .getFieldErrors()
            .stream()
            .map(fe -> fe.getField() + ": " + fe.getDefaultMessage())
            .collect(Collectors.toList());
        return ApiResponse.validationError(errors);
    }

    @ExceptionHandler(AccessDeniedException.class)
    @ResponseStatus(HttpStatus.FORBIDDEN)
    public ApiResponse<Void> handleAccessDenied(AccessDeniedException ex) {
        return ApiResponse.error("Access denied");
    }
}

Теперь клиент всегда получает предсказуемую структуру:

// Успех
{
  "success": true,
  "message": "OK",
  "data": { "id": 1, "firstName": "Иван", "email": "ivan@example.com" },
  "errors": null,
  "meta": null
}

// Ошибка валидации
{
  "success": false,
  "message": "Validation failed",
  "data": null,
  "errors": ["email: must be a valid email", "firstName: must not be blank"],
  "meta": null
}

// Пагинация
{
  "success": true,
  "message": "OK",
  "data": [...],
  "errors": null,
  "meta": { "page": 0, "size": 20, "totalElements": 150, "totalPages": 8 }
}

Важные детали

Некоторые команды выбирают более лёгкий вариант без `success`/`errors` и просто полагаются на HTTP-статусы. Это тоже валидный подход. Главное — единообразие: выбранный формат должен применяться ко всем эндпоинтам без исключений.

Почему опытные разработчики это ценят: Единообразие API — признак зрелой кодовой базы. Это разница между API, с которым внешние команды работают с удовольствием, и тем, интеграции с которым боятся.

Паттерн 5: @JsonView для ролевого формирования ответов

Проблема

Бизнес-требование: публичные пользователи должны видеть имя и email; менеджеры - также дату рождения и телефон; администраторы должны видеть всё, включая внутренние заметки и историю входов. Самое простое решение — создать три отдельных DTO: `UserPublicResponse`, `UserManagerResponse`, `UserAdminResponse`. Однако, при десяти ролях и двадцати сущностях это превращается в сотни DTO-классов, которые нужно синхронизировать при каждом изменении.

Решение

Jackson `@JsonView` позволяет управлять видимостью полей на уровне сериализации: одна сущность, несколько представлений, ноль дублирующихся классов.

Полный пример

// Определение иерархии представлений
public class UserViews {
    // Иерархия через наследование:
    // Admin видит всё, что видит Manager,
    // Manager видит всё, что видит Public
    public interface Public {}
    public interface Manager extends Public {}
    public interface Admin extends Manager {}
}

// Сущность с разметкой полей
@Entity
@Table(name = "users")
public class User {

    @Id
    @JsonView(UserViews.Public.class)
    private Long id;

    @JsonView(UserViews.Public.class)
    private String firstName;

    @JsonView(UserViews.Public.class)
    private String lastName;

    @JsonView(UserViews.Public.class)
    private String email;

    // Видно менеджерам и выше
    @JsonView(UserViews.Manager.class)
    private String phone;

    @JsonView(UserViews.Manager.class)
    private LocalDate birthDate;

    @JsonView(UserViews.Manager.class)
    private String department;

    // Только для администраторов
    @JsonView(UserViews.Admin.class)
    private String internalNotes;

    @JsonView(UserViews.Admin.class)
    private LocalDateTime lastLoginAt;

    @JsonView(UserViews.Admin.class)
    private String lastLoginIp;

    @JsonView(UserViews.Admin.class)
    private boolean accountLocked;

    // Поля без @JsonView не попадают ни в один ответ
    private String passwordHash;
    private String resetToken;
}

// Контроллер с тремя представлениями
@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    // Публичный профиль — для всех
    @GetMapping("/{id}/profile")
    @JsonView(UserViews.Public.class)
    public User getPublicProfile(@PathVariable Long id) {
        return userService.findById(id);
        // Ответ: id, firstName, lastName, email
    }

    // Расширенный профиль — для менеджеров
    @GetMapping("/{id}/details")
    @JsonView(UserViews.Manager.class)
    @PreAuthorize("hasAnyRole('MANAGER', 'ADMIN')")
    public User getUserDetails(@PathVariable Long id) {
        return userService.findById(id);
        // Ответ: id, firstName, lastName, email, phone, birthDate, department
    }

    // Полный профиль — только для администраторов
    @GetMapping("/admin/{id}")
    @JsonView(UserViews.Admin.class)
    @PreAuthorize("hasRole('ADMIN')")
    public User getAdminProfile(@PathVariable Long id) {
        return userService.findById(id);
        // Ответ: все поля, размеченные @JsonView(Admin.class) и выше
    }
}

Важные детали

Тестирование ролевой видимости — важная часть работы с `@JsonView`:

@Test
void publicProfileShouldNotExposePhone() throws Exception {
    mockMvc.perform(get("/api/v1/users/1/profile"))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.phone").doesNotExist())
        .andExpect(jsonPath("$.internalNotes").doesNotExist())
        .andExpect(jsonPath("$.email").exists());
}

Программное переключение представления — когда роль определяется динамически:

@GetMapping("/{id}")
public ResponseEntity<String> getUser(@PathVariable Long id) throws JsonProcessingException {
    User user = userService.findById(id);

    Class<?> view = SecurityUtils.isAdmin()
        ? UserViews.Admin.class
        : UserViews.Public.class;

    ObjectWriter writer = objectMapper.writerWithView(view);
    return ResponseEntity.ok(writer.writeValueAsString(user));
}

Ограничение паттерна: `@JsonView` применяется только к сериализации. Если вы возвращаете саму сущность, вы всё равно загружаете из базы все поля. Для оптимизации запросов к БД этот паттерн нужно комбинировать с проекциями (паттерн 3).

Почему опытные разработчики это ценят: Ролевое управление видимостью полей — требование безопасности в большинстве production-систем. `@JsonView` реализует его на уровне сериализации — самом надёжном месте, где невозможно случайно «забыть» применить фильтрацию.

Сравнение паттернов: когда что применять

| Паттерн | Лучше всего для | Компромисс |

| Record-классы | Любые DTO, быстрый старт | Ручное маппирование при простых случаях |

| MapStruct | Большие проекты, много сущностей | Требует настройки зависимости |

| Проекции | Эндпоинты списков и чтения | Ограниченная гибкость при сложных вычислениях |

| Envelope | Публичные API, интеграции с партнёрами | Небольшой оверхед структуры ответа |

| @JsonView | Ролевой доступ к полям | Не оптимизирует запрос к БД |

На практике паттерны комбинируются. Зрелый проект обычно использует их все одновременно:

// Все паттерны вместе
@GetMapping("/{id}")
@JsonView(UserViews.Public.class)           // Паттерн 5: ролевая фильтрация
public ApiResponse<UserResponse> getUser(@PathVariable Long id) {
    return ApiResponse.ok(                  // Паттерн 4: конверт ответа
        userMapper.toResponse(              // Паттерн 2: MapStruct
            userService.findById(id)
        )
    );
    // UserResponse — это Record (Паттерн 1)
}

Заключение

Возврат сырых сущностей из REST API — это не просто технический долг. Это ошибка проектирования с реальными последствиями: утечки данных в production, сломанные клиенты после рефакторинга схемы, бесконечные вопросы от frontend-команды «а что именно возвращает этот эндпоинт?».

Каждый из пяти паттернов решает конкретную задачу:

Record-классы — явный, самодокументируемый контракт ответа без шаблонного кода.

MapStruct — безопасное маппирование на этапе компиляции вместо молчаливых ошибок в runtime.

Проекции — производительность и безопасность на уровне SQL-запроса.

Envelope-обёртки — единообразие, которое внешние команды перестают замечать, потому что «оно просто работает».

@JsonView — ролевое управление видимостью без взрыва DTO-классов.

Начать можно с малого. Если сегодня ваши контроллеры возвращают сырые сущности — введите Record-классы. Это займёт немного времени и сразу закроет риск утечки полей. Затем добавьте MapStruct. Envelope-паттерн введите перед первой внешней интеграцией. Проекции — когда появятся жалобы на производительность списков. `@JsonView` — как только появятся разные роли пользователей.

Поломалась оснастка порты управляемых сетей в zVirt

2026-03-30T11:39:55Z

В какой то момент в zVirt поломалась возможность импортировать виртуальные машины из образов в формате OVA размещённых на дисках хоста с гипервизором. Но о том как это чинить, как-нибудь в другой раз, а может и в очередном обновлении починится.
Дело в том, неудачные попытки импорта имеют неприятные последствия. В интерфейсе настройки Управляемых сетей на вкладке Порты нас встречает сообщение вида.

«Порт с идентификатором c7808f18-b5ab-4045-a230-c4ce59a86139 не найден»

И это все, что мы можем наблюдать на этой вкладке, соответственно управлять портами из веб-интерфейса становиться не возможно.
Как показало небольшое исследование, данная проблема возникает вследствие неудачного импорта. Во время импорта создаётся новая ВМ , для неё создаётся порт в соответствующей логической сети SDN. Но после краха процедуры импорта, виртуальная машина из конфигурации zvirt удаляется, а вот в базе данных программно определяемых сетей zvirt остаётся, что и вызывает вышеуказанное сообщение.
Чтобы исправить ситуацию сначала нужно найти какому порту соответствует указанный в ошибке идентификатор. Все парамеры портов хранятся в базе данных OVN , которую можно посмотреть на менеджере виртуализации.
Искомый идентификатор задаётся в параметре ovirt_device_id в поле external_ids в свойствах порта. Для поиска нужного порта можно использовать команду

ovn-nbctl find logical_switch_port external_ids:ovirt_device_id=<ИД из ошибки>

ovn-nbctl find logical_switch_port external_ids:ovirt_device_id=c7808f18-b5ab-4045-a230-c4ce59a86139 
_uuid               : e7ff4956-2151-4190-aee4-4d5681691050
 addresses           : ["56:6f:7e:2b:00:a2"]
 dhcpv4_options      : []
 dhcpv6_options      : []
 dynamic_addresses   : []
 enabled             : true external_ids        : {ovirt_device_id="c7808f18-b5ab-4045-a230-c4ce59a86139", ovirt_device_owner=oVirt, ovirt_nic_name=nic1, ovirt_security_groups="", zvirt_mode=dynamic, zvirt_namespace=common}
 ha_chassis_group    : []
 mirror_rules        : []
 name                : "c9afb0db-de90-4a42-a26c-88e69eb4c183"
 options             : {}
 parent_name         : []
 port_security       : []
 tag                 : [] 
tag_request         : [] 
type                : ""
 up                  : false

В поле name указано имя порта.
На всякий случай можно проверить в базе данных менеджера нет ли ВМ использующей этот порт, по имени порта или MAC адресу. Я просто поискал в дампе базы данных извлечённой из резервной копии (о том как делать резервные копии мы подробно рассказываем тут) и увидел такую запись

grep  05ef7f198d82   out_engine 21703    00000000-0000-0000-0000-000000000000    SYSTEM    \N        \N        \N        2026-03-25 11:24:02.987+03    SDN_PORT_CREATE_SUCCESS    16301    0    Port nic1 (9223a5aa-8394-4caf-9a33-05ef7f198d82) for VM DC602-location1 created successfully    f    \N        \N        \N        \N    \N    \N        \N        oVirt    \N    \N    \N    f    \N    \N    \N    \N

Что усилило мои подозрения.
Теперь фантомный порт необходимо удалить из базы данных OVN. Перед удаление настоятельно рекомендуется выполнить резервное копирование конфигурации менеджера.
Удаление выполняется с помощью команды ovn-nbctl lsp-del <имя порта >

ovn-nbctl lsp-del c9afb0db-de90-4a42-a26c-88e69eb4c183

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

Невидимые пользователи: Проектируем цифровую среду, доступную каждому

2026-03-09T16:28:05Z

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

Доступность (Accessibility, часто сокращаемая как A11y — где 11 означает количество букв между 'A' и 'y') — это не просто моральный долг или соответствие юридическим нормам. Это фундаментальное качество продукта, определяющее, сможет ли им воспользоваться каждый пятый житель планеты.

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

Часть 1: WCAG 2.2 — Навигационная карта доступности

Web Content Accessibility Guidelines (WCAG) — это «золотой стандарт» доступности, разработанный Консорциумом Всемирной паутины (W3C). В октябре 2023 года была утверждена новая редакция — WCAG 2.2, которая пришла на смену версии 2.1.

1.1. Четыре принципа POUR

В основе WCAG лежат четыре фундаментальных принципа, известных по аббревиатуре POUR. Контент должен быть:

Воспринимаемым (Perceivable): Пользователи должны иметь возможность воспринимать информацию, даже если у них есть сенсорные ограничения. Информация не может быть невидимой для всех органов чувств сразу .
Управляемым (Operable): Интерфейс должен работать с разными устройствами ввода. Пользователь должен иметь возможность управлять интерфейсом (например, нажимать кнопки), даже если не может использовать мышь .
Понятным (Understandable): И информация, и управление интерфейсом должны быть ясными. Пользователь должен понимать, где он находится и что происходит на странице.
Надёжным (Robust): Контент должен быть совместим с различными пользовательскими агентами, включая ассистивные технологии (скрин-ридеры, брайлевские дисплеи) .

1.2. Что нового в WCAG 2.2?

Главное изменение в версии 2.2 — фокус на пользователей с ограниченной моторикой и когнитивными нарушениями . Добавлено 9 новых критериев, а один устаревший исключен . Вот ключевые нововведения, на которые стоит обратить внимание:

Фокус не должен исчезать (Focus Appearance — уровень AA): Визуальный индикатор фокуса клавиатуры (обычно контур вокруг элемента) должен иметь достаточный контраст и размер, чтобы его было легко заметить.
Перетаскивание (Dragging — уровень AA): Действия, требующие перетаскивания объектов (drag & drop), должны иметь альтернативный простой способ выполнения (например, нажатие кнопок), так как многие пользователи с моторными нарушениями не могут удерживать кнопку мыши при перемещении.
Целевой размер (Target Size — уровень AA): Для интерактивных элементов (кнопок, ссылок) рекомендуется минимальный размер 24x24 пикселя, чтобы по ним было легко попасть людям с тремором рук или при использовании мобильных устройств. Исключения делается для ссылок внутри текстового абзаца.
Аутентификация (Accessible Authentication — уровень AA): Процессы входа в систему не должны требовать решения задач, основанных на запоминании пароля или распознавании объектов (капча), если для этого нет альтернативы. Это критически важно для людей с когнитивными нарушениями.

Понимание WCAG 2.2 становится обязательным не только для госсектора. С 28 июня 2025 года Европейский акт о доступности (EAA) распространяет требования уровня AA на частный бизнес в ЕС: интернет-магазины, банки, телеком-операторов и многих других .

Часть 2: Дизайн для всех — учет особенностей пользователей

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

2.1. Нарушения зрения (от слепоты до дальтонизма)

Это самая очевидная аудитория для применения стандартов доступности. По данным ВОЗ, более 2,2 млрд человек имеют те или иные нарушения зрения.

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

Контрастность: Обеспечьте достаточный контраст между текстом и фоном. Для обычного текста на уровне AA требуется контраст 4.5:1, для крупного текста — 3:1 . Используйте инструменты проверки контраста (Color Contrast Analyser, WebAIM).
Визуальные сигналы: Не используйте цвет как единственный сигнал, дающий информацию о состоянии объекта. Статус системы должен быть визуально понятным даже в черно-белом исполнении. Простыми словами, дублируйте сигнал иконками, текстом или подчеркиванием .
Текстовые альтернативы: Все значимые изображения должны иметь атрибут alt с описанием содержания. Декоративные изображения должны быть скрыты от скрин-ридеров (пустой alt="") , .
Масштабируемость: Интерфейс должен корректно отображаться при увеличении экрана до 400% без потери функциональности.

2.2. Нарушения моторики

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

Что делать дизайнеру:

Управление с клавиатуры: Все функции, доступные мышью, должны быть доступны с клавиатуры. Это означает логичный порядок фокуса (обычно совпадающий с визуальным порядком на странице) и видимый индикатор фокуса .
Крупные кликабельные области: Как требует WCAG 2.2, кнопки и ссылки должны быть большими, чтобы в них было легко попасть .
Достаточно времени: Избегайте таймеров или давайте возможность их продлить/отключить. Людям с моторными нарушениями может потребоваться больше времени на заполнение формы.
Отказ от сложных жестов: Предоставляйте простую альтернативу сложным жестам (смахивание, мультитач).

2.3. Когнитивные особенности

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

Что делать на практике:

Простота и предсказуемость: Интерфейс должен быть последовательным. Навигация и кнопки должны находиться на привычных местах. Избегайте неожиданных переходов и всплывающих окон.
Понятный язык: Используйте короткие предложения, избегайте сложных терминов и жаргона. Расшифровывайте аббревиатуры . Пишите "Январь" вместо "Янв".
Четкая структура: Используйте заголовки, списки и иконки для визуального разделения информации . Пользователю должно быть легко сканировать страницу взглядом.
Упрощенная аутентификация: Дайте возможность войти по биометрии или с помощью ссылки на email вместо запоминания сложного пароля.

Часть 3: Техническая реализация и семантическая верстка

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

3.1. Почему семантика — это основа?

Семантическая верстка — это использование HTML-элементов строго по их назначению. Это язык, на котором сайт общается с браузером, поисковиками и, что важнее всего, со скрин-ридерами.

Например, можно сделать "кнопку" так:

<div class="btn" role="button" tabindex="0">Купить</div>

Но гораздо правильнее и проще так:

<button>Купить</button>

Элемент <button> «из коробки» имеет правильную роль, управление с клавиатуры (Tab, Enter/Пробел) и фокус .

Ключевые семантические теги:

<header>, <nav>, <main>, <footer>, <aside> — создают навигационные вехи (landmarks), по которым пользователи скрин-ридеров могут быстро перемещаться.
<h1> — <h6> — создают иерархию заголовков. Никогда не пропускайте уровни (не перескакивайте с <h2> на <h4>). <h1> должен быть на странице один.
<ul>, <ol>, <li> — для списков.
<table> с <th> — для таблиц с данными (указывайте заголовки столбцов/строк).
<a> — для ссылок. Текст ссылки должен быть понятен вне контекста (никогда не пишите "нажмите здесь") .

3.2. Доступные формы

Формы — частый источник проблем. Чтобы сделать их доступными:

Каждый <input>, <select> или <textarea> должен быть связан с подписью через связку id и <label for="id"> или быть вложенным в <label>.
Группируйте логически связанные поля (например, адрес) в <fieldset> и давайте группе имя через <legend>.
Четко обозначайте обязательные поля и формат ввода данных в подписях, а не только цветом.

3.3. Когда HTML не справляется: WAI-ARIA

Иногда мы создаем сложные интерфейсные компоненты (например, кастомный выпадающий список с автодополнением), для которых нет подходящего HTML-тега. В таких случаях на помощь приходит WAI-ARIA (Accessible Rich Internet Applications).

ARIA позволяет добавить к элементам атрибуты, которые сообщают скрин-ридеру дополнительную информацию:

Роль (role): Что это за элемент? (role="dialog", role="tablist", role="progressbar").
Состояние и свойства: В каком он состоянии? (aria-expanded="true/false", aria-checked="true", aria-hidden="true").

Важное правило: Не использовать ARIA там, где можно обойтись нативным HTML. ARIA — это как хирургический инструмент для исправления сложных случаев, а не замена простым и понятным тегам.

Подробнее о создании доступной среды благодаря HTML

Часть 4: Тестирование — Смотрим и слушаем мир чужими глазами

Автоматические инструменты (Lighthouse, axe) — отличный первый шаг, но они находят лишь около 30% проблем. Настоящее тестирование доступности — это ручной труд и эмпатия.

4.1. Тестирование клавиатурой

Самый простой и эффективный тест. Отключите мышь и попробуйте пользоваться сайтом только с клавиатуры.

Используйте клавишу Tab, чтобы перемещаться по интерактивным элементам.
Всегда ли видно, где находится фокус (синяя или пунктирная обводка)?
Логичен ли порядок перехода? Не прыгает ли фокус с главного меню сразу в подвал?
Можно ли открыть все выпадающие списки, выбрать пункт и закрыть их?
Можно ли активировать все кнопки пробелом или энтером?

4.2. Тестирование со скрин-ридерами

Скрин-ридеры (читалки экрана) преобразуют цифровой текст в синтезированную речь или шрифт Брайля. Это основной инструмент для незрячих пользователей. Тестирование с ними — обязательный этап.

Популярные комбинации скрин-ридеров:

Windows: NVDA (бесплатный, лучше всего работает с Firefox). Или JAWS (платный, самый популярный в корпоративном секторе) .
macOS: VoiceOver (встроен в систему, лучше всего работает с Safari).
Android: TalkBack (встроен).
iOS: VoiceOver (встроен).

Что проверять с помощью скрин-ридера:

Чтение содержимого: Пройдитесь по странице стрелками (режим виртуального курсора). Все ли элементы озвучиваются? Правильно ли озвучиваются изображения (через alt)?
Навигация по заголовкам (клавиша H): Можете ли вы составить "карту" страницы и перейти к нужному разделу только по заголовкам? Не пропущены ли уровни? .
Навигация по ссылкам (клавиша K): Понятно ли, куда ведут ссылки, при прослушивании их вне контекста?
Навигация по вехам (landmarks) (клавиша D): Можно ли быстро перейти к основному контенту (<main>), минуя шапку и навигацию?
Работа с формами (клавиши F, E, C, R, B): Озвучивается ли подпись поля, когда вы входите в него? Правильно ли читаются сообщения об ошибках?
Динамический контент: Оповещает ли скрин-ридер о появлении всплывающих окон или обновлении части страницы?

4.3. Инструменты для помощи в тестировании

Помимо ручного тестирования, полезно использовать:

Accessibility Insights for Web (браузерный плагин): Помогает проходить проверки пошагово.
Lighthouse (встроен в Chrome DevTools): Быстрая автоматическая проверка основных метрик.
Инструменты разработчика (браузера): Позволяют инспектировать дерево доступности (Accessibility Tree), чтобы увидеть, какую именно информацию браузер передает скрин-ридеру.

Заключение

Доступность — это не финальный штрих и не чек-лист для галочки. Это философия проектирования, которая ставит человека в центр вселенной продукта. Интегрируя знания о WCAG 2.2, создавая продуманный дизайн для разных групп пользователей, опираясь на семантическую верстку и проверяя свою работу с реальными инструментами (от клавиатуры до VoiceOver), мы перестаем делить мир на "обычных" и "особенных" пользователей. Мы просто создаем качественный, удобный и честный продукт для всех.

Как я сократил время итерации в 3 раза на проекте с микросервисами

2026-03-04T11:28:24Z

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

На моём проекте - 10+ микросервисов на kotlin/spring, docker, gradle - один такой круг занимал примерно 3 минуты: секунд 15–30 на сборку всего проекта, около 2 минут на запуск контейнеров и ещё секунд 30 на тестирование. Казалось бы, 3 минуты - мелочь. Но представьте, что за одну задачу вы проходите этот цикл 10 раз (а это вполне реалистично). Получается 30 минут чистого ожидания - просто сидишь и смотришь в монитор. Мне показалось, что с этим стоит что-то сделать.

Первая мысль была в духе «надо как-то ускорить сборку». Но потом я понял, что проблема не в скорости отдельных шагов, а в том, что на каждой итерации собиралось и запускалось всё. Все 10+ сервисов. Каждый раз. Хотя для проверки моей гипотезы обычно нужны один-два из них.

Вопрос переформулировался: как сделать так, чтобы на каждую итерацию собиралось и поднималось только то, что действительно нужно?

До этого я запускал gradle из терминала, это была прям укоренившаяся привычка. Но оказалось, что idea собирает gradle-проект заметно быстрее. Уже одно это дало заметный выигрыш. Но главное в idea сборку можно встроить в единый пайплайн с запуском контейнеров.

Всё в одной конфигурации

В idea можно создать docker сompose конфигурацию, которая за один запуск делает всё: собирает нужные модули и поднимает контейнеры. Вот как это выглядит:

Тут указываем путь до docker compose файла, а в Services вместо указания 10+ сервисов, перечисляем только те, которые нужны для текущей задачи, по желанию указываем флаги для docker compose up. В Before-launch добавляем gradle-таски clean assemble, но только для конкретных модулей - это позволит idea выполнить их перед тем как запустить docker compose up.

Экономим энергию и пару секунд хоткеем Shift+F10 и радуемся результату - idea сначала собрала два нужных модуля, потом подняла два контейнера. Всё. Не нужно помнить порядок команд, не нужно их прописывать вручную.

Вместо одной «универсальной» конфигурации, которая поднимает всё, я создаю отдельную под каждую задачу. Работаю над gateway и some - конфигурация gateway+some. Завтра нужен другой набор сервисов - создаю новую. Создание такой конфигурации занимает пару минут. Но эта пара минут окупается уже на второй итерации.

Давайте глянем на цифры: сборка теперь занимает в среднем 5 секунд, а запуск 15 секунд. Итого мне нужно 50 секунд на проверку гипотезы, вместо 180, а это разница в 3 раза и это ощущается - стало легче сохранять фокус и контекст во время ожидания.

Если у вас похожий стек - kotlin/spring, gradle, docker, несколько микросервисов - попробуйте. Возможно, самое дорогое время в вашем рабочем дне - это не написание кода, а ожидание, пока он соберётся.

HashMap в Java: 10 фактов, о которых вы, возможно, не знали

2026-03-04T09:04:06Z

HashMap – наверное, самая используемая коллекция в Java. Мы кладём в неё элементы, достаём, редко задумываясь, что происходит под капотом. И в целом это нормально: класс работает, документация есть, сообщество стабильно советует переопределять equals и hashCode. Но если копнуть чуть глубже, обнаруживается немало деталей, которые могут удивить даже опытного разработчика.

Я собрала десять таких моментов. Не про то, как устроен HashMap в целом, а про то, что обычно остаётся за скобками.

1. Почему порог деревизации – именно 8

С Java 8, когда в одной корзине становится больше восьми элементов, связанный список преобразуется в красно-чёрное дерево. Логика понятна: начиная с какого-то размера список работает слишком медленно. Но почему порог установлен именно на восьми?

Ответ лежит в теории вероятностей. Разработчики Oracle смоделировали ситуацию с хорошей хеш-функцией и стандартным нагрузочным фактором 0.75. Согласно распределению Пуассона, вероятность того, что в одну корзину попадёт восемь элементов, составляет примерно 0.00000006. Это шесть случаев на десять миллионов.

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

2. Сдвиг на 16 бит: зачем он нужен

В исходном коде HashMap есть такая строчка:

(h = key.hashCode()) ^ (h >>> 16)

На первый взгляд кажется лишней. Зачем перед вычислением индекса ещё что-то делать с хеш-кодом?

Дело в том, что размер внутреннего массива всегда является степенью двойки. Индекс корзины вычисляется не через взятие остатка, а через побитовое И: (n - 1) & hash. Это быстро, но есть ограничение: в вычислении участвуют только младшие биты хеш-кода. Старшие, по сути, игнорируются.

Сдвиг на 16 бит и XOR решают эту проблему. Они «перемешивают» старшие и младшие биты, и даже если у двух объектов хеш-коды различаются только в старшей части, они всё равно попадут в разные корзины.

3. Массив создаётся не сразу

Когда вы пишете new HashMap<>(), внутренний массив ещё не существует. Он создаётся только при первой вставке элемента. До этого объект занимает минимум памяти – фактически только накладные расходы на сам экземпляр.

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

4. Начальная ёмкость считается не так, как вы думаете

Конструктор new HashMap<>(100) часто понимают неправильно. Кажется, что если передать 100, то можно положить 100 элементов без расширения. На самом деле 100 – это размер внутреннего массива. Порог срабатывает при превышении ёмкость * loadFactor, то есть при 75 элементах.

Чтобы без расширения поместилось ровно 100 элементов, раньше нужно было писать (int) Math.ceil(100 / 0.75). Выглядит как заклинание… К счастью, в Java 19 появился метод HashMap.newHashMap(100), который делает этот расчёт автоматически.

5. Итерация зависит от ёмкости, а не только от размера

В документации сказано: время итерации пропорционально ёмкости плюс размер. Это не просто формальность.

Если вы создали мапу с ёмкостью 10 000, но положили в неё два элемента, итератор всё равно обойдёт все 10 000 корзин, проверяя каждую на наличие данных. Пустые корзины не пропускаются. Поэтому если вы планируете часто перебирать элементы, не стоит завышать начальную ёмкость без необходимости.

6. putAll может работать медленнее ручного копирования

Неожиданный факт, но в некоторых версиях Java для больших мап метод putAll (и конструктор копирования) работает медленнее, чем обычный цикл по entrySet() с ручным добавлением.

Исследователи OpenJDK связывают это с тем, что JIT-компилятор не всегда может эффективно оптимизировать полиморфные вызовы на границах методов. В простом же цикле оптимизаций больше, и код выполняется быстрее – разница может достигать 20–30%. Ситуация варьируется от версии к версии, но о ней полезно знать, если вы работаете с действительно большими объёмами данных.

7. Ключ null всегда попадает в нулевую корзину

То, что HashMap допускает один ключ null, знают все. Но мало кто задумывается, куда именно он попадает.

В методе hash() есть явная проверка: для null возвращается 0. При вычислении индекса (n - 1) & 0 результат всегда будет 0. То есть все ключи null хранятся строго в нулевой корзине и всегда располагаются первыми в списке или дереве этой корзины.

8. Бесконечный цикл в Java 7 больше не актуален

В Java 7 и более ранних версиях в многопоточной среде при одновременном расширении HashMap мог возникнуть бесконечный цикл – программа просто зависала.

Причина была в способе переноса элементов: использовалась вставка в начало списка, что в конкурентной среде могло замкнуть список само на себя. В Java 8 отказались от этого подхода в пользу вставки в конец. Бесконечные циклы ушли в прошлое. Но это не делает HashMap потокобезопасной – проблемы с потерей данных и состояниями гонки остались.

9. computeIfAbsent и merge могут бросить исключение во время выполнения

Методы compute, computeIfAbsent и merge удобны тем, что позволяют атомарно выполнить сложную логику вставки. Но у них есть особенность: они могут изменять мапу во время работы переданной функции.

Если внутри этой функции попытаться снова изменить ту же мапу (например, вызвать put), можно получить ConcurrentModificationException. Это не баг, а защита от некорректного состояния. Методы стараются отследить такие ситуации и прервать выполнение, чтобы не допустить разрушения структуры данных.

10. Даже списки в Java 8 ищут быстрее

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

Это микрооптимизация, но она хорошо иллюстрирует подход разработчиков: улучшения делаются даже там, где кажется, что они не особо нужны

Эти детали редко всплывают в повседневной работе. Но когда сталкиваешься с неожиданным поведением или пытаешься выжать из приложения максимум производительности, знание внутреннего устройства HashMap помогает быстрее понять, что идёт не так и как это исправить.
Исходный код HashMap открыт, и в нём можно найти ещё много интересного. Иногда полезно просто заглянуть – хотя бы ради любопытства.

Go вместе изучать Go. Часть 6 (Заключительная)

2026-03-01T15:09:42Z

Введение

Добро пожаловать в заключительную статью нашей серии о языке программирования Go.

В ней мы рассмотрим три возможности языка: работу с изображениями через пакет image, обобщения (дженерики) для написания универсального кода и конкурентность — одну из главных «визитных карточек» Go.

Работа с изображениями

Go использует интерфейсы для определения поведения. Интерфейс Image демонстрирует, как определить набор методов, которые должна реализовывать структура, чтобы считаться "изображением".

package image

type Image interface {
    ColorModel() color.Model
    Bounds() Rectangle
    At(x, y int) color.Color
}

Этот интерфейс описывает три метода: ColorModel() возвращает цветовую модель изображения, Bounds() — его границы в виде прямоугольника, а At(x, y int) — цвет пикселя по заданным координатам.

Обратите внимание: возвращаемое значение Rectangle метода Bounds на самом деле является типом image.Rectangle, поскольку объявление находится внутри пакета image.

Типы color.Color и color.Model также являются интерфейсами, но для простоты мы будем использовать готовые реализации color.RGBA и color.RGBAModel из пакета image/color.

package main

import (
	"fmt"
	"image"
)

func main() {
	// Создаем 100x100 пикселей типа RGBA
	m := image.NewRGBA(image.Rect(0, 0, 100, 100)) 
	
    // Мы можем вызвать методы, потому что *image.RGBA 
    // неявно реализует интерфейс image.Image.
	fmt.Println(m.Bounds())
	fmt.Println(m.At(0, 0).RGBA())
}
// Вывод:
// (0,0)-(100,100)
// 0 0 0 0

В этом примере мы создаём RGBA-изображение размером 100×100 пикселей. Функция Bounds() возвращает прямоугольник от точки (0,0) до точки (100,100). Метод At(0, 0).RGBA() возвращает четыре нуля — это значения красного, зелёного, синего и альфа-каналов для пикселя в левом верхнем углу. Нули означают полностью прозрачный чёрный цвет.

Универсальность кода: Обобщения (Generics)

Обобщения, появившиеся в Go 1.18, позволяют писать функции и типы, которые могут работать с любым типом данных, сохраняя при этом типобезопасность.

Параметры типов

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

func Index[T comparable](s []T, x T) int

Это объявление означает, что s — это срез элементов любого типа T, который удовлетворяет встроенному ограничению comparable. Значение x имеет тот же тип.

Ограничение comparable позволяет использовать операторы == и != для значений данного типа. В примере ниже мы используем его для сравнения значения со всеми элементами среза до нахождения совпадения:

package main

import "fmt"

// Index возвращает индекс x в срезе s или -1, если элемент не найден.
func Index[T comparable](s []T, x T) int {
    for i, v := range s {
        if v == x {
            return i
        }
    }
    return -1
}

func main() {
    // Index работает со срезом целых чисел
    si := []int{10, 20, 15, -10}
    fmt.Println(Index(si, 15))

    // Index также работает со срезом строк
    ss := []string{"foo", "bar", "baz"}
    fmt.Println(Index(ss, "hello"))
}

// Вывод:
// 2
// -1

Функция Index универсальна: она работает и с числами, и со строками — с любым типом, поддерживающим сравнение. Компилятор сам определяет конкретный тип T на основе переданных аргументов.

Обобщённые типы

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

Вот пример объявления типа для односвязного списка, хранящего значения любого типа, с добавленной функциональностью:

package main

import "fmt"

// List представляет односвязный список, хранящий значения любого типа.
type List[T any] struct {
    next *List[T]
    val  T
}

// Push добавляет новый элемент в начало списка и возвращает новую голову.
func (l *List[T]) Push(val T) *List[T] {
    return &List[T]{next: l, val: val}
}

// Len возвращает длину списка.
func (l *List[T]) Len() int {
    count := 0
    for current := l; current != nil; current = current.next {
        count++
    }
    return count
}

// ToSlice преобразует список в срез.
func (l *List[T]) ToSlice() []T {
    var result []T
    for current := l; current != nil; current = current.next {
        result = append(result, current.val)
    }
    return result
}

// Find ищет элемент в списке (работает только для comparable типов).
func Find[T comparable](l *List[T], val T) bool {
    for current := l; current != nil; current = current.next {
        if current.val == val {
            return true
        }
    }
    return false
}

func main() {
    // Создаём список целых чисел
    var head *List[int]
    head = head.Push(1)
    head = head.Push(2)
    head = head.Push(3)

    fmt.Println("Длина списка:", head.Len())
    fmt.Println("Элементы:", head.ToSlice())
    fmt.Println("Содержит 2?", Find(head, 2))
    fmt.Println("Содержит 5?", Find(head, 5))
}

// Вывод:
// Длина списка: 3
// Элементы: [3 2 1]
// Содержит 2? true
// Содержит 5? false

Обратите внимание: метод Push возвращает новую голову списка, поскольку мы добавляем элементы в начало. Функция Find объявлена отдельно с ограничением comparable, потому что не все типы поддерживают сравнение через ==.

Конкурентность

Горутины

Горутина — это легковесный поток, управляемый средой выполнения Go:

go f(x, y, z)

Эта команда запускает новую горутину, выполняющую f(x, y, z). Вычисление f, x, y и z происходит в текущей горутине, а выполнение f — в новой.

Горутины работают в одном адресном пространстве, поэтому доступ к общей памяти должен быть синхронизирован. Пакет sync предоставляет полезные примитивы, хотя в Go чаще используются другие механизмы — каналы.

package main

import (
    "fmt"
    "time"
)

func say(s string) {
    for i := 0; i < 5; i++ {
        time.Sleep(100 * time.Millisecond)
        fmt.Println(s)
    }
}

func main() {
    go say("world")
    say("hello")
}

В этом примере две горутины выполняются параллельно: одна печатает «world», другая — «hello». Порядок вывода может варьироваться от запуска к запуску, поскольку горутины работают конкурентно.

// Пример вывода (порядок может меняться):
// hello
// hello
// world
// world
// ...

Каналы

Каналы — это типизированные каналы связи, через которые можно отправлять и получать значения с помощью оператора <-:

Каналы (chan) служат для безопасного обмена данными между горутинами.

ch <- v    // Отправить v в канал ch.
v := <-ch  // Получить значение из ch и присвоить его v.

Данные «текут» в направлении стрелки. Как и карты (maps) и срезы, каналы нужно создавать перед использованием:

ch := make(chan int)

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

package main

import "fmt"

func sum(s []int, c chan int) {
    sum := 0
    for _, v := range s {
        sum += v
    }
    c <- sum // отправить сумму в канал c
}

func main() {
    s := []int{7, 2, 8, -9, 4, 0}

    c := make(chan int)
    go sum(s[:len(s)/2], c)
    go sum(s[len(s)/2:], c)
    x, y := <-c, <-c // получить из канала c

    fmt.Println(x, y, x+y)
}

// Вывод: -5 17 12

Здесь работа по суммированию распределяется между двумя горутинами. Каждая считает сумму своей половины среза и отправляет результат в канал. Главная горутина получает оба значения и складывает их.

Буферизованные каналы

Каналы могут быть буферизованными. Размер буфера указывается вторым аргументом make.

Буферизованные каналы позволяют отправить несколько значений, не блокируя отправителя, пока буфер не заполнится.

ch := make(chan int, 100)

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

Вот что происходит при переполнении буфера:

package main

import "fmt"

func main() {
    ch := make(chan int, 2)
    ch <- 1
    ch <- 2
    // ch <- 3 // Эта строка вызовет deadlock!
    
    fmt.Println(<-ch)
    fmt.Println(<-ch)
}

Если раскомментировать строку ch <- 3, программа зависнет (deadlock), потому что буфер размером 2 уже заполнен, и отправка будет ждать, пока кто-то не прочитает из канала. Но читать некому — главная горутина заблокирована на отправке. Результат — взаимная блокировка:

fatal error: all goroutines are asleep - deadlock!

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

Завершение передачи данных (Range и Close)

Отправитель может закрыть канал, чтобы сигнализировать, что больше значений не будет. Получатель может проверить, закрыт ли канал:

v, ok := <-ch

Значение ok будет false, если канал закрыт и пуст.

Цикл for i := range c получает значения из канала до его закрытия.

Важно: закрывать канал должен только отправитель, никогда — получатель. Отправка в закрытый канал вызовет панику. При этом каналы не похожи на файлы — их обычно не нужно закрывать. Закрытие необходимо только когда получателю нужно знать, что значений больше не будет.

package main

import "fmt"

func fibonacci(n int, c chan int) {
    x, y := 0, 1
    for i := 0; i < n; i++ {
        c <- x
        x, y = y, x+y
    }
    close(c) // Сигнал об окончании
}

func main() {
    c := make(chan int, 10)
    go fibonacci(cap(c), c)

	// Цикл range автоматически завершится, когда fibonacci вызовет close(c).
    for i := range c {
        fmt.Println(i)
    }
}

// Вывод: 0 1 1 2 3 5 8 13 21 34

Управляемый выбор: select

Оператор select позволяет горутине ожидать готовности нескольких каналов связи. Он выбирает первый готовый случай, а если их несколько — выбирает случайным образом.

package main

import "fmt"

func fibonacci(c, quit chan int) {
    x, y := 0, 1
    for {
        select {
        case c <- x:
            x, y = y, x+y
        case <-quit:
            fmt.Println("quit")
            return
        }
    }
}

func main() {
    c := make(chan int)
    quit := make(chan int)
    go func() {
        for i := 0; i < 10; i++ {
            fmt.Println(<-c)
        }
        quit <- 0
    }()
    fibonacci(c, quit)
}

select блокируется до тех пор, пока один из его case-ов не сможет выполниться. Если готовы несколько — выбирается случайный.

Default в Select

Ветка default выполняется, если ни один другой case не готов. Это позволяет выполнять неблокирующие операции:

select {
case i := <-c:
    // Данные пришли
default:
    //Данные не пришли немедленно, продолжаем работу
}

Взаимное исключение: sync.Mutex

Каналы отлично подходят для коммуникации между горутинами. Но если нам нужно просто гарантировать, что только одна горутина имеет доступ к переменной в данный момент (общение через каналы в данном случае просто напросто избыточно)?

Для этого существует взаимное исключение (mutex). Стандартная библиотека Go предоставляет sync.Mutex с двумя методами: Lock и Unlock.

package main

import (
    "fmt"
    "sync"
    "time"
)

// SafeCounter безопасен для конкурентного использования.
type SafeCounter struct {
    mu sync.Mutex
    v  map[string]int
}

// Inc увеличивает счётчик для заданного ключа.
func (c *SafeCounter) Inc(key string) {
    c.mu.Lock()
    c.v[key]++
    c.mu.Unlock()
}

// Value возвращает текущее значение счётчика.
func (c *SafeCounter) Value(key string) int {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.v[key]
}

func main() {
    c := SafeCounter{v: make(map[string]int)}
    for i := 0; i < 1000; i++ {
        go c.Inc("somekey")
    }

    time.Sleep(time.Second)
    fmt.Println(c.Value("somekey"))
}

// Вывод: 1000

Без мьютекса 1000 горутин, одновременно изменяющих карту, вызвали бы гонку данных (data race) и непредсказуемое поведение. Мьютекс гарантирует, что в каждый момент времени только одна горутина работает с картой.

Обратите внимание на использование defer c.mu.Unlock() в методе Value — это гарантирует разблокировку даже при ранних возвратах или панике.

Заключение

Из этой статьи мы научились работать с несколькими важными аспектами Go. Мы узнали, как использовать пакет image для создания и манипулирования изображениями через интерфейс Image. Освоили дженерики — мощный механизм для написания универсального, переиспользуемого кода с параметрами типов и ограничениями вроде comparable и any. Погрузились в мир конкурентности Go: изучили горутины как легковесные потоки, каналы как средство безопасной коммуникации, оператор select для работы с несколькими каналами одновременно и мьютексы для защиты общих данных.

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

Успехов в ваших проектах!

iOS разработка: Как обнулить счетчик уведомлений в приложении

2026-02-26T13:16:20Z

Хотя мобильная разработка и не является основным профилем нашей компании, порой среди требований к корпоративному порталу оказывается его доступность с мобильных устройств. В связи с этим иногда приходится браться за нетипичные для нас задачи в виде разработки iOS и Android приложений. Однако оставим задачу систематического изложения основ мобильной разработки на другой раз. В этой заметке кратко зафиксируем, как наиболее просто решить проблему с красным значком с количеством уведомлений у иконки iOS-приложения, который не пропадает при переходе в программу. Речь идет о подобном красном кружке:

Зачастую происходит так, что при открытии приложения счетчик непрочитанных уведомлений не исчезает, а остается неизменным. Особенно часто такое возникает в случае, если переход происходит не по клику на уведомление в "Центре уведомлений", а непосредственно через экранное меню айфона.

Если мы хотим, чтобы все новые уведомления в приложении отмечались как прочитанные при переходе в приложение, то ответ кроется в модификации класса SceneDelegate. SceneDelegate - это класс в Swift, который отвечает за управление жизненным циклом конкретного экземпляра пользовательского интерфейса (сцены). Класс создает объект "контейнер" для элементов UIWindow, управляет состояниями приложения, размещением контента на странице, обработкой касаний разных элементов, переходами между фоновым и активным режимами.

Отличие SceneDelegate от AppDelegate в том, что последний предназначен для глобальной конфигурации всего приложения в целом. Там же происходит и регистрация Push-уведомлений, инициализация Firebase или иных уведомлений. Сейчас же нам нужен SceneDelegate, поскольку именно он обрабатывает событие открытия "сцены" приложения, при переходе в которую мы хотим обнулять счетчик уведомлений. Метод, который нам нужен для обработки события - sceneDidBecomeActive(_:). Он вызывается, когда сцена стала активной и готова к взаимодействию с пользователем.

Кусок кода на языке Swift, чтобы достичь поставленной задачи:

import UIKit
import SwiftUI

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        guard let _ = (scene as? UIWindowScene) else {
            return
        }
    }

    func sceneDidBecomeActive(_ scene: UIScene) {
            if #available(iOS 17.0, *) {
                UNUserNotificationCenter.current().setBadgeCount(0) { error in
                    if let error = error { print("sceneDidBecomeActive ERROR: \(error)") }
                }
            } else {
                UIApplication.shared.applicationIconBadgeNumber = 0
            }
            UNUserNotificationCenter.current().removeAllDeliveredNotifications()
        }

}

Для управления уведомлениями в iOS используется класс UNUserNotificationCenter. Во фрагменте кода выше мы используем его методы для сброса счетчика уведомлений на иконке приложения в ноль (метод setBadgeCount), а также для удаления уведомлений, пришедших от нашего приложения, в ленте "Центра уведомлений" (метод removeAllDeliveredNotifications). Метод удаления через UIApplication.shared.applicationIconBadgeNumber является устаревшим (для версий до iOS 17)

Tune IT

Strapi в эпоху AI-coding: почему dev-first CMS выигрывает

Состояние рынка

Что такое Strapi

Архитектура: схема как код

Кастомная бизнес-логика

Почему dev-first архитектура выигрывает у AI-агентов

Strapi AI и MCP

Сравнение с конкурентами

Self-hosting: что нужно учесть

Когда выбирать Strapi

Именованное деструктурирование в Kotlin

Проблема

Деструктурирование через интерфейс

Итог

Микроанимация в интерфейсах: Как сделать цифровой продукт живым, понятным и комфортным

Часть 1. Что такое микроанимация и зачем она нужна?

Часть 2. Типы микроанимаций: что, где и когда уместно?

Часть 3. Принципы хорошей микроанимации: как не навредить?

Часть 4. Лучшие примеры микроанимаций

Часть 5. Инструменты и технологии

Часть 6. Заключение

Gitlab CI: запуск пайплайна при обновлении upstream-репозитория

Эволюция инженера: как перейти в AI Engineering, не бросая всё, что вы умеете

Введение: почему этот разговор важен именно сейчас

Часть первая: Деконструкция иллюзий

Почему опытные разработчики избегают AI-тематики

Часть вторая: Технические основы - архитектурный взгляд

Шаг 1. Понимание механики генеративного ИИ

Шаг 2. Структурирование хаоса: от текста к типизированным объектам

Шаг 3. От простых вызовов к агентам

Шаг 4. Управление состоянием сложных агентных систем

Шаг 5. Архитектура RAG: дать модели доступ к вашим данным

Шаг 6. Потоковая передача и асинхронность

Часть третья: Инженерный фундамент как конкурентное преимущество

Почему опыт классической разработки - это преимущество, а не балласт

Инструментальный стек AI-инженера в 2026 году

Заключение: правильный взгляд на трансформацию

UX-тексты для новичков: Как писать интерфейсы, которые говорят на языке пользователя

Что такое UX-тексты и чем они отличаются от копирайтинга?

На что обратить внимание новичку

Как не облажаться: Типичные ошибки новичков и как их избежать

Ошибка №1: «Сейчас я им объясню...»

Ошибка №2: Копирование «крутых» фраз из чужих интерфейсов

Ошибка №3: Смешение «я» и «ты» (мы/вы/я)

Ошибка №4: Игнорирование негативных сценариев

Чек-лист для проверки: 15 вопросов перед публикацией

UX-текст — это уважение

Неоднозначные отношения Kotlin с Hibernate

Ловушка data class и equals/hashCode

Проблема final и отсутствие open

Конструкторы без аргументов

Проблема Default values

Немного о porcelain и plumbing командах, а также о типах объектов в git

Astro.js: современный фреймворк для контент-ориентированных сайтов

Astro.js: современный фреймворк для контент-ориентированных сайтов

Что такое Astro и зачем он нужен

Ключевые преимущества

Производительность «из коробки»

UI-агностичность

Гибкая модель интерактивности

Content Collections

Технические основы: как это работает

Этапы сборки

Клиентские директивы

Синтаксис .astro-файлов

Layouts — переиспользуемые макеты

Маршрутизация и работа с данными

Файловая маршрутизация

Динамические маршруты и getStaticPaths

Content Collections с типизацией

API-эндпоинты

Сравнение с другими фреймворками

Сводная таблица

Интеграция с UI-фреймворками на практике: Preact

Установка и конфигурация

Особенности и тонкости при работе с Preact в Astro

Итог

Введение в архитектуру ПО. Часть 1: Истинная ценность структуры и цена спешки

Введение

Ловушка `data class` и `equals`/`hashCode`

Проблема `final` и отсутствие `open`

Синтаксис `.astro`-файлов

Динамические маршруты и `getStaticPaths`