VO(Value Object), 우리는 왜 그리고 어떻게 쓰고 있는가

안녕하세요 노머스 프론트엔드 개발자 김민주입니다.

이번 글에선 저희 팀이 VO를 어떻게 사용하고 있는지 살펴보고 , 현재 사용 방식에서 발견한 문제와 개선 방향에 대해 이야기해보려고 합니다.

이 글에서 말하는 VO는 DDD에서 정의하는 Value Object를 그대로 의미하는 것이 아니라, 저희 팀에서 API 응답 데이터를 도메인에서 사용하는 형태로 변환하고 관련 로직을 캡슐화하기 위해 사용하는 모델 클래스를 의미합니다.

따라서 이 글에서는 먼저 DDD에서 말하는 VO와 저희 팀의 VO가 어떻게 다른지 살펴보고, 현재의 사용 방식과 함께 개선할 수 있는 방향을 이야기해보려고 합니다.

1. VO란?

DDD에서 말하는 Value Object

DDD에서 Value Object는 고유한 식별자보다 값 자체로 의미와 동일성을 가지는 객체를 의미합니다. 대표적으로 Money, Address, Date Range 등이 있습니다. 또한 일반적으로 불변성을 가지며, 해당 값과 관련된 규칙이나 행동을 객체 안에 캡슐화할 수 있습니다.

그렇다면 우리가 사용하는 VO는?

저희 팀에서는 OptionVo, ManagerVo와 같이 API 응답 데이터를 프론트엔드에서 사용하는 형태로 변환하고, 타입 변환이나 필드 매핑, 파생값 계산 등의 로직을 함께 캡슐화하는 클래스를 VO라고 부르고 있습니다.

이렇게 보면 현재 저희 팀의 VO는 DDD에서 말하는 Value Object와 동일한 개념은 아닙니다. 오히려 API DTO와 도메인 모델 사이의 변환 역할과 도메인 로직의 일부를 함께 담당하고 있습니다.

2. 우리 팀이 VO를 쓰는 법

타입 변환

API에서 문자열이나 숫자로 전달되는 값을 프론트엔드에서 사용하는 도메인 타입으로 변환합니다.

문자열/숫자로 전달되는 금액을 Decimal로 변환해 금액 연산이 필요한 곳에서 일관된 타입으로 사용할 수 있게 합니다.

this.addPrice = new Decimal(response.addPrice);

API 필드 → 도메인 필드 변환

API의 필드명과 프론트엔드에서 사용하는 필드명이 다를 경우 VO에서 이를 변환합니다.

예를 들어 API에서는 maxCountPerUser라는 이름으로 전달되는 값을 도메인에서는 maxCount로 사용할 수 있습니다. 혹은 여러 필드를 조합해 새로운 값을 만듭니다.

Option.vo파일을 예시로 보겠습니다.

export class OptionVo {
    id: number;
    name: string;
    addPrice: Decimal;
    maxCount?: number;
    // ...
    static from(response: GetGoodsOptionsResponse) { return new OptionVo(response); }
    constructor(response: GetGoodsOptionsResponse) {
        this.id = response.id;
        this.addPrice = new Decimal(response.addPrice);
        this.maxCount = response.maxCountPerUser; // API 필드명 → 도메인 필드명
        // ...
    }
}

컴포넌트 입장에서는 option.addPrice.plus(goods.price)처럼 바로 연산하면 되고, new Decimal(...)이나 API 필드명도 신경 쓸 필요가 없습니다. 결국 VO를 통해 API 응답에 대한 변환 로직을 한 곳에서 관리하고, 컴포넌트에서는 프론트엔드 도메인에 맞게 변환된 값을 사용할 수 있습니다.

다형성 표현

장바구니 상품은 일반 상품과 번들 상품에 따라 필요한 데이터와 동작이 달라집니다. 저희 팀에서는 이를 BaseCartGoodsVo를 상속한 CartGoodsVo와 CartBundleVo로 나누어 표현하고 있습니다.

