구인구직 시스템

채널과 소유 모듈

도메인 REST 는 호스트가 아니라 각 BC 의 -web 모듈이 소유합니다. 두 호스트는 이 컨트롤러들을 컴포넌트 스캔으로 올리고, 자기 시큐리티로 어느 경로를 열지 막을지만 정합니다.

URL 은 소비자를 /api 다음에 박습니다. 1차 주체가 API 이고 그다음이 소비자, 그다음이 도메인입니다. 1차 소비자는 사용자라 세그먼트를 생략합니다.

컨트롤러 폴더만 나눈 것이 아니라 요청과 응답 DTO 도 공유하지 않습니다. 한 번 공유하면 어드민 전용 필드가 사용자 응답으로 새는 것은 시간 문제입니다. 나중에 한 채널을 걷어낼 때 다른 채널이 깨지지 않게 하려는 것이기도 합니다.

화면이 여러 도메인을 필요로 할 때, 그 조합의 소유자는 도메인이 아니라 화면입니다. 도메인 서비스는 남의 도메인을 모릅니다. 조각의 조회 API 가 그 채널에 이미 열려 있으면 브라우저에서 합치고(어드민 고객 상세, 마이페이지), 아니면 호스트가 in 포트를 모아 합칩니다(개제요청자 선택 팝업). 페이징이 있어도 마찬가지입니다. 검색 조건은 uuid 집합으로 해석해 도메인에 내리고, 이름 붙이기는 돌아온 한 페이지에만 겁니다. 남의 필드로 정렬해야 할 때만 예외인데, 그때도 도메인에 조립을 밀어 넣지 않고 스냅샷을 떠서 자기 필드로 만듭니다.

REST 를 어디까지 지켰나

아래는 /api 로 시작하는 엔드포인트 전체를 훑어 본 결과입니다. 지켜진 것, 근거를 갖고 어긴 것, 아직 미달인 것으로 갈랐습니다.

리처드슨 성숙도 모델로는 레벨 2 입니다. 자원을 URI 로 식별하고, HTTP 메서드로 행위를 구분하고, 상태코드를 의미대로 씁니다. 레벨 3(HATEOAS)은 의도적으로 하지 않았습니다.

메서드로 행위를 가릅니다

경로에 행위를 담지 않습니다. 예외는 둘입니다. 상태 전이를 하위 자원으로 표현한 자리와, 검색을 POST 로 받는 두 자리입니다.

이력서를 예로 들면 경력을 하나만 고쳐도 PUT 으로 전체를 받습니다. 애그리거트 루트가 자식 리스트를 통째로 교체하는 쓰기 모델과 PUT 의 의미가 맞아떨어지는 자리입니다. 자식만 고치는 PATCH 를 열면 루트를 우회하는 경로가 생깁니다.

멱등성이 메서드 의미와 맞습니다. PUT 을 두 번 보내면 같은 결과이고, PATCH 의 전이는 두 번째 호출이 도메인에서 막힙니다. 이미 답한 제안에는 다시 답할 수 없고, 이미 판정한 채용은 되돌리기 전에는 다시 판정할 수 없습니다. 두 번 눌러도 안전한가를 프론트의 버튼 비활성화가 아니라 도메인이 보장합니다.

상태코드를 봉투가 아니라 HTTP 로 내려보냅니다

상태코드를 봉투가 아니라 HTTP 로 내려보냅니다. 예외 번역 advice 가 전부 ResponseEntity.status(...) 로 상태를 실어 보냅니다. 봉투의 success 는 상태코드를 대신하는 것이 아니라 같은 사실을 프론트가 읽기 쉬운 자리에 한 번 더 적어 둔 것입니다.

403 과 404 를 가르는 기준이 하나입니다

URL 규약

기술적 의사결정 여섯 개

이 프로젝트에서 남길 가치가 있는 것은 결과 구조가 아니라 무엇을 놓고 고민했고 무엇을 버렸는가입니다. 코드는 최종 선택만 보여주고 기각된 선택지는 남기지 않습니다. 결정마다 상황 → 선택 → 이유 → 대가 순으로 적습니다.

1. 01

   도메인 소유를 호스트가 아니라 BC 에 둡니다

   portal(사용자용)과 admin(백오피스) 두 앱이 같은 도메인을 씁니다. 이력서 로직을 누가 소유하고 다른 쪽은 그걸 어떻게 쓰는가.

   대신 버렸다

   호스트가 도메인 소유 · admin 을 없애고 한 앱으로 · 지금 바로 MSA

   골랐다

   도메인 소유를 호스트에서 BC 로

   MSA 로 가야 할 이유(경계, 독립 진화)와 지금 가면 안 되는 이유(운영 비용)를 동시에 만족하는 지점입니다. 경계는 MSA 기준으로 긋되 배포는 모놀리식으로 둡니다. 나중에 MSA 로 갈 때 바뀌는 것이 integration 모듈의 어댑터 구현뿐이 되도록 형태를 잡았습니다. 호스트가 여러 도메인의 조회를 모아 화면 모양으로 깎는 일은 오히려 호스트에 둡니다. 그 조합은 도메인이 아니라 화면의 관심사이기 때문입니다.

   치른 대가: admin 과 portal 이 같은 JVM 에서 같은 코드를 공유하므로 장애 격리가 없습니다. 공유 BC 의 컨트롤러가 양쪽 컨텍스트에 뜨는 문제도 생겼습니다(경로 분리와 default deny 로 대응). 격리가 필요해지는 시점이 서비스 분리의 트리거입니다.

