내부 및 외부 통합

통합 만들기

통합은 다른 컨텍스트, 내부 서비스 또는 외부 시스템과의 명시적인 통신을 나타냅니다. 이름, 계약, 인증, timeout, 오류 전략, 명확한 책임을 가져야 합니다.

lino integration new --name <ServiceName>
lino integration list

새 통합을 만들기 전에 integration list로 기존 통합을 확인하세요. CommonIntegration 같은 일반적인 통합은 명확한 경계 없이 책임을 축적하기 쉬우므로 피합니다.

통합을 만들기 전에 외부 레지스트리 조회, 청구 전송, 구독 검증, 사용자 동기화, 내부 모듈 소비, 다른 시스템으로 데이터 게시 등 어떤 문제를 해결하는지 정의하세요. 통합에 구체적인 의도가 없다면 아직 생성된 계약이 될 준비가 되지 않았을 가능성이 큽니다.

• 통합되는 컨텍스트로 이름 지정: 일반 이름보다 Billing, Identity, Catalog, Shipping을 선호합니다.
• 계약과 구현 분리: 도메인과 애플리케이션은 transport 세부 사항에 직접 의존해서는 안 됩니다.
• 외부 실패를 가정: 모든 원격 통합은 느려지거나, 사용할 수 없거나, 부분 오류를 반환하거나, 계약이 변경될 수 있습니다.

통합 resources

resources는 통합이 노출하거나 소비하는 객체를 나타냅니다. 예를 들면 customers, invoices, tenants, subscriptions, users, documents가 있습니다.

lino integration resource new --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino integration resource list --service <ServiceName> --module <ModuleName> --entity <EntityName>

통합 resource는 도메인 엔터티와 같을 필요가 없습니다. 흔히 데이터 교환 계약, 외부 뷰, 또는 컨텍스트 간 통신에 필요한 최소 표현입니다. 전체 엔터티를 외부 계약으로 복사하면 내부 세부 사항이 노출되고 진화 비용이 증가하는 경우가 많습니다.

• 통합된 시스템의 어휘로 resource를 모델링합니다.
• 내부 엔터티를 외부 계약으로 노출하지 않습니다.
• 어떤 필드가 식별자, 필터, 반환 데이터인지 정의합니다.
• 존재하는 경우 페이지네이션, 인증, 호출 제한을 문서화합니다.

resource가 다른 모듈의 데이터를 나타내는 경우 소비자에게 필요한 것만 포함합니다. 같은 원칙은 shadow entities에도 나타납니다. 소비 모듈은 생산자 모듈의 전체 모델에 의존하는 대신, 자신의 Use Case에 맞는 작은 로컬 복사본을 유지합니다.

통합 작업

작업은 통합 resource에서 사용할 수 있는 동작을 설명합니다. 생성, 조회, 업데이트, 취소, 전송, 동기화, 검증 등이 있습니다.

lino integration operation new --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino integration operation list --service <ServiceName> --module <ModuleName> --entity <EntityName>

각 작업은 의도, 입력, 출력, 호출 방식, 오류 동작, 안전하게 재실행할 수 있는지 여부를 정의해야 합니다.

• 조회에는 timeout과 사용 불가 상태에 대한 처리가 있어야 합니다.
• 원격 명령은 가능하면 멱등적이어야 합니다.
• 비즈니스가 비동기 처리를 허용한다면 외부 실패가 주 트랜잭션을 깨뜨려서는 안 됩니다.
• 시스템 간 호출을 추적하려면 로그와 correlation id를 사용합니다.

멱등성은 쓰기 작업에서 특히 중요합니다. 외부 시스템이 동작을 실행한 후 시도가 실패하면 재시도로 인해 청구가 중복되거나, 레코드가 반복 생성되거나, 메시지가 두 번 전송될 수 있습니다. 가능하면 멱등성 키, 외부 식별자 또는 문서화된 재실행 규칙을 사용하세요.

통합 소비

통합, resource, 작업을 모델링한 후 소비를 사용하여 애플리케이션을 생성된 계약에 연결합니다. 목표는 HTTP 호출, URL 조립, headers, 응답 parsing, 오류 처리를 여러 handlers에 흩뿌리는 대신, Use Case가 예측 가능한 입력과 출력을 가진 이름 있는 추상화에 의존하도록 만드는 것입니다.

lino integration consume

Use Cases는 코드 곳곳에 흩어진 HTTP 세부 사항이 아니라 추상화에 의존해야 합니다. 이렇게 하면 테스트, 구현 교체, 일관된 실패 처리가 쉬워집니다. 또한 애플리케이션의 각 endpoint가 timeout, 인증, correlation id, 직렬화, 오류 매핑을 서로 다르게 다시 만드는 일을 방지합니다.

• 외부 서비스를 호출하기 전에 데이터를 검증합니다.
• cancellation token과 timeout을 사용합니다.
• 외부 응답을 예측 가능한 내부 오류로 매핑합니다.
• 변환 없이 원시 외부 payload를 도메인 규칙으로 저장하지 않습니다.

HTTP vs. in-process

모듈이 함께 실행될 때 in-process 통합은 단순하고 빠릅니다. HTTP는 프로세스 간 계약을 더 명시적으로 만들지만, 지연 시간, 네트워크 실패, 회복 탄력성의 필요를 추가합니다.

in-process 통합이 모든 것에 대한 자유로운 접근을 의미해서는 안 됩니다. 같은 runtime 안에서도 소비자는 내부 엔터티, DbContext 또는 다른 모듈의 repository가 아니라 계약을 통해 통신해야 합니다. 네트워크 비용은 낮지만 결합 위험은 여전히 존재합니다.

HTTP는 생산자와 소비자가 별도의 runtimes를 갖거나 경계를 운영상 명시적으로 만들고 싶을 때 더 적합합니다. In-process는 같은 애플리케이션이 컨텍스트를 호스팅하고 응답이 즉시 필요할 때 적합하지만, 의존성은 계속 계약으로 선언되어야 합니다.

이벤트 vs. 동기 통합

현재 작업을 완료하는 데 응답이 필요하면 동기 통합을 사용합니다. 소비자가 나중에 반응할 수 있고 eventual consistency가 허용된다면 이벤트를 사용합니다.

이 선택은 기술적 결정이기 전에 비즈니스 결정입니다. 결제 서비스가 승인을 확인한 후에만 주문을 만들 수 있다면 동기 호출은 Use Case의 핵심 부분일 수 있습니다. 주문 생성이 알림, 프로젝션 업데이트 또는 다른 모듈로의 동기화를 트리거하기만 하면 된다면 이벤트가 더 적합한 경우가 많습니다.