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

Backend SDK — Руководство Разработчика

Назначение​

Этот раздел является практическим руководством разработчика для работы с Pin shared building blocks, NuGet/csproj пакетами, инфраструктурными абстракциями, правилами DDD, паттернами тестирования и правилами построения отчётов. Он дополняет, а не заменяет архитектурные ADR и спецификации сервисов.

Перед реализацией любого сервиса нужно прочитать:

  1. AGENTS.md — главные правила репозитория.
  2. Backend Rules — правила разработки.
  3. Backend Shared Standards Index — индекс всех shared стандартов.
  4. Этот раздел — практическое руководство по SDK.

Содержание Раздела​

ДокументЧто Описывает
01 — DDD и Domain ModelRich vs Anemic модели, Aggregate Root, Value Objects, Domain Events, Invariants, DDD в разных слоях.
02 — Base Entities, Documents, EventsБазовые типы сущностей, Kafka envelope, Elasticsearch документы, ClickHouse факты, VersionedJsonDocument.
03 — NuGet Package StructureКарта пакетов Talent.Common.* и Pin.Kernel.*: что в каждом, как подключать, как расширять.
04 — Actors, Providers, MiddlewareIdentityContext, actor types, scope providers, middleware order, как правильно использовать context в handlers.
05 — Repository Pipeline и Scope FiltersInterceptors TenantId/BrandId/UserId/PartnerId, ScopeOptions, mutation pipeline, bypass audit, тестирование.
06 — MediatR, CQRS, Pipeline BehaviorsПорядок behaviors, контракты Commands/Queries, idempotency, transaction, domain events dispatch, примеры.
07 — Caching, Scrutor Decorators, RedisICacheableQuery, cache key convention, Scrutor decorator registration, logging/tracing decorators, locks.
08 — ТестированиеxUnit, FluentAssertions, Moq, AutoFixture, Testcontainers, WebApplicationFactory, MassTransit harness, примеры.
09 — Reporting и ExportClosedXML Excel, CSV, JSON экспорт, поля, фильтры, форматы, роли admin/partner, privacy, audit.
10 — SignalR RealtimeSignalR WebSocket architecture, Redis backplane для multi-replica k8s, IRealtimeProducer, RealtimeNotificationRelay, message contracts.
11 — Distributed Lockingmadelson/DistributedLock, IPinLockProvider, Redis operational locks, PostgreSQL advisory migration locks, DistributedJobRunner.
12 — Resilience, FluentValidation, AuditPolly/Http.Resilience pipelines, ResilientPortDecorator, FluentValidation two-level, Audit.NET admin API deep audit, AuditDbContext.
13 — Code Quality And TypingNullability, records, sealed, required, primary constructors, pattern matching, guard clauses, async/await, exception strategy — enterprise .NET 10.
14 — Security PatternsDefence-in-depth authorization, PII/secrets в логах, input validation, OWASP mapping, JWT validation, tenant isolation, rate limiting, callback HMAC.

Архитектурная Позиция SDK​

  • Talent.Common.* — переиспользуемые абстракции и реализации без бизнес-логики конкретного сервиса.
  • Pin.Kernel.* — bootstrap, startup классы, dependency injection, middleware pipeline, health.
  • Pin.Contracts.* — публичные event contracts и DTO для межсервисного обмена.
  • Сервисный код не знает о других сервисах напрямую; только через contracts и events.

Ключевые Принципы​

Dependency Direction. Domain → не зависит ни от чего. Application → зависит от Domain. Infrastructure → зависит от Application. Api → зависит от Application. Между сервисами — только Contracts.

Scope Safety. Каждый query/mutation автоматически фильтруется по TenantId, BrandId, UserId/PartnerId через repository interceptors. Ручная передача scope id в каждый handler запрещена — providers и interceptors делают это автоматически.

DDD где бизнес-логика, CRUD где её нет. Rich model используется для финансовых, compliance и core доменов. Anemic model допустима для справочников, конфигурации и admin dictionaries.

Outbox-first. Любой интеграционный event публикуется через MassTransit Transactional Outbox внутри transaction boundary команды, а не в HTTP response handler-е.

No Raw Exceptions. Ожидаемые бизнес-ошибки — typed Result<T> failure. Unexpected exceptions — логируются, маппятся в generic 500. Error code — стабильный контракт.

Быстрый Старт — Новый Сервис​

  1. Создать solution по шаблону: Pin.<Service>.{Api, Application, Domain, Infrastructure, Migrator, Background, Contracts}.
  2. В Api/Program.cs подключить PinHost.CreateWeb(args).UseStartup<{Service}WebStartup>().Run().
  3. Реализовать {Service}WebStartup : BaseWebStartup с override DescribeService, AddApplication, AddInfrastructure, AddApi, AddMessaging.
  4. Создать {Service}DbContext : PinDbContext с entity configurations в Infrastructure.
  5. Добавить feature slices в Application по шаблону {FeatureGroup}/{Feature}/{Feature}Command.cs.
  6. Зарегистрировать repository pipeline через builder.AddRepositoryPipeline().
  7. Подключить MediatR behaviors через AddPinMediatR() в Application module.
  8. Написать integration test с PinWebApplicationFactory<{Service}WebStartup>.

Детали каждого шага — в соответствующих документах раздела.

Ссылки На Смежные Разделы​

  • Shared Package Map
  • Base Domain And Contract Models
  • Bootstrap Kernel
  • API Middleware And Filters
  • Repository Abstractions And Scope Filters
  • MediatR Pipeline Behaviors
  • Context Providers And Middlewares
  • Caching, Decorators And Resilience
  • Data Access Providers
  • Actors And Identity Building Blocks
  • Event Contracts
  • Backend Testing Rules