2. 02

   헥사고날 의존 방향을 Maven 모듈로 강제하고, 레이어 퍼스트로 자릅니다

   의존이 바깥에서 안으로만 흐르게 하려면 두 가지를 정해야 합니다. 무엇을 경계로 자를 것인가, 그 경계를 무엇이 막을 것인가.

   대신 버렸다

   도메인(서브도메인) 퍼스트 · 패키지 + ArchUnit · Java Module System(JPMS)

   골랐다

   레이어 퍼스트 · Maven 멀티모듈

   규칙을 열거할 필요가 없기 때문입니다. 의존 그래프가 문서가 아니라 pom 에 있습니다. 대가로 모듈 수가 BC 수의 몇 배로 불어나고 IDE 로딩과 풀빌드가 느려지지만, 그 마찰 자체가 '경계를 넘고 있다'는 신호라서 없애지 않았습니다.

   치른 대가: 레이어를 축으로 골랐으므로 막히는 것도 레이어뿐입니다. 같은 talent-application 안에서 jobseeker 가 resume 내부를 import 해도 컴파일은 통과합니다. 승급 기준은 '떼어내는 단위가 서브도메인이 될 때'로 잡아 뒀고 아직 아닙니다. 그때까지 이 축은 ArchUnit 이 후보입니다.

3. 03

   애그리거트 루트 단일 쓰기, 읽기는 포트를 쪼갭니다

   이력서는 자식이 7종입니다. 자식마다 리포지토리를 둘 것인가, 루트로만 쓸 것인가. 자식 리포지토리를 두면 편하지만, 그 순간 루트를 우회하는 쓰기 경로가 생깁니다. '메인 이력서는 하나뿐' 같은 불변식은 루트가 자식 전체를 봐야 검사할 수 있습니다.

   대신 버렸다

   자식 리포지토리 유지 + 규칙으로 금지 · 자식 리포지토리를 package-private 으로

   골랐다

   자식 리포지토리 삭제, 루트로만 쓰기

   쓰기는 ResumeRepositoryPort 하나로 모으고, 읽기는 화면 단위로 쪼갰습니다(ResumeChildReadPort, ResumeSectionReadPort, ResumeDetailReadPort, ResumeStatisticsReadPort). 이 프로젝트에서 CQRS 가 사는 곳이 여기입니다. 서비스 클래스를 둘로 나누는 것이 아니라 out 포트 층에서 갈립니다. 읽기 포트를 하나로 두면 잡화점이 됩니다(공고 조회 오퍼레이션이 13개까지 늘어난 적이 있습니다). 그래서 화면 하나에 조회 리포지토리 하나로 나눕니다. 쓰기의 경계가 '함께 바뀌는 것'이라면 읽기의 경계는 '함께 보이는 것'입니다.

   치른 대가: 부분 수정(경력 한 건만 바꾸기)도 루트 전체를 다시 저장합니다. 이력서 크기에서는 문제가 아니지만 자식이 수백 건인 애그리거트라면 이 방식이 맞지 않습니다. ResumeDetailReadPort 는 JPA 엔티티가 없는 레거시 테이블을 raw SQL 로 조합해 순수하지 않지만, 읽기 전용이고 쓰기는 여전히 루트로만 가므로 불변식은 지켜집니다.

4. 04

   크로스도메인 표시 조합은 화면이 소유하고, 도메인은 남을 모릅니다

   한 화면이 여러 BC 의 데이터를 필요로 하는데 BC 는 남의 테이블을 조인하지 않기로 했습니다. 이 조합을 누가, 어디서 하는가. 소유자는 항상 화면입니다. 진짜 질문은 '어디서 실행하나'이고, 그 답을 가르는 것은 남의 필드를 표시하는지, 검색하는지, 정렬하는지입니다.

   대신 버렸다

   DB VIEW + @Immutable 엔티티 · QueryDSL 로 BC 를 넘는 JOIN · 1차 목록을 가진 BC 가 out 포트로 조립

   골랐다

   호스트가 in 포트를 모아 조립 (BFF) · 브라우저가 도메인별 호출을 합침 · 스냅샷 (쓰기 시점에 값을 박아 둠)

   표시와 검색은 늘 밖으로 뺄 수 있습니다. 검색 조건을 uuid 집합으로 해석해 1차 쿼리에 IN 으로 내리고, 표시는 돌아온 한 페이지에만 이름을 붙입니다. 정렬만 못 뺍니다. 전체 순서를 알아야 하므로 스냅샷을 떠서 자기 필드로 만듭니다. 호스트가 하는 것은 읽기 전용 이어붙이기와 같은 프로세스의 in 포트 호출이라, 쓰기 소유권을 BC 에 둔다는 원칙과 부딪히지 않습니다.

   치른 대가: BFF 는 방치하면 계층으로 자랍니다. 가드레일이 컴파일러가 아니라 코드 주석이라 리뷰에서 봐야 합니다. 왕복이 늘고(검색 한 번에 도메인 호출 두세 번), 브라우저 조립은 부분 실패와 인가를 화면마다 따로 처리해야 합니다. 스냅샷은 소급되지 않습니다. 그래도 경계가 성능보다 되돌리기 어렵다고 봤습니다. subscription 은 어떤 도메인도 모르는 채로 이 3단계가 실제로 통한다는 증거입니다.

