@gringo342

Свой маркиратор для Честного знака на картридже HP45 и ESP32: от одной точки до рабочего прототипа в производстве

gringo342 — Wed, 11 Nov 2026 16:55:08 GMT

Вступление

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

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

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

Первым делом я изучил тему. Искать пришлось на английском, и информации оказалось очень мало. В итоге я наткнулся на энтузиаста, который уже провёл реверс‑инжиниринг картриджа, — его сайт. Оттуда же нашлась ссылка на патент HP US5946012. Благодаря этому автору я разобрался, как работает картридж, за что отвечают его контакты и что такое адреса и примитивы. Поначалу было вообще непонятно, как всё устроено, но со временем информация уложилась в голове и превратилась в ценный опыт.

Теория

HP45 — это термоструйный (TIJ, thermal inkjet) картридж. Он состоит из резервуара для чернил, контактной площадки на задней стороне и двух рядов сопел на нижней. Резервуар объёмом 42 мл удерживается под небольшим отрицательным давлением с помощью пружины — так чернила не вытекают из сопел самопроизвольно. Картридж имеет 300 сопел, которые в сумме дают разрешение 600 DPI, работает от 12 В и имеет 52 контакта.

Каждое сопло — это нагревательный элемент сопротивлением около 30 Ом и полевой транзистор. Затвор транзистора подключён к адресной линии, нагреватель — к линии примитива, исток — к GND.

Схема сопла картриджа HP45 (источник: ytec3d.com )

Схема сопла картриджа HP45 (источник:

)

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

Сопла объединены в матрицу, благодаря чему 300 сопел управляются всего 36 линиями: 22 адресами и 14 примитивами. Адресу достаточно открыть затвор транзистора, поэтому большой ток ему не нужен — основной ток течёт через примитивы. На схеме земля показана отдельными линиями, но внутри печатающей головки все они соединены. Другие компоненты, например датчик температуры, тоже заземлены через эти выводы.

Что такое адрес и примитив

Адрес открывает затворы транзисторов у группы сопел, а примитив подаёт ток на нагреватели. Сопло срабатывает только тогда, когда одновременно активны его адрес и его примитив.

Схема матрицы сопел (источник: ytec3d.com )

Схема матрицы сопел (источник:

)

Алгоритм выстрела выглядит так:

Подаём 12 В на адрес, чтобы открыть затворы.
Ждём около 2 мкс, пока затворы откроются.
Подаём от 9 до 12 В на нужные примитивы (на все или на часть) на 2 мкс.
Снимаем напряжение с примитивов.
Через 3 мкс закрываем адрес.
Переходим к следующему адресу по порядку — от 1 до 22 или от 22 до 1.

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

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

Диаграмма синхронизации сопла

Диаграмма синхронизации сопла

Диаграмма синхронизации адресов. Адреса каскадом переключаются от 1 до 22, затем снова с 1 (или в обратном порядке)

Сопла разделены на две группы — чётную и нечётную. Чётные примитивы управляют чётным рядом сопел, нечётные — нечётным. Адресные линии общие для обоих рядов. Расположение контактов показано ниже.

Фактическое расположение контактов на печатающей головке HP45

Фактическое расположение контактов на печатающей головке HP45

Как узнать температуру картриджа

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

R10X — опорный резистор, сопротивление которого примерно в 10 раз больше сопротивления нагревателя, то есть около 300 Ом. С ним сравнивается сопротивление датчика.
TSR (thermal sense resistor) — терморезистор с номинальным сопротивлением около 300 Ом. При нагреве его сопротивление растёт, при охлаждении — падает.

Сравнивая сопротивление TSR с опорным R10X, можно оценить температуру головки.

Чтобы было нагляднее, мы с командой вскрыли один сломанный картридж и посмотрели, как он устроен внутри.

Пружинная пластина, которая создаёт отрицательное давление в картридже

Пружинная пластина, которая создаёт отрицательное давление в картридже

Первый импульс

Поначалу никакой контактной площадки для картриджа у меня не было, поэтому для первого подключения я просто припаялся к его контактам. Картриджу нужно 12, а микроконтроллер работает с логикой 3,3, поэтому понадобилось согласование уровней. Я набросал схему ключа на N и P‑канальных MOSFET в симуляторе, получил в нём рабочий результат и перешёл к сборке.

К собранной схеме я подключил ESP32, быстро написал тестовый скетч и начал проверять. Не с первой попытки, но на бумаге появилась одна маленькая точка. Это стало стартом для первого прототипа — маленькая победа.

Первый прототип

Схема

Дальше я взялся за схему уже под весь картридж, попутно исправив ошибки первого опыта. Проектировал на SMD‑компонентах, чтобы с обратной стороны платы ничего не торчало и не мешало прижимать картридж к контактной площадке. Получился каскад ключей, и стало ясно, что MOSFET‑ов потребуется больше 50.

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

Плата

Платы заказали в NextPCB без монтажа. Партия пришла с косяками, и виноват в этом был я: вместо резисторов 0603 поставил в проекте 0201 (паять их вручную очень тяжело), а для MOSFET выбрал не тот футпринт, из‑за чего выводы оказались перепутаны. Эти платы отправились в мусор. Урок усвоен. Я перепроектировал плату, перезаказал, и на этот раз пришло ровно то, что нужно.

Плата, подключённая к микроконтроллеру

Плата, подключённая к микроконтроллеру

Прошивка

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

Проект под ESP32 я писал в PlatformIO на фреймворке Arduino, и главным пожирателем времени оказались как раз функции Arduino. Один вызов

digitalWrite()

занимал больше 1 мкс. Функция ESP‑IDF

gpio_set_level()

работала быстрее, но тоже заметно тормозила. Самым быстрым вариантом стала прямая запись в регистры GPIO ESP32 (

GPIO.out_w1ts

GPIO.out_w1tc

) через макросы — переключение вывода сократилось с микросекунд до наносекунд.

      
#define SET_HIGH(Pin) ((Pin) >= 32 ? (GPIO.out1_w1ts.val = (1 << ((Pin) - 32))) : (GPIO.out_w1ts = (1 << (Pin))))
#define SET_LOW(Pin)  ((Pin) >= 32 ? (GPIO.out1_w1tc.val = (1 << ((Pin) - 32))) : (GPIO.out_w1tc = (1 << (Pin))))

Вторым сюрпризом стала

delayMicroseconds()

: она давала задержку чуть больше заданных 2 мкс. Поэтому вместо неё я, как и ytec3d в своём коде, использовал пустые инструкции процессора (NOP):

      
for (uint8_t d = 0; d < 13; d++) { // NOP    
  __asm__("nop\n\t""nop\n\t""nop\n\t""nop\n\t""nop\n\t""nop\n\t""nop\n\t""nop\n\t");
}

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

Отдельный момент — прерывания. Если во время импульса примитива сработает прерывание или проснётся Wi‑Fi‑стек, импульс растянется, а для нагревателя это опасно. Поэтому критичный участок генерации импульсов нужно выполнять с запрещёнными прерываниями и желательно на отдельном ядре.

Затем я написал функцию выстрела всеми соплами одного ряда (чётного или нечётного). Каждый примитив управлялся своим GPIO, и тут проявилась проблема схемы. Я включал GPIO по очереди, ждал 2 мкс и по очереди же их выключал. Первые включившиеся примитивы ждали, пока переключатся остальные, задержки складывались, и вместо 2 мкс получалось около 4 мкс. Чтобы уложиться в адекватные тайминги, я просто убрал явную задержку: переключение всей линии примитивов само по себе занимало около 2 мкс, и для экспериментов этого хватало.

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

Первая линия

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

Пропуски — это мёртвые примитивы в правом ряду сопел

Пропуски — это мёртвые примитивы в правом ряду сопел

Библиотека DataMatrix для печати кодов Честного знака

Готовых библиотек DataMatrix для ESP32 я не нашёл. Зато нашлась ZXing‑C++, не адаптированная под микроконтроллеры. Я успешно встроил её в проект: подтянул нужные зависимости и вырезал всё лишнее, чтобы библиотека не занимала много места.

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

uint8_t

, где каждый байт хранит 8 точек.

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

Картридж я двигал руками, поэтому коды получались растянутыми

Напечатанный Qr‑code

Промежуточный прототип

Схема

Мне не давало покоя количество MOSFET‑ов и занятых выводов контроллера. Только на управление картриджем уходило 36 линий (22 адреса и 14 примитивов), и это съедало почти все свободные GPIO ESP32. А в конечном устройстве нужны выводы ещё и под датчики и интерфейсы связи.

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

74HC595 — сдвиговые регистры для расширения портов;
TLC59213 — 8-битный драйвер с параллельным входом для коммутации 12 В на примитивы;
4017 — десятичные счётчики для адресов, соединённые каскадом через логику «И» 4081 со сбросом;
питание — на линейном стабилизаторе, у каждой микросхемы керамический конденсатор 0,1 мкФ, плюс электролит 100 мкФ для чистоты питания.

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

Самодельные платы

Подготовка

Для самодельной двухслойной платы понадобятся:

двусторонний фольгированный текстолит, нарезанный по размеру;
проект платы;
негативный плёночный фоторезист;
ламинатор для накатки фоторезиста;
фотополимерный 3D‑принтер;
мини‑дрель с цангой под свёрла меньше 1 мм.

Плату я проектировал в Fusion 360. Открываем её в 3D‑виде, добавляем рамки для совмещения, отключаем всё лишнее и экспортируем верхний и нижний слои в два STL‑файла. Затем с помощью ламинатора накатываем фоторезист на текстолит с обеих сторон.

Засветка

Для засветки мы использовали фотополимерный принтер Elegoo Mars 2 Pro: снимаем с него ванночку и всё лишнее, нужен только экран. Он засвечивает фоторезист ультрафиолетом и позволяет получать очень тонкие дорожки. Задание для принтера я подготовил в слайсере CHITUBOX.

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

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

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

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

Вариантов плат было много. На фото — версия для быстрого теста, где полигоны ради экономии времени не лудили

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

Прошивка

В прошивке появилась передача данных по SPI в регистры 74HC595. Регистров в цепочке два, поэтому за одну передачу уходит 16 бит, и все нужные выходы выставляются разом. Проблема с задержками ушла: нужные примитивы теперь включаются одновременно.

С драйвером TLC59213 всё довольно просто. Один вывод (RST) мгновенно сбрасывает все выходы в низкий уровень, а на вывод CLK я подаю импульс по таймингам из даташита, чтобы защёлкнуть новое состояние выходов.

Адреса теперь переключает каскад счётчиков — по порядку от 1 до 22. В конце обязательно нужен сброс, иначе счётчик зациклится на последней микросхеме в цепочке.

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

Хорошо печаталась только верхняя дата. Причина была в прошивке: я неправильно составил таблицу соответствия сопел адресам и примитивам. При неверной адресации что‑то печатается, но результат плохой. Сверив свою таблицу с таблицей ytec3d, я нашёл ошибки и переписал её. Теперь каждую дату уже можно было хотя бы прочитать:

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

Запустить её без дисплея можно тремя способами:

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

Сначала я пошёл вторым путём, потому что ещё не знал про третий: взял подходящий по размеру дисплей 160×512 и смог рисовать дату и вообще всё, что умеет библиотека. Позже нейросеть подсказала третий вариант — он оказался самым правильным, и я переделал на него.

На тестах я успешно печатал тексты, картинки и коды Честного знака. Самодельную тестовую плату никуда не встроишь, поэтому дальше я начал трассировать итоговую плату для заказа в Китае.

Итоговый прототип

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

Схема

В итоговой версии я разделил электронику на две платы:

маленькую плату‑коннектор, к которой подключается картридж и на которой стоит только FFC‑разъём для шлейфа;
основную плату со всей остальной электроникой.

Так печатающая голова получается компактной и не громоздкой.

