116 lines
12 KiB
Markdown
116 lines
12 KiB
Markdown
---
|
|
title: Spring Boot Kotlin Multi Module로 구성해보는 헥사고날 아키텍처 (우아한형제들)
|
|
source_type: company-tech-blog
|
|
url: https://techblog.woowahan.com/12720/
|
|
archive_url:
|
|
status: raw
|
|
confidence: medium
|
|
tags: [ca-architecture-layout, hexagonal, woowahan, ceo-united, kotlin, multi-module, company-tech-blog]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-architecture-enforcement-rules, feature-skeleton-package-blueprint-contract, feature-domain-feature-onboarding-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# Spring Boot Kotlin Multi Module로 구성해보는 헥사고날 아키텍처 (우아한형제들)
|
|
|
|
> Layer: `raw/company-tech-blogs/` — 우아한형제들 (WoowaTech) 기술블로그 발췌. 한국 대기업의 hexagonal 실 적용 사례 (ceo-united, 배민 사장님 POS 백엔드).
|
|
> **company-tech-blog 분류 — 공식 best practice 로 격상 금지.** Cockburn / Spring 공식 doc 으로 corroborate 되지 않는 사항은 vendor-specific 결정으로만 인용.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
> 이 자료는 혼자 존재하지 않는다. ca-tmpl architecture 결정 비교군의 한 축.
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-architecture-enforcement-rules]] | Gradle multi-module 로 컴파일 타임 의존성을 layer 단위로 강제한 사례 — ArchUnit vs Gradle module 경계 강제의 비교 근거 |
|
|
| [[raw/branch-notes/feature-skeleton-package-blueprint-contract]] | 우아한형제들 4-Hexagon (Domain/Application/Framework/Bootstrap) layer-단위 multi-module vs ca-tmpl feature-단위 single-module 비교 |
|
|
| [[raw/branch-notes/feature-domain-feature-onboarding-contract]] | hexagonal 도입 시 outputPort 인터페이스 폭증 문제 — ca-tmpl 의 feature 추가 워크플로우가 같은 문제를 겪는지 비교 (실증 사례) |
|
|
|
|
특정 branch 없이 foundational 조사로 수집한 경우:
|
|
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] — §20 Skeleton Blueprint Contract / §19 Domain Application Readiness Contract 의 사례 비교 (대안 2: hexagonal, 한국 vendor case)
|
|
|
|
## 컨텍스트
|
|
|
|
ca-tmpl 의 feature-first 결정에 대한 대안 3: Hexagonal Architecture 의 한국 대기업 실 적용 사례. 공식 best practice 가 아닌 "한 회사가 어떻게 적용했는가" 의 1차 증거. 4-Hexagon 분류 방식과 outputPort 폭증 문제는 ca-tmpl 결정에 직접 참고 가치 있음 (단, **company-case-study** 수준이며 일반화 금지).
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://techblog.woowahan.com/12720/
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: WoowaTech (우아한형제들 기술블로그)
|
|
- 발행일: 2023-07-11
|
|
- 프로젝트: ceo-united (배민 사장님용 POS 백엔드)
|
|
- 마지막 확인일: 2026-05-27
|
|
- **재검증 상태 (2026-05-27)**: WebFetch 로 우아한형제들 기술블로그 페이지 재확인 완료 — 5/5 핵심 인용 페이지 존재 확인. 단 4건이 paraphrase 였음을 발견 (C1: "...대표적인 애플리케이션 아키텍처입니다" 어미 누락 / C2: "ceo-united는" 주어 누락 / C3: "총 4개의 핵사곤(Layer)으로 정의하였습니다" 순서 차이 / C4: "패키지를 나눠 기계적으로 코드를 옮겨오는 작업을 하다 보니" 중간 어절 누락). [2026-05-27 verified] verbatim 을 별도 추가. ceo-united 실 환경 동작·측정값은 외부 검증 여전히 불가능. **회사 블로그 사례 — Cockburn 원형 / 공식 vendor doc 으로 corroborate 되지 않은 사항 (특히 4-Hexagon 분류) 은 vendor-specific 결정. `company-case-study` Strength 유지 (`official-vendor-doc` 으로 격상 금지).**
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§도입 이유 — 2026-05-25 capture] "헥사고날 아키텍처는 비즈니스 요구사항을 빠르게 개발할 때 기술 선택에 대한 고민으로 소모되는 비용을 아낄 수 있다"
|
|
>
|
|
> [§도입 이유 — 2026-05-27 verified] "헥사고날 아키텍처는 비즈니스 요구사항을 빠르게 개발할 때 기술 선택에 대한 고민으로 소모되는 비용을 아낄 수 있는 대표적인 애플리케이션 아키텍처입니다."
|
|
|
|
> [§프로젝트 소개 — ceo-united — 2026-05-25 capture] "배달의민족에서 사장님들이 사용하는 포스(POS) 프로그램의 백엔드 기능을 담당하기 위한 프로젝트"
|
|
>
|
|
> [§프로젝트 소개 — ceo-united — 2026-05-27 verified] "ceo-united는 배달의민족에서 사장님들이 사용하는 포스(POS) 프로그램의 백엔드를 기능을 담당하기 위한 프로젝트"
|
|
|
|
> [§4-Hexagon 구조 — 2026-05-25 capture] "Domain Hexagon, Application Hexagon, Framework Hexagon, Bootstrap Hexagon 총 4개의 핵사곤으로 정의"
|
|
>
|
|
> [§4-Hexagon 구조 — 2026-05-27 verified] "총 4개의 핵사곤(Layer)으로 정의하였습니다. Domain Hexagon, Application Hexagon, Framework Hexagon, Bootstrap Hexagon"
|
|
|
|
> [§trade-off — outputPort 폭증 — 2026-05-25 capture] "헥사고날 아키텍처의 특성상 외부 기술과의 연계는 모두 인터페이스를 통해 이루어지기 때문에 수많은 outputPort 인터페이스들이 생겨나게 되었습니다"
|
|
>
|
|
> [§trade-off — outputPort 폭증 — 2026-05-27 verified] "헥사고날 아키텍처의 특성상 외부 기술과의 연계는 모두 인터페이스를 통해 이루어지기 때문에 패키지를 나눠 기계적으로 코드를 옮겨오는 작업을 하다 보니 수많은 outputPort 인터페이스들이 생겨나게 되었습니다."
|
|
|
|
> [§팀 효과 — 2026-05-27 verified] "이러한 과정들이 내부 결속력을 높이며 제품에 대한 오너십을 강하게 만들 수 있었던 계기가 되기도 하였습니다."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| HEX-WOOWA-C1 | (우아한형제들 ceo-united 팀의 주장) 헥사고날 아키텍처가 비즈니스 요구사항을 빠르게 개발할 때 기술 선택 고민 비용을 아낄 수 있는 대표적 아키텍처 | [§도입 이유] [2026-05-27 verified] "헥사고날 아키텍처는 비즈니스 요구사항을 빠르게 개발할 때 기술 선택에 대한 고민으로 소모되는 비용을 아낄 수 있는 대표적인 애플리케이션 아키텍처입니다." | `company-case-study` | ceo-united (배민 사장님 POS) 의 환경 | "비용 절감" 의 정량 측정값 없음. "대표적" 표현은 ceo-united 팀의 평가이지 official best practice 아님. 다른 도메인 보장 없음. **공식 best practice 로 격상 금지** |
|
|
| HEX-WOOWA-C2 | ceo-united 는 배달의민족에서 사장님들이 사용하는 POS 프로그램의 백엔드 기능을 담당하는 프로젝트 | [§프로젝트 소개 — ceo-united] [2026-05-27 verified] "ceo-united는 배달의민족에서 사장님들이 사용하는 포스(POS) 프로그램의 백엔드를 기능을 담당하기 위한 프로젝트" | `company-case-study` | ceo-united 컨텍스트 식별 | 프로젝트 규모 (인원 / 트래픽 / 도메인 수) 는 본 인용에 없음 — 일반화 어려움 |
|
|
| HEX-WOOWA-C3 | ceo-united 는 hexagonal 을 **4개 핵사곤(Layer)** (Domain / Application / Framework / Bootstrap) 으로 정의 | [§4-Hexagon 구조] [2026-05-27 verified] "총 4개의 핵사곤(Layer)으로 정의하였습니다. Domain Hexagon, Application Hexagon, Framework Hexagon, Bootstrap Hexagon" | `company-case-study` | ceo-united 의 vendor-specific 분류 | **Cockburn 원형의 hexagonal 정의와 다름** — Cockburn 은 single application core 모델. ceo-united 는 핵사곤을 **Layer 와 동등시** ("핵사곤(Layer)") 하므로 사실상 hexagonal 명명을 layered 구조에 차용 — 4-Hexagon 분류는 ceo-united 자체 해석이며 공식 hexagonal 정의가 아님 |
|
|
| HEX-WOOWA-C4 | hexagonal 의 특성상 외부 기술 연계가 모두 interface 를 통해 이루어지므로, 패키지를 나눠 기계적으로 코드를 옮기다 보니 수많은 outputPort 인터페이스가 생겨남 (ceo-united 가 경험한 trade-off) | [§trade-off — outputPort 폭증] [2026-05-27 verified] "헥사고날 아키텍처의 특성상 외부 기술과의 연계는 모두 인터페이스를 통해 이루어지기 때문에 패키지를 나눠 기계적으로 코드를 옮겨오는 작업을 하다 보니 수많은 outputPort 인터페이스들이 생겨나게 되었습니다." | `company-case-study` | hexagonal 적용 시 외부 의존성이 많은 도메인 | "수많은" 의 정량 (인터페이스 개수) 없음. "패키지를 나눠 기계적으로" 라는 이행 과정에 기인한 결과일 수 있음 — hexagonal 본질적 문제라는 보장 없음 |
|
|
| HEX-WOOWA-C5 | (팀 차원 효과) hexagonal 도입 과정이 내부 결속력 향상 + 제품 오너십 강화의 계기가 됨 | [§팀 효과] [2026-05-27 verified] "이러한 과정들이 내부 결속력을 높이며 제품에 대한 오너십을 강하게 만들 수 있었던 계기가 되기도 하였습니다." | `company-case-study` | ceo-united 팀의 회고 | 정성적 회고 — 다른 팀의 hexagonal 도입에서도 같은 결과라는 보장 없음 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것**:
|
|
- `HEX-WOOWA-C1` ~ `C5`: ceo-united 팀이 hexagonal 을 어떻게 분류 (4-Hexagon) 하고, 어떤 trade-off (outputPort 폭증) 를 경험했으며, 팀 차원 효과를 어떻게 회고하는지
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- **hexagonal 의 "공식" best practice** — 본 자료는 company-case-study, Cockburn 원형이 아님
|
|
- **4-Hexagon 분류가 hexagonal 의 표준** — ceo-united vendor-specific 해석. [[raw/official-docs/hexagonal-cockburn-wikipedia-summary]] 의 Wikipedia 정의는 "application core + adapters" single core 모델
|
|
- outputPort 폭증이 hexagonal 의 본질적 약점 — ceo-united 의 도메인 특성 (외부 시스템 연계 多) 에 기인할 가능성
|
|
- Gradle multi-module 분리가 ArchUnit 패키지 enforcement 보다 우월하다는 보장
|
|
- 측정값 (응답시간 / lead time / 결함률 / 인원 변화 등) — 본문에 정량 없음
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- ca-tmpl 의 외부 시스템 연계 수가 ceo-united 수준인지 (outputPort 폭증이 ca-tmpl 에서도 재현될지)
|
|
- ca-tmpl 의 feature-단위 분리 vs ceo-united 의 layer-단위 multi-module 분리 중 어느 쪽이 ca-tmpl 의 enforcement 요구에 맞는지
|
|
- **본 사례를 면접/포트폴리오에서 인용 시 "우아한형제들 사례" 로 명시하고 "공식 권장" 으로 격상 금지** (CLAUDE.md §5 출처 신뢰도 기준 준수)
|
|
|
|
## 메모 / Notes (내 프로젝트 해석)
|
|
|
|
> 본 섹션은 자료 직접 인용 아님. ca-tmpl 비교 컨텍스트 해석.
|
|
|
|
- 적용 시나리오: 비즈니스 요구사항 변경이 잦고 외부 시스템 연계가 많은 도메인 서비스.
|
|
- 장점 (user 추론): 비즈니스 코드가 framework 변경으로부터 격리됨. Gradle multi-module 로 컴파일 타임 의존성 강제 가능.
|
|
- 단점: outputPort 인터페이스 수 폭증 — 우아한형제들도 본문에서 이 점을 명시 (`HEX-WOOWA-C4`). 학습 비용 높음.
|
|
- ca-tmpl(feature-first) 와의 차이: 우아한형제들은 **layer 단위로 multi-module 분리** (Domain/Application/Framework/Bootstrap, `HEX-WOOWA-C3`). ca-tmpl 은 **feature 단위로 패키지 분리** 후 그 안에 layer. 모듈 경계 강제 강도: 우아한형제들 > ca-tmpl (user 해석).
|
|
- 신뢰도: `company-case-study` — 사례/관점으로만 사용. **"Spring 공식 권장" 으로 격상 금지**. Cockburn 원형 / Spring Modulith official 로 corroborate 되지 않는 사항 (특히 4-Hexagon 분류) 은 vendor-specific 결정.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 raw:
|
|
- [[raw/official-docs/hexagonal-cockburn-wikipedia-summary]] (Hexagonal 원형 official — 본 사례와 분류 다름)
|
|
- [[raw/official-docs/hexagonal-thombergs-buckpal-github]] (Spring/Java reference — 본 사례와 패키지 구조 다름)
|
|
- [[raw/official-docs/modulith-spring-official-doc]] (공식 modular monolith 대안)
|
|
- [[raw/official-docs/onion-palermo-original-2008]] (자주 혼동되는 Onion 원형)
|
|
- 인용하는 branch / project:
|
|
- [[raw/branch-notes/feature-architecture-enforcement-rules]]
|
|
- [[raw/branch-notes/feature-skeleton-package-blueprint-contract]]
|
|
- [[raw/branch-notes/feature-domain-feature-onboarding-contract]]
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]]
|
|
- 인용한 wiki 요약: (미작성)
|