SI 프로젝트를 하다보면 거의 무조건 만나는 테이블이 있다.
바로 공통그룹코드랑 공통코드 테이블이다.

보통 아래처럼 테이블 두개를 세트로 묶어서 많이 써왔고 지금도 대부분의 SI 현장에서는 이렇게 쓰는거 같다.

TB_CMMN_GRP_CD (공통그룹코드)

  • GRP_CD VARCHAR(20) (PK)
  • GRP_CD_NM VARCHAR(100)
  • USE_YN CHAR(1)
  • REG_DT DATETIME

TB_CMMN_CD (공통상세코드) (1:N 관계)

  • GRP_CD VARCHAR(20) (PK, FK)
  • DTL_CD VARCHAR(20) (PK)
  • DTL_CD_NM VARCHAR(100)
  • SORT_ORD INT
  • USE_YN CHAR(1)

주문 상태나 결제 수단 같은걸 전부 저 테이블에 밀어넣고 화면에 뿌릴때는 공통코드 테이블을 조인하거나 서브쿼리로 코드명을 가져오는 식이다.
어드민 화면에서 코드 하나 추가하면 배포 없이 셀렉트박스에 바로 나오는 장점은 있는데 막상 개발할때는 불편한 점이 한두개가 아니었다.

가장 답답했던건 코드만 봐서는 이게 무슨 값인지 알수가 없다는 점이다.

// 01이 결제대기인지 결제완료인지 DB를 안열어보면 모른다
if ("01".equals(order.getStatusCd())) {
    // ...
}

비즈니스 로직에 "01", "02" 같은 문자열이 그대로 박히다보니 항상 DB를 열어보거나 정의서를 찾아봐야 했다.
게다가 개발DB에는 코드를 넣어놓고 운영DB에 insert 스크립트 치는걸 까먹어서 장애가 나는 일도 심심치 않게 봤다.

서비스 기업이나 사이드 프로젝트에서 본 Enum 방식

그러다 서비스 기업 코드나 사이드 프로젝트들을 보게 됐는데 여기서는 상태값을 DB 공통코드 테이블에 넣지 않고 그냥 코드 레벨의 Enum으로 관리하는걸 발견했다.

public enum OrderStatus {
    PENDING("결제대기"),
    PAID("결제완료"),
    CANCELLED("주문취소");

    private final String description;

    OrderStatus(String description) {
        this.description = description;
    }

    public String getDescription() {
        return description;
    }
}

이렇게 써보니 확실히 DB에 종속적이지 않고 훨씬 좋다는 생각이 들었다.
일단 IDE에서 자동완성이 되니까 오타가 날 일이 없고 "01" 대신 OrderStatus.PAID처럼 이름이 명확하게 보이니 코드 읽기가 엄청 편해졌다.
특히 상태값에 따라 분기 치거나 상태 변경 가능 여부를 체크하는 로직도 Enum 안에 메서드로 같이 묶어둘수 있어서 객체지향적으로도 훨씬 깔끔했다.

더 찾아보다가 발견한 IDL 방식

그럼 Enum이 무조건 끝판왕인가 싶어서 나중에 AI랑 같이 이것저것 열심히 리서치를 좀 더 해봤다.
그랬더니 서비스가 커지고 서버가 여러개로 쪼개지는 환경에서는 Enum만으로는 안되는 지점이 있었다.

자바 서버 하나만 있을때는 Java Enum으로 충분한데 만약 백엔드에 Python이나 Go 서버가 섞여있거나 프론트엔드랑 같은 상수랑 데이터 규격을 공유해야 한다면 결국 각 언어마다 똑같은 Enum을 중복으로 만들어야 한다.
한쪽에서 상태값이 추가됐는데 다른 서버에 반영을 안하면 그대로 문제가 터지는 구조다.

이걸 해결하는 더 발전된 방식으로 특정 백엔드 언어에 종속적이지 않은 .idl이나 .proto 같은 스키마 정의 방식을 발견했다.

syntax = "proto3";

package order.v1;

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_PAID = 2;
  ORDER_STATUS_CANCELLED = 3;
}