После трассировки я несколько раз перепроверил схему: каждая ошибка на этом этапе стоит денег. Платы заказали со сборкой в Китае через AliExpress, общались с производителем по почте на английском. Вывод на будущее: если заказываете сборку у китайцев, сразу проектируйте в EasyEDA — там подключена библиотека компонентов LCSC, и вам не придётся согласовывать кучу правок, когда что‑то не сходится по размерам или чего‑то нет в наличии.

Плата

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

Архитектура и прошивка

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

Общая схема получилась такой:

Плюсы такого разделения:

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

Основной протокол связи работает по UART. Дополнительно я сделал HTTP API по Wi‑Fi, но заранее закладывал переход на Ethernet: на производстве Wi‑Fi ненадёжен из‑за помех от высокочастотного оборудования.

Через команды можно менять параметры маркиратора, запускать печать и загружать данные в буфер. Целостность загружаемого буфера проверяется по CRC-16/CCITT‑FALSE. Маркиратор сообщает хосту об ошибках, а все вводимые параметры проверяются на допустимый диапазон.Все команды я задокументировал в инструкции для разработчиков хоста.

Чтобы уместить Wi‑Fi‑стек, я использовал схему разметки флеш‑памяти

min_spiffs.csv

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

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

Настоящие 600 DPI

Отдельно я реализовал печать в 600 DPI. По ходу выяснилось, что на ручных китайских маркираторах режим 600 DPI неполноценный. Дело в том, что каждый ряд сопел HP45 сам по себе даёт только 300 DPI, а честные 600 DPI получаются, только когда оба ряда работают синхронно и их точки ложатся между собой.

Реализовать это можно двумя способами:

Простой. Печатать одним рядом в 300 DPI и делать несколько выстрелов в одну точку. Отпечаток выходит жирнее и визуально похож на 600 DPI, но реального прироста разрешения нет.
Сложный. Организовать синхронную работу обоих рядов сопел.

Я выбрал второй вариант. Для него понадобился параметр сдвига точек, который отвечает за совмещение двух рядов. Расстояние между рядами +-4.1 мм исходя из данных патента, но параметр я оставил настраиваемым, чтобы его можно было откалибровать на конкретном оборудовании.

В режиме 600 DPI критически важно направление печати. Сдвиг задерживает выстрелы одного ряда относительно другого с расчётом на определённое направление движения. Если картридж движется в обратную сторону, ряды не сойдутся ни при каком значении сдвига.

Хост

На производстве у меня два основных сценария интеграции:

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

Для первого сценария хост у меня уже был: веб‑панель на Python Flask, которая управляет ЧПУ и системой компьютерного зрения. Сервером служит Orange Pi, объединяющий станок, камеру, а теперь и маркиратор. В панель я добавил блок настроек маркиратора:

ввод даты и партии;
размер текста;
положение на холсте и предпросмотр того, что уйдёт в буфер;
сверка буфера — проверка, что сейчас лежит в памяти устройства.

Текст на холсте рисуется библиотекой Pillow. Для маркиратора я добавил отдельное подключение по UART и реализовал команды по своей документации.

Блок настроек маркиратора на рабочей панели

Для второго сценария я решил сделать полноценное универсальное приложение для ПК. Выбирал между Qt и Tauri (Rust) и остановился на Qt: это самый популярный фреймворк для подобных приложений, и мне хотелось получить опыт работы с ним.

Главная задача этого хоста — потоковая отправка кодов Честного знака на печать. Приложение читает CSV‑файлы с кодами, выгруженные из Честного знака. Если код не удалось прочитать или маркиратор не смог его сгенерировать, код отбраковывается, хост уведомляет об этом и переходит к следующему. В будущем я подключу к системе сканер кодов с отбраковщиком, чтобы снимать с линии продукцию с нечитаемыми кодами. У нашей компании уже есть такой опыт — мы собирали на аутсорс линию со сканером и отбраковкой, так что проблем здесь не ожидаю.

Готовая панель на Qt

Итоги

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

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

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

Кстати, нашли тут ещё один классный VPS, который работает прямо в центре города. Уже сами протестировали - всё отлично! Оставлю ссылку: moremore.pro

Как ломается модульный монолит и как с этим бороться

gringo342 — Wed, 11 Nov 2026 15:51:12 GMT

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

В конце той статьи я привёл список поломок, которые проходят сборку, а иногда и локальную отладку. Здесь покажу, как превратить их в ошибки компиляции и красные тесты.

Это четвёртая статья по мотивам моего доклада «Модульность без микросервисов в ASP.NET из коробки» на DotNext 2026:

Модульность без микросервисов: почему она того стоит.
Модульный монолит в ASP.NET из коробки.
Модульная модель данных в EF Core.
Как ломается модульный монолит и как с этим бороться (вы здесь).
eShop: запилить микросервисы в модульный монолит.

TL;DR

Тест поднимает топологию той же переменной HOSTINGSTARTUPASSEMBLIES, что и деплой, и проверяет её таблицы, маршруты и сервисы.
Топологии в одном тестовом процессе делят модель EF Core, пока в ключе кэша модели нет набора модулей.
Анализаторы Roslyn запрещают модулю публичные типы, хосту и библиотекам использовать модули, а классу модуля обходиться без ModuleBase и атрибута.
Список модулей для design-time фабрики пишет генератор, и тот же список проверяет переменную на старте.
Генератор в модулях и анализатор в хосте вместе следят, чтобы у таблицы и сущности был один модуль-владелец.

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

Тесты топологий

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

      
public class TopologyFactory(params string[] modules) : WebApplicationFactory
{
    protected override void ConfigureWebHost(IWebHostBuilder builder) => builder
        .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, string.Join(';', modules))
        // База не нужна: модель EF Core строится без подключения, а миграции тесту ни к чему
        .UseSetting("ConnectionStrings:Postgres", "Host=localhost;Database=topology")
        .UseSetting("Database:Migrate", "false");

    // Таблицы модели: "схема.таблица"
    public string[] Tables() =>
        [.. Model().GetEntityTypes().Select(e => $"{e.GetSchema()}.{e.GetTableName()}")];

    // Внешние ключи: "откуда → куда"
    public string[] ForeignKeys() =>
    [
        .. from entity in Model().GetEntityTypes()
           from key in entity.GetForeignKeys()
           select $"{entity.GetTableName()} → {key.PrincipalEntityType.GetTableName()}"
    ];

    // Маршруты: "[http_method] [route_pattern]", по строке на каждый метод
    public string[] Routes() =>
    [
        .. from endpoint in Services.GetRequiredService().Endpoints.OfType()
           from method in endpoint.Metadata.GetMetadata()?.HttpMethods ?? ["ANY"]
           select $"{method} {endpoint.RoutePattern.RawText}"
    ];

    // Контекст берём как DbContext, так же, как его берут модули
    IModel Model()
    {
        using var scope = Services.CreateScope();
        return scope.ServiceProvider.GetRequiredService().Model;
    }
}

На каждую топологию по одному тесту:

      
public class TopologyTests
{
    static readonly string[] Monolith = ["Orders.Entities", "Customers.Entities", "Monolith"];
    static readonly string[] Orders = ["Orders.Entities", "OrdersMicroservice"];
    static readonly string[] Customers = ["Customers.Entities", "CustomersMicroservice"];

    [Test]
    public async Task Monolith_HasBothTables_AndTheForeignKey()
    {
        await using var factory = new TopologyFactory(Monolith);

        await Assert.That(factory.Tables()).IsEquivalentTo(new[] { "Marketing.Customers", "Sales.Orders" });
        await Assert.That(factory.ForeignKeys()).IsEquivalentTo(new[] { "Orders → Customers" });
    }

    [Test]
    public async Task Orders_HasOnlyItsTable_AndItsRoutes()
    {
        await using var factory = new TopologyFactory(Orders);

        await Assert.That(factory.Tables()).IsEquivalentTo(new[] { "Sales.Orders" });
        await Assert.That(factory.ForeignKeys()).IsEmpty();
        await Assert.That(factory.Routes()).IsEquivalentTo(new[] { "GET /orders/unpaid" });
    }
}

Тест сравнивает строки, поэтому ему не нужен ни один тип из модулей, а

IsEquivalentTo

не смотрит на порядок.

Если при старте вызывается

MigrateAsync

, его надо уметь выключать. Я завёл для этого параметр конфигурации

Database:Migrate

, фабрика выше ставит его в

false

      
var app = builder.Build();

if (app.Configuration.GetValue("Database:Migrate", true))
{
    await using var scope = app.Services.CreateAsyncScope();
    await scope.ServiceProvider.GetRequiredService().Database.MigrateAsync();
}

Сравнение целиком заодно работает как негативный тест. Маршрут

POST /seed

и таблица клиентов в образе есть, но в топологии заказов их быть не должно, и

Orders_HasOnlyItsTable_AndItsRoutes

их не пропустит.

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

Program

, а устроена она так же.

RemoteRmq

в тесте нет: его hosted-сервис на EasyNetQ при старте фабрики полезет к RabbitMQ.

      
[Test]
[Arguments("Local")]
[Arguments("RemoteRest")]
[Arguments("RemoteGrpc")]
public async Task Calculator_ComesFromThisTopology(string module)
{
    await using var factory = new TopologyFactory(module);

    // Зависимости контроллеров контейнер на старте не проверяет:
    // без транспорта топология стартует и падает на первом запросе
    var isService = factory.Services.GetRequiredService();
    await Assert.That(isService.IsService(typeof(ICalculator))).IsTrue();

    // Два модуля с одним интерфейсом не падают, побеждает последний. Проверяем, чей
    await using var scope = factory.Services.CreateAsyncScope();
    var calculator = scope.ServiceProvider.GetRequiredService();
    await Assert.That(calculator.GetType().Assembly.GetName().Name).IsEqualTo(module);
}

Ещё я бы сравнивал с ожидаемым список

IHostedService

AddHostedService

в модуле запускает воркер в каждой реплике каждой топологии, где этот модуль загружен.

Несколько топологий в одном процессе

Можно написать тест моделей данных:

      
[Test]
public async Task ThreeTopologiesInOneProcess_EachHasItsOwnModel()
{
    await using var monolith = new TopologyFactory(Monolith);
    await using var orders = new TopologyFactory(Orders);
    await using var customers = new TopologyFactory(Customers);

    await Assert.That(monolith.Tables()).IsEquivalentTo(new[] { "Marketing.Customers", "Sales.Orders" });
    await Assert.That(orders.Tables()).IsEquivalentTo(new[] { "Sales.Orders" });
    await Assert.That(customers.Tables()).IsEquivalentTo(new[] { "Marketing.Customers" });
}

Без доработок этот тест будет красным.

EF Core кэширует модель по типу контекста, и второй хост получает модель первого. Ничего не падает, просто в модели не те таблицы. Лечится своим ключом кэша модели:

      
class AppDbContext(DbContextOptions options, IConfiguration configuration) : DbContext(options)
{
    // Модули, из которых собрана модель
    IReadOnlyList Modules { get; } = ModuleBase.GetLoadedModules(configuration);

    // Состав модулей для ключа кэша модели
    public string ModuleFingerprint => string.Join(';', Modules.Select(a => a.GetName().Name));

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        foreach (var assembly in Modules)
            modelBuilder.ApplyConfigurationsFromAssembly(assembly);
    }
}

class ModuleAwareModelCacheKeyFactory : IModelCacheKeyFactory
{
    public object Create(DbContext context, bool designTime) => context is AppDbContext app
        ? (typeof(AppDbContext), app.ModuleFingerprint, designTime)
        : (object)(context.GetType(), designTime);
}

builder.Services.AddDbContext(b => b
    .UseNpgsql(builder.Configuration.GetConnectionString("Postgres"))
    .ConfigureWarnings(o => o.Log(RelationalEventId.PendingModelChangesWarning))
    .ReplaceService());

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

Modules

. Если звать

GetLoadedModules

и в инициализаторе, и в

OnModelCreating

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

Набор модулей

GetLoadedModules

берёт из реестра в конфигурации хоста. Брать загруженные сборки из

AppDomain

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

Без

ReplaceService

падает ещё и

Orders_HasOnlyItsTable_AndItsRoutes

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

