Package Exports

aact

Readme

Architecture As Code Tools (aact)

CLI и библиотека для валидации, анализа и генерации архитектуры микросервисных систем, описанной "as Code" (PlantUML C4, Structurizr).

Инструменты для работы с архитектурой в формате "as Code":

Код и примеры покрытия тестами микросервисной архитектуры, описанной в plantuml (#)
Автогенерация архитектуры (#)
Тестирование архитектуры модульного монолита (#)

Планы развития инструментов и репозитория. PullRequest'ы и Issues'ы приветствуются.

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

Телеграм-канал: Архитектура распределённых систем

Quick Start (CLI)

# Инициализация конфига
npx aact init

# Проверка правил архитектуры
npx aact check

# Анализ метрик
npx aact analyze

# Генерация артефактов
npx aact generate --format plantuml
npx aact generate --format kubernetes

Конфигурация

aact init создаст файл aact.config.ts:

import { defineConfig } from "aact";

export default defineConfig({
  source: {
    type: "plantuml", // "plantuml" | "structurizr"
    path: "./architecture.puml",
  },
  rules: {
    acl: true,
    acyclic: true,
    crud: true,
    dbPerService: true,
    cohesion: true,
  },
});

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

import {
  loadPlantumlElements,
  mapContainersFromPlantumlElements,
  checkAcl,
  checkAcyclic,
  checkCrud,
  analyzeArchitecture,
} from "aact";

const elements = await loadPlantumlElements("architecture.puml");
const model = mapContainersFromPlantumlElements(elements);

// Проверка правил
const aclViolations = checkAcl(model.allContainers);
const cyclicViolations = checkAcyclic(model.allContainers);

// Анализ метрик
const { report } = analyzeArchitecture(model);
console.log(`Elements: ${report.elementsCount}`);

Примеры

Banking (PlantUML) — проверка правил, CCR-анализ, генерация K8s-конфигов
Microservices (Structurizr) — полный цикл: правила, анализ, генерация

Документация

Справочник паттернов — принципы и паттерны с примерами тестов
ADR — Architecture Decision Records
Roadmap — планы развития

Публичные материалы

Раз архитектура — «as Code», почему бы её не покрыть тестами?!

https://www.youtube.com/watch?v=POIbWZh68Cg https://www.youtube.com/watch?v=tZ-FQeObSjY

Статья на Хабре

Автогенерация архитектуры

https://www.youtube.com/watch?v=fb2UjqjHGUE

Покрытие архитектуры тестами

Что это, какую боль решает, и с чего начать?

Раз архитектура — «as Code», почему бы её не покрыть тестами?!

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

Подход помогает решить проблемы неактуальности, декларативности и отсутствия контроля ИТ-архитектур и инфраструктуры (ограничение и требование — архитектура и инфраструктура должны быть "as code").

Тесты проверяют 2 больших блока:

актуальность архитектуры реальному работающему в продакшне решению
соответствие "нарисованной" архитектуры выбранным принципам и паттернам проектирования

Подробнее о подходе, решаемых проблемах, схеме работы представленного в репозитории примера и проверяемых в тестах репозитория принципах — на слайдах.

Схема работы

Визуализация примера автоматически проверяемого принципа (отсутствие бизнес-логики в CRUD-сервисах)

Пример архитектуры, которую покроем тестами

Пример тестов

find diff in configs and uml containers — проверяет актуальность списка микросервисов на архитектуре и в конфигурации инфраструктуры
find diff in configs and uml dependencies — проверяет актуальность зависимостей (связей) микросервисов на архитектуре и в конфигурации инфраструктуры
check that urls and topics from relations exist in config — проверяет соответствие между параметрами связей микросервисов (REST-урлы, топики kafka) на архитектуре и в конфигурации инфраструктуры
only acl can depend on external systems — проверяет, что не нарушен выбранный принцип построения интеграций с внешними системами только через ACL (Anti Corruption Layer). Проверяет, что только acl-микросервисы имеют зависимости от внешних систем.
connect to external systems only by API Gateway or kafka — проверяет, что все внешние интеграции идут через API Gateway или через kafka

Автогенерация архитектуры

Генерация архитектуры из описанной «as Code» инфраструктуры

Сравнение ~~белковой~~ составленной вручную архитектуры и сгенерированной.

Ручная:

Сгенерированная:

Тестирование модульного монолита

Тестами можно покрывать не только архитектуру микросервисов, но архитектуру монолитов, особенно, если они модульные.

Тест архитектуры модульного монолита на C#

Тестирование на основе информации из кода

Информацию об архитектуре реализованной системы можно извлечь и из ее кода, особенно, если он написан качественно;)

Извлечение информации об архитектуры системы из ее кода