Broadleaf Commerce를 어떻게 분석했는가
GS SHOP 입사 과제로 받은 Broadleaf Commerce 문서를 분석할 때 가장 먼저 한 일은 “무엇을 만들 것인가”보다 “이 플랫폼이 기본적으로 어디까지 갖고 있고, 어디서부터 확장이 시작되는가”를 확인하는 것이었습니다. 처음 보는 플랫폼을 이해할 때는 문서만 읽는 것보다, 실행과 소스 구조를 같이 보는 편이 훨씬 빨랐기 때문입니다.
내가 택한 분석 순서
실제로는 아래 순서로 접근했습니다.
- Broadleaf가 어떤 제품인지, 커뮤니티 버전과 문서가 어디에 있는지 확인
- 데모를 직접 보고 admin/customer 화면에서 Catalog, Customer & Orders, Inventory & Fulfillment, Admin, Search 축이 어떻게 보이는지 파악
- 로컬 실행으로 Spring Boot, Hibernate, PU, SolrStarter 같은 런타임 요소와 Broadleaf의 기본 도메인 제공 범위 확인
- 구현 대상에 맞춰 Admin Controller, Entity, Permission, MessageSource 확장 포인트 탐색
- 실제 테스트를 통해 admin/site에 메시지가 반영되는지 확인
이 순서가 잘 먹혔던 이유는, 프레임워크 설명과 실무 확장 포인트를 한 번에 연결해 볼 수 있었기 때문입니다.
처음부터 모든 클래스를 다 따라가려 했다면 오히려 오래 걸렸을 겁니다. 먼저 “이 시스템은 무엇으로 기동되고”, “Broadleaf가 기본적으로 어떤 도메인을 제공하고”, “관리자 기능은 어떤 구조로 붙고”, “Breeze 같은 제품 계층은 어느 지점부터 확장을 시작하는가”만 잡아도 전체 모양이 빠르게 보였습니다.
문서보다 먼저 본 것들
과제 문서 안에는 데모 링크와 공식 문서 링크가 먼저 정리되어 있었습니다. 이 부분이 중요했습니다. 데모를 먼저 보면 관리자 화면이 어떤 단위로 구성되는지 감이 생기고, 그 다음 공식 문서를 보면 어떤 클래스와 설정을 따라가야 할지 훨씬 좁혀집니다.
문서를 읽기 전에 데모를 본 것은 꽤 효과적이었습니다. 화면이 먼저 보이면 이후 코드와 문서에서 등장하는 개념들이 어디에 놓이는지 훨씬 빨리 매핑됩니다. 반대로 코드부터 보면 구조를 이해하기 전에 세부 구현에 끌려 들어가기 쉽습니다.
로컬 실행도 큰 힌트를 줬습니다. 문서에는 Spring Boot 1.5 계열, Hibernate, multiple persistence unit, SolrStarter 대응과 standalone Solr 구성까지 남아 있습니다. 이런 정보는 “이 플랫폼이 어떤 레이어로 구성돼 있는지”를 빠르게 알려줍니다.
특히 Solr이 중요한 단서였습니다. Broadleaf 쪽 기본 검색 축을 따라가다 보면 카탈로그 인덱싱이 검색 품질과 운영 경험에 꽤 큰 비중을 차지한다는 걸 바로 느낄 수 있었습니다. 당시 기억으로도 카탈로그 인덱싱 과정에서 유의어, 유사어 같은 검색 사전을 손보며 인덱싱 품질을 맞췄고, 이 점이 Broadleaf가 단순한 CRUD 플랫폼이 아니라 Product Browse & Search까지 포함하는 플랫폼이라는 인상을 강하게 줬습니다.
과제 문서에서 실제로 본 확장 포인트
문서를 다시 보면 다음 네 축이 반복적으로 나옵니다.
1. 관리자 확장
AdminBasicEntityController, section key, 메뉴 구성 같은 요소가 등장합니다. 즉 관리자 화면은 독립적인 화면 개발이 아니라, Broadleaf가 제공하는 관리자 구조 위에 섹션을 붙이는 방식이었습니다.
2. 기본 도메인과 확장 지점
custom entity, locale join, named query, cacheable query 같은 내용이 정리되어 있습니다. 이 부분은 Broadleaf가 기본적으로 제공하는 Catalog, Customer & Orders, Inventory & Fulfillment 구조 위에 Breeze 계열 기능을 어떤 식으로 확장을 얹어야 하는지 파악하는 데 중요했습니다.
3. 권한과 메뉴
permission import, module data import가 따로 등장합니다. 화면 하나가 동작하려면 컨트롤러만 추가해서 끝나는 게 아니라, 관리자 권한과 메뉴 데이터까지 함께 맞춰야 한다는 의미였습니다.
4. 메시지와 i18n
MessageSource를 DB 기반으로 확장하고, admin/site에서 동작 확인까지 하는 흐름이 정리돼 있습니다. 이건 Broadleaf가 단순한 CRUD 플랫폼이 아니라, 메시지 체계와 리소스 체계까지 확장 가능한 플랫폼이라는 점을 보여줬습니다.
왜 이 순서가 빨랐는가
Broadleaf는 처음 보면 annotation과 XML 설정이 많아 다소 난해합니다. 그런데 실행, 기본 도메인, 관리자, 메시지라는 네 축으로 나눠서 보면 의외로 구조가 단순해집니다. 중요한 건 이 네 축이 Broadleaf가 이미 제공하는 기반이라는 점이고, 실제 제품 요구는 그 위에 추가된다는 점입니다.
즉 제가 Broadleaf Commerce 과제 문서를 이해할 때 중요했던 건 문서 해석 자체가 아니라, “어디를 건드리면 되는지”를 빨리 찾아내는 일이었습니다. 이 기준은 이후 Breeze 계열 구조를 볼 때도 그대로 이어졌습니다.
이 접근은 새로운 플랫폼을 볼 때 지금도 유효합니다. 기능 요구사항을 바로 구현하려고 달려들기보다, 먼저 구조의 접점과 제약을 찾는 편이 훨씬 빠르고 안정적입니다.
다음 글에서는 Broadleaf 위에 실제 제품 계층이 얹힌 Breeze Commerce를 빠르게 이해할 때 어떤 축을 먼저 봐야 했는지 정리합니다: Breeze Commerce를 빠르게 이해할 때 먼저 봐야 했던 것들