response.goods.isBundle ? CartBundleVo.from(...) : CartGoodsVo.from(...)

생성 시점 - 쿼리에서 VO로 변환

현재 저희 팀에서는 API 응답을 쿼리에서 VO로 변환한 뒤 컴포넌트에 전달하는 방식을 사용하고 있습니다.

queryFn: () => getManagers(query).then((response) => response.managers.map(ManagersVo.from))

컴포넌트에서 vo의 사용법

VO를 거친 이후 컴포넌트에서는 API 응답의 구체적인 형태나 타입 변환 과정을 알 필요 없이, 도메인에서 사용하는 값과 속성을 그대로 사용할 수 있습니다.

amount: order.price.toNumber(),

const isMembership = orderGoodsItem.isMembership;

위치와 네이밍

• src/vo/ 아래 도메인별로 정리해 중앙집중화해서 사용하거나 src/domains/*/*/vo/처럼 각 도메인 폴더안에 함께 두는 방식으로 사용합니다. 현재 저희 팀은 프로젝트 특성에 따라 조금 상이하게 사용중입니다.
• 클래스는 static from(response) 팩토리 메서드와 constructor(response)를 사용해 API 응답을 VO로 변환하는 형태를 주로 사용합니다.

3. DTO와 우리의 VO

여기서 한 가지 구분할 필요가 있습니다. API 응답값을 내부에서 필요한 형태로 변환한다는 설명만 보면 DTO와 VO의 역할이 비슷해 보일 수 있습니다.

DTO가 계층이나 시스템 간에 데이터를 전달하기 위한 구조라면, VO는 도메인에서 해당 값이 어떤 의미와 규칙을 가지는지를 표현하는 데 초점이 있습니다.

현재 저희 팀의 VO는 API 응답을 도메인에서 사용하는 형태로 변환하는 역할과 도메인 관련 로직을 캡슐화하는 역할이 함께 존재합니다. 따라서 DTO와 VO의 역할이 일부 섞여 있는 형태라고 볼 수 있습니다.

4. 현재 VO 사용 방식에서 발견한 문제

조사하면서 VO를 더 잘 활용할 수 있었던 지점들이 보였습니다.

① VO에서 제공하는 파생값을 컴포넌트에서 다시 계산하고 있다

StatisticsMembershipCount.vo.ts에는 현재 유일하게 파생값을 getter로 제공하는 패턴이 있습니다.

get existingJoinCount() { return this.totalJoinCount - this.newJoinCount; }

그런데 실제 사용처에서는 해당 getter를 사용하지 않고 컴포넌트에서 다시 totalJoinCount - newJoinCount를 계산하고 있습니다.

즉, VO에서 이미 정의한 계산 로직을 컴포넌트에서 다시 구현하고 있는 상황입니다. VO에 파생값을 getter로 정의했다면, 사용처에서도 해당 getter를 사용하도록 수정해야 파생값에 대한 계산 로직을 VO에서 일관되게 관리할 수 있습니다.

다만 모든 계산 로직을 VO로 옮겨야 한다는 의미는 아닙니다. 도메인에서 의미를 가지는 값이나 규칙이라면 VO에서 관리하고, 단순히 화면을 구성하기 위한 계산이라면 컴포넌트에서 처리하는 등 기준을 구분할 필요가 있습니다. 구분의 기준은 팀내 논의가 필요해보입니다

② 날짜 포맷팅 로직의 책임 범위가 명확하지 않다

현재 저희팀의 코드를 살펴보면 dayjs를 사용하지 않고 여러 컴포넌트에서 각각 날짜 포맷팅을 처리하고 있습니다.

금액의 경우 Decimal을 사용해 연산에 필요한 타입을 VO에서 관리하고 있습니다. 반면 날짜의 경우 startAt, endAt 자체를 VO에서 관리하는 것과 화면에 표시할 형식까지 VO에서 결정하는 것은 다른 문제라고 볼 수 있습니다.

