API 서비스 - 헥사고날 아키텍처 전환 및 질의입력 엔드포인트 구현

[VitoJeong]

개요

헥사고날 아키텍처 전환 및 질의입력 및 SSE 릴레이를 구현했습니다.

구현 항목

작업내용 문서는 on-seoul-api/docs/api-service-implementation.md를 참고해주세요

헥사고날 아키텍처 전환

• common / domain / application / adapter / bootstrap / collector 모듈 구성으로 전환
• 의존 방향 단방향 강제: adapter → application → domain
• ArchUnit 테스트로 모듈별 잘못된 의존성 포함되는지 검증

질의입력 엔드포인트 및 SSE 릴레이 구현

• POST /query → AI 서비스 /chat/stream WebClient 호출 → SseEmitter 릴레이
• 스트림 완료 후 ChatRoom / ChatMessage(USER·ASSISTANT) 이력 저장

[f-lab-ted]

헥사고날 전환의 핵심을 중점적으로 리뷰:

• 모듈 분리: common → domain → application → adapter 의존 방향 단방향 강제, bootstrap/collector를 별도 부트스트랩으로 분리
• 포트/어댑터 구현: domain.port.in(유스케이스 인터페이스), domain.port.out(외부 의존 인터페이스), adapter(구현체) 분리
• ArchUnit 검증: domain의 프레임워크 의존 금지, application→adapter 의존 금지 룰 설정
• SSE 릴레이 흐름: ChatController → AiServiceAdapter(WebClient Flux) → SseEmitter 릴레이 → SendQueryService로 이력 저장

잘한 점

헥사고날 아키텍처 전환이 교과서적으로 잘 구현되었습니다. domain 모듈의 순수 POJO 유지, ArchUnit을 활용한 의존성 경계 자동 검증, bootstrap/collector 부트스트랩 분리를 통한 Web API와 배치의 독립 기동 등 설계 의도가 명확하고 일관성이 있습니다. SendQueryServiceTest의 테스트 커버리지도 양호합니다.

보완할 점

1. ChatController의 아키텍처 위반: Controller가 AiServicePort(어댑터 계층 인터페이스)를 직접 의존하고 있어, SSE 릴레이 로직이 컨트롤러에 누출되었습니다. 이는 헥사고날 아키텍처의 핵심 원칙인 "adapter→application→domain" 단방향 의존을 위반합니다.
2. SSE 스트림의 saveAnswer() 호출이 트랜잭션 밖에서 실패할 경우: Reactive 콜백 내에서 예외 발생 시 사용자 메시지는 저장되었지만 ASSISTANT 응답이 유실될 수 있습니다.
3. SessionCreationPolicy.IF_REQUIRED: JWT 기반 stateless 인증을 사용하면서 세션 생성 정책이 IF_REQUIRED로 설정되어 있어 불필요한 HttpSession이 생성될 수 있습니다.

결론

Request Changes

• ChatController가 adapter 계층의 AiServicePort를 직접 의존하는 구조적 문제와 SSE 콜백에서의 saveAnswer() 에러 처리 미비는 반드시 수정 바람.
• 나머지 리뷰 코멘트에 대해서는 검토 후 반영 여부 결정.

[f-lab-ted]

[Critical] 헥사고날 아키텍처 위반: Controller가 adapter 계층의 AiServicePort를 직접 의존

ChatController(inbound adapter)가 AiServicePort(outbound adapter 패키지에 위치한 인터페이스)를 직접 import하고 있습니다. 이는 이 PR의 핵심 설계 원칙인 adapter → application → domain 단방향 의존을 위반합니다.

현재 구조:

ChatController (adapter.in) → AiServicePort (adapter.out) ← 위반
ChatController (adapter.in) → SendQueryUseCase (domain.port.in) ← 정상

SSE 스트리밍 + 토큰 릴레이 + 이력 저장이라는 오케스트레이션 로직이 컨트롤러에 누출되었습니다. 해결 방안:

1. AiServicePort를 domain.port.out으로 이동하여 도메인 포트로 승격시키거나,
2. SSE 릴레이 로직 전체를 application 서비스로 이동하여 컨트롤러는 유스케이스 호출만 담당하도록 변경

예를 들어 SendQueryUseCase에 Flux<String> streamAndSave(SendQueryCommand) 같은 메서드를 두고, application 서비스가 AI 호출 + 이력 저장을 모두 오케스트레이션하면 컨트롤러는 SseEmitter 변환만 담당하게 됩니다.

[VitoJeong]