Контроль модульности при компиляции

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

Вот что хочется получить:

      
[assembly: HostingStartup(typeof(Module))]

class Module : ModuleBase { }

public class Leak { }                                // ошибка компиляции
public record struct AddRequest(int A, int B);       // ошибка. Моя первая версия смотрела только на классы и это пропустила
public class Outer { public class Nested { } }       // ошибка только на Outer

public class Order { public int Id { get; set; } }   // можно: это сущность
class OrderConfiguration : IEntityTypeConfiguration { public void Configure(EntityTypeBuilder b) { } }

Сущность узнаётся по

IEntityTypeConfiguration

в той же сборке. Остальные типы, которые нужны больше чем одному модулю, переезжают в contracts-сборку без

[HostingStartup]

Анализатор - библиотека под

netstandard2.0

      

  
    netstandard2.0
    latest
    true

Версия

Microsoft.CodeAnalysis.CSharp

задаёт минимальный компилятор: анализатор, собранный под 5.3.0, не загрузится в SDK или Visual Studio со старым Roslyn (будет CS8032). Пока анализатор живёт проектом в своём решении, это неважно. Для пакета я бы ставил минимально нужную версию.

Подключается анализатор ко всем проектам сразу, в

Directory.Build.props

Отдельно помечать модули не нужно. Анализатор сам определяет: модуль - сборка с

[assembly: HostingStartup]

, хост - сборка с точкой входа.

Код анализатора:

      
[DiagnosticAnalyzer(LanguageNames.CSharp)]
public class ModuleAnalyzer : DiagnosticAnalyzer
{
    static readonly DiagnosticDescriptor PublicType = new(
        "MOD0001", "Модуль не отдаёт публичных типов",
        "Тип '{0}' публичный, а сборка является модулем. Сделайте его internal или перенесите в contracts-сборку.",
        "Design", DiagnosticSeverity.Error, isEnabledByDefault: true);

    public override ImmutableArray SupportedDiagnostics => [PublicType];

    public override void Initialize(AnalysisContext context)
    {
        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
        context.EnableConcurrentExecution();
        context.RegisterCompilationStartAction(start =>
        {
            var compilation = start.Compilation;

            // Модуль - сборка с [assembly: HostingStartup] и без точки входа
            if (!HasHostingStartup(compilation.Assembly) ||
                compilation.GetEntryPoint(start.CancellationToken) is not null)
                return;

            // Сущности - типы T, для которых в этой же сборке есть IEntityTypeConfiguration
            var configuration = compilation.GetTypeByMetadataName(
                "Microsoft.EntityFrameworkCore.IEntityTypeConfiguration`1");
            var entities = compilation.GetSymbolsWithName(_ => true, SymbolFilter.Type, start.CancellationToken)
                .OfType()
                .SelectMany(type => type.AllInterfaces)
                .Where(i => SymbolEqualityComparer.Default.Equals(i.OriginalDefinition, configuration))
                .Select(i => i.TypeArguments[0])
                .ToImmutableHashSet(SymbolEqualityComparer.Default);

            start.RegisterSymbolAction(ctx =>
            {
                var type = (INamedTypeSymbol)ctx.Symbol;
                // Вложенный тип виден снаружи только вместе с внешним, поэтому хватает типов верхнего уровня
                if (type is { DeclaredAccessibility: Accessibility.Public, ContainingType: null } &&
                    !entities.Contains(type))
                    ctx.ReportDiagnostic(Diagnostic.Create(PublicType, type.Locations[0], type.Name));
            }, SymbolKind.NamedType);
        });
    }

    internal static bool HasHostingStartup(IAssemblySymbol assembly) =>
        assembly.GetAttributes().Any(a =>
            a.AttributeClass?.ToDisplayString() == "Microsoft.AspNetCore.Hosting.HostingStartupAttribute");
}

Контроллеры тоже internal

Первая версия правила, та, что в репозитории доклада, разрешала публичные контроллеры: ASP.NET MVC по умолчанию находит только их. Но публичный контроллер тянет за собой наружу всё, что принимает:

      
public class HomeController(IOrderQueries orders) : Controller   // CS0051: IOrderQueries internal
{
    public async Task Index() => View(await orders.Unpaid());
}

Компилятор заставит сделать публичным

IOrderQueries

, за ним его DTO, и в итоге правило формально соблюдено, а публичной стала половина модуля. Проще научить MVC находить

internal

-контроллеры. Для этого нужен свой провайдер:

      
sealed class InternalControllerProvider : IApplicationFeatureProvider
{
    public void PopulateFeature(IEnumerable parts, ControllerFeature feature)
    {
        var types = parts.OfType().SelectMany(part => part.Types);
        foreach (var type in types.Where(IsInternalController))
            if (!feature.Controllers.Contains(type))
                feature.Controllers.Add(type);
    }

    // Условия стандартного провайдера, кроме публичности. IsNotPublic бывает только
    // у типов верхнего уровня, так что вложенный класс контроллером по-прежнему не станет
    static bool IsInternalController(TypeInfo type) =>
        type is { IsNotPublic: true, IsClass: true, IsAbstract: false, ContainsGenericParameters: false } &&
        !type.IsDefined(typeof(NonControllerAttribute)) &&
        (type.Name.EndsWith("Controller", StringComparison.OrdinalIgnoreCase) ||
         type.IsDefined(typeof(ControllerAttribute)));
}

public static class InternalControllers
{
    public static IMvcBuilder AllowInternalControllers(this IMvcBuilder mvc) =>
        mvc.ConfigureApplicationPartManager(manager =>
        {
            // Контроллеры могут быть у нескольких модулей, а провайдер нужен один
            if (!manager.FeatureProviders.OfType().Any())
                manager.FeatureProviders.Add(new InternalControllerProvider());
        });
}

В модуле добавляется одна строка, и контроллер становится

internal

      
protected override void ConfigureServices(WebHostBuilderContext ctx, IServiceCollection services)
{
    services.AddControllersWithViews()
            .AddApplicationPart(typeof(Module).Assembly)
            .AllowInternalControllers();
}

[Area(Module.AreaName)]
class HomeController(IOrderQueries orders) : Controller   // internal, как и IOrderQueries
{
    public async Task Index() => View(await orders.Unpaid());
}

Без

AllowInternalControllers()

такой контроллер компилируется и отдаёт 404.

Есть и обратная сторона: любой вспомогательный класс с именем на

Controller

теперь тоже станет контроллером, и его надо пометить

[NonController]

Код здесь упрощён, чтобы уместиться в статью. Кроме контроллеров, публичными в модуле должны оставаться тег-хелперы (internal-хелпер Razor молча выведет обычным HTML) и ViewComponent. Для Web API показанного хватает.

Связи между сборками

Хост ссылается на модули, чтобы они попали в образ, но использовать их не должен, иначе модуль станет обязательным в любом деплое:

      
// Program.cs хоста
using Customers;                                    // можно: импорт ещё не использование

var app = WebApplication.CreateBuilder(args).Build();
var type = typeof(Customer);                        // ошибка: хост использует модуль Customers.Entities
app.Run();

/// См.    // можно: комментарий модуль в деплой не тянет
static class Docs { }

Обычной библиотеке тоже нельзя ссылаться на модуль: она затащит сборку модуля туда, где его

IHostingStartup

не выполнялся.

Компилятор знает, какие ссылки он использовал: GetUsedAssemblyReferences.

Моя первая версия верила ему на слово и ругалась на

using

, на

cref

/doc

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

      
context.RegisterCompilationAction(ctx =>
{
    var compilation = ctx.Compilation;
    if (IsTestProject(ctx.Options)) return;   // тестам ссылаться можно

    var isHost = compilation.GetEntryPoint(ctx.CancellationToken) is not null;
    if (!isHost && ModuleAnalyzer.HasHostingStartup(compilation.Assembly))
        return;   // модулю ссылаться на модули можно: это сверяет ValidateReferences на старте

    // Первый вопрос, дешёвый: какие сборки-модули компилятор считает использованными
    var suspects = compilation.GetUsedAssemblyReferences(ctx.CancellationToken)
        .Select(compilation.GetAssemblyOrModuleSymbol)
        .OfType()
        .Where(a => !a.Name.StartsWith("Microsoft.AspNetCore."))   // IIS Integration тоже hosting startup
        .Where(ModuleAnalyzer.HasHostingStartup);

    // Второй, точный: где именно
    foreach (var module in suspects)
        if (FindUse(compilation, module, ctx.CancellationToken) is { } location)
            ctx.ReportDiagnostic(Diagnostic.Create(
                isHost ? HostUsesModule : LibraryUsesModule,   // MOD0004 : MOD0005
                location, module.Name));
});

// Первый узел кода, который обращается к символу из сборки. DescendantNodes не заходит в trivia,
// поэтому  из doc-комментария не в счёт. using пропускаем сами: импорт ещё не использование
static Location? FindUse(Compilation compilation, IAssemblySymbol assembly, CancellationToken ct)
{
    bool FromAssembly(ISymbol? symbol) =>
        SymbolEqualityComparer.Default.Equals(symbol?.ContainingAssembly, assembly);

    foreach (var tree in compilation.SyntaxTrees)
    {
#pragma warning disable RS1030   // только в конце компиляции и только для подозреваемых сборок
        var model = compilation.GetSemanticModel(tree);
#pragma warning restore RS1030
        foreach (var node in tree.GetRoot(ct).DescendantNodes(n => n is not UsingDirectiveSyntax))
            if (FromAssembly(model.GetSymbolInfo(node, ct).Symbol) ||
                FromAssembly(model.GetTypeInfo(node, ct).Type))
                return node.GetLocation();
    }
    return null;
}

static bool IsTestProject(AnalyzerOptions options) =>
    options.AnalyzerConfigOptionsProvider.GlobalOptions
        .TryGetValue("build_property.IsTestProject", out var value) &&
    string.Equals(value, "true", StringComparison.OrdinalIgnoreCase);

GetSemanticModel

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

ModuleBase и атрибут

      
[assembly: HostingStartup(typeof(PlainStartup))]

class PlainStartup : IHostingStartup { ... }    // ошибка: не попадёт в реестр, сущностей не будет в модели
class Forgotten : ModuleBase { }                // ошибка: нет атрибута, сборку загрузят, а модуль пропустят
abstract class CompanyModule : ModuleBase { }   // можно: общая база сама не модуль

Хуже всего

Forgotten

: приложение стартует, health-check зелёный, а модуль отвечает 404. Оба случая ловит одна проверка классов, которые реализуют

IHostingStartup

      
context.RegisterCompilationStartAction(start =>
{
    var compilation = start.Compilation;
    var hostingStartup = compilation.GetTypeByMetadataName("Microsoft.AspNetCore.Hosting.IHostingStartup");
    var moduleBase = compilation.GetTypeByMetadataName("ModuleBase");
    if (hostingStartup is null) return;

    // Классы, названные в [assembly: HostingStartup(typeof(...))]
    var named = compilation.Assembly.GetAttributes()
        .Where(a => a.AttributeClass?.ToDisplayString() == "Microsoft.AspNetCore.Hosting.HostingStartupAttribute")
        .SelectMany(a => a.ConstructorArguments)   // пусто, если атрибут написан с ошибкой
        .Select(argument => argument.Value)
        .OfType()
        .ToImmutableHashSet(SymbolEqualityComparer.Default);

    start.RegisterSymbolAction(ctx =>
    {
        var type = (INamedTypeSymbol)ctx.Symbol;
        if (type.IsAbstract || !type.AllInterfaces.Contains(hostingStartup, SymbolEqualityComparer.Default))
            return;

        if (!named.Contains(type))
            ctx.ReportDiagnostic(Diagnostic.Create(NotNamed, type.Locations[0], type.Name));        // MOD0003
        else if (moduleBase is null || !DerivesFrom(type, moduleBase))
            ctx.ReportDiagnostic(Diagnostic.Create(NotModuleBase, type.Locations[0], type.Name));   // MOD0002
    }, SymbolKind.NamedType);
});