찾아보니 이런 방식을 쓰는 곳들은 아예 서비스 코드랑 분리해서 IDL 저장소만 따로 판다는걸 확인했다.
특정 언어에 묶이지 않는 중립적인 파일로 데이터 구조랑 공통 상수를 정의해두고 각 프로젝트에서 가져다 쓰는 구조다.

직접 테스트 삼아 사용해보니 가져다 쓰는 쪽에서 IDL에 정의되어 있는걸 공통으로 쓰기가 아주 좋았다.
특히 서버가 여러개로 나뉘는 MSA 환경에서 서로 통신할때 데이터 규격이나 상태코드를 맞추기에 이만한게 없는거 같다.

실무에서는 IDL을 어떻게 굴릴까

처음에는 “그럼 개발할때마다 각자 로컬에서 IDL 파일 가져와서 컴파일 명령어 치고 코드 생성해야 하나?” 싶었는데 실무에서 쓰는 방식을 찾아보니 훨씬 체계적이었다.
실무에서는 IDL로 생성된 코드를 사내 패키지 저장소에 등록해두고 그냥 일반 라이브러리 쓰듯이 가져다 쓴다는걸 알게 됐다.

흐름을 정리해보면 대충 이렇다.

  1. IDL 전용 Git 저장소에 누군가 스키마를 수정해서 PR을 올린다
  2. CI 파이프라인에서 buf.build 같은 툴을 돌려서 스키마 문법 린팅을 하고 기존에 쓰던 필드를 지우거나 타입을 바꿔서 하위호환성이 깨지지는 않았는지 자동으로 검사한다
  3. 이상이 없어서 main 브랜치에 머지되면 CI가 자동으로 각 언어별(Java, Go, TypeScript 등) 코드를 빌드해서 Nexus나 GitHub Packages 같은 사내 패키지 저장소에 버전업해서 배포한다
  4. 각 서버 개발자는 직접 IDL을 컴파일할 필요 없이 그냥 build.gradle이나 package.json에서 라이브러리 버전만 올려서 import해서 쓴다

이렇게 파이프라인을 구축해두면 개발자는 그냥 라이브러리 하나 불러오는 감각으로 타입이랑 공통코드를 안전하게 쓸수 있다.

API를 넘어서 이벤트와 프론트 병렬 개발까지

더 파보다보니 이 IDL을 단순히 서버 간 API 호출에만 쓰는게 아니었다.

Kafka나 RabbitMQ 같은 메시지 브로커를 쓸때도 이벤트 페이로드 규격을 IDL에 정의해서 쓴다고 한다.
원래 이벤트 메시지는 JSON 문자열로 주고받다보면 프로듀서가 필드 이름을 바꿨을때 컨슈머 쪽에서는 런타임에 메시지 까보기 전까지 에러를 알기가 힘든데 IDL로 묶어버리면 컴파일 시점에 바로 잡을수 있다.

그리고 활용법 중에 꽤 인상 깊었던게 두가지 더 있었다.

  • IDL 정의만 잘 해두면 거기서 Swagger(OpenAPI) 같은 API 문서를 자동으로 뽑아내서 문서화 용도로 그대로 사용할수 있다
  • 백엔드 API가 아직 구현이 안됐을때도 선행으로 프론트랑 백엔드가 IDL 명세만 먼저 합의해두면 그걸 기반으로 Mock 서버를 바로 띄울수 있다. 그러면 백엔드 개발이 끝날때까지 기다릴 필요 없이 프론트엔드도 병렬로 개발 작업을 진행할수 있다고 한다

정리

처음 SI에서 당연하게 쓰던 DB 공통코드 테이블부터 시작해서 Java Enum을 거쳐 MSA 환경의 IDL까지 쭉 찾아봤다.
무조건 최신 방식이 정답은 아니겠지만 시스템 규모가 커지고 여러 언어나 팀이 얽힐수록 “DB에 넣어두고 조인하자"에서 “코드와 타입으로 규격을 강제하고 자동화하자"는 방향으로 발전해왔다는게 꽤 흥미로웠다.