5. 05

   커머스를 액터가 아니라 생명주기로 갈랐습니다

   주문, 결제, 상품, 포인트, 구독을 몇 개의 BC 로 가를 것인가. 액터로 가르면 다 '회원이 산다'라서 갈리지 않습니다. 실제로 다른 것은 변경 주기였습니다. 카탈로그는 운영자가 매주 바꾸고, 주문은 한번 만들어지면 절대 바뀌면 안 됩니다.

   대신 버렸다

   커머스 단일 BC · payment 를 독립 BC 로

   골랐다

   생명주기로 4분할, payment 는 order 서브도메인으로

   떼면 트랜잭션을 갈라야 하는가가 기준이었습니다. 갈라도 되는 것(상품 지급)은 뗐고, 갈라선 안 되는 것(결제 승인과 주문 확정)은 붙여 뒀습니다. 결제가 확정되면 같은 트랜잭션에서 OrderPaymentPort.markPaid 로 주문이 PAID 가 됩니다. 반대로 구독 발급과 포인트 지급은 뗐습니다. 실패해도 결제는 유효하고 재시도로 복구되는 성질이라 OrderPaidEvent 로 끊어 반응합니다. 주문 생성 시 상품 단가, 환불정책을 그 시점 값으로 스냅샷 복사합니다. 환불정책이 나중에 바뀌었다고 지난 주문에 새 정책을 적용하면 분쟁이 됩니다.

   치른 대가: 결제 승인과 주문 확정을 한 트랜잭션에 묶은 만큼 결제 상태와 기록이 order 안에 남습니다. payment 를 따로 떼야 할 때가 오면 그때 갈라야 합니다. 스냅샷은 같은 값을 두 곳에 두는 선택이라, 주문이 상품 단가와 유형, 환불정책, 프로비저닝 스펙을 복사해 안고 갑니다. 구독 발급과 포인트 지급은 라인마다 독립 트랜잭션이라 하나가 실패해도 나머지는 진행되지만, 실패한 라인은 미지급으로 남고 그것을 다시 집는 배치가 없어 재처리가 아직 사람 손입니다. 부분 취소와 대사 배치도 없어 전체 취소만 됩니다.

6. 06

   파일 접근 인가를 게이트웨이가 아니라 file BC 가 소유합니다

   이력서, 증빙, 위촉서류처럼 민감한 파일을 다룹니다. 접근 허용은 operation 권한과 그 파일 카테고리의 도메인 권한, 두 축의 곱입니다. 첫 축은 URL 로 표현돼 게이트웨이가 볼 수 있지만, 둘째 축은 파일 메타를 읽어야 압니다. URL 만 보고는 그 UUID 가 이력서인지 공지 첨부인지 모릅니다.

   대신 버렸다

   호스트 시큐리티에서 URL 인가로만 · 파일을 소유한 각 도메인이 판단

   골랐다

   file BC 가 판단, 호스트는 신원만 브리지

   판단을 file BC(FileAccessDecisionUseCase, FileAccessGuard)로 옮기고 호스트는 SecurityContext 의 신원을 인자로 넘기는 역할만 합니다. 미리보기와 다운로드도 다른 권한(FILE_PREVIEW/FILE_DOWNLOAD)으로 갈랐습니다. 화면에서 훑는 것과 파일이 조직 밖으로 나가는 것은 신뢰 수준이 다릅니다. 카테고리별 권한 매핑을 코드가 아니라 file_category_permission 테이블에 둬서, 운영 중 정책 변경마다 배포하지 않아도 되게 했습니다.

   치른 대가: 판정 엔진이 매칭되는 모든 규칙을 OR 로 평가하고 우선순위가 없습니다. 넓은 패턴이 남아 있으면 세분 규칙을 아무리 더해도 넓은 규칙이 계속 열어버립니다. 세분화하려면 넓은 규칙을 반드시 지워야 합니다.

• 되돌리기 비용이 큰 쪽을 먼저 지킵니다. 성능은 나중에 고칠 수 있지만 경계는 한번 새면 되돌리는 데 재작성이 듭니다.
• 강제할 수 없는 규칙은 규칙이 아닙니다. 문서로 지키자고 한 것은 지켜지지 않았고, 컴파일러가 막은 것만 지켜졌습니다.
• 떼어내는 단위로 생각합니다. '이걸 단독 프로세스로 떼면 무엇이 어디에 있어야 하나'를 물으면 대부분의 배치 문제가 풀렸습니다.