static bool DerivesFrom(INamedTypeSymbol type, INamedTypeSymbol baseType) =>
    type.BaseType is { } parent &&
    (SymbolEqualityComparer.Default.Equals(parent, baseType) || DerivesFrom(parent, baseType));

Что ещё проверять при сборке

Этот список у меня растёт из реальных отказов:

AddSingleton(this) в модуле: ModuleBase это уже сделал, и повторный маршрут уронит старт.
Забытый параметр GenerateMvcApplicationPartsAssemblyAttributes в хосте притащит контроллеры всех модулей во все топологии. Анализатором надо ловить ApplicationPartAttribute в сборке хоста.
CreateSlimBuilder и CreateEmptyBuilder игнорируют HOSTINGSTARTUPASSEMBLIES, и модули молча не загрузятся.
Hub с internal-интерфейсом клиента падает с TypeLoadException на первом клиенте. Нужен InternalsVisibleTo для динамической сборки SignalR.
Assembly.GetEntryAssembly() в модуле вернёт сборку хоста. Это ломает код, который добавляет типы в DI, когда такой код переезжает в отдельный модуль.

Анализаторы для паттернов, которые недопустимы именно в вашем коде, вы можете написать сами. Главное, не подавляйте эти правила через

NoWarn

. Для случаев «так и задумано» есть

#pragma

с комментарием у конкретной строки.

Улучшаем модульность с помощью Source Generator

Design-time фабрика для EF из прошлой статьи перечисляет модули руками:

      
static readonly string[] AllModules = ["Customers.Entities", "Orders.Entities", "Monolith"];

Добавили новый модуль с моделью для EF и забыли вписать его сюда - миграция для него не создастся. А если несколько веток правят этот список параллельно, будут ещё и конфликты.

Этот список можно генерировать для хоста с помощью Source Generator:

      
[Generator(LanguageNames.CSharp)]
public sealed class KnownModulesGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        // Список нужен только запускаемым сборкам: хосту и тестам. Результат - строка,
        // а строки сравниваются по значению: правка, не меняющая набор модулей, файл не перегенерирует
        var names = context.CompilationProvider.Select(static (compilation, _) =>
            compilation.Options.OutputKind == OutputKind.DynamicallyLinkedLibrary
                ? null
                : string.Join(", ", ModuleNames(compilation).Select(name => $"\"{name}\"")));

        context.RegisterSourceOutput(names, static (spc, names) =>
        {
            if (names is null) return;
            spc.AddSource("KnownModules.g.cs", $$"""
                // 
                internal static class KnownModules
                {
                    public static readonly string[] Names = [{{names}}];
                }
                """);
        });
    }

    // Сборки среди ссылок проекта, помеченные [assembly: HostingStartup]
    static IEnumerable ModuleNames(Compilation compilation) => compilation.References
        .Select(compilation.GetAssemblyOrModuleSymbol)
        .OfType()
        .Where(a => !a.Name.StartsWith("Microsoft.AspNetCore."))   // IIS Integration тоже hosting startup
        .Where(ModuleAnalyzer.HasHostingStartup)
        .Select(a => a.Name)
        .OrderBy(name => name, StringComparer.Ordinal);
}

Фильтр

Microsoft.AspNetCore.

я дописал после первого запуска, когда в списке оказался IIS Integration. Фабрика больше не знает имён модулей:

      
var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: true)
    .AddEnvironmentVariables()
    .AddInMemoryCollection([new(WebHostDefaults.HostingStartupAssembliesKey, string.Join(';', KnownModules.Names))])
    .AddInMemoryCollection(ModuleBase.CreateModuleRegistry(KnownModules.Names))
    .Build();

Генератор работает и в тестовом проекте. Тестовый проект тоже exe, анализатор подключён к нему через

Directory.Build.props

, и там появляется свой

KnownModules

, собранный из транзитивных ссылок. Раз тесты ссылаются на хост, список совпадёт с хостовым. Если хост открыл тестам internals через

InternalsVisibleTo

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

Порядок модулей

Генератор отдаёт имена по алфавиту, и

Monolith

оказывается раньше

Orders.Entities

      
// Monolith
class OrderEntityConfiguration : IEntityTypeConfiguration   // Order в сигнатуре: ссылка на Orders.Entities есть в reference-сборке
{
    public void Configure(EntityTypeBuilder entity)
    {
        entity.HasOne()                                  // Customer только в теле метода: ссылки на Customers.Entities там нет
              .WithMany()
              .HasForeignKey(e => e.CustomerId);
    }
}

При таком порядке создание внешнего ключа в

Monolith

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

В третьей статье порядок задавала переменная, и

Monolith

надо было ставить в ней последним. Теперь порядок строит

GetLoadedModules

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

      
public static IReadOnlyList GetLoadedModules(IConfiguration configuration)
{
    var order = (configuration[WebHostDefaults.HostingStartupAssembliesKey] ?? string.Empty)
        .Split(';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);

    var modules = configuration.GetSection(ModulesSection).GetChildren()
        .ToDictionary(m => m.Key, m => Assembly.Load(m.Key), StringComparer.OrdinalIgnoreCase);

    int Depth(Assembly module) => module.GetReferencedAssemblies()
        .Where(r => modules.ContainsKey(r.Name!))
        .Select(r => Depth(modules[r.Name!]) + 1)
        .DefaultIfEmpty(0)
        .Max();

    // Сначала то, на что ссылаются, при равной глубине по порядку переменной.
    // Сборки приложения в переменной нет, её индекс −1, и она остаётся первой
    return [.. modules.Values
        .OrderBy(Depth)
        .ThenBy(m => Array.FindIndex(order, n =>
            string.Equals(n, m.GetName().Name, StringComparison.OrdinalIgnoreCase)))];
}

Depth

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

С переменной

Monolith;Customers.Entities;Orders.Entities

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

Customers.Entities;Orders.Entities;Monolith

, и внешний ключ на месте.

Опечатка в переменной HOSTINGSTARTUPASSEMBLIES

Если указать имя несуществующего модуля, ASP.NET Core пишет в лог с уровнем

crit

и стартует дальше. Список от генератора позволяет это поймать:

      
public static void ValidateModules(IConfiguration configuration, IEnumerable modules)
{
    var registry = configuration.GetSection(ModulesSection);
    var requested = configuration[WebHostDefaults.HostingStartupAssembliesKey] ?? string.Empty;

    // Модуль хоста обязан оказаться в реестре, чужому hosting startup достаточно загрузиться
    var broken = requested.Split(';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
        .Where(name => registry[name] is null &&
                       (modules.Contains(name, StringComparer.OrdinalIgnoreCase) || !CanLoad(name)))
        .ToArray();

    if (broken.Length > 0)
        throw new InvalidOperationException(
            $"HOSTINGSTARTUPASSEMBLIES = '{requested}': не активированы {string.Join(", ", broken)}");
}

static bool CanLoad(string name)
{
    try { Assembly.Load(name); return true; }
    catch (IOException) { return false; }   // FileNotFoundException, FileLoadException
}

Хост вызывает проверку сразу после создания билдера:

      
var builder = WebApplication.CreateBuilder(args);
ModuleBase.ValidateModules(builder.Configuration, KnownModules.Names);

Чужой hosting startup вроде Application Insights в реестр не пишет, от него требуется только загрузиться. Тест:

      
[Test]
public async Task Typo_FailsStartup()
{
    await using var factory = new TopologyFactory("Orders.Entitys", "OrdersMicroservice");
    await Assert.That(() => factory.Services).Throws()
        .WithMessageContaining("Orders.Entitys");
}

Текст сообщения я проверяю не просто так.

InvalidOperationException

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

Бонус: проверка владения сущностью и таблицей

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

Например, новому модулю срочно нужны заказы. Ссылаться на

Orders

нельзя: это поменяет топологию, и упадут тесты.

Зато можно так:

      
// Модуль Billing
class Order { public int Id { get; set; } public decimal Amount { get; set; } }   // своя копия заказа

class OrderConfiguration : IEntityTypeConfiguration
{
    public void Configure(EntityTypeBuilder entity) => entity.ToTable("Orders", "Sales");   // таблица модуля Orders
}

Ссылок между сборками нет, компилятор доволен, всё работает, пока

Orders

не поменяет схему. Такая же протечка бывает через общую сборку

Shared

: два модуля настраивают один класс сущности, и EF Core молча берёт конфигурацию того, кто применился последним.

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

ToTable

. Связывающий модуль

Monolith

из демо настраивает

Order

, но

ToTable

не вызывает, поэтому владельцем не считается.

Проверять правило надо в хосте, только он видит все модули сразу. Но

ToTable

вызывается в теле метода, а хост видит модули как reference-сборки без тел.

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

Очень много кода

      
[Generator(LanguageNames.CSharp)]
public sealed class OwnedTablesGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        // Вызовы entity.ToTable("Orders", "Sales") с константными аргументами
        var owned = context.SyntaxProvider.CreateSyntaxProvider(
                static (node, _) => node is InvocationExpressionSyntax
                {
                    Expression: MemberAccessExpressionSyntax { Name.Identifier.ValueText: "ToTable" }
                },
                static (ctx, ct) => Owned(ctx, ct))
            .Where(static line => line is not null)
            .Collect()
            .Select(static (lines, _) => string.Join("\n", lines.Distinct().OrderBy(l => l, StringComparer.Ordinal)));

        var isModule = context.CompilationProvider
            .Select(static (compilation, _) => ModuleAnalyzer.HasHostingStartup(compilation.Assembly));

        context.RegisterSourceOutput(owned.Combine(isModule), static (spc, input) =>
        {
            var (lines, isModule) = input;
            if (!isModule || lines.Length == 0) return;
            spc.AddSource("OwnedTables.g.cs", $$"""
                // 
                {{lines}}

                [System.AttributeUsage(System.AttributeTargets.Assembly, AllowMultiple = true)]
                internal sealed class OwnsTableAttribute(string table, string entity) : System.Attribute { }
                """);
        });
    }

    static string? Owned(GeneratorSyntaxContext ctx, CancellationToken ct)
    {
        var call = (InvocationExpressionSyntax)ctx.Node;
        var builder = ((MemberAccessExpressionSyntax)call.Expression).Expression;

        // entity имеет тип EntityTypeBuilder, отсюда тип сущности
        if (ctx.SemanticModel.GetTypeInfo(builder, ct).Type is not INamedTypeSymbol
            {
                Name: "EntityTypeBuilder", TypeArguments.Length: 1
            } builderType)
            return null;
        var entity = builderType.TypeArguments[0];

        var args = call.ArgumentList.Arguments
            .Select(a => ctx.SemanticModel.GetConstantValue(a.Expression, ct))
            .ToArray();
        if (args.Length == 0 || args[0].Value is not string table) return null;   // имя не константа: не угадываем
        var schema = args.Length > 1 && args[1].Value is string s ? s + "." : "";

        return $"[assembly: OwnsTable(\"{schema}{table}\", \"{entity.ToDisplayString()}\")]";
    }
}

В сборке

Orders.Entities

появляется файл:

      
// 
[assembly: OwnsTable("Sales.Orders", "Orders.Order")]

[System.AttributeUsage(System.AttributeTargets.Assembly, AllowMultiple = true)]
internal sealed class OwnsTableAttribute(string table, string entity) : System.Attribute { }

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

      
[DiagnosticAnalyzer(LanguageNames.CSharp)]
public class OwnedTablesAnalyzer : DiagnosticAnalyzer
{
    static readonly DiagnosticDescriptor TwoOwners = new(
        "OWN0001", "У таблицы и сущности один владелец",
        "'{0}' владеют модули {1}",
        "Design", DiagnosticSeverity.Error, isEnabledByDefault: true,
        customTags: WellKnownDiagnosticTags.CompilationEnd);

    public override ImmutableArray SupportedDiagnostics => [TwoOwners];

