|| WORXPHERESection Api 백엔드 설계와 버전 퍼블리시 아키텍처들어가며
안녕하세요, 저희는 웍스피어에서 통합 전시 시스템 백엔드 개발을 담당하고 있습니다. 
여러분, 이런 경험 있으신가요?
“이번 프로모션 배너 위치 좀 바꿔주세요.” “홈 화면에 새 섹션 하나 추가해주세요.” “아, 그리고 오늘 중으로요.”
앱 화면 하나 바꾸려면 클라이언트 코드 수정, 빌드, 스토어 심사, 배포… 빠르면 며칠, 길면 일주일. 기획자분들의 한숨이 깊어지는 순간이죠.
이 문제를 해결하기 위해 저희는 Server-Driven UI 아키텍처를 도입했습니다. 서버에서 UI 구성 정보를 내려주면, 클라이언트는 그걸 그대로 그려주는 방식이에요. 배포 없이도 앱 화면을 자유롭게 변경할 수 있게 된 거죠!
그리고 이 SD-UI의 핵심 구성 단위가 바로 Section입니다.
오늘은 이 Section을 관리하는 백엔드 API를 어떻게 설계하고, 어떤 고민을 거쳤는지 이야기해보겠습니다.
Section이 뭔데?
잠깐, Section이 뭔지부터 짚고 넘어가겠습니다.
앱 홈 화면을 떠올려보세요. “오늘의 추천 공고”, “AI 인사이트”, “맞춤 채용정보” 같은 블록들이 쭉 나열되어 있잖아요? 이 블록 하나하나가 Section이에요.
각 Section에는 어떤 형태로 보여줄지(renderType), 데이터를 어디서 가져올지(apiUrl), 제목은 뭘로 할지(title) 등의 메타 정보가 들어갑니다. 클라이언트는 이 정보를 받아서 화면을 조립하기만 하면 되는 거죠.
즉, Section API는 SD-UI의 뼈대를 관리하는 핵심 API라고 할 수 있습니다.
전체 아키텍처, 어떻게 잡았을까?
Clean Architecture를 기반으로 계층을 나눴습니다. 왜 이렇게 했냐고요? Section 하나에 얽힌 관심사가 생각보다 많았기 때문이에요.
Controller (API 진입점)
↓
AppService (유스케이스 오케스트레이션)
├── Validator (정책 기반 검증)
├── Mapper (DTO 도메인 변환)
├── HistoryAppService (변경 이력 추적)
└── VersionManifestUpdater (배포 퍼블리시)
↓
Domain Service (비즈니스 로직)
↓
Repository (데이터 접근)
Controller는 HTTP 요청만 받고, AppService가 비즈니스 흐름을 조율합니다. 도메인 로직은 Domain Service에 격리시켜서, API 계층 변경이 도메인에 영향을 주지 않도록 했어요.
이 구조 덕분에 “검증 정책을 추가해달라”, “이력 저장 방식을 바꿔달라” 같은 요구사항이 들어와도 해당 컴포넌트만 수정하면 됩니다. 각 계층이 독립적으로 진화할 수 있는 거죠.
Section CRUD, 단순해 보이지만…생성: “이미 있는 섹션인데요?”
섹션 생성 API는 단순한 save 하나가 아닙니다. 꽤 많은 검증 단계를 거쳐요.
POST /sections/{siteType}/{alias}
중복 검증 → SectionExistenceValidator
필드 검증 → SectionValidator (N개의 정책 조합)
DTO → 도메인 변환 → SectionReqResMapper
저장 (섹션 + 더보기 + 광고) → SectionService.save()
변경 이력 이벤트 발행 → SectionHistoryAppService
첫 번째 관문은 중복 검증입니다. siteType + alias 조합은 유니크해야 하는데, 이걸 SectionExistenceValidator가 담당해요.
// 이미 존재하는 섹션이 있으면 SECTION_ALREADY_EXISTS 위반
if(existingSection.isPresent()){
violations.add(new SectionViolation("alias", SECTION_ALREADY_EXISTS, n
여러분, 이런 경험 있으신가요?
“이번 프로모션 배너 위치 좀 바꿔주세요.” “홈 화면에 새 섹션 하나 추가해주세요.” “아, 그리고 오늘 중으로요.”
앱 화면 하나 바꾸려면 클라이언트 코드 수정, 빌드, 스토어 심사, 배포… 빠르면 며칠, 길면 일주일. 기획자분들의 한숨이 깊어지는 순간이죠.
이 문제를 해결하기 위해 저희는 Server-Driven UI 아키텍처를 도입했습니다. 서버에서 UI 구성 정보를 내려주면, 클라이언트는 그걸 그대로 그려주는 방식이에요. 배포 없이도 앱 화면을 자유롭게 변경할 수 있게 된 거죠!
그리고 이 SD-UI의 핵심 구성 단위가 바로 Section입니다.
오늘은 이 Section을 관리하는 백엔드 API를 어떻게 설계하고, 어떤 고민을 거쳤는지 이야기해보겠습니다.
Section이 뭔데?
잠깐, Section이 뭔지부터 짚고 넘어가겠습니다.
앱 홈 화면을 떠올려보세요. “오늘의 추천 공고”, “AI 인사이트”, “맞춤 채용정보” 같은 블록들이 쭉 나열되어 있잖아요? 이 블록 하나하나가 Section이에요.
각 Section에는 어떤 형태로 보여줄지(renderType), 데이터를 어디서 가져올지(apiUrl), 제목은 뭘로 할지(title) 등의 메타 정보가 들어갑니다. 클라이언트는 이 정보를 받아서 화면을 조립하기만 하면 되는 거죠.
즉, Section API는 SD-UI의 뼈대를 관리하는 핵심 API라고 할 수 있습니다.
전체 아키텍처, 어떻게 잡았을까?
Clean Architecture를 기반으로 계층을 나눴습니다. 왜 이렇게 했냐고요? Section 하나에 얽힌 관심사가 생각보다 많았기 때문이에요.
Controller (API 진입점)
↓
AppService (유스케이스 오케스트레이션)
├── Validator (정책 기반 검증)
├── Mapper (DTO 도메인 변환)
├── HistoryAppService (변경 이력 추적)
└── VersionManifestUpdater (배포 퍼블리시)
↓
Domain Service (비즈니스 로직)
↓
Repository (데이터 접근)
Controller는 HTTP 요청만 받고, AppService가 비즈니스 흐름을 조율합니다. 도메인 로직은 Domain Service에 격리시켜서, API 계층 변경이 도메인에 영향을 주지 않도록 했어요.
이 구조 덕분에 “검증 정책을 추가해달라”, “이력 저장 방식을 바꿔달라” 같은 요구사항이 들어와도 해당 컴포넌트만 수정하면 됩니다. 각 계층이 독립적으로 진화할 수 있는 거죠.
Section CRUD, 단순해 보이지만…생성: “이미 있는 섹션인데요?”
섹션 생성 API는 단순한 save 하나가 아닙니다. 꽤 많은 검증 단계를 거쳐요.
POST /sections/{siteType}/{alias}
중복 검증 → SectionExistenceValidator
필드 검증 → SectionValidator (N개의 정책 조합)
DTO → 도메인 변환 → SectionReqResMapper
저장 (섹션 + 더보기 + 광고) → SectionService.save()
변경 이력 이벤트 발행 → SectionHistoryAppService
첫 번째 관문은 중복 검증입니다. siteType + alias 조합은 유니크해야 하는데, 이걸 SectionExistenceValidator가 담당해요.
// 이미 존재하는 섹션이 있으면 SECTION_ALREADY_EXISTS 위반
if(existingSection.isPresent()){
violations.add(new SectionViolation("alias", SECTION_ALREADY_EXISTS, n