[숫자 코드] 숫자에 의미를 부여하는 설계 전략

728x90

숫자 코드 

데이터를 다루는 거의 모든 시스템에는 숫자 코드(유효 숫자 코드)가 존재합니다. 사용자 상태, 주문 단계, 권한 등 다양한 정보를 0, 1, 2처럼 숫자로 표현하는 방식이죠. 이러한 숫자는 겉보기에 단순해 보이지만, 실제로는 시스템의 상태와 흐름을 효율적으로 제어하는 열쇠가 됩니다.

 

---

1.  숫자 코드란?

숫자 코드(Numeric Code)는 시스템 내에서 특정 상태, 역할, 분류 등을 숫자로 표현한 값입니다. 일반적으로 데이터베이스나 API 응답, enum 타입, 테이블 등에서 사용되며, 다음과 같은 장점이 있습니다:

• 데이터 저장 공간 절약
• 문자열 비교보다 빠른 성능
• 시스템 간 통신의 표준화
• 유지보수 시 코드 일관성 유지

 

---

2.  숫자 코드가 쓰이는 예시

사용자 권한 예시

권한 코드	권한 이름
0	일반 사용자
1	관리자
2	슈퍼 관리자

백엔드 API 응답 예시

{
  "userId": 1024,
  "role": 1
}

프론트엔드 처리 예시

const roleMap = {
  0: "일반 사용자",
  1: "관리자",
  2: "슈퍼 관리자"
};

console.log(roleMap[user.role]); // "관리자"

 

---

3.  왜 "유효 숫자 코드"인가?

실무에서 숫자 코드는 단순 숫자 이상으로, "의미가 있는 코드값"이라는 점에서 유효 숫자 코드(Valid Numeric Code)라고 부를 수 있습니다. 이는 "0", "1"처럼 보이지만 시스템 설계자 입장에서 의도와 의미가 명확히 부여된 숫자라는 뜻입니다.

유효하지 않은 숫자 코드는 다음과 같은 문제가 생깁니다.

• 의미 없는 숫자 나열 (ex: 1, 2, 3인데 각각이 뭘 의미하는지 없음)
• 문서화 부재
• 개발자 간 혼동
• 테스트 누락

 

---

4.  어떻게 설계해야 할까?

a.  명확한 문서화

숫자코드는 사람이 직관적으로 알기 어려우므로, 반드시 별도의 코드 테이블이나 주석, 위키 문서로 의미를 설명해야 합니다.

b.  코드 테이블 또는 주석으로 의미 명시

• 프론트, 백엔드, DB 모두 동일하게 참조 가능한 형태로 정의
• API 문서나 OpenAPI(Swagger)에도 명시

{
  "status": 2 // 2 = 배송중
}

const statusMap = {
  0: "주문 완료",
  1: "결제 완료",
  2: "배송 중",
  3: "배송 완료"
}

c.  Enum 사용 권장

• Java, TypeScript, Python 등에서 enum을 쓰면 자동완성, 유효성 검증, 가독성 향상

enum OrderStatus {
  ORDERED = 0,
  PAID = 1,
  SHIPPED = 2,
  DELIVERED = 3
}

d.  숫자 체계를 분할해 설계

• 100 단위 또는 범위 구분 사용 (ex: 1xx, 2xx)
• 예 : 100 = 사용자, 200 = 관리자, 300 = 시스템

 

---

5.  숫자 코드 vs 문자열 코드 - 언제 어떤 걸 써야 할까?

항목	숫자 코드	문자열 코드
저장 공간	작음	큼
성능	빠름 (정수 비교)	느림 (문자열 비교)
가독성	낮음 (의미를 외부에 명시해야)	높음
유지보수	enum 구조나 매핑 필요	의미가 코드에 포함됨
권장 사용 사례	상태 코드, 권한, DB 저장 등	국제화 메시지 키, UI 텍스트 등

 

---

6.  마무리

• 숫자 코드는 프론트-백-DB 간의 약속입니다. 반드시 일관되게 관리해야 합니다.
• Swagger나 API 문서에서 enum 설명을 추가합니다.
• 잘 설계된 숫자 코드는 상태 전이(State Transition)가 와도 연결됩니다.

숫자 코드는 단순히 숫자를 사용하는 것이 아니라, 의미 있는 구조로 시스템을 표현하는 도구입니다. 이를 유효 숫자 코드로 만들기 위해서는 명확한 정의, 매핑 테이블, enum 사용, 문서화를 함께 고려해야 하며, 이를 통해 시스템의 일관성과 유지보수성을 크게 높일 수 있습니다.

 

---

반응형