넵 반영후 ArchTest 통해 확인했습니다!
static final ArchRule inbound_adapter_must_not_depend_on_outbound_adapter

[f-lab-ted]

[Critical] SSE 완료 콜백에서 saveAnswer() 실패 시 에러 처리 부재

onComplete 콜백 내의 saveAnswer()에서 예외가 발생하면(DB 장애, 트랜잭션 실패 등):

1. emitter.complete()가 호출되지 않아 클라이언트가 120초 타임아웃까지 대기
2. 사용자 메시지(USER)는 prepare()에서 이미 커밋되었지만, AI 응답(ASSISTANT)은 유실됨
3. 예외가 어디에도 로깅되지 않아 장애 추적 불가

() -> {
    try {
        sendQueryUseCase.saveAnswer(roomId, answer.toString());
    } catch (Exception e) {
        log.error("ASSISTANT 응답 저장 실패: roomId={}", roomId, e);
    } finally {
        emitter.complete();
    }
}

최소한 위처럼 try-catch-finally로 감싸서 emitter.complete()는 항상 호출되도록 하고, 실패 시 로깅을 추가해야 합니다.

[VitoJeong]

반영했습니다.

[f-lab-ted]

[Major] Reactive subscribe()를 Servlet 스레드에서 사용 시 Thread-Safety 문제

StringBuilder answer가 Reactive 스트림의 onNext 콜백에서 사용되고, onComplete에서 읽힙니다. WebClient의 Flux는 Reactor의 이벤트 루프(Netty) 스레드에서 실행되므로, SseEmitter.send()와 StringBuilder.append()가 Servlet 컨테이너 스레드가 아닌 Reactor 스레드에서 호출됩니다.

SseEmitter는 Spring MVC에서 비동기 응답을 지원하지만, Reactor 스레드에서 직접 send()를 호출하는 것은 Servlet 스펙과의 스레딩 계약에 주의가 필요합니다. StringBuilder는 thread-safe하지 않으므로, 만약 스케줄러 전환이 발생하면 데이터 손상 가능성이 있습니다.

고려사항:

• publishOn(Schedulers.boundedElastic())으로 콜백 스레드를 명시적으로 지정하거나
• StringBuffer나 동기화된 대안을 사용하는 것을 권장합니다.

[VitoJeong]

publishOn(Schedulers.boundedElastic()) 으로 직렬화를 보장하도록 보완했습니다.

[f-lab-ted]

[Major] AiServicePort가 adapter 패키지에 위치 — 포트 인터페이스의 위치 재고 필요

헥사고날 아키텍처에서 포트 인터페이스는 domain.port.out 패키지에 위치해야 외부 시스템(AI 서비스)에 대한 의존을 도메인 계층에서 추상화할 수 있습니다. 현재 adapter.out.aiservice 패키지에 있어서:

1. application 서비스가 이 포트를 사용하려면 adapter에 의존해야 하는 구조가 됨 (ArchUnit 룰 위반)
2. 다른 outbound 포트(LoadUserPort, SaveChatRoomPort 등)는 모두 domain.port.out에 있어 일관성이 깨짐

domain.port.out.AiAgentStreamPort 등의 이름으로 도메인 포트 패키지로 이동하는 것을 권장합니다. 구현체(AiServiceAdapter)만 adapter 패키지에 유지하면 됩니다.

[VitoJeong]

넵 리패키징 반영하면서 클래스명 AiServiceStreamPort로 변경했습니다!

[f-lab-ted]

[Major] SessionCreationPolicy.IF_REQUIRED는 JWT stateless 인증과 불일치

JWT 기반 stateless 인증을 사용하고 있으므로 SessionCreationPolicy.STATELESS가 적합합니다. 현재 IF_REQUIRED로 설정되어 있어:

1. 매 요청마다 불필요한 HttpSession이 생성될 수 있음 (메모리 낭비)
2. CSRF를 비활성화한 것과 세션 사용 가능 상태가 보안적으로 일관되지 않음

OAuth2 로그인 플로우에서 authorization_request를 세션에 저장해야 하므로 IF_REQUIRED를 선택한 것으로 보이지만, OAuth2 콜백 완료 후에는 세션이 필요 없습니다. OAuth2 로그인 경로만 세션을 허용하고 나머지는 STATELESS로 처리하는 방법을 고려해보세요.

.sessionManagement(session ->
    session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))

