Ch01. 공통 코드 설계 - 공통 코드가 필요한 이유

공통 코드가 필요한 이유?

데이터베이스를 설계하다 보면 비슷한 종류의 데이터가 여러 테이블에 걸쳐 반복되는 상황을 자주 만난다. 예를 들어 주문 상태, 회원 등급, 결제 방법 같은 것들이다. 이런 데이터를 어떻게 관리해야 할까? 먼저 문제 상황부터 살펴보자.

 

문제 상황 - 하드코딩된 상태값

쇼핑몰을 운영한다고 가정하자. 주문 테이블에는 주문 상태가 필요하다. 가장 단순한 방법은 상태값을 문자열로 직접 저장하는 것이다.

DROP TABLE IF EXISTS orders;
CREATE TABLE orders (
	order_id BIGINT PRIMARY KEY AUTO_INCREMENT,
	member_id BIGINT NOT NULL,
	order_status VARCHAR(20) NOT NULL,
	total_amount INT NOT NULL,
    created_at DATETIME NOT NULL
);

INSERT INTO orders (member_id, order_status, total_amount, created_at) VALUES
(1, '주문완료' , 50000, '2026-01-15 10:30:00'),
(2,'결제완료', 75000, '2026-01-15 11:00:00'),
(3, '배송중', 30000, '2026-01-15 12:00:00'),
(1,'배송완료', 120000, '2026-01-14 09:00:00'),
(4,'주문취소', 45000, '2026-01-13 15:00:00');

select *
from orders;

쿼리 결과

• 언뜻 보기에는 문제가 없어 보이나, 실무에서 이 방식을 사용하면 여러 가지 문제가 생긴다.

문제 1: 데이터 불일치

개발자 A는 주문 상태를 "주문완료"로 입력하고, 개발자 B는 "주문 완료"(띄어쓰기 포함)로 입력한다. 또 다른 개발자 C는 "ORDER_COMPLETE"로 입력한다.

INSERT INTO orders (member_id, order_status, total_amount, created_at) VALUES
(5,'주문 완료', 80000, '2026-01-16 10:00:00'),
(6, 'ORDER_COMPLETE', 65000, '2026-01-16 11:00:00');

select 
	order_id,
    order_status
from orders
where order_status = '주문완료';

쿼리 결과

• 같은 의미인데 서로 다른 값이 저장되었다.
• 분명히 3건이 주문완료 상태인데, 1건만 조회된다. 데이터 불일치로 인해 비즈니스 로직에 오류가 발생한 것이다.

문제 2: 오타로 인한 버그

상태값을 직접 문자열로 입력하면 오타가 발생할 수 있다.

INSERT INTO orders (member_id, order_status, total_amount, created_at) VALUES
(7,'배송증', 55000, '2026-01-17 09:00:00'); -- '배송중'을 '배송증'으로 오타

• 이 데이터는 정상적으로 저장된다.
  • 데이터베이스는 "배송증"이 오타인지 알 수 없기 때문이다.
• 이런 오타는 나중에 발견하기 매우 어렵고, 발견하더라도 이미 많은 데이터가 잘못 저장된 후일 수 있다.

문제 3: 상태 변경의 어려움

기획팀에서 "주문완료"라는 단어가 명확하지 않다고 앞으로는 "주문완료"라는 단어 대신에 "주문성공"이라는 단어로 상태를 변경하자고 요청한다. 이 경우 이미 저장된 모든 데이터를 UPDATE 해야 한다.

SET SQL_SAFE_UPDATES = 0; -- 안전 업데이트 모드 끄기
UPDATE orders SET order_status = '주문성공' 
WHERE order_status ='주문완료';
SET SQL_SAFE_UPDATES = 1; -- 안전 업데이트 모드 활성화

• 데이터가 수백만 건이라면?
  • 이 UPDATE 문은 매우 오래 걸리고, 그 동안 테이블에 락이 걸려 서비스에 영향을 줄 수 있다.
• 그리고 앞서 본 것처럼 "주문 완료"(띄어쓰기 포함), "ORDER_COMPLETE" 같은 변형된 데이터는 UPDATE 되지 않는다.

문제 4: 표시 이름과 코드값의 혼재

