Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

12 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

Hexagonal Architecture (Ports & Adapters) — Alistair Cockburn 원문

Layer: raw/official-docs/ — Alistair Cockburn 의 "Hexagonal Architecture" (alias: Ports & Adapters) 원문 발췌. inside/outside asymmetry + port + adapter 의 정의·동기 1차 출처. ca-tmpl 의 application port 와 adapter 분리 결정의 기반.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-repository-access-permission-contract	D3 (application layer 가 driving/driven port interface 만 노출), D4 (Repository 가 driven port 의 한 종류) 의 1차 근거
raw/branch-notes/feature-architecture-enforcement-rules	inside (application/domain) 에서 outside (adapter/infrastructure) 로의 의존 금지를 ArchUnit 규칙으로 강제할 때의 개념적 기반
raw/branch-notes/feature-application-port-usecase-contract	UseCase = primary/driving port 정의, Repository = secondary/driven port 정의의 명명 정당화

컨텍스트

ca-tmpl 의 application 레이어가 외부로 노출하는 것이 "use case interface" 인지 "service class" 인지의 결정, 그리고 Repository 가 application 레이어에 속하는지 domain 에 속하는지의 결정 모두 Cockburn 의 port/adapter 정의와 inside/outside asymmetry 에 기반한다. 본 raw 는 원문 verbatim 만 보관하고, ca-tmpl 패키지 매핑은 wiki/projects 에서 별도 정리.

출처 / Source

원본 URL: https://alistair.cockburn.us/hexagonal-architecture/
아카이브 URL:
저자 / 조직: Alistair Cockburn (personal site alistair.cockburn.us) — Hexagonal Architecture 원저자
발행일: 2005 (페이지에 "Hexagonal architecture the original 2005 article" 표기). 페이지 자체는 이후 refresh.
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§The Pattern — Intent] "Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases."

[§Nature of the Solution] "The asymmetry to exploit is not that between left and right sides of the application but between inside and outside of the application."

[§Nature of the Solution — port] "the application communicates over ports to external agencies. The word "port" is supposed to evoke thoughts of ports in an operating system, where any device that adheres to the protocols of a port can be plugged into it"

[§Nature of the Solution — adapter] "For each external device there is an adapter that converts the API definition to the signals needed by that device and vice versa."

[§Nature of the Solution — symmetry] "The hexagonal, or ports and adapters, architecture solves these problems by noting the symmetry in the situation: there is an application on the inside communicating over some number of ports with things on the outside. The items outside the application can be dealt with symmetrically."

[§Nature of the Solution — why hexagon] "The hexagon is not a hexagon because the number six is important, but rather to allow the people doing the drawing to have room to insert ports and adapters as they need, not being constrained by a one-dimensional layered drawing."

[§Nature of the Solution — port purpose] "A port identifies a purposeful conversation. There will typically be multiple adapters for any one port, for various technologies that may plug into that port."

[§Nature of the Solution — primary focus] "the primary purpose of this pattern is to focus on the inside-outside asymmetry, pretending briefly that all external items are identical from the perspective of the application."

Claims Extracted / 추출된 주장

