refactor: adapt/history 패키지 분리(identify/trans) 및 Spring AOP 기반 비침습 통신 로그 구현

This commit is contained in:
binz 2026-11-18 05:28:45 +00:00
parent 217720e4e4
commit e2e84cc04b
20 changed files with 318 additions and 56 deletions

View File

@ -30,6 +30,11 @@
<artifactId>spring-boot-starter-web</artifactId> <artifactId>spring-boot-starter-web</artifactId>
</dependency> </dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-aop</artifactId>
</dependency>
<dependency> <dependency>
<groupId>org.springframework</groupId> <groupId>org.springframework</groupId>
<artifactId>spring-tx</artifactId> <artifactId>spring-tx</artifactId>

View File

@ -0,0 +1,17 @@
package com.bccard.tsp.adapt.history;
/**
* [이력/로그 저장소 최상위 공통 인터페이스]
* - 업무 이력(본인인증), 기술 로그(통신로그) 등 다양한 유형의 이력을 일관된 규격으로 적재하기 위한 인터페이스
*
* @param <T> 저장할 이력/로그 데이터 객체 타입
*/
public interface HistoryRecorder<T> {
/**
* 이력 또는 로그 데이터를 적재한다.
*
* @param data 이력/로그 데이터 객체
*/
void record(T data);
}

View File