OAuth2 플로우의 state 파라미터 보관은 HttpSessionOAuth2AuthorizationRequestRepository 대신 쿠키 기반 구현(Cookie-based AuthorizationRequestRepository)으로 대체하면 완전 stateless가 가능합니다.

[VitoJeong]

피드백 감사합니다! 현재 Spring Security 프레임워크를 기반으로 동작을 검토하여 의견을 공유드립니다.

JWT 인증 요청 — 세션 미생성 (확인됨)

Spring Security 6.x에서 SecurityContextPersistenceFilter는 deprecated되고 SecurityContextHolderFilter로 교체됐습니다. 이 필터는 read-only라서 요청 종료 시 SecurityContext를 세션에 저장하지 않고있습니다. JwtAuthenticationFilter가 인증을 설정해도 세션이 생성되지 않아, 피드백주신 "매 요청마다 세션 생성" 문제는 현재 환경(Spring Boot 3.5 / Spring Security 6.5)에서는 발생하지 않아 성능이 개선됐다고 볼 수 있을 것 같았습니다.

참고 포스트

위 내용과 별개로, ExceptionTranslationFilter는 401 응답 직전에 HttpSessionRequestCache.saveRequest()를 호출하여 인증 실패 경로에서 불필요한 세션이 생성되는 문제를 확인할 수 있었습니다. STATELESS 설정이면 NullRequestCache로 자동 대체되지만 IF_REQUIRED는 그렇지 않았습니다.

JWT + 쿠키 기반의 현재 인증방식에서는 SavedRequest는 사용되지 않으므로 NullRequestCache를 requestCache로 설정해 수정했습니다.

.requestCache(cache -> cache.requestCache(new NullRequestCache()))

결론

세션생성 정책을 STATELESS로 전환하게 되면 이미 프레임워크 측에서 개선된 부분을 위해 따로 구현 비용이 발생할 것으로 보여 IF_REQUIRED 유지하는게 어떨까 합니다.

[f-lab-ted]

Spring Security 6.x에서 SecurityContextHolderFilter가 read-only로 동작하면서 세션 생성을 자제하는 부분이나, NullRequestCache로 401/403 누수를 막은 건 정확한 대응입니다. 제가 놓쳤던 부분이네요.

그럼에도 STATELESS 설정과 쿠키 기반 저장소를 말씀드리는 건 서비스의 확장성, 즉 스케일 아웃(Scale-out) 상황 때문입니다.

현재 설정에서도 일반 API 요청은 괜찮겠지만, OAuth2 로그인을 처리하는 그 짧은 과정에서는 여전히 서버 세션이 만들어집니다. 기본 저장소인 HttpSessionOAuth2AuthorizationRequestRepository가 동작하기 때문인데요.

이게 서버가 한 대일 때는 상관없지만, 나중에 서버를 여러 대로 늘렸을 때 문제가 됩니다. 사용자가 1번 서버에서 로그인을 시작했는데 인증 콜백이 2번 서버로 들어오면 세션이 없어서 로그인이 실패하게 됩니다. 이걸 해결하려고 나중에 Redis 같은 공유 세션 저장소를 붙이거나 로드밸런서 설정을 만지는 건 생각보다 번거로운 일이 됩니다.

그래서 로그인을 시도할 때의 임시 상태값까지 쿠키에 담아 클라이언트로 넘기자고 제안드리는 것입니다. 그렇게 하면 서버는 어떤 순간에도 상태를 갖지 않는 완전한 무상태(Pure Stateless)가 되고, 서버를 아무리 늘려도 인프라 걱정 없이 유연하게 대응할 수 있습니다.

초기에 쿠키 기반 저장소를 구현하는 공수가 조금 들더라도, 나중에 서버 확장 시 발생할 구조적 결함을 미리 방지한다는 점에서 장기적으로는 훨씬 남는 장사라고 생각합니다.

---

혹시 IF_REQUIRED를 유지해야만 하는 별도의 이유가 있을까요?

[VitoJeong]

찾아보니 멘토님이 피드백해주신 말씀이 맞겠네요. HttpSessionOAuth2AuthorizationRequestRepository가 인증 과정의 state를 서버 세션에 저장하기 때문에, 분산 환경에서 콜백이 다른 서버로 라우팅되면 state 검증 과정에서 인증이 실패할 수 있겠네요. 확장성 측면에서는 고려하지 못했습니다.
쿠키 기반 저장소를 구현하면 인증 설계에서 Stateless를 달성할 수 있고, Redis 세션 공유 같은 인프라 의존도 제거할 수 있겠네요. 가이드해주신 내용대로 수정해보겠습니다!

