Ch 1. hera-v4 읽는 법¶

1. hera-v4는 어떤 프로젝트인가¶

hera-v4는 Java 25와 Spring Boot 4 기반의 MSA 엔터프라이즈 프레임워크입니다. 시스템 관리, 인사관리, 워크플로우 세 도메인을 독립 서비스로 분리하고, 화면·API 계약·데이터 모델·공통 라이브러리를 조합해 업무 메뉴를 빠르게 만들도록 설계했습니다.

처음 접하는 개발자에게는 이렇게 설명할 수 있습니다.

"업무 화면 하나를 만들 때 필요한 화면, API, 서비스, DB 매핑, 권한, 공통 코드 패턴을 미리 갖춘 사내 표준 프레임워크"

코드를 열었을 때 파일이 많아 막막한 이유는 hera-v4가 단일 애플리케이션이 아니라 여러 Gradle 모듈로 구성되기 때문입니다. 이 챕터에서는 모듈 지도를 먼저 파악하고, 요청 하나가 어디서 시작해 어디서 끝나는지를 추적합니다.

2. 모듈 지도¶

settings.gradle에 선언된 모듈은 크게 다섯 그룹으로 나눌 수 있습니다.

2.1 모듈 목록¶

실제 업무 개발에서 주로 다루는 모듈은 hera-webapp, hera-system, hera-api-client, hera-domain-data입니다.

2.2 의존 방향¶

flowchart TD
    Webapp[hera-webapp] --> ApiClient[hera-api-client]
    ApiClient --> Gateway[_msa-api-gateway]
    Gateway --> Bootstrap[bootstrap-system]
    Bootstrap --> System[hera-system]
    System --> DomainData[hera-domain-data]
    System --> Commons[hera-commons]
    Webapp --> Commons
    Webapp --> DomainData

핵심 규칙은 세 가지입니다.

• hera-webapp은 화면과 진입 API만 담당합니다. DB를 직접 건드리지 않습니다.
• 실제 데이터 처리는 도메인 서비스 (hera-system 등)가 맡습니다.
• hera-webapp은 hera-api-client의 Feign client를 통해 도메인 서비스를 호출합니다.
• hera-domain-data는 webapp과 system이 함께 사용하는 데이터 계약 모듈입니다.

3. 두 갈래 요청¶

브라우저에서 서버로 오는 요청은 두 가지 유형으로 나뉩니다.

두 유형 모두 hera-webapp에서 처음 받지만, 이후 경로가 갈립니다.

flowchart TD
    Browser[Browser]

    Browser -->|HTML 페이지 요청| ViewRouter[hera-webapp\nXxxViewRouter]
    ViewRouter -->|model 준비 후 뷰 이름 반환| Template[Thymeleaf 템플릿]
    Template -->|HTML| Browser

    Browser -->|Ajax JSON 요청| WebApi[hera-webapp\nXxxApiController]
    WebApi -->|Feign client 호출| Gateway[_msa-api-gateway]
    Gateway -->|라우팅| DomainApi[도메인 서비스\nXxxApiController]
    DomainApi --> Service[Service]
    Service --> Mapper[Mapper]
    Mapper --> DB[(PostgreSQL)]
    DB --> Mapper
    Mapper --> Service
    Service -->|Entity → VO 변환| DomainApi
    DomainApi --> Gateway
    Gateway --> WebApi
    WebApi -->|JSON 응답| Browser

3.1 ViewRouter — 화면 진입 처리¶

ViewRouter는 HTML 페이지 요청을 받아, 화면에 필요한 공통 정보를 모델에 담고 뷰 이름을 반환하는 클래스입니다.

// hera-webapp: Sys0101ViewRouter.java
@Controller
public class Sys0101ViewRouter extends BaseViewRouter {

    @GetMapping("/sys/0101")
    public String index(Model model) {
        prepareBaseInfo(model, Domain.SYS_0101);  // 공통 모델 준비
        return "sys/sys0101";                      // templates/sys/sys0101.html
    }
}

prepareBaseInfo를 호출하면 BaseViewRouter가 세션 사용자, 다국어 메시지, 사이드 메뉴 등을 모델에 자동으로 채웁니다. Thymeleaf 템플릿은 이 모델로 화면을 렌더링합니다.

3.2 ApiController — 데이터 요청 처리¶

