깃허브의 다른 사람들이 작성한 코드들을 보면 바로 알 수 있듯이, 사람마다 모두 아키텍처 설계 방법과, 코드 구조 설계는 모두 다르다. 현재 Dataracy라는 플랫폼 개발에서 나도 어떻게 설계를 해야할 지 많은 고민을 하며 계속해서 바꾸어 나가고 있다.

처음에는 Controller, Service, Domain, Repository 이렇게 계층별로 설계하였고, 바로 이전 프로젝트인 HitZone에서는 DDD 구조에 대해서 고민을 해보았는데 이번 프로젝트를 시작하며 DDD와 헥사고날 아키텍처에 대해서 접하게 되어 이번 프로젝트에 나에게 커스텀하여 적용해보았다.

---

🤔 왜 레이어드에서 포트/어댑터로 전환했는가

❌ 기존 레이어드 아키텍처의 한계

• 규칙 희석 & 결합도 증가
  Service가 DTO 조립·쿼리·외부 호출까지 모두 떠안음
  → 시간이 지날수록 도메인 규칙이 I/O에 잠식될 수 있다.
• 변경 내성 부족
  저장소/검색/캐시 전략을 바꾸면 Controller·Service까지 연쇄 수정 필요
• 읽기/쓰기 관심사 충돌
  읽기(조인/프로젝션/캐시)와 쓰기(트랜잭션)가 같은 레이어에서 섞임
• 느리고 불안정한 테스트
  Service 테스트가 통합 테스트화되어 느림

🎯 전환 목표

• 코어(도메인/유스케이스)를 구현 기술로부터 격리 : 도메인/유스케이스에서 프레임워크·I/O 제거
• 단방향 의존 : Adapters → Application → Domain
• 경계-한정 매핑 : 변환은 Web↔App, App↔Domain(명령/응답), Domain↔Persistence(JPA/Query), App↔Index/Cache(Redis/ES) 경계에서만 수행한다.

👉 한 줄 요약:
“기술이 바뀌어도 규칙은 안 바뀌게” → 규칙은 도메인/유스케이스, 기술은 어댑터.
나중에 구현할 기술이 바뀌거나 추가되어도 비즈니스 로직은 영향을 받지 않는다.

---

🧩 핵심 개념 정리: DDD & 헥사고날

📘 DDD (Domain-Driven Design)

• Ubiquitous Language : 팀이 쓰는 용어를 코드에 그대로 투영
• 모델 응집 : 엔티티/VO/도메인 서비스/불변식 등으로 규칙을 코드에 고정
• Bounded Context : 의미 충돌 없는 경계 단위로 나누어 독립 진화

🛠 헥사고날 (Ports & Adapters)

• Port(계약) : 코어가 외부와 상호작용하는 추상 인터페이스
• Adapter(구현) : Port를 구현해 UI/DB/캐시/검색 같은 기술을 연결
• Driving Adapter (입력/상위) : Controller 같은 UI 계층 → 코어 호출
• Driven Adapter (출력/하위) : JPA/Query/Redis/Index → 코어의 요청 수행

👉 왜 Controller도 어댑터인가?
HTTP 요청을 받아 Port In(UseCase)을 호출하는 "구현체"이기 때문.
즉, Controller = 코어를 호출하는 입력 어댑터.

---

📑 각 계층에 무엇이 있어야 하는가 (가이드라인)

🏛 Domain

• 도메인 모델, VO, ENUM, 도메인 서비스,
• 불변식, 도메인 예외
  ➡️ 프레임워크 불가

⚙️ Application

• Port In (UseCase)
• Application Service
  • 오케스트레이션 : 도메인 규칙을 적용하기 위해 어떤 순서로, 어떤 포트를 불러야 하는지 조합하는 것이 애플리케이션 서비스의 책임
• Port Out (외부 I/O 계약)
• App DTO, App Mapper
  ➡️ 외부 I/O 구현 방법은 모름

🌐 Adapters