    public override void Initialize(AnalysisContext context)
    {
        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
        context.EnableConcurrentExecution();
        context.RegisterCompilationAction(ctx =>
        {
            var compilation = ctx.Compilation;
            if (compilation.GetEntryPoint(ctx.CancellationToken) is null) return;   // сверяет хост

            // Каждый модуль сам записал, чем владеет
            var owners = compilation.References
                .Select(compilation.GetAssemblyOrModuleSymbol)
                .OfType()
                .Where(ModuleAnalyzer.HasHostingStartup)
                .SelectMany(module => module.GetAttributes()
                    .Where(a => a.AttributeClass?.Name == "OwnsTableAttribute")
                    .SelectMany(a => a.ConstructorArguments)          // и таблица, и сущность
                    .Select(argument => (Key: (string)argument.Value!, Module: module.Name)));

            foreach (var key in owners.GroupBy(o => o.Key))
            {
                var modules = key.Select(o => o.Module).Distinct().OrderBy(m => m).ToArray();
                if (modules.Length > 1)
                    ctx.ReportDiagnostic(Diagnostic.Create(TwoOwners, Location.None, key.Key, string.Join(", ", modules)));
            }
        });
    }
}

Хост с модулем Billing из примера больше не собирается:

      
error OWN0001: 'Sales.Orders' владеют модули Billing, Orders.Entities

Если Billing вместо копии настроит чужой

Orders.Order

под свою таблицу, ошибка будет про

'Orders.Order'

Генератор видит только

ToTable

с константами. Таблицу, названную по соглашению из

DbSet

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

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

Location.None

#pragma

к ней не приложить, и остаётся только

NoWarn

на весь хост, от которого я выше отговаривал.

Тот же приём годится для всего, что живёт в телах методов и нужно хосту: регистрации сервисов, маршруты, имена очередей.

Выводы

Всё, что показано в статье, собрано из стандартных деталей: ASP.NET, EF Core,

WebApplicationFactory

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

Есть популярное возражение:

В эпоху ИИ архитектура больше не важна. Говоришь клоду «сделай хорошо», он сделает, а значит, и модульность не нужна, клод разберётся.

Вместо “хорошо” было другое слово, но цензура.

Агент, конечно, сделает «хорошо». Сделает для той задачи, которую ему дали: тест зелёный, фича работает. О том, что модуль Orders перестал запускаться отдельно, он не узнает, потому что такую топологию никто не запускал. Архитектуру агент не отменяет. Он просто ломает её с той же скоростью, с какой пишет код.

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

internal

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

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

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

Я всё это уже проделал и собрал в библиотеку.

FusionModules

FusionModules - открытая библиотека под MIT для модульных приложений на ASP.NET Core. В ней базовый класс модуля, проверки топологии на старте, пакет для тестов топологий и анализаторы MOD0001-MOD0005 из этой статьи, с исправлениями. Есть и правила, которых в статье нет: MOD0011 ловит контроллеры модуля без application part, а MOD0014 - два модуля, которые зарегистрировали один интерфейс. Проверки владения таблицей из бонуса в пакете пока нет.

      
dotnet add package FusionModules

В следующей статье я пошагово покажу, как переделать микросервисный eShop от Microsoft в модульный монолит с помощью FusionModules.

Материалы

Доклад: Модульность без микросервисов в ASP.NET из коробки, DotNext 2026
Репозиторий доклада:. Демо, на которых выросли примеры из статьи: modular-data, modular-endpoints, modular-analyzer, load-test; в ветке fusionmodules те же демо на FusionModules 0.3
Библиотека: FusionModules на GitHub
Тесты: TUnit, интеграционные тесты в ASP.NET Core, IModelCacheKeyFactory
MVC: application parts и feature providers
Roslyn: написание анализаторов, генераторы кода, Compilation.GetUsedAssemblyReferences

Кстати, есть ещё одна интересная находка - VPS в самом центре города. Мы его уже проверили, можем рекомендовать! Ссылка: moremore.pro

От COM-интеграций к централизованной схеме: как проверить новую интеграционную архитектуру до промышленного внедрения

gringo342 — Wed, 11 Nov 2026 14:48:50 GMT

На связи Анна Астахова, директор по развитию ИТ-интегратора «Белый код». Почти всегда тем, кто обращается к нам с вопросом о выборе шины, мы говорим, что надо проверять на реальной задаче. Пилотный проект — хорошая возможность оценить, насколько вашей архитектуре и вашим требованиям подходит конкретная интеграционная платформа. Расскажу на примере. Для одного из заказчиков мы реализовали три интеграционных потока, и это помогло увидеть реальную пользу DATAREON Platform.

Заказчик: инжиниринговый холдинг.

Задача: проверить на пилотном контуре централизованную схему интеграции, в которой «1С:Документооборот» становится единым источником данных по объекту «Проект», а обмен между системами выполняется через DATAREON Platform.

О компании

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

С чем обратился заказчик

На момент старта проекта обмен данными между системами был построен через COM-взаимодействие.

Процесс работы с объектом «Проект» выглядел так:

проект создавался в «1С:Документооборот»;
затем через COM передавался в «БИТ.ФИНАНС»;
в «1С БИТ» создавалась связанная номенклатурная группа;
после этого проект и номенклатурная группа передавались в «1С:ЗУП» также через COM.

Основная сложность этой схемы заключалась в том, что «1С:ЗУП» получала данные о проекте не напрямую из исходной системы, а через «БИТ.ФИНАНС». Из-за этого целевой обмен зависел от промежуточной системы, а происхождение данных было менее прозрачным.

Заказчик хотел проверить другую модель: определить «1С:Документооборот» как единый источник данных по проектам и организовать передачу информации через централизованный интеграционный слой DATAREON Platform. В интеграционном контуре пилотного проекта использовались три системы: «1С:Документооборот», «БИТ.ФИНАНС» и «1С:ЗУП».

Что сделали

В рамках пилота мы реализовали три интеграционных потока:

«1С:Документооборот» → «БИТ.ФИНАНС» — передача справочника «Проекты».
«1С:Документооборот» → «1С:ЗУП» — передача справочника «Проекты».
«БИТ.ФИНАНС» → «1С:ЗУП» — передача справочника «Номенклатурные группы».

Ключевое изменение по сравнению с исходной схемой — проект стал поступать в «1С:ЗУП» напрямую из «1С:Документооборот», а не через «БИТ.ФИНАНС».

При этом роль «БИТ.ФИНАНС» сохранилась: после получения проекта в системе формируется связанная номенклатурная группа, которая затем передается в «1С:ЗУП».

DATAREON Platform использовалась как единый интеграционный слой пилотного решения.

Дополнительно объекты «Проект» и «Номенклатурная группа» в процессе обмена записывались в Банк данных DATAREON. Отдельного создания объектов внутри Банка данных не предусматривалось: объект проходит через него, а в Банке данных сохраняется его текущая версия. История изменений и версионирование в границы пилота не входили.

Сам пилот был намеренно ограничен по объему. В него не входили:

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

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

Результат

По итогам пилота удалось проверить работу централизованной схемы обмена через DATAREON Platform.

В пилотном контуре:

реализованы и настроены три целевых интеграционных потока;
«1С:Документооборот» выступает единым источником данных по объекту «Проект»;
проект передается из «1С:Документооборот» в «БИТ.ФИНАНС»;
проект передается из «1С:Документооборот» напрямую в «1С:ЗУП»;
номенклатурная группа передается из «БИТ.ФИНАНС» в «1С:ЗУП»;
проверена передача объектов по каждому потоку;
подтверждено соблюдение ограничений пилота, в том числе исключение табличных частей из обмена.

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

А ещё, кстати, наткнулись на интересный VPS который работает прямо в центре города. Решили проверить сами - результат порадовал. Вот ссылка, вдруг пригодится: moremore.pro

OpenAPI спецификация как инструмент frontend-разработчика: практическое применение и типичные проблемы

gringo342 — Wed, 11 Nov 2026 13:41:28 GMT

Спецификация OpenAPI

OpenAPI — это спецификация для документирования API в формате YAML или JSON. Она позволяет стандартизированно описывать REST API.

Swagger UI и ReDoc — это популярные инструменты, которые преобразуют спецификацию OpenAPI в интерактивную документацию (UI для спецификации OpenAPI).

Как найти исходную спецификацию OpenAPI по Swagger UI или ReDoc? Открыв документацию Swagger UI или ReDoc в браузере, в консоли разработчика можно найти сетевые запросы к файлу спецификации (формата *.json, *.yaml или *.yml и содержимое будет начинаться с версии спецификации OpenAPI).

Как найти исходную спецификацию OpenAPI по Swagger UI или ReDoc?

Как можно применить спецификацию OpenAPI?

1. Генерация типов TypeScript

Одно из главных преимуществ — возможность генерировать TypeScript типы (для всех эндпоинтов, request/response моделей) из спецификации. Особенно полезно в небольших стартапах или на начальных этапах разработки проекта, когда api быстро меняется, а изменения не всегда обратно совместимы, и вручную уследить за всеми изменениями сложно.

Примеры инструментов:

openapi-typescript - генерирует чистые TypeScript-типы (paths, components) из OpenAPI 3.0/3.1 без runtime-кода, быстро и с поддержкой YAML/JSON (локально/удалённо);
dtsgenerator - Создаёт.d.ts файлы из JSON Schema или OpenAPI (v2/v3), с CLI, плагинами и поддержкой stdin/url;
openapi-generator - Универсальный генератор (CLI /openapi-generator-cli) для клиентов, серверов, документации в 50+ языках, включая TypeScript-варианты (axios, fetch);

1.1. Пример генерации типов для RTK

Полный код рабочего примера на github

Как это работает:

1.1.1. Генерируем типы из OpenAPI спецификации через npm команду

      
// ...
"scripts": {
  //...
  "generate-types": "dtsgen --out src/api/types/generated-counter-api-types.d.ts specs/prepared-counter-api.yaml",
  //...
}
// ...

1.1.2. Генерируются файлы с API типами

      
// ...

declare namespace Components {
    namespace Schemas {
        export interface CounterResponse {
            value: number; // int32
        }
        export interface CounterRequest {
            value: number; // int32
        }
    }
}

declare namespace Paths {
    namespace GetCounter {
        export interface QueryParameters {
            version?: string;
        }
        namespace Responses {
            export type $200 = Components.Schemas.CounterResponse;
        }
    }
    namespace SaveCounter {
        export type RequestBody = Components.Schemas.CounterRequest;
        namespace Responses {
            export type $200 = Components.Schemas.CounterResponse;
        }
    }
}

// ...

1.1.3. Создаём RTK Query API с использованием сгенерированных типов файл

      
/// 

// ...

export const counterApi = createApi({
  // ...
  endpoints: (builder) => ({
    getCounter: builder.query({
      // ...
    }),
    saveCounter: builder.mutation<
      Paths.SaveCounter.Responses.$200,
      Paths.SaveCounter.RequestBody
    >({
      // ...
    }),
  }),
});

// ...

1.1.4. Используем типобезопасные хуки в React компонентах файл

      
// ...

const { data, isLoading, error } = useGetCounterQuery({ version });
const [saveCounter] = useSaveCounterMutation();

// data имеет тип Paths.GetCounter.Responses.$200
// saveCounter принимает параметры типа Paths.SaveCounter.RequestBody

// ...

1.2. Пример генерации типов для react-query

Полный код рабочего примера на github

Как это работает детально:

1.2.1. Генерируем типы из OpenAPI спецификации через npm команду

      
// ...
"scripts": {
  // ...
  "generate-types": "dtsgen --out src/api/types/generated-api-types.d.ts specs/prepared-openapi.json"
  // ...
}
// ...

1.2.2. Генерируются файлы с API типами

      
declare namespace Components {
    namespace Schemas {
        export interface Pet {
            id?: number; // int64
            name: string;
            photoUrls: string[];
            status?: "available" | "pending" | "sold";
            category?: Category;
            tags?: Tag[];
        }
    }
}

declare namespace Paths {
    namespace GetPetById {
        export interface PathParameters {
            petId: number; // int64
        }
        namespace Responses {
            export type $200 = Components.Schemas.Pet;
        }
    }
}

