transact
transact는 클라이언트의 업무 거래 요청을 수신하고, 거래 계약의 CommandType에 따라 실행 모듈로 라우팅한 뒤 표준 응답을 반환하는 중심 모듈입니다. HandStack에서 화면, API, 배치, workflow가 공통 거래 모델로 만나는 지점입니다.
책임 범위
- 거래 계약을 로드하고
ApplicationID|ProjectID|TransactionID|ServiceID기준으로 실행 대상을 찾습니다. RoutingCommandUri를 사용해dbclient,graphclient,function,command,prompter로 요청을 전달합니다.- 요청 검증, 공개 거래 허용 범위, 환경 구분, 코드 데이터 캐시를 적용합니다.
- 거래 로그와 집계 데이터를 저장하고 필요 시
logger모듈로 전송합니다. - workflow 계약을 실행하고 단계 간 입력/출력 매핑, assertion, fallback 흐름을 처리합니다.
주요 API
| 메서드 | 경로 | 용도 |
|---|---|---|
GET | /transact/api/transaction/has | 거래 계약 존재 여부를 확인합니다. |
GET | /transact/api/transaction/refresh | 거래 계약 캐시를 갱신합니다. |
GET | /transact/api/transaction/retrieve | 거래 계약 원문 또는 상세 정보를 조회합니다. |
GET | /transact/api/transaction/meta | 입력/출력 메타 정보를 반환합니다. |
POST | /transact/api/transaction/execute | 단일 거래를 실행합니다. |
POST | /transact/api/workflow/execute | workflow 거래를 실행합니다. |
GET | /transact/api/transaction/cache-clear | 코드 데이터 캐시를 초기화합니다. |
GET | /transact/api/aggregate/summary | 거래 집계 요약을 조회합니다. |
핵심 구현
Areas/transact/Controllers/TransactionController.cs: 단일 거래 API 진입점입니다.Areas/transact/Controllers/WorkflowController.cs: workflow 실행 진입점입니다.Areas/transact/Controllers/AggregateController.cs: 거래 집계 조회와 moved 상태 관리를 담당합니다.Extensions/TransactClient.cs: 라우팅, 요청 검증, 실행 결과 검증의 핵심 구현입니다.Events/TransactRequestHandler.cs: 모듈 내부 거래 실행 요청을 처리합니다.
계약과 식별자
계약은 기본적으로 다음 위치에 둡니다.
contracts/transact/{ApplicationID}/{ProjectID}/{TransactionID}.xml
거래 ID는 다음 형식입니다.
ApplicationID|ProjectID|TransactionID|ServiceID
거래 계약에는 CommandType, ReturnType, TransactionScope, 입력/출력 모델, 캐시와 검증 정보가 포 함됩니다.
CommandType 라우팅
현재 기본 라우팅 대상은 다음과 같습니다.
| CommandType | 실행 모듈 | 기본 URL |
|---|---|---|
D | dbclient | /dbclient/api/query |
G | graphclient | /graphclient/api/query |
F | function | /function/api/execution |
C | command | /command/api/execution |
P | prompter | /prompter/api/query |
RoutingCommandUri의 key는 다음 형식입니다.
ApplicationID|ProjectID|CommandType|Environment
라우팅 예시는 다음과 같습니다.
{
"HDS|*|D|D": "http://localhost:8421/dbclient/api/query",
"HDS|*|G|D": "http://localhost:8421/graphclient/api/query",
"HDS|*|F|D": "http://localhost:8421/function/api/execution",
"HDS|*|C|D": "http://localhost:8421/command/api/execution",
"HDS|*|P|D": "http://localhost:8421/prompter/api/query"
}
주요 설정
| 설정 | 설명 |
|---|---|
AllowRequestTransactions | 애플리케이션별 요청 허용 프로젝트 범위입니다. |
PublicTransactions | 인증 없이 공개할 거래 범위입니다. |
AvailableEnvironment | 허용할 실행 환경 구분입니다. |
RoutingCommandUri | CommandType과 환경별 실행 모듈 URL입니다. |
IsValidationRequest | 분산 캐시 기반 요청 검증 사용 여부입니다. |
UseApiAuthorize | API 인증 토큰 검사 사용 여부입니다. |
IsCodeDataCache, CodeDataCacheTimeout | 코드/기초 데이터 캐시 설정입니다. |
IsTransactAggregate, IsTransactAggregateRolling | 거래 집계 저장과 롤링 방식입니다. |
DynamicWorkflowTransaction, DynamicWorkflowServices | 동적 workflow 실행 허용 거래와 서비스 범위입니다. |
Workflow 실행
workflow는 여러 거래 단계를 하나의 요청으로 묶습니다. 각 단계의 CommandType이 D, G, F, C, P이면 기존 RoutingCommandUri 규칙으로 실행 모듈에 전달됩니다.
개발자가 확인해야 할 핵심 규칙은 다음과 같습니다.
transaction.dataFormat이 비어 있으면J로 처리하며,J와T만 허용합니다.environment는AvailableEnvironment에 포함되어야 합니다.AllowRequestTransactions,PublicTransactions,AccessScreenID규칙을 통과해야 합니다.X-Workflow-Contract로 일회성 workflow를 보낼 때는 BearerToken과DynamicWorkflowclaim, 서버 설정의 동적 workflow 허용 범위를 모두 만족해야 합니다.InputMappings,OutputMappings,Assertions는 단계 간 데이터 전달과 검증 실패 처리를 결정합니다.
운영 주의사항
transact는 모든 업무 요청의 관문이므로 인증, 공개 거래, 라우팅 범위를 가장 먼저 점검합니다.RoutingCommandUri가 누락되면 해당CommandType거래는 실행 모듈을 찾지 못합니다.- 거래 로그에는 요청/응답 데이터가 포함될 수 있으므로
IsDataMasking과 로그 보관 정책을 함께 설계합니다. - workflow는 강력하지만 장애 범위도 넓어집 니다. 단계별 timeout, fallback, assertion을 계약에 명시합니다.