• Web: Controller, Web DTO, Web Mapper
• Query: QueryDSL Adapter (조건/조인/프로젝션/정렬/페이징)
• JPA: Entity, JpaRepository, Impl, Entity Mapper (영속 ↔ 도메인)
• Redis: 인증/보안 관련 토큰 관리 (예: Refresh Token 저장·조회, 만료 TTL 적용), 조회수/중복방지 TTL
• Index/Search: 검색 인덱싱/업데이트, 조회 최적화 (ES/Painless Script 등)

---

🔄 설계 회로: 구조도 & 시퀀스

🏗 구조도 (Mermaid)

🏗 시퀀스 Diagram

프로젝트 세부 정보 조회 API를 가정
프로젝트 조회 시 세부 정보 반환 및 프로젝트 게시글 조회수 증가 로직

👤 사용자 ->> 🌐 웹 컨트롤러: GET /api/v1/projects/{id}

🌐 웹 컨트롤러 ->> 🎯 입력포트(유스케이스): getProjectDetail(id, userId, viewerId) 호출
🎯 입력포트(유스케이스) ->> ⚙️ 애플리케이션 서비스: ProjectReadService 실행
⚙️ 애플리케이션서비스 ->> 🧩 도메인규칙: 불변식/규칙 확인
⚙️ 애플리케이션 서비스 ->> 🛠️ 조회 출력포트: findProjectWithDataById(id) 요청

🛠️ 조회 출력포트 ->> 📊 쿼리 어댑터: 조건·조인·프로젝션·정렬·페이징 처리
📊 쿼리 어댑터 -->> 🛠️ 조회 출력포트: Project + DataIds 반환
⚙️ 애플리케이션 서비스 ->> 🛠️ 레디스(캐시) 출력포트: increaseViewCount(id, viewerId, "PROJECT") 요청
🛠️ 레디스(캐시) 출력포트 ->> ⚡ 레디스어댑터: ➕ setIfAbsent + increment 실행

⚙️ 애플리케이션서비스 -->> 🌐 웹컨트롤러: Application DTO 반환
🌐 웹컨트롤러 -->> 👤 사용자: Web DTO 변환 후 200 OK 응답

---

📖 구현 예시: 프로젝트 상세 조회 (조회수·좋아요 포함)

🌐 Web Layer (Driving Adapter)

📌 역할

• HTTP 진입점(Controller).
• 요청 헤더/파라미터를 파싱하고, Port In(UseCase) 을 호출한다.
• Web DTO ↔ App DTO 변환을 책임진다.
• 즉, Web Layer는 UI 계약만 담당한다.

💻 핵심 코드

@RestController
@RequiredArgsConstructor
public class ProjectReadController implements ProjectReadApi {
    private final GetProjectDetailUseCase getProjectDetailUseCase; // Port In

    @Override
    public ResponseEntity<SuccessResponse<ProjectDetailWebResponse>> getProjectDetail(
            HttpServletRequest request, HttpServletResponse response, Long projectId) {

        Long userId   = extractHeaderUtil.extractAuthenticatedUserIdFromRequest(request);
        String viewer = extractHeaderUtil.extractViewerIdFromRequest(request, response);

        ProjectDetailResponse appDto =
            getProjectDetailUseCase.getProjectDetail(projectId, userId, viewer);

        ProjectDetailWebResponse webDto = projectReadWebMapper.toWebDto(appDto);
        return ResponseEntity.ok(SuccessResponse.of(ProjectSuccessStatus.GET_PROJECT_DETAIL, webDto));
    }
}

📝 설명

• Web Layer는 비즈니스 로직이 전혀 없다.
• 오직 요청/응답 변환과 포트 호출, 쿠키와 헤더 설정에만 집중한다.
• 따라서 테스트하기 쉽고, UI 계약(API 스펙) 변경에도 Application을 건드리지 않는다.

---

⚙️ Application Layer (Port + Service + Tx/Orchestration)

🔌 Ports (계약)

📌 역할

• Service와 Adapter 간의 추상 계약.
• Adapter 교체 가능성을 확보한다. (예: JPA → MyBatis로 변경해도 Service는 그대로)

