오해 없는 소통을 위한 명확한 인터페이스 만들기

들어가며

안녕하세요. 노머스에서 백엔드 서비스를 개발하고 있는 유근수라고 합니다.

프롬스토어가 오픈 된지도 꽤 오랜 시간이 지났습니다.

프롬스토어는 여타 다른 커머스와 마찬가지로 다양한 제품들을 판매하며, 그 중 배송이 필요한 제품들은 국가별/제품별로 다양한 배송비 정책을 적용해야 했습니다.

주요 정책으로는 고정 배송비 정책 / 무게별 배송비 정책 / 수량별 배송비 정책 등이 있고, 배송비 계산 모듈에 전략 패턴을 적용하여 개발을 했습니다.

기존 배송비 계산 interface

배송비 계산을 위한 interface는 대략 아래와 같습니다.
배송비 계산이 필요한 상품들을 가지고 있는 items, 배송할 국가 정보와 함께, 해당 상품들에 적용할 배송 정책 strategy를 넘겨서 배송비를 계산하게 됩니다.

interface DeliveryItemType {
    id: number;
    weight: number;
    amount: number;
    deliveryPolicyId: number;
}

interface DeliveryFeeType {
    items: DeliveryItemType[];
    countryCode: Country;
}

class DeliveryFeeCalculator {
    calculateDeliveryFee(deliveryItems: DeliveryFeeType, strategy: Strategy<UnionDeliveryPolicy>) {
        return strategy.calculate(deliveryItems);
    }
}

각 전략 객체들은 해당 정책에 맞게 배송비 계산을 하게 됩니다.

// 수량별 배송비 정책
class DiffAmountRangeStrategy implements Strategy<DiffAmountRangePolicy> {
    calculate(deliveryItems: DeliveryFeeType) {
        ...
    }
}

// 무게별 배송비 정책
class DiffWeightRangeStrategy implements Strategy<DiffWeightRangePolicy> {
    calculate(deliveryItems: DeliveryFeeType) {
        ...
    }
}

오해의 시작

그렇게 시간이 지나고, 무게별 배송비 정책 계산에 추가 배송비를 부과해야 하는 요구사항이 생겼습니다.

전략 객체로 구현했기 때문에, 무게별 배송비 정책 class만 수정하면 문제없이 요구사항을 구현할 수 있을거라 생각했고,
공통으로 사용하고 있던 DeliveryItemType 에 추가 배송비 계산에 필요한 extraDeliveryPolicyId를 추가했습니다.

export interface DeliveryItemType {
    id: number;
    weight: number; // 무게
    amount: number; // 수량
    deliveryPolicyId: number; // 배송비 정책
    extraDeliveryPolicyId?: number; // 추가 배송비 정책
}

그렇게 구현을 하는 중에, 기존 코드에서 상품들의 총 무게를 계산하는 부분에 버그가 있는 것을 발견했습니다.

interface를 보면, 각 상품 별로 weight 와 amount를 전달하고 있는데, 상품별 수량은 무시하고 무게만 더해서 계산을 하고 있었습니다. 500g 짜리 상품 5개, 300g 짜리 상품 3개를 사면, 3400g이 되어야 하는데, 800g 으로 계산하고 있었던 것이었습니다.

// 무게별 배송비 정책
class DiffWeightRangeStrategy implements Strategy<DiffWeightRangePolicy> {
    calculate(deliveryItems: DeliveryFeeType) {
        const totalWeight = deliveryItems.items.reduce(
            (prev, cur) => prev + cur.weight,
            0
        )
    }
}

그래서 빠진 부분을 수정하고 테스트를 해보니 배송비가 이상하게 많이 나왔습니다.

알고보니, deliveryItems로 넘기는 weight 는 이미 해당 상품의 weight * amount 로 계산이 끝난 상태로 넘기고 있었습니다.
버그인줄 알았던 부분이 버그가 아니고 구현은 문제없이 잘되어 있었습니다.

개발하는 당시에는 해당 interface의 weight 에 이미 amount가 곱해져 있다는 것과, DiffAmountRangeStrategy 에서는 interface에 있던 amount는 사용하지 않는다는 사실을 잘 인지하고 있었지만,
시간이 흐르고 코드의 일부만 보면서 interface를 봤을때는 그 기억을 잃어버린 상태였습니다.

새로운 배송비 계산 interface

오해의 소지를 제거하기 위해 하나로 정의했던 interface를 각 정책의 type별로 분리하고,
weight 대신 weightSum 이라는 명칭으로 변경했습니다.

interface DeliveryFeeDiffAmountType {
    id: number;
    amount: number;
    deliveryPolicyId: number;
}

interface DeliveryFeeDiffWeightType {
    id: number;
    weightSum: number; // weight * amount
    deliveryPolicyId: number;
    extraDeliveryPolicyId: number;
}

interface UnionDeliveryFeeType {
    items: Array<DeliveryFeeDiffAmountType | DeliveryFeeDiffWeightType>;
    countryCode: Country;
}

변경된 interface를 적용한 코드는 아래와 같습니다.

// deliveryItems를 UnionDeliveryFeeType으로 변경
class DeliveryFeeCalculator {
    calculateDeliveryFee(deliveryItems: UnionDeliveryFeeType, strategy: Strategy<UnionDeliveryPolicy>) {
        return strategy.calculate(deliveryItems);
    }
}

// 무게별 배송비 정책
class DiffWeightRangeStrategy implements Strategy<DiffWeightRangePolicy> {
    calculate(deliveryItems: {items: DeliveryFeeDiffWeightType[]; countryCode: Country}) {
        const totalWeight = deliveryItems.items.reduce(
            (prev, cur) => prev + cur.weightSum,
            0
        )
    }
}

결론

개발 당시에는 잘 이해하고 있었던 코드도 시간이 지나면 기억이 희미해지는 경우가 많은 것 같습니다.
그 당시에는 너무나 당연해보였던 로직이나 코드도 그렇지 않은 경우도 많고 놓치는 부분들도 생기는 것 같습니다.

특히 interface를 정의할 때는 시간이 흘러도 바로 이해할 수 있도록 정확하게 표현해주는 게 중요한 것 같습니다.

어쩔 수 없이 코드만으로 명확하게 표현하기 어려운 경우에는, 주석이라도 잘 남겨놓는 게 필요한 것 같습니다.

끝까지 읽어주셔서 감사합니다~ 😆