날짜의 유효기간이나 기간 계산처럼 도메인 의미를 갖는 로직은 VO에서 관리할 수 있지만, 단순 표시 형식까지 VO의 책임으로 볼 것인지는 팀 차원의 기준이 필요합니다.

③ 동일한 도메인 안에서도 VO 적용 기준이 일관되지 않다

partner 프로젝트를 살펴보면 동일한 도메인 안에서도 VO를 적용하는 방식이 서로 다릅니다.

// useGetManager.ts, useGetManagers.ts → VO로 감쌈
queryFn: () => getManager(id).then((response) => ManagerVo.from(response))

// useGetPermissionChannels.ts, useGetPermissionArtis.ts 등 → VO 없이 raw 그대로
select: (data) => data.channels

같은 도메인에서 어떤 데이터는 VO로 변환하고, 어떤 데이터는 API 응답을 그대로 사용하는 형태입니다.

이런 불일치 때문에 팀 회의에서 API 응답은 기본적으로 VO로 감싼다는 컨벤션을 정했고, 위 코드는 그 이전에 작성된 레거시입니다. 남은 일은 이 코드들을 컨벤션에 맞게 정리하는 것입니다.

5. 개선 방향 제안

1. VO 컨벤션 문서화와 레거시 정리 “API 응답은 기본적으로 VO로 감싼다”는 컨벤션을 CLAUDE.md나 코드 리뷰 체크리스트에 명시하고, 아직 반영되지 않은 코드를 순차적으로 정리합니다.
2. 날짜·금액의 도메인 로직과 표현 로직 구분 금액의 계산에 필요한 Decimal, 날짜의 유효기간·기간 계산 등 도메인 의미를 갖는 로직은 VO에서 관리할 수 있지만, 화면 표시를 위한 포맷팅은 별도의 표현 영역에서 관리하는 것이 좋을 것 같습니다. 여러 프로젝트에서 공통으로 사용하는 가격 포맷팅 로직은 공용 패키지로 분리해 프로젝트별 중복 구현을 줄일 수 있을것 같습니다.
3. getter 추가 시 사용처까지 함께 리팩토링 새로운 getter를 추가할 때 기존에 동일한 값을 직접 계산하고 있는 사용처가 있는지 함께 확인해 VO에 정의된 계산 로직의 중복 구현을 방지합니다.
4. VO라는 이름과 실제 역할 사이의 간극 현재 저희 팀의 VO는 DDD의 Value Object와 달리 API 응답을 도메인 형태로 변환하는 역할과 도메인 로직을 함께 담당하고 있습니다. 프로젝트의 히스토리를 모르는 사람이 OptionVo와 같은 이름만 봤을 때, 일반적으로 알고 있는 Value Object를 기대할 가능성이 높습니다. 따라서 현재의 VO라는 네이밍이 실제 역할을 충분히 전달하고 있는지 검토해볼 필요가 있다고 생각합니다. 다만 이름을 변경하는 것보단 현재 VO가 어떤 책임을 가져야 하는지를 명확하게 정의하는 것이 더 중요합니다.

마치며

당연하게 쓰고 있던 VO를 다시 들여다보니, DDD의 정의와 일치하는지보다 지금 우리 VO가 어떤 역할을 하고 있고 그 역할에 맞는 기준을 가지고 쓰이는지가 더 중요하다는 생각이 들었습니다.

저희 팀의 VO는 DDD의 Value Object와 동일한 형태는 아니지만 나름의 명확한 역할을 가지고 있습니다. 팀 안에서 그 역할과 사용 기준이 합의되어 있다면, 이름이 무엇이든 충분히 유용한 도구가 될 수 있다고 생각합니다.

이번 글을 계기로 그 기준을 조금 더 명확하게 다듬어가려고 합니다.

읽어주셔서 감사합니다.