• 화면에 표시되는 이름을 데이터베이스에 직접 저장하면 또 다른 문제가 생긴다.
• 만약 영어 서비스를 추가해야 한다면?
  • "주문완료"를 "Order Complete"로 표시해야 하는데, 데이터베이스에 한글로 저장되어 있으면 처리가 복잡해진다.

해결책 - 코드값 분리

이 문제들을 해결하려면 코드값과 표시 이름을 분리해야 한다. 데이터베이스에는 코드값만 저장하고, 화면에 표시할 이름은 별도로 관리하는 것이다.

DROP TABLE IF EXISTS orders;
CREATE TABLE orders (
	order_id BIGINT PRIMARY KEY AUTO_INCREMENT,
	member_id BIGINT NOT NULL,
	order_status VARCHAR(20) NOT NULL,
	total_amount INT NOT NULL,
	created_at DATETIME NOT NULL
);

INSERT INTO orders (member_id, order_status, total_amount, created_at) VALUES
(1, 'ORDER', 50000, '2026-01-15 10:30:00'),
(2, 'PAID', 75000, '2026-01-15 11:00:00'),
(3, 'SHIPPING', 30000, '2026-01-15 12:00:00'),
(1, 'DELIVERED', 120000, '2026-01-14 09:00:00'),
(4, 'CANCEL', 45000, '2026-01-13 15:00:00');

SELECT * FROM orders;

쿼리 결과

• 이번에는 상태값을 영문 코드로 저장한다.
• 그리고 코드값과 표시 이름의 매핑 정보는 별도로 관리한다.
  • 이 매핑 정보를 어디에 저장할까? 바로 공통 코드 테이블이다.

공통 테이블 예시

 

공통 코드란?

공통 코드(Common Code)는 시스템 전체에서 사용하는 코드값과 그에 대응하는 이름을 중앙에서 관리하는 방식이다. 코드값은 데이터베이스에 저장되고, 표시 이름은 공통 코드 테이블에서 조회한다. 공통 코드를 사용하면 다음과 같은 이점이 있다.

• 데이터 일관성 보장
  • 정해진 코드값만 사용하도록 강제할 수 있다.
  • 개발자가 임의로 다른 값을 넣을 수 없다.
• 표시 이름 변경 용이
  • "주문접수"를 "주문완료"로 변경하고 싶다면, 공통 코드 테이블의 이름만 수정하면 된다.
  • 실제 데이터가 저장된 주문 테이블은 건드리지 않아도 된다.
• 다국어 지원 용이
  • 한글 이름, 영문 이름 등을 공통 코드 테이블에서 관리하면 다국어 지원이 쉬워진다.
• 중앙 집중 관리
  • 모든 코드값을 한 곳에서 관리하므로, 어떤 코드값들이 있는지 한눈에 파악할 수 있다.
  • 새로운 개발자가 투입되어도 공통 코드 테이블만 보면 시스템에서 사용하는 코드값들을 쉽게 이해할 수 있다.

 

공통 코드가 필요한 대표적인 경우

• 상태값
  • 주문 상태: ORDER, PAID, SHIPPING, DELIVERED, CANCEL
  • 회원 상태: ACTIVE, DORMANT, WITHDRAWN
  • 결제 상태: PENDING, COMPLETE, FAILED, REFUND
• 유형/종류
  • 회원 유형: NORMAL, VIP, VVIP
  • 상품 유형: PHYSICAL, DIGITAL, SUBSCRIPTION
  • 결제 수단: CARD, BANK, VIRTUAL, MOBILE
• 카테고리성 데이터
  • 배송 방법: QUICK, PICKUP
  • 문의 유형: PRODUCT, DELIVERY, REFUND, ETC
• 기타 코드성 데이터
  • 성별: MALE, FEMALE
  • 요일: MON, TUE, WED, THU, FRI, SAT, SUN

 

하드코딩된 문자열로 상태값이나 유형을 관리하면 데이터 불일치, 오타로 인한 버그, 변경의 어려움 등 다양한 문제가 발생한다. 공통 코드를 도입하면 이러한 문제들을 해결하고, 코드값을 중앙에서 일관되게 관리할 수 있다.