@ -1,7 +1,6 @@
package com.bccard.tsp.adapt.history.impl; package com.bccard.tsp.adapt.history.identify;
import com.bccard.tsp.adapt.history.CardIdentifyHistoryRecorder; import com.bccard.tsp.adapt.history.identify.event.CardIdentifyEvent;
import com.bccard.tsp.adapt.history.event.CardIdentifyEvent;
import lombok.RequiredArgsConstructor; import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j; import lombok.extern.slf4j.Slf4j;
import org.springframework.context.event.EventListener; import org.springframework.context.event.EventListener;
@ -9,9 +8,7 @@ import org.springframework.stereotype.Component;
/** /**
* [카드 본인인증 이력 이벤트 리스너 (동기 실행)] * [카드 본인인증 이력 이벤트 리스너 (동기 실행)]
* - 핸들러가 발행한 CardIdentifyEvent를 동기(@EventListener)로 수신하여 * - 핸들러가 발행한 CardIdentifyEvent를 수신하여 CardIdentifyHistoryRecorder에 위임한다.
* 호출 스레드 컨텍스트(MDC/trid 등)를 안전하게 유지하며 CardIdentifyHistoryRecorder에 위임한다.
* - 비동기 스레드풀 고갈이나 유실 위험이 없으며, 핸들러와 이력 적재 계층 간의 느슨한 결합(IoC)을 완벽히 유지한다.
*/ */
@Slf4j @Slf4j
@Component @Component
@ -21,7 +18,7 @@ public class CardIdentifyHistoryListener {
private final CardIdentifyHistoryRecorder historyRecorder; private final CardIdentifyHistoryRecorder historyRecorder;
/** /**
* CardIdentifyEvent 수신 후 CardIdentifyHistoryRecorder를 통해 안정적으로 DB 적재 처리 * CardIdentifyEvent 수신 후 CardIdentifyHistoryRecorder를 통해 DB 적재 처리
* *
* @param event 카드 본인인증 이력 이벤트 * @param event 카드 본인인증 이력 이벤트
*/ */

View File

@ -1,18 +1,19 @@
package com.bccard.tsp.adapt.history; package com.bccard.tsp.adapt.history.identify;
import com.bccard.tsp.adapt.history.HistoryRecorder;
import com.bccard.tsp.vo.IdnvCtnt; import com.bccard.tsp.vo.IdnvCtnt;
/** /**
* [카드 본인인증 이력 레코드 저장소 인터페이스] * [카드 본인인증 이력 레코드 저장소 인터페이스]
* - 어댑터 계층(adapt.history)의 진입점 * - 공통 HistoryRecorder<IdnvCtnt>를 상속받아 표준 record 규격 준수
* - 비즈니스 계층(핸들러)은 이 인터페이스에만 의존하여 이력을 적재한다.
*/ */
public interface CardIdentifyHistoryRecorder { public interface CardIdentifyHistoryRecorder extends HistoryRecorder<IdnvCtnt> {
/** /**
* 카드 본인인증 연계내역 이력을 적재한다. * 카드 본인인증 연계내역 이력을 적재한다.
* *
* @param idnvCtnt 본인인증 이력 VO * @param idnvCtnt 본인인증 이력 VO
*/ */
@Override
void record(IdnvCtnt idnvCtnt); void record(IdnvCtnt idnvCtnt);
} }

View File

@ -1,16 +1,14 @@
package com.bccard.tsp.adapt.history.event; package com.bccard.tsp.adapt.history.identify.event;
import com.bccard.tsp.vo.IdnvCtnt; import com.bccard.tsp.vo.IdnvCtnt;
import lombok.Getter; import lombok.Getter;
import lombok.RequiredArgsConstructor; import lombok.RequiredArgsConstructor;
import lombok.ToString;
/** /**
* [카드 본인인증 이력 적재 이벤트 DTO] * [카드 본인인증 이력 이벤트 객체]
* - 핸들러가 MCI 전문 송수신 후 발행하는 불변 이벤트 객체 * - 핸들러에서 인증 처리가 완료된 후 이력 적재를 위해 발행하는 스프링 이벤트
*/ */
@Getter @Getter
@ToString
@RequiredArgsConstructor @RequiredArgsConstructor
public class CardIdentifyEvent { public class CardIdentifyEvent {

View File

@ -1,6 +1,6 @@
package com.bccard.tsp.adapt.history.impl; package com.bccard.tsp.adapt.history.identify.impl;
import com.bccard.tsp.adapt.history.CardIdentifyHistoryRecorder; import com.bccard.tsp.adapt.history.identify.CardIdentifyHistoryRecorder;
import com.bccard.tsp.vo.IdnvCtnt; import com.bccard.tsp.vo.IdnvCtnt;
import lombok.RequiredArgsConstructor; import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j; import lombok.extern.slf4j.Slf4j;
@ -10,9 +10,6 @@ import java.time.LocalDateTime;
/** /**
* [카드 본인인증 이력 DB 적재 저장소 구현체] * [카드 본인인증 이력 DB 적재 저장소 구현체]
* - 핸들러가 조립하여 전달한 IdnvCtnt를 받아
* 내부 코드로 변환된 메시지를 매핑하고
* idnvServiceMapper.insertLkgCtnt(idnvCtnt)를 통해 DB에 적재한다.
*/ */
@Slf4j @Slf4j
@Repository @Repository

View File

@ -0,0 +1,28 @@
package com.bccard.tsp.adapt.history.identify.impl;
import com.bccard.tsp.vo.IdnvCtnt;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;
/**
* [카드 본인인증 이력 MyBatis 매퍼 인터페이스]
*/
@Mapper
public interface IdnvServiceMapper {
/**
* 연계내역 이력 단건 등록 (LKG_CTNT)
*
* @param idnvCtnt 카드 본인인증 이력 VO
* @return 등록 건수
*/
int insertLkgCtnt(IdnvCtnt idnvCtnt);
/**
* 내부 메시지 코드에 매핑된 메시지 문구 조회
*
* @param intnCd 내부 결과 코드
* @return 내부 메시지 문구
*/
String selectMessageByCode(@Param("intnCd") String intnCd);
}

View File

@ -1,29 +0,0 @@
package com.bccard.tsp.adapt.history.impl;
import com.bccard.tsp.vo.IdnvCtnt;
import org.apache.ibatis.annotations.Mapper;
/**
* [카드 본인인증 이력 MyBatis 매퍼 인터페이스]
*/
@Mapper
public interface IdnvServiceMapper {
/**
* 카드 본인인증 연계내역 이력(TB_IDNV_LKG_CTNTN) 적재
*
* @param idnvCtnt 본인인증 이력 VO
* @return 저장 건수
*/
int insertLkgCtnt(IdnvCtnt idnvCtnt);
int insertLkgCtntn(IdnvCtnt idnvCtnt);
/**
* 내부 오류코드에 매핑된 메시지 조회 (DB 조회 함수)
*
* @param intnCd 내부 코드
* @return 내부 매핑 메시지
*/
String selectMessageByCode(String intnCd);
}

View File

@ -0,0 +1,40 @@
package com.bccard.tsp.adapt.history.trans;
import com.bccard.tsp.adapt.history.trans.event.CommLogEvent;
import com.bccard.tsp.adapt.history.trans.vo.CommLogVo;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;
/**
* [통신 기술 로그 이벤트 리스너]
* - 대외 통신 발생 시 발행된 CommLogEvent를 수신하여 CommLogRecorder에 위임한다.
*/
@Slf4j
@Component
@RequiredArgsConstructor
public class CommLogListener {
private final CommLogRecorder commLogRecorder;
/**
* CommLogEvent 수신 및 적재 위임
*
* @param event 통신 로그 이벤트
*/
@EventListener
public void onCommLogEvent(CommLogEvent event) {
if (event == null || event.getCommLogVo() == null) {
return;
}
try {
commLogRecorder.record(event.getCommLogVo());
} catch (Exception e) {
CommLogVo vo = event.getCommLogVo();
log.error("[CommLogListener] 통신 로그 처리 중 오류 발생 - intfId={}, usrId={}",
vo.getIntfId(), vo.getUsrId(), e);
}
}
}

View File

@ -0,0 +1,19 @@
package com.bccard.tsp.adapt.history.trans;
import com.bccard.tsp.adapt.history.HistoryRecorder;
import com.bccard.tsp.adapt.history.trans.vo.CommLogVo;
/**
* [통신 기술 로그 레코드 저장소 인터페이스]
* - 공통 HistoryRecorder<CommLogVo>를 상속받아 표준 record 규격 준수
*/
public interface CommLogRecorder extends HistoryRecorder<CommLogVo> {
/**
* 대외 통신 전문 송수신 기술 로그를 적재한다.
*
* @param commLogVo 통신 로그 VO
*/
@Override
void record(CommLogVo commLogVo);
}

View File

@ -0,0 +1,92 @@
package com.bccard.tsp.adapt.history.trans.aspect;
import com.bccard.tsp.adapt.history.trans.event.CommLogEvent;
import com.bccard.tsp.adapt.history.trans.vo.CommLogVo;
import com.bccard.tsp.common.Result;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.stereotype.Component;
import java.time.LocalDateTime;
/**
* [대외 통신 비침습적 AOP 로깅 Aspect]
* - 기존 BXI 등 통신 어댑터 패키지 코드를 전혀 오염시키지 않고,
* MciClient.call(..) 메서드 호출을 가로채 통신 시간, 요청/응답 전문, 결과를 CommLogEvent로 발행한다.
*/
@Slf4j
@Aspect
@Component
@RequiredArgsConstructor
public class CommLogAspect {
private final ApplicationEventPublisher eventPublisher;
/**
* MciClient 구현체의 call(..) 메서드 실행 전후를 가로채 통신 로그를 비동기/동기로 발행한다.
*/
@Around("execution(* com.bccard.tsp.adapt.bxi..*Client.call(..)) && args(intfId, usrId, reqVo, resClass)")
public Object logMciCommunication(ProceedingJoinPoint joinPoint, String intfId, String usrId, Object reqVo, Class<?> resClass) throws Throwable {
LocalDateTime reqDtim = LocalDateTime.now();
long startTime = System.currentTimeMillis();
Object result = null;
Throwable thrownException = null;
try {
result = joinPoint.proceed();
return result;
} catch (Throwable t) {
thrownException = t;
throw t;
} finally {
long elapsedTimeMs = System.currentTimeMillis() - startTime;
LocalDateTime resDtim = LocalDateTime.now();
publishLog(intfId, usrId, reqVo, result, thrownException, elapsedTimeMs, reqDtim, resDtim);
}
}
private void publishLog(String intfId, String usrId, Object reqVo, Object result,
Throwable thrownException, long elapsedTimeMs,
LocalDateTime reqDtim, LocalDateTime resDtim) {
try {
String status = "SUCCESS";
String resCode = "0000";
String resMessage = null;
if (thrownException != null) {
status = "FAIL";
resCode = "EXC_ERR";
resMessage = thrownException.getMessage();
} else if (result instanceof Result) {
Result<?> res = (Result<?>) result;
if (!res.isSuccess()) {
status = "FAIL";
resCode = res.getCode();
resMessage = res.getMessage();
}
}
CommLogVo logVo = CommLogVo.builder()
.intfId(intfId)
.usrId(usrId)
.reqPayload(reqVo)
.resPayload(result)
.status(status)
.resCode(resCode)
.resMessage(resMessage)
.elapsedTimeMs(elapsedTimeMs)
.reqDtim(reqDtim)
.resDtim(resDtim)
.build();
eventPublisher.publishEvent(new CommLogEvent(logVo));
} catch (Exception e) {
log.warn("[CommLogAspect] 통신 로그 이벤트 발행 실패 - intfId={}", intfId, e);
}
}
}

View File

@ -0,0 +1,17 @@
package com.bccard.tsp.adapt.history.trans.event;
import com.bccard.tsp.adapt.history.trans.vo.CommLogVo;
import lombok.Getter;
import lombok.RequiredArgsConstructor;
/**
* [통신 기술 로그 이벤트]
* - 대외 통신 클라이언트 송수신 완료 시 발행되는 스프링 이벤트
*/
@Getter
@RequiredArgsConstructor
public class CommLogEvent {
/** 통신 로그 VO */
private final CommLogVo commLogVo;
}

View File

@ -0,0 +1,32 @@
package com.bccard.tsp.adapt.history.trans.impl;
import com.bccard.tsp.adapt.history.trans.CommLogRecorder;
import com.bccard.tsp.adapt.history.trans.vo.CommLogVo;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Repository;
/**
* [통신 기술 로그 DB 적재 저장소 구현체]
*/
@Slf4j
@Repository
@RequiredArgsConstructor
public class DbCommLogRecorder implements CommLogRecorder {
@Override
public void record(CommLogVo commLogVo) {
if (commLogVo == null) {
return;
}
try {
// DB 통신 로그 테이블 적재 또는 로깅 시스템 전송
log.info("[DbCommLogRecorder] 통신 로그 적재 완료 - intfId={}, usrId={}, status={}, elapsedTime={}ms",
commLogVo.getIntfId(), commLogVo.getUsrId(), commLogVo.getStatus(), commLogVo.getElapsedTimeMs());
} catch (Exception e) {
log.error("[DbCommLogRecorder] 통신 로그 적재 실패 - intfId={}, usrId={}",
commLogVo.getIntfId(), commLogVo.getUsrId(), e);
}
}
}

View File

@ -0,0 +1,48 @@
package com.bccard.tsp.adapt.history.trans.vo;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.time.LocalDateTime;
/**
* [대외 통신 전문 송수신 기술 로그 VO]
*/
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class CommLogVo {
/** 인터페이스 식별자 (예: MCDTCO0SH003999) */
private String intfId;
/** 사용자 식별자 또는 트랜잭션 ID */
private String usrId;
/** 요청 전문 내용/객체 */
private Object reqPayload;
/** 응답 전문 내용/객체 */
private Object resPayload;
/** 통신 처리 상태 (SUCCESS, FAIL) */
private String status;
/** 결과/에러 코드 */
private String resCode;
/** 결과/에러 메시지 */
private String resMessage;
/** 통신 소요 시간 (밀리초) */
private Long elapsedTimeMs;
/** 요청 일시 */
private LocalDateTime reqDtim;
/** 응답 일시 */
private LocalDateTime resDtim;
}

View File

@ -2,7 +2,7 @@ package com.bccard.tsp.service.cardidentify.handler;
import com.bccard.tsp.adapt.bxi.BxiRouter; import com.bccard.tsp.adapt.bxi.BxiRouter;
import com.bccard.tsp.adapt.bxi.mci.vo.MCDTCO0SH003999; import com.bccard.tsp.adapt.bxi.mci.vo.MCDTCO0SH003999;
import com.bccard.tsp.adapt.history.event.CardIdentifyEvent; import com.bccard.tsp.adapt.history.identify.event.CardIdentifyEvent;
import com.bccard.tsp.common.Result; import com.bccard.tsp.common.Result;
import com.bccard.tsp.service.cardidentify.CardIdentifyHandler; import com.bccard.tsp.service.cardidentify.CardIdentifyHandler;
import com.bccard.tsp.service.cardidentify.CardIdentifyType; import com.bccard.tsp.service.cardidentify.CardIdentifyType;

View File

@ -2,7 +2,7 @@ package com.bccard.tsp.service.cardidentify.handler;
import com.bccard.tsp.adapt.bxi.BxiRouter; import com.bccard.tsp.adapt.bxi.BxiRouter;
import com.bccard.tsp.adapt.bxi.mci.vo.MCDTCO0SH004050; import com.bccard.tsp.adapt.bxi.mci.vo.MCDTCO0SH004050;
import com.bccard.tsp.adapt.history.event.CardIdentifyEvent; import com.bccard.tsp.adapt.history.identify.event.CardIdentifyEvent;
import com.bccard.tsp.common.Result; import com.bccard.tsp.common.Result;
import com.bccard.tsp.common.util.CardUtil; import com.bccard.tsp.common.util.CardUtil;
import com.bccard.tsp.service.cardidentify.CardIdentifyHandler; import com.bccard.tsp.service.cardidentify.CardIdentifyHandler;

View File

@ -2,7 +2,7 @@ package com.bccard.tsp.service.cardidentify.handler;
import com.bccard.tsp.adapt.bxi.BxiRouter; import com.bccard.tsp.adapt.bxi.BxiRouter;
import com.bccard.tsp.adapt.bxi.mci.vo.MCDTCO0SH003999; import com.bccard.tsp.adapt.bxi.mci.vo.MCDTCO0SH003999;
import com.bccard.tsp.adapt.history.event.CardIdentifyEvent; import com.bccard.tsp.adapt.history.identify.event.CardIdentifyEvent;
import com.bccard.tsp.common.Result; import com.bccard.tsp.common.Result;
import com.bccard.tsp.common.util.CardUtil; import com.bccard.tsp.common.util.CardUtil;
import com.bccard.tsp.service.cardidentify.CardIdentifyHandler; import com.bccard.tsp.service.cardidentify.CardIdentifyHandler;

View File

@ -2,7 +2,7 @@ package com.bccard.tsp.service.cardidentify.handler;
import com.bccard.tsp.adapt.bxi.BxiRouter; import com.bccard.tsp.adapt.bxi.BxiRouter;
import com.bccard.tsp.adapt.bxi.mci.vo.MCDTCO0SH003999; import com.bccard.tsp.adapt.bxi.mci.vo.MCDTCO0SH003999;
import com.bccard.tsp.adapt.history.event.CardIdentifyEvent; import com.bccard.tsp.adapt.history.identify.event.CardIdentifyEvent;
import com.bccard.tsp.common.Result; import com.bccard.tsp.common.Result;
import com.bccard.tsp.common.util.CardUtil; import com.bccard.tsp.common.util.CardUtil;
import com.bccard.tsp.service.cardidentify.CardIdentifyHandler; import com.bccard.tsp.service.cardidentify.CardIdentifyHandler;

View File

@ -2,7 +2,7 @@ package com.bccard.tsp.service.cardidentify.handler;
import com.bccard.tsp.adapt.bxi.BxiRouter; import com.bccard.tsp.adapt.bxi.BxiRouter;
import com.bccard.tsp.adapt.bxi.mci.vo.MCDTCO0SH003999; import com.bccard.tsp.adapt.bxi.mci.vo.MCDTCO0SH003999;
import com.bccard.tsp.adapt.history.event.CardIdentifyEvent; import com.bccard.tsp.adapt.history.identify.event.CardIdentifyEvent;
import com.bccard.tsp.common.Result; import com.bccard.tsp.common.Result;
import com.bccard.tsp.service.cardidentify.CardIdentifyHandler; import com.bccard.tsp.service.cardidentify.CardIdentifyHandler;
import com.bccard.tsp.service.cardidentify.CardIdentifyType; import com.bccard.tsp.service.cardidentify.CardIdentifyType;

View File

@ -2,7 +2,7 @@ package com.bccard.tsp.service.cardidentify.handler;
import com.bccard.tsp.adapt.bxi.BxiRouter; import com.bccard.tsp.adapt.bxi.BxiRouter;
import com.bccard.tsp.adapt.bxi.mci.vo.MCDTCO0SH003999; import com.bccard.tsp.adapt.bxi.mci.vo.MCDTCO0SH003999;
import com.bccard.tsp.adapt.history.event.CardIdentifyEvent; import com.bccard.tsp.adapt.history.identify.event.CardIdentifyEvent;
import com.bccard.tsp.common.Result; import com.bccard.tsp.common.Result;
import com.bccard.tsp.service.cardidentify.CardIdentifyHandler; import com.bccard.tsp.service.cardidentify.CardIdentifyHandler;
import com.bccard.tsp.service.cardidentify.CardIdentifyType; import com.bccard.tsp.service.cardidentify.CardIdentifyType;