💻 핵심 코드

public interface FindProjectPort {
    Optional<ProjectWithDataIdsResponse> findProjectWithDataById(Long projectId);
}

public interface CacheProjectViewCountPort {
    void increaseViewCount(Long targetId, String viewerId, String targetType);
}

📝 설명

• Service는 Port만 바라본다.
• 구현체는 Adapter에서 제공한다.
• Port = “Application의 의존성 역전”을 구현하는 핵심.

---

🔍 Service

📌 역할

• UseCase 구현체이자 트랜잭션 경계.
• 여러 Port를 조합하여 비즈니스 요구사항을 충족한다.
• 도메인 불변식 검사, 멱등 처리 트리거 등 오케스트레이션 책임만 가진다.

💻 핵심 코드

@Service
@RequiredArgsConstructor
public class ProjectReadService implements GetProjectDetailUseCase {

    private final FindProjectPort findProjectPort;         
    private final ValidateTargetLikeUseCase likeUseCase;   
    private final CacheProjectViewCountPort viewCountPort; 

    @Override @Transactional(readOnly = true)
    public ProjectDetailResponse getProjectDetail(Long projectId, Long userId, String viewerId) {
        var res = findProjectPort.findProjectWithDataById(projectId)
            .orElseThrow(() -> new ProjectException(ProjectErrorStatus.NOT_FOUND_PROJECT));

        boolean isLiked = (userId != null) &&
            likeUseCase.hasUserLikedTarget(userId, projectId, TargetType.PROJECT);

        viewCountPort.increaseViewCount(projectId, viewerId, "PROJECT"); // TTL·멱등

        return projectDetailDtoMapper.toResponseDto(res.project(), /* ... */ isLiked, /* ... */);
    }
}

📝 설명

• Service는 “이 작업을 위해 어떤 Port를 호출해야 하는가?”를 고민한다.
• 모든 I/O는 Port 뒤로 숨기므로, Infra 세부사항(DB, Redis, ES 등) 은 Application이 모른다.
• @Transactional을 붙여 트랜잭션 단위(읽기/쓰기)를 보장한다.

---

📊 Adapter - Query (읽기 최적화)

📌 역할

• 실제 QueryDSL로 DB에서 데이터를 조회한다. (Jpa는 Persistence Adapter)
• 조건/조인/프로젝션/페이징은 전부 Adapter 안에서 끝낸다.
• Application은 “쿼리 세부”를 모른 채 단순 DTO나 엔티티에서 변환된 도메인 모델만 받는다.

💻 핵심 코드

@Repository
@RequiredArgsConstructor
public class ReadProjectQueryDslAdapter implements FindProjectPort {
    private final JPAQueryFactory q;

    @Override
    public Optional<ProjectWithDataIdsResponse> findProjectWithDataById(Long id) {
        ProjectEntity e = q.selectFrom(QProjectEntity.projectEntity)
            .where(QProjectEntity.projectEntity.id.eq(id),
                   QProjectEntity.projectEntity.isDeleted.isFalse())
            .fetchOne();
        if (e == null) return Optional.empty();

        return Optional.of(new ProjectWithDataIdsResponse(ProjectEntityMapper.toMinimal(e), List.of()));
    }
}

📝 설명

• DB 쿼리 최적화는 Adapter에서만 고민한다.
• Application은 “findProjectWithDataById”라는 계약만 알면 된다.
• 유지보수성이 높아지고, DB 교체(MySQL → PostgreSQL) 시 Application은 변경이 없다.

---

🔄 Adapter - Redis (조회수 멱등)

📌 역할

• TTL(5분) 기반으로 조회수 중복 방지.
• 같은 viewer가 5분 내 여러 번 조회해도 1회로만 카운트.
• 새로고침/봇 스파이크를 완충.

💻 핵심 코드

@Component
@RequiredArgsConstructor
public class ProjectViewCountRedisAdapter implements CacheProjectViewCountPort {
    private final StringRedisTemplate redis;