1.2.3. Создаём API-функции с использованием сгенерированных типов

      
/// 

export async function fetchPetById(petId: number): Promise {
  const res = await fetch(`http://localhost:4010/api/v3/pet/${petId}`);
  if (!res.ok) {
    throw new Error('Pet is not found');
  }
  return res.json();
}

1.2.4. Используем типобезопасные хуки React Query в компонентах

      
import { useQuery } from '@tanstack/react-query';
import { fetchPetById } from './api/fetchPetById';

// ...

function App() {
  // ...
  const { isPending, error, data } = useQuery({
    queryKey: ['pet', petId],
    queryFn: () => fetchPetById(petId),
  });
  // ...
}

1.3. Пример генерации типов для нативного fetch

Полный код рабочего примера на github

Как это работает детально:

1.3.1. Генерируем типы из OpenAPI спецификации через npm команду

      
// ...
"scripts": {
  //...
  "generate-types": "dtsgen --out src/api/types/generated-api-types.d.ts specs/prepared-openapi.json",
  //...
}
// ...

1.3.2. Генерируются файлы с API типами

      
// ...

declare namespace Components {
    namespace Schemas {
        export interface Pet {
            id?: number; // int64
            name: string;
            photoUrls: string[];
            status?: "available" | "pending" | "sold";
            category?: Category;
            tags?: Tag[];
        }
    }
}

declare namespace Paths {
    namespace GetPetById {
        export interface PathParameters {
            petId: number; // int64
        }
        namespace Responses {
            export type $200 = Components.Schemas.Pet;
            export interface $404 {}
        }
    }
}

// ...

1.3.3. Создаём типобезопасную обёртку над нативным fetch с использованием сгенерированных типов файл

      
/// 

export class ApiClient {
  private baseUrl: string;

  constructor(baseUrl: string) {
    this.baseUrl = baseUrl;
  }

  async get(path: string, options?: RequestInit): Promise> {
    const url = `${this.baseUrl}${path}`;
    const res = await fetch(url, { ...options, method: 'GET' });
    if (!res.ok) {
      const error = new ApiError(res.statusText, res.status);
      return [error, null];
    }
    const data = (await res.json()) as T;
    return [null, data];
  }

  // Специфичный метод с использованием сгенерированных типов
  async fetchPetByIdSafe(petId: number): Promise> {
    return this.get(`/api/v3/pet/${petId}`);
  }
}

1.3.4. Используем типобезопасный API клиент в React компонентах файл

      
import { ApiPet, ApiTag } from './api/types/models';
import { ApiClient, ApiError } from './api/client';

// ...
const apiClient = new ApiClient('http://localhost:4010');
// ...

function App() {
  // ...

  const [data, setData] = useState(null);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState(null);

  // ...
 
  useEffect(() => {
    const fetchPet = async () => {
      setIsLoading(true);
      setError(null);
      const [err, pet] = await apiClient.fetchPetByIdSafe(petId);
      if (err) {
        setError(err.message);
      } else {
        setData(pet);
      }
      setIsLoading(false);
    };

    fetchPet();
  }, [petId]);

  // ...
}

2. Генерация API-клиентов

Из OpenAPI спецификации можно генерировать готовые API-клиенты.

Не нужно вручную писать fetch/axios запросы, автоматическая обработка headers, query параметров.

Примеры инструментов:

orval - Генерирует React Query/TanStack Query, Axios/Fetch клиенты с типами из OpenAPI v3/Swagger v2.
Hey API (@hey-api/openapi-ts) - CLI для клиентов (Fetch, Axios, Angular, Next/Nuxt), SDK, валидаторов; OpenAPI 2/3/3.1 с плагинами.
openapi-typescript-codegen - Генерирует Axios/Fetch клиенты с типами, поддержка JSON/YAML, external refs
swagger-typescript-api - CLI для Fetch/Axios API клиентов из Swagger/OpenAPI
@openapitools/openapi-generator-cli - Универсальный CLI для SDK в 50+ языках/фреймворках (TS-axios, fetch и др.).
@rtk-query/codegen-openapi - Генерирует RTK Query (Redux Toolkit) хуки/endpoint’ы из OpenAPI.
openapi-fetch - Легкий (6kb) type-safe Fetch-клиент на runtime (с типами из openapi-typescript)

2.1. Пример сгенерированного клиента с использованием orval

Полный код рабочего примера на github

Как это работает детально:

2.1.1. Пишем конфигурацию

      
export default defineConfig({
  api: {
    input: {
      target: './specs/prepared-openapi.json',
    },
    output: {
      target: './src/api/generated/api.ts',
      client: 'fetch',
      mode: 'tags',
      baseUrl: 'http://localhost:4010',
    },
  },
});

2.1.2. Запускаем генерацию через npm комманду

      
// ...

"scripts": {
  //...
  "generate-types": "orval",
  //...
}

// ...

2.1.3. Генерируются файлы с api клиентами

      
// ...

export const getPetById = async (petId: number, options?: RequestInit): Promise => {
   // ...
   const res = await fetch(getGetPetByIdUrl(petId));
   // ...
}

// ...

2.1.4. Генерируются файлы с api типами

      
// ...

export interface Pet {
  category?: Category;
  id?: number;
  name: string;
  photoUrls: string[];
  /** pet status in the store */
  status?: PetStatus;
  tags?: Tag[];
}

// ...

3. Типизация endpoints в BFF-прокси на Node.js с Express

Автоматическая типизация запросов/ответов (генерируя общие TypeScript-типы из API-контрактов из OpenAPI спецификации), исключает ошибки парсинга данных на фронте и упрощает интеграцию с React/TypeScript без ручного описания интерфейсов. Фронтенд получает “глупый” клиент с полной автодополняемостью и валидацией на этапе компиляции, снижая время на отладку API-интеграций. Это особенно полезно в микросервисах, где BFF адаптирует backend-API под нужды UI.

3.1. Пример типизации express endpoints через общие TypeScript-типы

Полный код рабочего примера на github

Как это работает:

3.1.1. Генерируем типы из OpenAPI спецификации через npm команду

      
"scripts": {
  //...
  "generate-types": "dtsgen --out src/services/petstore/generated-api-types.d.ts specs/prepared-petstore.json",
  //...
}

3.1.2. Генерируются файлы с API типами

      
// ...

declare namespace PetstoreComponents {
    namespace Schemas {
    	// ...
    	export interface Order {
            complete?: boolean;
            /**
             * example:
             * 10
             */
            id?: number; // int64
            /**
             * example:
             * 198772
             */
            petId?: number; // int64
            /**
             * example:
             * 7
             */
            quantity?: number; // int32
            shipDate?: string; // date-time
            /**
             * Order Status
             * example:
             * approved
             */
            status?: "placed" | "approved" | "delivered";
        }
    	// ...
    }
}

declare namespace PetstorePaths {
	// ...
    namespace StoreOrder$OrderId {
        namespace Get {
            namespace Parameters {
                export type OrderId = number; // int64
            }
            export interface PathParameters {
                orderId: Parameters.OrderId /* int64 */;
            }
            namespace Responses {
                export type $200 = PetstoreComponents.Schemas.Order;
                export interface $400 {
                    id?: number; // int64
                }
                export interface $404 {
                    message?: string;
                }
            }
        }
    }
    // ...
}

3.1.3. Определяем типобезопасный контроллер через интерфейс

TypedController

      
// ...
export type TypedController = (
    request: TypedRequest,
    response: TypedResponse,
    next: TypedNext,
) => Promise | void;
// ...

3.1.4. Создаём типобезопасные контроллеры с использованием сгенерированных типов

      
// Определяем тип маршрута с параметрами запроса и возможными ответами

type GetOrderByIdRoute = {
  request: {
    params: {
      orderId: PetstorePaths.StoreOrder$OrderId.Get.Parameters.OrderId;
    };
  };
  responses: {
    success: PetstorePaths.StoreOrder$OrderId.Get.Responses.$200;
    error:
        | PetstorePaths.StoreOrder$OrderId.Get.Responses.$400
        | PetstorePaths.StoreOrder$OrderId.Get.Responses.$404; 
  };
}

// ...

// Типизированный контроллер для маршрута GetOrderById
const getOrderByIdRouteTypedController: TypedController = async (request, response, next) => {
	// ...

	const responseMock = await getMockFromOpenApi('post', '/store/order', '200');
    
	// ...
    response.result = responseMock;
    next();

    // ...

    // Example: not valid response body
    // Intentionally assign an invalid object to demonstrate TypeScript error checking
    // @ts-expect-error: TS2322: Type '{ foo: string; }' is not assignable to type 'Order'. Object literal may only specify known properties, and 'foo' does not exist in type 'Order'.
    response.result = { foo: 'bar'};
}

// Регистрируем маршрут с типобезопасным контроллером
app.get('/store/order/:orderId', getOrderByIdRouteTypedController);

3.1.5. Примеры типобезопасных контроллеров для разных типов запросов:

POST запрос с телом:

      
type PlaceOrderRoute = {
    request: {
        body: PetstorePaths.StoreOrder.Post.RequestBody;
    };
    responses: {
        success: PetstorePaths.StoreOrder.Post.Responses.$200;
        error:
            | PetstorePaths.StoreOrder.Post.Responses.$400
            | PetstorePaths.StoreOrder.Post.Responses.$422;
    };
}

const placeOrderRouteTypedController: TypedController = async (request, response, next) => {
    const order = request.body; // order типизирован как PetstoreComponents.Schemas.Order
    // ...
}

GET запрос с query параметрами:

      
type LoginUserRoute = {
    request: {
        query: PetstorePaths.UserLogin.Get.QueryParameters;
    };
    responses: {
        success: PetstorePaths.UserLogin.Get.Responses.$200;
        error: PetstorePaths.UserLogin.Get.Responses.$400;
    };
}

const loginUserRouteTypedController: TypedController = async (request, response, next) => {
    const username = request.query.username; // типизирован как string | undefined
    const password = request.query.password; // типизирован как string | undefined
    // ...
}

Примеры других инструментов:

tRPC - Полная end-to-end типизация без схем; интегрируется с Express, идеален для React+BFF; типы генерируются автоматически из роутеров
routing-controllers - Декораторы для классов-контроллеров в Express; типизирует handlers с @Get/@Post, поддерживает валидацию

4. Валидация в обработчиках (handlers) Express

OpenAPI спецификация значительно упрощает валидацию в обработчиках (handlers) Express, обеспечивая автоматическую проверку запросов и ответов на соответствие заранее определённым схемам.

Примеры библиотек:

express-openapi-validator - предоставляет Express middleware для автоматической валидации запросов, ответов (JSON) и security по OpenAPI 3.0/3.1
openapi-request-validator - валидирует свойства запросов (query, body, headers, params) против OpenAPI схем, работает standalone
openapi-response-validator - проверяет HTTP-ответы по responses схемам OpenAPI, standalone для тестирования или runtime

4.1. Пример валидации запросов

Полный код рабочего примера на github

Как это работает:

      
app.use(
  OpenApiValidator.middleware({
    apiSpec: openApiSpec,
    validateRequests: true,
    validateResponses: true,
  }),
);

5. Генерация моковых/sample данных/сущностей для разработки и интеграционных тестов

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

Примеры инструментов:

openapi-sampler - генерирует детерминированные примеры JSON из OpenAPI Schema Objects (3.0/3.1), учитывая examples, enum, default, constraints и compound keywords как allOf/oneOf/anyOf
@openapi-contrib/openapi-schema-to-json-schema + json-schema-faker - @openapi-contrib/openapi-schema-to-json-schema конвертирует OpenAPI Schema/Parameter в JSON Schema Draft 4 (удаляет nullable → type: [‘null’], поддержка nested allOf), для совместимости с JSON Schema инструментами. json-schema-faker (jsf) генерирует случайные (не детерминированные) данные из JSON Schema Draft 4+.

5.1. Пример генерации моковых данных

Полный код рабочего примера на github