데이터 요청은 hera-webapp의 XxxApiController가 받아 Feign client로 도메인 서비스에 위임합니다. hera-webapp은 데이터를 직접 처리하지 않습니다.

// hera-webapp: Sys0101ApiController.java
@RestController
@RequestMapping("/api/sys")
public class Sys0101ApiController {

    private final CommonCodeClient commonCodeClient;

    @GetMapping("/common-codes/pageable")
    public PageResponse<CommonCodeVO> findAllOnPageable(
            @RequestBody PageRequest<CommonCodeVO, CommonCodeSP> pageRequest) {
        return commonCodeClient.findAllOnPageable(pageRequest);
    }
}

4. 요청 흐름 한 사이클: sys0101 따라가기¶

sys0101 공통코드 관리 화면을 기준으로 전체 흐름을 추적합니다. 이 화면은 hera-v4의 대표 참조 구현입니다.

4.1 흐름 다이어그램¶

sequenceDiagram
    participant Browser
    participant Webapp as hera-webapp
    participant Client as CommonCodeClient
    participant Gateway as _msa-api-gateway
    participant System as hera-system
    participant DB as PostgreSQL

    Browser->>Webapp: GET /sys/0101 (페이지 요청)
    Webapp-->>Browser: sys0101.html + sys0101.js

    Browser->>Webapp: GET /api/sys/common-codes/pageable (Ajax)
    Webapp->>Client: commonCodeClient.findAllOnPageable(pageRequest)
    Client->>Gateway: GET /api/v1/sys/common-codes/pageable
    Gateway->>System: 라우팅
    System->>DB: CommonCodeMapper / MyBatis
    DB-->>System: common code rows
    System-->>Client: PageResponse
    Client-->>Webapp: PageResponse
    Webapp-->>Browser: JSON (그리드 데이터)

4.2 핵심 파일 경로¶

5. 데이터 객체 4종¶

hera-v4에서는 데이터를 담는 객체를 네 가지로 구분합니다. 같은 테이블을 다루더라도 계층에 따라 사용하는 객체가 다릅니다.

5.1 Entity — DB와 1:1¶

Entity는 DB 테이블 컬럼과 1:1로 매핑되는 객체입니다. Service와 Mapper 계층에서만 사용하며, API 응답으로 그대로 내보내지 않습니다.

모든 Entity는 AuditModel 타입 중 하나를 상속합니다. 어떤 타입을 상속하느냐에 따라 createdBy, createdAt 같은 감사 필드를 프레임워크가 자동으로 처리해 줍니다.

5.2 VO — 화면/API 응답¶

VO는 Service 계층이 Entity를 변환해서 Controller에 전달하는 객체입니다. 화면 표시 형식에 맞춰 값을 가공한 뒤 JSON으로 내려줍니다.

Mapper → Entity 조회
→ Service에서 Entity를 VO로 변환
→ Controller가 VO를 JSON으로 응답

5.3 SP — 검색 조건¶

SP는 화면의 검색 조건을 담아 API에 전달하는 객체입니다. 모든 SP는 BaseSP를 상속하며, 도메인에 필요한 검색 필드를 덧붙입니다.

CommonCodeSP를 예로 들면 다음과 같습니다.

public class CommonCodeSP extends BaseSP {
    private String categoryCode;
    private String groupCode;
    private String code;
    private String name;
    @Builder.Default
    private String useYn = "Y";    // 기본값: 사용 중인 코드만 조회
    // ...
}

SP의 필드는 Service의 searchCondition 메서드가 QueryWrapper로 변환해 DB 조건으로 사용합니다.

5.4 JVO — 조인 응답¶

JVO는 여러 테이블을 조인한 결과를 화면에 내려줄 때 사용합니다. 단일 테이블 조회는 VO로 충분하지만, 연관 테이블을 한 번에 조회해야 할 때 JVO를 만듭니다.

6. 명명 규칙¶

hera-v4의 모듈 코드와 도메인 코드는 일정한 규칙으로 이름을 정합니다.

sys0101을 예로 들면 다음과 같이 연결됩니다.

화면 URL      /sys/0101
도메인 코드   SYS0101
ViewRouter    Sys0101ViewRouter.java
Thymeleaf     sys0101.html
JavaScript    sys0101.js
ApiController Sys0101ApiController.java

7. 이 챕터 요약¶