모듈식 모놀리스와 헥사고날 아키텍처로 구성된 Nearby 서버 구조 분석하기

아키텍처 선택 이유

SOPT에서 세미나, 솝커톤, 합동 세미나 모두 모두 레이어드 아키텍처를 사용해왔다. 하지만 이번 AppJam에서는 새로운 구조를 직접 경험하고, 기존 방식과 어떤 차이가 있는지 알아보고 싶었다.

처음에는 어떤 아키텍처가 있고 어떤 걸 선택해야 하는지 또 각 아키텍처가 어떤 특징을 가지는지 충분히 알지 못 하였다. 이후 서버 리드가 제안한 모듈식 모놀리스와 헥사고날 아키텍처의 도입 배경을 듣고, 새로운 구조를 학습할 좋은 기회라고 생각해 해당 아키텍처를 적용하게 되었다.

아키텍처를 이해하고 프로젝트 구조를 파악하는 과정에서 가장 많은 도움을 받은 글은 다음 글이었다.

미리 회고하자면

아키텍처를 선택한 이후 가장 큰 문제는 이를 실제 코드로 구현하는 방법이었다. 팀 내에 모듈식 모놀리스와 헥사고날 아키텍처를 충분히 경험해 본 사람이 없었기 때문에, 명확한 기준 없이 구조를 만들어가야 했다.

프로젝트를 진행하면서 모듈식 모놀리스에서는 단순히 Gradle 모듈이나 패키지를 여러 개로 나누는 것보다, 먼저 도메인의 경계와 각 도메인의 책임을 명확하게 정의하는 것이 중요하다는 점을 알게 되었다.

처음부터 모듈식 모놀리스를 적용하기보다는 하나의 모놀리스로 시작해 도메인에 대한 이해가 충분히 쌓인 이후, 경계를 기준으로 모듈을 분리하는 접근도 있다는 사실도 뒤늦게 알게 되었다.

하지만 우리 팀은 초기에 도메인 영역과 책임을 충분히 나누지 못한 상태에서 구조를 먼저 설계했다. 여기에 해당 아키텍처에 대한 경험 부족까지 겹치면서 모듈의 책임이 불분명해지거나, 의존성의 방향이 의도와 다르게 구성되는 등 여러 시행착오를 겪었다.

결국 새로운 아키텍처를 선택하는 것보다 더 중요한 것은, 해당 아키텍처가 해결하려는 문제가 무엇인지 이해하고 프로젝트의 도메인에 맞게 적용하는 것이라는 점을 배울 수 있었다.

---

구조 분석하기

• adapter-in/web: HTTP 요청을 받는 곳
• application: 도메인 모델과 핵심 업무 규칙, 유스케이스, Port를 정의하는 애플리케이션 코어
• adapter-out/persistence: DB에 접근하는 곳
• bootstrap: 각 모듈을 조립하고 애플리케이션을 실행하는 곳
• common, logging: 공통 기능

우선 모듈 구조는 위와 같이 나누게 되었다. 이렇게 나눈 이유는 아래 사진처럼 헥사고날 구조를 가져가기 위함이였다.

헥사고날의 특징이라고 하면 핵심 비즈니스 로직을 데이터베이스, API, 사용자 인터페이스와 같은 외부 시스템과 분리하는 소프트웨어 설계 접근 방식이라고 할 수 있다. 이를 통해 유연하고 유지 관리가 용이하며 테스트가 간편한 애플리케이션을 구축할 수 있게 된다.

Nearby는 Google Maps 장소 검색, 카카오 인증, Solapi 문자 발송, S3 이미지 저장 및 JPA·Redis 영속성 처리를 어댑터로 분리했다. 이를 통해 동행 신청, 매칭, 일정 확정과 같은 핵심 비즈니스 규칙을 외부 기술의 변화와 분리하고, 실제 외부 시스템 없이도 유스케이스를 독립적으로 테스트할 수 있도록 했다.

→ 외부 시스템과의 상호작용을 Port 인터페이스로 추상화하여, 핵심 비즈니스 로직이 JPA, Redis, 외부 API와 같은 구체적인 기술 구현에 직접 의존하지 않도록 하는 것이 핵심!

최종 Gradle 모듈 구조

nearby
├── bootstrap
├── application
├── adapter-in
│   └── web
├── adapter-out
│   ├── persistence
│   └── security
├── common
└── logging

모듈별 구조

모듈	책임	판단 근거
bootstrap	Spring Boot 실행 진입점, 런타임 조립, 설정 로딩, Actuator, Spring Modulith 런타임 구성	실행 가능한 애플리케이션을 만드는 책임은 비즈니스 코드나 어댑터 구현과 분리되어야 한다. 이 모듈만 Spring Boot 애플리케이션 플러그인을 사용한다.
application	도메인 모델, 업무 규칙, Outbound Port	헥사고날 아키텍처의 중심은 외부 기술에 의존하지 않는 애플리케이션 코어다. 현재는 도메인 모델과 Port가 중심이며, 추후 Use Case Service가 생기면 이 모듈에 둔다.
adapter-in:web	HTTP Controller, Request·Response DTO, Validation, 웹 예외 처리, Swagger 설정	HTTP 요청은 애플리케이션 코어로 들어오는 Inbound Adapter다. Spring MVC와 OpenAPI 의존성은 이 모듈 안에 머무는 것이 적절하다.
adapter-out:persistence	JPA Entity, Spring Data Repository, Redis, Persistence Mapper, Outbound Port 구현	데이터 저장소는 애플리케이션 코어가 의존하면 안 되는 외부 기술이다. JPA와 Redis 의존성을 별도의 Outbound Adapter에 둔다.
adapter-out:security	Spring Security 기반 인증·인가 구현	보안 구현은 Persistence와는 다른 기술 영역이다. 인증 필터, Security Context, Token 처리 등의 책임이 커질 수 있으므로 별도 Outbound Adapter로 분리한다.
common	여러 모듈에서 공유할 수 있는 안정적인 예외와 Port 보조 타입	특정 Feature나 기술 구현에 종속되지 않는 계약만 둔다. 단순히 편리하다는 이유로 코드를 모아두는 장소로 사용하지 않는다.
logging	MDC, Request ID, 요청 로그 필터, 민감 정보 마스킹	로깅은 업무 규칙이 아닌 횡단 관심사이자 인프라 책임이다. Spring Web과 Servlet Filter에 의존하므로 common이 아닌 별도 모듈로 분리하는 것이 적절하다.

---

의존 방향

bootstrap -> adapter-in:web
bootstrap -> adapter-out:persistence
bootstrap -> adapter-out:security
bootstrap -> application
bootstrap -> common
bootstrap -> logging

adapter-in:web -> application
adapter-in:web -> common
adapter-in:web -> logging

adapter-out:persistence -> application
adapter-out:persistence -> common
adapter-out:persistence -> logging

adapter-out:security -> application
adapter-out:security -> common
adapter-out:security -> logging

application -> common
logging -> common
common -> none

• 핵심 규칙은 application 이 외부 기술을 모르는 것이다.
• Spring Web, JPA, Redis, Security 의존성은 adapter 쪽에 있고, application은 port 인터페이스를 통해 필요한 기능만 표현한다