[f-lab-ted]

[Suggestion] ArchUnit 검증 범위 확장 제안

현재 두 가지 룰(domain의 프레임워크 무의존, application의 adapter 무의존)로 핵심 경계를 잘 검증하고 있습니다. 추가로 다음 룰을 보완하면 아키텍처 경계가 더 견고해집니다:

1. adapter.in → adapter.out 직접 의존 금지: 현재 ChatController가 AiServicePort(adapter.out)를 직접 의존하는 것을 잡아낼 수 있습니다.

@ArchTest
static final ArchRule inbound_adapter_must_not_depend_on_outbound_adapter = noClasses()
    .that().resideInAPackage("..adapter.in..")
    .should().dependOnClassesThat().resideInAPackage("..adapter.out..");

2. collector/bootstrap 모듈의 domain.model 직접 참조 금지: 현재 collector와 bootstrap은 조합(composition root) 역할만 담당하므로, 도메인 모델을 직접 참조하지 않고 반드시 domain.port(유스케이스 인터페이스)를 통해서만 접근해야 합니다. 실제로 현재 CollectionScheduler는 CollectDatasetUseCase 포트만 의존하고 있어 올바른 구조입니다. 하지만 이 경계를 명시적으로 검증하지 않으면, 향후 개발 시 scheduler에서 CollectionHistory나 ApiSourceCatalog 같은 도메인 모델을 직접 조작하는 코드가 유입될 수 있습니다.

@ArchTest
static final ArchRule collector_must_not_depend_on_domain_model = noClasses()
    .that().resideInAPackage("..collector..")
    .should().dependOnClassesThat().resideInAPackage("..domain.model..");

@ArchTest
static final ArchRule bootstrap_must_not_depend_on_domain_model = noClasses()
    .that().resideInAPackage("..bootstrap..")
    .should().dependOnClassesThat().resideInAPackage("..domain.model..");

이 룰의 핵심은 composition root(collector/bootstrap)가 "어떤 유스케이스를 실행할지"만 알고, "도메인 객체를 어떻게 다루는지"는 모르게 하는 것입니다. 도메인 모델 조작은 application 레이어의 서비스가 전담하고, collector/bootstrap은 포트 인터페이스(CollectDatasetUseCase, SendQueryUseCase 등)만 호출하는 구조를 CI 단계에서 강제할 수 있습니다.

[VitoJeong]

넵 반영후 통과 확인했습니다!

[f-lab-ted]

답글 주세요~

[f-lab-ted]

Spring Security 6.x에서 SecurityContextHolderFilter가 read-only로 동작하면서 세션 생성을 자제하는 부분이나, NullRequestCache로 401/403 누수를 막은 건 정확한 대응입니다. 제가 놓쳤던 부분이네요.

그럼에도 STATELESS 설정과 쿠키 기반 저장소를 말씀드리는 건 서비스의 확장성, 즉 스케일 아웃(Scale-out) 상황 때문입니다.

현재 설정에서도 일반 API 요청은 괜찮겠지만, OAuth2 로그인을 처리하는 그 짧은 과정에서는 여전히 서버 세션이 만들어집니다. 기본 저장소인 HttpSessionOAuth2AuthorizationRequestRepository가 동작하기 때문인데요.

이게 서버가 한 대일 때는 상관없지만, 나중에 서버를 여러 대로 늘렸을 때 문제가 됩니다. 사용자가 1번 서버에서 로그인을 시작했는데 인증 콜백이 2번 서버로 들어오면 세션이 없어서 로그인이 실패하게 됩니다. 이걸 해결하려고 나중에 Redis 같은 공유 세션 저장소를 붙이거나 로드밸런서 설정을 만지는 건 생각보다 번거로운 일이 됩니다.

그래서 로그인을 시도할 때의 임시 상태값까지 쿠키에 담아 클라이언트로 넘기자고 제안드리는 것입니다. 그렇게 하면 서버는 어떤 순간에도 상태를 갖지 않는 완전한 무상태(Pure Stateless)가 되고, 서버를 아무리 늘려도 인프라 걱정 없이 유연하게 대응할 수 있습니다.

초기에 쿠키 기반 저장소를 구현하는 공수가 조금 들더라도, 나중에 서버 확장 시 발생할 구조적 결함을 미리 방지한다는 점에서 장기적으로는 훨씬 남는 장사라고 생각합니다.

---

혹시 IF_REQUIRED를 유지해야만 하는 별도의 이유가 있을까요?