Claim ID	Claim	Evidence quote	Strength	Applies to	Does not prove
HEX-COCKBURN-ORIG-C1	Hexagonal Architecture 의 Intent 는 application 이 사용자·프로그램·자동화 테스트·batch script 에 의해 동등하게 (equally) 구동될 수 있고, 실제 런타임 device/DB 와 격리된 채 개발·테스트 될 수 있게 하는 것	[§Intent] "Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases."	`engineering-blog`	application 의 외부 채널 다양화 + 테스트 격리 요구가 있는 시스템	"equally" 가 모든 driving channel 이 정확히 같은 코드 경로를 통과해야 한다는 강제는 아님 — 각 adapter 가 동일 port 에 plug-in 된다는 의미
HEX-COCKBURN-ORIG-C2	핵심 비대칭은 좌/우(UI vs DB) 가 아니라 inside / outside 이다 — 코드 분리 기준의 원칙적 출발점	[§Nature of the Solution] "The asymmetry to exploit is not that between left and right sides of the application but between inside and outside of the application."	`engineering-blog`	레이어드 아키텍처 vs hexagonal 의 분류 기준 결정	어떤 클래스가 inside 인지 outside 인지의 구체 판정 기준 (도메인 객체 vs Repository impl 등) 은 본 인용에 없음
HEX-COCKBURN-ORIG-C3	port 는 외부 agency 와의 conversation 을 위한 application 의 plug-point — OS 의 port 처럼 protocol 을 따르는 어떤 device 든 꽂힐 수 있다	[§Nature of the Solution] "the application communicates over ports to external agencies. The word "port" is supposed to evoke thoughts of ports in an operating system, where any device that adheres to the protocols of a port can be plugged into it"	`engineering-blog`	port 인터페이스 명명·범위 결정	port 가 반드시 Java interface 로 표현되어야 한다는 강제는 본 인용에 없음 (구현 언어/표현은 열려 있음)
HEX-COCKBURN-ORIG-C4	adapter 는 각 external device 별로 존재하며, port 의 API 정의를 해당 device 의 signal 로 양방향 변환한다	[§Nature of the Solution] "For each external device there is an adapter that converts the API definition to the signals needed by that device and vice versa."	`engineering-blog`	REST controller / JPA repository impl / Kafka consumer 등의 분류	한 adapter 가 여러 port 를 동시에 implement 할 수 있는지 여부는 본 인용에 없음
HEX-COCKBURN-ORIG-C5	hexagonal 명칭은 application 이 outside 의 여러 things 와 symmetric 하게 통신한다는 통찰에서 비롯 — outside 의 item 들은 symmetric 하게 다뤄질 수 있다	[§Nature of the Solution] "The hexagonal, or ports and adapters, architecture solves these problems by noting the symmetry in the situation: there is an application on the inside communicating over some number of ports with things on the outside. The items outside the application can be dealt with symmetrically."	`engineering-blog`	UI/DB 양쪽을 동일 메커니즘 (port + adapter) 으로 처리하는 설계	UI 와 DB 가 정확히 동일한 종류 의 port 라는 뜻은 아님 — primary/secondary 구분은 §Application Notes 에서 별도 도입
HEX-COCKBURN-ORIG-C6	hexagon 모양 자체는 의미 없음 — 6이라는 숫자가 중요한 것이 아니라 여러 port/adapter 를 그릴 공간 이 필요해서일 뿐	[§Nature of the Solution] "The hexagon is not a hexagon because the number six is important, but rather to allow the people doing the drawing to have room to insert ports and adapters as they need, not being constrained by a one-dimensional layered drawing."	`engineering-blog`	hexagonal 다이어그램 작성 시 layer 수 강제 금지	실제 application 에서 port 수에 상한이 있다는 의미는 아님 (저자 본인은 "최대 4개를 만났다" 라고 별도 언급)
HEX-COCKBURN-ORIG-C7	하나의 port 는 purposeful conversation 을 식별하며, 같은 port 에 대해 여러 기술의 adapter 가 plug-in 될 수 있다	[§Nature of the Solution] "A port identifies a purposeful conversation. There will typically be multiple adapters for any one port, for various technologies that may plug into that port."	`engineering-blog`	동일 port (e.g., UserRepository) 에 대해 JPA / in-memory mock / Redis 등 복수 adapter 구현 정당화	모든 port 가 multiple adapter 를 가져야 한다는 강제는 아님 (typically — 일반적 경향)
HEX-COCKBURN-ORIG-C8	이 패턴의 primary purpose 는 inside-outside asymmetry 에 집중하는 것이며, 모든 외부 item 을 application 관점에서 일단 동일하게 본다	[§Nature of the Solution] "the primary purpose of this pattern is to focus on the inside-outside asymmetry, pretending briefly that all external items are identical from the perspective of the application."	`engineering-blog`	초기 설계 시 driving vs driven 의 차이를 일단 미루는 사고 절차	UI 와 DB 가 영원히 동일 취급되어야 한다는 의미는 아님 — left/right asymmetry 는 §Application Notes 에서 다시 도입

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- HEX-COCKBURN-ORIG-C1~C2: Hexagonal 의 Intent 와 핵심 비대칭이 inside/outside 라는 점
- HEX-COCKBURN-ORIG-C3~C4: port 와 adapter 의 정확한 정의 (OS port 비유 + 양방향 신호 변환)
- HEX-COCKBURN-ORIG-C5~C7: symmetry 관찰의 의미 + hexagon 모양의 비-의미 + 1 port — N adapter 관계
- HEX-COCKBURN-ORIG-C8: pattern 의 primary purpose
이 자료가 증명하지 않는 것:
- 본 글이 공식 표준 (RFC / ISO) 이라는 점 — Cockburn 의 personal site (alistair.cockburn.us). 단, Hexagonal Architecture 의 원저자 본인의 글이므로 historical/authoritative reference 이지만 strength 는 engineering-blog 로 보수적 분류.
- "primary port" vs "secondary port" 의 정확한 명명 — 본 페이지 인용 범위에서는 driving/driven 의 명시적 정의 인용을 추출하지 않았음. 별도 페이지 (Application Notes / Structure 섹션) 추가 인용 필요.
- Java/Spring 환경에서 port 가 반드시 interface 로 표현되어야 한다는 점 (구현 언어 무관, "API" 라는 추상 표현만 등장)
- ca-tmpl 의 application 패키지가 "port + use case interactor" 로 정확히 분할되어야 한다는 결정 (본 자료는 패턴 정의만 제공, 패키지 매핑은 wiki/projects 에서 결정)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- driving port (UseCase) 의 명명 규칙과 driven port (Repository, Gateway) 의 명명 규칙 (raw/branch-notes/feature-application-port-usecase-contract)
- Cockburn 의 Application Notes 섹션 (좌/우 asymmetry, primary/secondary 구분) 의 verbatim quote 보강
- Clean Architecture (Uncle Bob) 4동심원과 본 inside/outside 의 매핑 관계 (wiki/concepts 합성)

메모 / Notes

본 페이지는 "the original 2005 article" 로 명시. Cockburn 본인이 Hexagonal 명칭을 처음 도입한 1차 출처. 다만 personal site 이며 표준화 기관이 발행한 사양이 아니므로 strength 는 engineering-blog.
본 자료를 "공식 best practice" 로 인용할 수 없음. 단, ports & adapters 라는 용어의 정의 출처 로는 가장 적합.
ca-tmpl 의 application 패키지 분할은 Clean Architecture 와 Hexagonal 의 합성 으로 정당화될 가능성이 높음. wiki/concepts 에서 두 출처를 같이 인용하여 합성 결정의 근거 표를 작성할 것.

같은 주제 다른 raw:
- raw/official-docs/arch-clean-architecture-uncle-bob (Uncle Bob 4동심원 원문)
- raw/official-docs/archunit-user-guide (port/adapter 의존 방향 강제 도구)
이 자료를 인용하는 branch:
인용하는 project:
- raw/project-notes/ca-skeleton-operational-contract
이 자료를 인용한 wiki 요약: (미작성)

12 KiB Raw Permalink Blame History