Общие TypeScript-контракты между Angular и NestJS

Angular и NestJS используют TypeScript, но это не делает internal models безопасным shared contract. Types исчезают в runtime, HTTP сериализует values, deployments происходят в разное время, а старый browser build может вызывать новый API. Надёжный contract определяет wire shape, semantics, validation и compatibility независимо от implementation.

Практические варианты — малый shared package, generation из OpenAPI или schema-first source для runtime validators и static types. GARNO.TECH объединяет разработку Angular и разработку NestJS, выбирая strategy по repository ownership, release cadence, consumers и governance.

Разделяйте wire contract, а не implementation

Никогда не экспортируйте ORM entities в browser. Entities содержат persistence columns, relations, lazy-loading behavior, audit fields и sensitive properties, изменения которых не должны становиться API changes. Backend decorators могут также затянуть server-only dependencies во frontend build. Преобразуйте domain objects в явные request и response contracts на transport boundary.

Определите required, optional и nullable fields, dates, timezones, money, identifiers, enum evolution, pagination и errors. Angular HttpClient generic является compile-time assertion, а не runtime validation. NestJS должен валидировать input, а consumers — responses там, где этого требует trust или independent change.

Используйте shared package в контролируемом monorepo

Shared package эффективен в monorepo или при контролируемом publishing. Оставляйте его dependency-light и transport-only: primitive aliases, stable enum values, request/response shapes и framework-neutral schemas. Исключите NestJS decorators, ORM models, repositories, domain services и frontend state.

Версионируйте package как external dependency, тестируйте serialization examples и запрещайте deep imports. Одновременное изменение package и двух apps доказывает лишь совместимость newest versions. Тестируйте old consumer с new server и new consumer с каждым supported old server.

Генерируйте clients из OpenAPI между repositories

OpenAPI является более сильной boundary для нескольких consumers, отдельных repositories, других языков или independent teams. NestJS генерирует document из controllers и DTO, но reflection не видит каждый interface, generic или union. Используйте decorators, extra models или Swagger CLI plugin и проверяйте artifact.

Публикуйте versioned specification, lint-ите её, обнаруживайте breaking changes и repeatably генерируйте Angular client. Не редактируйте generated files. Скройте transport за малым Angular service. Проверяйте errors, authentication, content types, nullability и pagination.

Выбирайте schema-first, когда ведёт runtime validation

Schema-first определяет executable schemas и выводит types. Он подходит для runtime validation на обеих сторонах, event payloads или framework-neutral governance. Убедитесь, что conversion не теряет OpenAPI и validation features. Schema не реализует authorization, cross-field domain rules или database invariants.

Не поддерживайте один payload в нескольких независимых definitions. Выберите одно source of truth, генерируйте secondary artifacts, фиксируйте tool versions и тестируйте valid и invalid examples на каждой boundary. Generated types уменьшают transcription errors, но не доказывают semantic compatibility.

Версионируйте contracts через compatibility rules

Предпочитайте additive changes. Добавление required request field, удаление или переименование field, изменение meaning или nullability, narrowing input или повторное использование enum value является breaking. Enum additions тоже ломают exhaustive clients, поэтому определите unknown-value behavior.

Применяйте expand-and-contract: server принимает old и new forms, consumers мигрируют с telemetry, затем old form удаляется после support window. Semantic versions нужны packages, HTTP versions — только genuine breaks. Contract tests и production usage делают removal доказательным.

Чек-лист contract strategy

• Выберите shared package, OpenAPI или schema-first по repositories, consumers, runtime validation и releases.
• Не включайте entities, domain behavior, framework decorators и frontend state в wire contract.
• Явно определите dates, money, identifiers, nullability, enums, pagination, errors и unknown fields.
• Генерируйте artifacts детерминированно и проверяйте drift и breaking changes в CI.
• Тестируйте old/new consumer-server combinations и удаляйте deprecated shapes по usage evidence.