Service Bootstrap Standard

Назначение

Документ задает единый способ собирать backend service: Program.cs, dependency injection, middleware pipeline, health checks, OpenAPI, observability и background processes.

Правило Композиции Через Kernel

Program.cs не содержит бизнес-логики и длинной wiring-логики. Он запускает service через Bootstrap Kernel:

return await PinHost
    .CreateWeb(args)
    .UseStartup<AccountingWebStartup>()
    .Run();

Для migrator и background processes используются BaseMigratorStartup и BaseBackgroundStartup:

return await PinHost
    .CreateMigrator(args)
    .UseStartup<AccountingMigratorStartup>()
    .Run();

return await PinHost
    .CreateWorker(args)
    .UseStartup<AccountingBackgroundStartup>()
    .Run();

Service-specific startup class описывает capabilities, modules и extension points, а общий порядок host/pipeline задает kernel.

DI Extension Names

Слой	Extension	Содержит
Application	Add<Service>Application	MediatR handlers, validators, Mapster mappings, policies, application services.
Infrastructure	Add<Service>Infrastructure	DbContext, repositories, Redis, Elasticsearch, ClickHouse, provider adapters, options.
Api	Add<Service>Api	MVC, auth schemes, filters, API model mapping, OpenAPI.
Background	Add<Service>Background	consumers, schedulers, hosted services.
Observability	Add<Service>Observability	Serilog enrichers, OTEL tracing/metrics, Sentry.

Shared packages предоставляют reusable extensions: AddPinMediatR, AddPinRepositoryPipeline, AddPinIdentityContext, AddPinHealthChecks.

Bootstrap package предоставляет base classes: BaseWebStartup, BaseGatewayStartup, BaseBackgroundStartup, BaseMigratorStartup.

Middleware Order

Порядок middleware/filter pipeline фиксируется в API Middleware And Filters Standard. Коротко:

1. forwarded headers;
2. correlation/request id;
3. request context;
4. exception/problem response middleware;
5. request logging and RED metrics;
6. tenant/brand resolution;
7. routing/authentication;
8. actor/context middleware;
9. authorization;
10. idempotency/rate limit, если применимо;
11. controllers/endpoints.

Context propagation описан в Execution Context Propagation.

Startup Validation

Сервис не должен стартовать, если:

• невалидны required options;
• нет обязательных connection strings/secret references;
• не зарегистрированы required MediatR handlers;
• отсутствуют required health checks;
• нарушены architecture tests для слоев.

Service Skeleton Checklist

• solution и projects созданы по стандарту Pin.<Service>.<Layer>;
• Program.cs использует PinHost и service-specific startup class;
• включены nullable reference types и warnings policy;
• подключены shared Result/Error, Audit, Idempotency, Context Providers, API middleware/filters;
• API endpoints описаны в документации до реализации;
• migrations лежат в owning service;
• MassTransit outbox/inbox включен для mutation service;
• K8s health endpoints /health/live и /health/ready включены;
• Docker compose и .env.example существуют для локальной разработки.

Запреты

• Не регистрировать provider credentials в Application или Domain.
• Не делать service locator поверх IServiceProvider в handlers.
• Не создавать ad-hoc middleware для tenant/user scope, если есть shared provider.
• Не смешивать API model binding, business decision и persistence в одном extension method.

Обратные ссылки

Автоссылки: где используется этот документ.

• adr (1): ADR-0049: Configuration, Secrets И Options Pattern
• backend-shared-standards-index.md (1): Backend Shared Standards Index