Генерация моковых/sample данных основана на конвертации OpenAPI схем в JSON Schema и использовании json-schema-faker

@openapi-contrib/openapi-schema-to-json-schema – конвертирует OpenAPI схемы в JSON Schema
@apidevtools/json-schema-ref-parser – разрешает все $ref ссылки в OpenAPI спецификации
json-schema-faker – генерирует валидные данные на основе JSON Schema

Как это работает детально:

      
// Утилита для генерации sample объекта для сущности из OpenAPI спецификации
// ...
async function createEntitySampleFromOpenApi(entityName: string): Promise {
  // Загружаем OpenAPI спецификацию
  const specPath = path.join(__dirname, '../specs/petstore.json');
  const spec = JSON.parse(fs.readFileSync(specPath, 'utf-8'));
  // Разрешаем все $ref ссылки
  const dereferenced: any = await RefParser.dereference(spec);
  // Находим схему для указанной сущности/компонента
  const entitySchema = dereferenced.components.schemas[entityName];
  if (!entitySchema) throw new Error('Component not found');
  // Конвертируем OpenAPI схему в JSON Schema
  const jsonSchema = openapiSchemaToJsonSchema(entitySchema);
  // Генерируем sample объект, соответствующий схеме
  return jsf.generate(jsonSchema) as T;
}

// Использование в тестах
it('should generate a valid Pet object', async () => {
  // Генерируем sample объект для сущности 'Pet', определённой в OpenAPI спецификации
  const sample = await createEntitySampleFromOpenApi('Pet');
  // sample типизирован как PetstoreComponents.Schemas.Pet
  expect(sample).toBeTruthy();
});

      
// Утилита для генерации sample ответа для endpoint'а из OpenAPI спецификации
async function createEndpointResponseSampleFromOpenApi(method: string, endpointPath: string, statusCode: string): Promise {
  // Загружаем OpenAPI спецификацию
  const specPath = path.join(__dirname, '../specs/petstore.json');
  const spec = JSON.parse(fs.readFileSync(specPath, 'utf-8'));
  // Разрешаем все $ref ссылки
  const dereferenced: any = await RefParser.dereference(spec);
  // Находим указанный endpoint
  const pathItem = dereferenced.paths[endpointPath];
  if (!pathItem) throw new Error('Path not found');
  // Находим указанный HTTP метод
  const op = pathItem[method.toLowerCase()];
  if (!op) throw new Error('Method not found');
  // Извлекаем ответ для указанного статус кода
  const resp = op.responses && op.responses[statusCode];
  if (!resp) throw new Error('Status code not found');
  // Получаем JSON схему для ответа
  const content = resp.content && resp.content['application/json'];
  if (!content || !content.schema) throw new Error('Response schema not found');
  // Конвертируем OpenAPI схему в JSON Schema
  const jsonSchema = openapiSchemaToJsonSchema(content.schema);
  // Генерируем sample объект, соответствующий схеме
  return jsf.generate(jsonSchema) as T;
}

// Использование в тестах
it('should generate a valid endpoint response', async () => {
  // Генерируем sample ответ для GET /pet/{petId} endpoint со статусом 200
  const sampleResponse = await createEndpointResponseSampleFromOpenApi(
    'get', 
    '/pet/{petId}', 
    '200'
  );
  // sampleResponse типизирован как PetstorePaths.Pet$PetId.Get.Responses.$200
  expect(sampleResponse).toBeTruthy();
});

      
// Утилита для генерации моковых данных из OpenAPI (используется в контроллерах)
async function getMockFromOpenApi(method: string, endpointPath: string, statusCode: string): Promise {
  const specPath = path.join(__dirname, '../specs/petstore.json');
  const spec = JSON.parse(fs.readFileSync(specPath, 'utf-8'));
  const dereferenced: any = await RefParser.dereference(spec);
  const pathItem = dereferenced.paths[endpointPath];
  const op = pathItem[method.toLowerCase()];
  const resp = op.responses && op.responses[statusCode];
  const content = resp.content && resp.content['application/json'];
  const jsonSchema = openapiSchemaToJsonSchema(content.schema);
  return jsf.generate(jsonSchema) as T;
}

// Использование в контроллере
const getOrderByIdRouteTypedController: TypedController = async (request, response, next) => {
    // ...

  // Генерируем моковый ответ для успешного ответа 200
  const responseMock = await getMockFromOpenApi(
    'get', 
    '/store/order/{orderId}', 
    '200'
  );
  response.result = responseMock; // типобезопасно
  next();

// ...

  // Example 4: valid error body
  // Generate a mock error response for a 400 error using OpenAPI types
  const responseErrorMock = await getMockFromOpenApi('post', '/store/order/{orderId}', '400');
    next(
        new ServiceResponseError({
            statusCode: 400,
            body: responseErrorMock
        }),
    );

    // ...
};

6. Создание mock-серверов

OpenAPI спецификация значительно упрощает создание mock-серверов, позволяя автоматически генерировать имитацию API на основе описанных эндпоинтов, схем данных и примеров ответов. Инструменты вроде MockServer, Smogger или Swagger Mock загружают спецификацию (в формате YAML/JSON) и динамически создают сервер, который возвращает реалистичные мок-ответы с рандомными данными по схемам, без необходимости писать код вручную. Это ускоряет frontend-разработку, тестирование и интеграцию, пока реальный бэкенд не готов, обеспечивая валидацию запросов и поддержку всех HTTP-методов из спецификации.

Примеры инструментов:

Prism (/prism-cli) запускает полноценный HTTP mock/proxy-сервер из OpenAPI 2/3 или Postman, с динамическими ответами, валидацией и transformations
msw + msw-auto-mock - перехватывает запросы в браузере/Node (Service Worker), генерируя TS-моки из OpenAPI с faker.js данными для dev-тестов
json-server - создаёт REST API из JSON-файла (db.json), с CRUD, auth-плагинами (json-server-auth), но без native OpenAPI — нужны кастомные плагины для схем

6.1. Пример запуска mock-сервера

Полный код рабочего примера на github

Как это работает детально:

Запускаем mock-сервер с помощью Prism CLI

      
"scripts": {
  //...
  "mock:api": "prism mock specs/prepared-openapi.json -h 0.0.0.0 -p 4010 --cors",
  //...
}

// npm run mock:api

Mock-сервер:

Читает OpenAPI спецификацию из specs/prepared-openapi.json
Автоматически генерирует валидные ответы на основе схем из спецификации
Запускается на
Поддерживает CORS для работы с фронтенд-приложением
Эмулирует все endpoint’ы, определённые в OpenAPI спецификации

Возникающие типичные проблемы и как их решить

Фронтендеры часто сталкиваются с тем, что OpenAPI документация от backend-команды неидеальна и мешает эффективной работе:

допускаются банальные опечатки, если бэкендеры пишут спецификацию вручную;
стандарт OpenAPI формальный, из-за этого иногда спецификацию пишут так, что ломаются интеграции с инструментами (например, из-за особенностей написания спецификации перестаёт работать генерация типов);
если бэкендеры генерируют спецификацию из кода, она может формироваться так, что ломаются интеграции с инструментами работы со спецификацией — возникает дилемма: либо дорабатывать фронтенд-инструменты, либо исправлять генерацию спецификации на бэкенде.

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

Есть несколько способов решить эту проблему:

1. Валидировать OpenApi спецификацию

Инструменты для валидации OpenApi спецификации:

Redocly CLI выполняет linting с рекомендациями по улучшению, поддерживает OpenAPI 3.x/2.0, bundling, документацию и API contract testing через Respect.
Spectral — это линтер на основе правил (rulesets/functions), ориентированный на OpenAPI, AsyncAPI и другие JSON/YAML, с высокой кастомизацией.
Swagger CLI в основном валидирует схему OpenAPI 3.0/Swagger 2.0 плюс базовые проверки (дубликаты, MIME-типы), но устарел и не развивается

При помощи валидации спецификации можно вовремя заметить ломающие изменения, но это не решает проблему неидеальности OpenAPI-спецификации.

2. Подготавливать OpenApi спецификацию

У Redocly CLI для модификации спецификации используется функция decorators, которая позволяет трансформировать документ (добавлять примеры, описания или изменять URL).

Decorators подходят для простых трансформаций (удаление эндпоинтов, добавление примеров), но для сложных случаев требуют custom plugins на JS, что усложняет поддержку.

Для упрощения подготовки OpenAPI-спецификации можно использовать openapi-modifier — он содержит широкий набор простых правил для трансформаций, которые применяются последовательно (собираются в pipeline). Таким образом можно строить сложные трансформации.

      
module.exports = {
  input: "./openapi.yaml",
  output: "./openapi.mod.yaml",
  logger: { verbose: true },
  pipeline: [
    // JIRA-232: добавляем ручки новой фичи
    { rule: "merge-openapi-spec", config: { path: "docs/feature-JIRA-232.yaml" } },

    // JIRA-8752: исправляем тип id, сохраняя остальные поля Pet
    { rule: "patch-component-schema", config: { descriptor: "Pet.id", patchMethod: "merge", schemaDiff: { type: "string", format: "uuid" } } },

    // Нормализуем форматы перед изменением JSON-ответа
    { rule: "change-content-type", config: { map: { "*/*": "application/json" } } },
    { rule: "filter-by-content-type", config: { disabled: ["multipart/form-data"] } },

    // Исправляем статусы в ответе — массиве объектов без $ref
    { rule: "patch-endpoint-response-schema", config: { endpointDescriptor: "GET /v1/pets", code: "200", contentType: "application/json", correction: "[].status", patchMethod: "merge", schemaDiff: { enum: ["active", "archived"] } } },

    // Нормализация под генераторы
    { rule: "remove-operation-id" },
    { rule: "remove-min-items" },

    // Убираем deprecated ручки
    { rule: "remove-deprecated", config: { showDeprecatedDescriptions: true } },
    // Убираем внутренние ручки
    { rule: "filter-endpoints", config: { disabledPathRegExp: [/^\/internal(?:\/|$)/] } },
    // Удаляем неиспользуемые компоненты
    { rule: "remove-unused-components", config: { printDeletedComponents: true } },
  ],
};

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

Типичные ситуации и как их решить:

Ниже — независимые примеры конфигураций. Имена моделей, полей и пути условные; замените их на свои. Входной и выходной файлы можно передать через CLI:

npx openapi-modifier --input openapi.yaml --output prepared-openapi.yaml --config openapi-modifier.config.js

Бэкенд указал неверный тип int вместо integer, что ломает кодогенерацию TS-типов или API-клиентов Пример конфигурации:

      
module.exports = {
  pipeline: [{
    rule: 'patch-component-schema',
    config: {
      // Исправляем тип поля id в модели Pet.
      descriptor: 'Pet.id',
      patchMethod: 'merge',
      schemaDiff: { type: 'integer' },
    },
  }],
};

Бэкенд допустил опечатку в формате поля, например указал datetime вместо date-time Пример конфигурации:

      
module.exports = {
  pipeline: [{
    rule: 'patch-component-schema',
    config: {
      // Исправляем формат даты в поле createdAt.
      descriptor: 'Pet.createdAt',
      patchMethod: 'merge',
      schemaDiff: { type: 'string', format: 'date-time' },
    },
  }],
};

Бэкенд забыл указать "type": "object" в схеме модели, что ломает кодогенерацию TS-типов или API-клиентов Пример конфигурации:

      
module.exports = {
  pipeline: [{
    rule: 'patch-component-schema',
    config: {
      // Указываем пропущенный тип модели Pet.
      descriptor: 'Pet',
      patchMethod: 'merge',
      schemaDiff: { type: 'object' },
    },
  }],
};

Бэкенд на проде находится под другой прокси, и нужно поменять basepath для всех endpoint в спецификации Пример конфигурации:

      
module.exports = {
  pipeline: [{
    rule: 'change-endpoints-basepath',
    // /pets → /api/v1/pets; меняются ключи paths, а не servers.
    config: { map: { '/': '/api/v1/' } },
  }],
};

