Перейти к основному содержимому

ADR-0038: Shared Building Blocks SDK — Карта И Правила Пакетов

Статус​

Принято.

Контекст​

По мере роста числа сервисов Pin каждый новый сервис копировал boilerplate: bootstrap, MediatR регистрацию, middleware pipeline, repository abstractions, logging scope, Redis lock helpers. Это приводило к расхождению поведения между сервисами, дублированию багов и несинхронным обновлениям security-critical кода.

ADR-0033 ввёл Bootstrap Kernel. Данный ADR фиксирует полную карту shared building blocks пакетов, их содержимое, правила зависимостей и процедуру добавления нового shared capability.

Решение​

Shared codebase организована в src/building-blocks/ и src/kernel/ как временные monorepo .csproj, подлежащие выносу в internal NuGet packages после стабилизации контрактов.

Пакеты​

ПакетЗона Ответственности
Talent.Common.DomainEntity contracts, Value Objects, Domain Events, strongly-typed ids, Specifications
Talent.Common.ApplicationMediatR contracts, Actor/Scope providers (interfaces), Result models, Paging, IClock
Talent.Common.IdentityJWT authentication schemes, Actor factories, Middleware, Authorization policies
Talent.Common.InfrastructureEF helpers, Repository pipeline + interceptors, UnitOfWork, Idempotency storage, Audit store
Talent.Common.MessagingKafka envelope, MassTransit conventions, Consumer idempotency, Event attributes
Talent.Common.ObservabilitySerilog enrichers, OpenTelemetry activities, Metrics instruments, Decorator base classes, Masking
Talent.Common.Domain.SearchElasticsearch repository abstractions, Alias management, Scope filters, Rebuild jobs
Talent.Common.AnalyticsClickHouse batch writer, Query client, Report repository, Fact base class
Talent.Common.ResiliencePolly policies, Timeout abstractions, Retry/CircuitBreaker decorators
Pin.Kernel.*Bootstrap, Startup base classes, Middleware pipeline, DI builders, Testing support

Детализация: NuGet Package Structure.

Dependency Direction​

Domain ← Application ← Identity
                      ← Infrastructure ← Observability
                      ← Messaging       ← Observability
Kernel → все building blocks

Domain не зависит ни от чего. Сервисный code не зависит от Kernel напрямую — только через Startup.

Правила Добавления Нового Shared Capability​

  1. Определить, нужен ли новый пакет или расширение существующего.
  2. Убедиться, что capability не содержит бизнес-логику конкретного сервиса.
  3. Добавить extension method AddPin<Capability>().
  4. Добавить Options class с ValidateOnStart.
  5. Написать tests нового пакета.
  6. Обновить shared-package-map.md и этот ADR.
  7. Оценить impact на все consuming сервисы.

Последствия​

  • Поведение всех сервисов стало унифицировано в части bootstrap, middleware, repository pipeline.
  • Security-critical код (tenant isolation, actor context) обновляется в одном месте.
  • Добавление нового сервиса требует только реализации extension points, а не boilerplate.
  • Любое изменение shared building blocks считается monorepo breaking change.

Ссылки​