    @Override
    public void increaseViewCount(Long projectId, String viewerId, String targetType) {
        if (viewerId == null) return;
        String dedupKey = "viewDedup:%s:%s:%s".formatted(targetType, projectId, viewerId);

        Boolean first = redis.opsForValue().setIfAbsent(dedupKey, "1", Duration.ofMinutes(5));
        if (Boolean.TRUE.equals(first)) {
            String countKey = "viewCount:%s:%s".formatted(targetType, projectId);
            redis.opsForValue().increment(countKey);
        }
    }
}

📝 설명

• Redis는 짧은 TTL 멱등 보장에 특화된 저장소.
• 본 예시에서는 “조회수 증가”를 안정적으로 다루기 위해 사용했다.
• 나중에 RDB와 동기화 시에도 안정적이다. (Scheduler Or Batch)

---

🗄️ JPA Entity & Mapper

📌 역할

• DB 테이블 매핑 전용.
• 비즈니스 로직 없음.
• Domain 객체와 분리하여 DB와 결합한 Adapter 전용으로 사용.

💻 핵심 코드

@Entity @Table(name = "project")
@Where(clause = "is_deleted = false")
public class ProjectEntity {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String title;
    private Long commentCount = 0L;
    private Long likeCount    = 0L;
    private Long viewCount    = 0L;
    ...
}

📝 설명

• Entity는 오직 DB와 결합된 ORM으로 DB에서 생성, 수정, 조회, 삭제 등의 작업에 사용된다.
• Mapper가 Entity <-> Domain 변환을 담당하여 관심사를 분리한다.

핵심: 영속 표현(JPA) ↔ 도메인 변환은 Entity Mapper에서만. 모델 침식 방지.

---

🚀 정리

• Web Layer: 요청/응답 계약, Port In 호출
• Application: Tx·오케스트레이션, Port Out 호출
• Ports: 계약 정의, Adapter 교체 가능성 보장
• Adapter: Web, Db, Persistence, Query, Redis 등 실제 구현을 담당

👉 이 구조 덕분에

• UI/API 변경 시 Application은 영향 없음
• Infra 교체(JPA → MyBatis, Redis → Memcached)에도 Service는 그대로
• 각 계층은 자기 책임만 수행

---

✨ 핵심 요약

✅ 얻는 이점

• 🔒 변경 내성: 저장소·검색·캐시 교체 시 어댑터만 수정, 코어(유스케이스·도메인)는 안정적
• 👀 가독성·유지보수성: 계층 역할이 분리돼 코드 의도가 선명하고 온보딩 용이
• ⚡ 성능·운영 최적화: Query Adapter에 성능 튜닝 집중, Redis TTL로 중복 요청 방어

⚖️ 고려사항

• 초기에 Port·Mapper가 많아보여 진입 장벽이 있음
• CQRS-lite는 필요한 곳만 적용해야 하며, 과도한 분리는 오히려 복잡도↑
• 의존 방향: Adapters → Application → Domain
• Controller는 Port In만 호출 (Repo 직접 접근 금지)
• Service는 Tx/오케스트레이션 전용, 모든 I/O는 Port Out 경유
• Query/업서트/TTL/멱등은 Adapter 내부 전용
• 경쟁 필드(조회수·좋아요)는 락·원자 연산·TTL·멱등으로 방어

---

🎯 마무리

왜 어댑터인가?

→ 구현을 코어 밖으로 밀어내 코어 규칙 보존

왜 Controller도 어댑터인가?

→ 헥사고날에서 UI는 Driving Adapter(Port In 호출자)

계층 역할

• Domain → 도메인 모델, 규칙, 불변식
• Application → 포트, Tx, 오케스트레이션
• Adapters → I/O 구현

👉 가독성·변경 내성·운영 안정성을 동시에 확보할 수 있다.
이렇게 현재 프로젝트에서 이 설계 구조를 토대로 개발을 진행하고 있는데 설계 구조는 정답이 없기에 계속해서 설계에 대해서 고민해보는 과정을 거치면 좋을 것 같다!!