Мешают minItems и maxItems для генерации типов или API-клиентов Пример конфигурации:

      
module.exports = {
  pipeline: [
    // Убираем ограничение на минимальную длину массивов.
    { rule: 'remove-min-items' },
    // Убираем ограничение на максимальную длину массивов.
    { rule: 'remove-max-items' },
  ],
};

Мешает operationId для генерации типов или API-клиентов Пример конфигурации:

      
module.exports = {
  pipeline: [
    // Удаляем operationId у всех операций.
    { rule: 'remove-operation-id' },
  ],
};

Нужно убрать лишние варианты ответов application/xml и переписать / на application/json для генерации типов или API-клиентов Пример конфигурации:

      
module.exports = {
  pipeline: [
    {
      // Убираем XML из запросов и ответов.
      rule: 'filter-by-content-type',
      config: { disabled: ['application/xml'] },
    },
    {
      // Заменяем */* на application/json.
      rule: 'change-content-type',
      config: { map: { '*/*': 'application/json' } },
    },
  ],
};

Не нужны все ручки из OpenAPI-спецификации, к примеру, нужно убрать /private/* ручки из документации для фронтенда. Это не ограничивает доступ к реальным эндпоинтам Пример конфигурации:

      
module.exports = {
  pipeline: [{
    // Исключаем /private и все пути внутри /private/.
    rule: 'filter-endpoints',
    config: { disabledPathRegExp: [/^\/private(?:\/|$)/] },
  }],
};

Параметр или свойство метода скоро исчезнет (оно еще не помечено как deprecated в документации), и нужно отредактировать спецификацию, чтобы после перегенерации типов или API-клиентов TypeScript подсказал, где нужно убрать его использование, и дополнительно не допустить повторного его использования Пример конфигурации:

      
module.exports = {
  pipeline: [{
    // Удаляем query-параметр version у GET /pets.
    rule: 'remove-parameter',
    config: {
      endpointDescriptor: 'GET /pets',
      parameterDescriptor: { name: 'version', in: 'query' },
    },
  }],
};

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

      
module.exports = {
  pipeline: [{
    rule: 'patch-component-schema',
    config: {
      descriptor: 'Pet',
      patchMethod: 'deepmerge',
      schemaDiff: {
        // Добавляем необязательное поле color, сохраняя остальные поля.
        properties: { color: { type: 'string' } },
      },
    },
  }],
};

Помимо данных правил, есть еще правила:

удаление deprecated компонентов, эндпоинтов, параметров и свойств (см. правило remove-deprecated) - позволяет вовремя замечать устаревания используемых элементов спецификации, например, бекендеры помечают элементы deprecated флагом - фронтендеры, замечая, что они пропадают с openapi вовремя замечают и съезжают с них
удаляющее неиспользуемые компоненты/cхемы, на которые нет ссылок или ref’ов (см. правило remove-unused-components) - позволяет очистить спецификацию от неиспользуемых элементов спецификации, к примеру, если были отфильтрованы ручки и остались неиспользуемые компоненты
объединение нескольких спецификаций (см. правило merge-openapi-spec) - полезно в ситуации, когда появляется новая фича, документация для ручек которой еще не готова для влития в основную, а параллельную разработку можно начинать.

Автоматизация — не нужно вручную править OpenAPI-файлы после каждого обновления
Исправление опечаток — быстрое исправление банальных ошибок без ожидания фикса от бэкенда
Документирование причин — каждое правило можно снабдить комментарием с номером задачи
Улучшение коммуникации в команде — единый источник правды
Ускорение онбординга новых разработчиков — самодокументируемый код, все причины правок документированы
Pipeline-подход — правила применяются последовательно, можно строить сложные трансформации. Любое правило можно применять несколько раз — дробите фиксы на мелкие осмысленные блоки с комментариями и ссылками на тикеты.

Модернизация JavaScript-проекта для моделирования физических экспериментов и роль ИИ в этом

gringo342 — Wed, 11 Nov 2026 12:41:18 GMT

Введение и описание
Описание демонстраций и теория по физике
Модернизация проекта и использование ИИ Исходное состояние Переход от модульного паттерна к использованию классов Создание языковой локализации Избавление от setTimeout и переход на механизм requestAnimationFrame для создания анимаций Адаптация под смартфоны и различные разрешения экрана Создание боковых, сворачивающихся панелей Создание новой демонстрации по теме “Затухающие колебания пружин”
Результаты, выводы

Введение и описание

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

Старый программный код можно найти по ссылке. Предыдущая статья доступна здесь. Также доступен работающий сайт со старыми демонстрациями по этому адресу.

Скриншот предыдущего проекта

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

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

В данной статье рассказано, как менялся проект, как использовался ИИ ChatGPT и Cursor и с какими проблемами пришлось столкнуться.

Описание демонстраций и теория по физике

Нынешняя версия проекта

С обновленным проектом можно ознакомиться здесь. Веб-сайт с демонстрациями доступен по этой ссылке.

Проект представляет собой классическое веб-приложение, в котором используются HTML– страницы, Javascript и CSS файлы без подключения каких-либо сторонних библиотек.

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

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

Закон сложения сил под углом к другу

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

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

Скриншот физической сцены “Сложение сил, направленных под углом друг к другу”

Закон гидростатики и аэростатики

Иллюстрация закона Архимеда

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

Пользователь в проекте может изменять:

(ро) — плотность жидкости или газа (

— объём погружённого тела (

) и вес тела. После перетаскивания и подвеса тела к пружинному динамометру подсчитываются объём тела, сила Архимеда, сила тяжести, а также демонстрируется анимация динамометра.

Скриншот физической сцены “Закон Архимеда”

Математический маятник

Иллюстрация математического маятника

Математический маятник — это материальная точка, подвешенная на невесомой нерастяжимой нити (идеализированная система). Период колебаний — время, за которое маятник совершает одно полное колебание. Вычисляется по формуле:

Пользователь в проекте может изменять

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

Скриншот физической сцены “Математический маятник”

Затухающие колебания пружин

Иллюстрация колебания пружин

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

Частота измеряется в герцах (

) и используется только для отображения информации пользователю. Для реальной реализации затухающих колебательных движений в коде применяется дифференциальное уравнение движения.

Пользователь сайта может изменять:

— жёсткость пружины(

— массу груза (

— коэффициент затухания(

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

Скриншот физической сцены “Затухающие колебания”

Модернизация проекта и использование ИИ

Исходное состояние

Центральной страницей проекта является

index.html

В предыдущей версии

index.html

подключал объекты JS - кода и скрипты напрямую через

Переход от модульного паттерна к использованию классов

Предыдущий подход разбиения архитектуры на блоки

const

, с сгруппированным функционалом является устаревшим. Это создавало неудобства при поддержке, при внесении изменений или расширении проекта. Кроме того, при применении объектов

const

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

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

      
function Appliance(options = {}) {
 // Значения по умолчанию 
 Object.assign(this, {
…
  }, options);
…
}

Прибор для измерения силы — динамометр — строился на основании этого абстрактного устройства с добавлением новых свойств. Для этого применялось прототипное наследование. Пример создания стрелочного динамометра и наследование от

Appliance

      
function Dynamometer(options) {
  Appliance.call(this, options); // вызов базового конструктора 
 ...
}
Dynamometer.prototype = Object.create(Appliance.prototype); // организация цепочки прототипов
Dynamometer.prototype.constructor = Dynamometer;

Dynamometer.prototype = {
  draw: function () { ... );
}

В современном JavaScript чаще используется подход использования модулей (

import/export

). Это позволяет экспортировать классы, функции для использования в других JS – файлах. В классах можно организовать код более структурировано и понятно, организовать поддержку приватных полей с помощью встроенного синтаксиса. Для использования экспортированных объектов достаточно прописать , что происходит их импорт на уровне JavaScript кода.

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

extends.

А чтобы получить доступ к конструктору родителя и его свойствам в классах используется простое использование конструкции

super

. К примеру, создание объекта

Appliance

и его наследника

Dynamometer

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

      
export class Appliance {
  #fieldsAppl; // приватные свойства
  constructor(options = {}) {
    // Свойства значения по умолчанию
    Object.assign(
      this,
      {
        centerX: 0,
        centerY: 0,
        radius: 50,
      },
      options,
    );
  }
  ...
}

// Dynamometer наследует Appliance
export class Dynamometer extends Appliance {
  constructor(options = {}) {
    // наследование конструктора от Appliance
    super(options);
    // Свойства значения по умолчанию для Dynamometer
    Object.assign(
      this,
      {
        maxValue: 10,
      },
      options,
    );
  }
  ...
}

На этом этапе для решения задачи по переходу на

 import/export

использовался ChatGPT вместе с Cursor. Cursor способен исследовать и переделать весь проект целиком. Однако такой объем изменений сложно будет отследить и позже переработать самостоятельно. Поэтому сначала объекты переводились в классы постепенно через ChatGPT.

Первая проблема, которая возникает, — не получается сделать модульными и настроить import/export объектов в проекте поочередно. Например, для начала, переводится в класс, прописывается export объекта

Spring

(функционал для отображения пружины из файла "Tools/spring.js" ). Если использовать

Spring

внутри другого объекта, который не является модульным, например внутри файла

springDynamometer.js

, топроявляетсяошибка “ Cannot use import statement outside a module”.

То есть нельзя сделать модульным

spring.js

, если

springDynamometer.js

подключается как обычный

@gringo342

Свой маркиратор для Честного знака на картридже HP45 и ESP32: от одной точки до рабочего прототипа в производстве

Вступление

Теория

Что такое адрес и примитив

Как узнать температуру картриджа

Первый импульс

Первый прототип

Схема

Плата

Прошивка

Первая линия

Библиотека DataMatrix для печати кодов Честного знака

Промежуточный прототип

Схема

Самодельные платы

Подготовка

Засветка

Прошивка

Итоговый прототип

Схема

Плата

Архитектура и прошивка

Настоящие 600 DPI

Хост

Итоги

Как ломается модульный монолит и как с этим бороться

TL;DR

Тесты топологий

Несколько топологий в одном процессе

Контроль модульности при компиляции

Контроллеры тоже internal

Связи между сборками

ModuleBase и атрибут

Что ещё проверять при сборке

Улучшаем модульность с помощью Source Generator

Порядок модулей

Опечатка в переменной HOSTINGSTARTUPASSEMBLIES

Бонус: проверка владения сущностью и таблицей

Очень много кода

Выводы

FusionModules

Материалы

От COM-интеграций к централизованной схеме: как проверить новую интеграционную архитектуру до промышленного внедрения

О компании

С чем обратился заказчик

Что сделали

Результат

OpenAPI спецификация как инструмент frontend-разработчика: практическое применение и типичные проблемы

Спецификация OpenAPI

Как можно применить спецификацию OpenAPI?

1. Генерация типов TypeScript

1.1. Пример генерации типов для RTK

1.2. Пример генерации типов для react-query

1.3. Пример генерации типов для нативного fetch

2. Генерация API-клиентов

2.1. Пример сгенерированного клиента с использованием orval

3. Типизация endpoints в BFF-прокси на Node.js с Express

3.1. Пример типизации express endpoints через общие TypeScript-типы

4. Валидация в обработчиках (handlers) Express

4.1. Пример валидации запросов

5. Генерация моковых/sample данных/сущностей для разработки и интеграционных тестов

5.1. Пример генерации моковых данных

6. Создание mock-серверов

6.1. Пример запуска mock-сервера

Возникающие типичные проблемы и как их решить

1. Валидировать OpenApi спецификацию

2. Подготавливать OpenApi спецификацию

Типичные ситуации и как их решить:

Модернизация JavaScript-проекта для моделирования физических экспериментов и роль ИИ в этом

Оглавление

Введение и описание

Описание демонстраций и теория по физике

Нынешняя версия проекта

Закон сложения сил под углом к другу

Закон гидростатики и аэростатики

Математический маятник

Затухающие колебания пружин

Модернизация проекта и использование ИИ

Исходное состояние