📏 자바스크립트와 Long 타입 ID (feat. NestJS)

최근 NestJS를 활용해 관리자 CMS 프로젝트를 진행하던 도중 백엔드 설계 시 고유 ID 값으로 BigInt를 사용할 때 발생할 수 있는 치명적인 자바스크립트 정밀도 유실 문제에 대해 알게 되었다.

당장 내 코드에서 에러가 나지 않더라도 서비스가 커져 ID 값이 커지는 순간 문제가 될 수 있기 때문에 왜 자바스크립트에서 큰 숫자를 다룰 때 문자열 처리가 필수인지 정리해보자.

1. 자바스크립트 숫자의 한계: IEEE 754 표준

자바스크립트는 정수(Int)와 실수(Float)의 구분 없이 모든 숫자를 64비트 부동 소수점(Double Precision) 형식으로만 저장한다. 이 표준(IEEE 754)에 따르면 64비트는 다음과 같이 배분된다.

• 부호 비트(1비트) : 양수와 음수를 결정
• 지수 비트(11비트) : 소수점의 위치를 결정
• 가수 비트(52비트) : 실제 숫자의 정밀도를 결정

여기서 핵심은 실제 정밀도를 담당하는 가수부가 52비트뿐이라는 점이다. 이로 인해 자바스크립트가 안전하게 표현할 수 있는 정수의 범위는 약 -0.9경 ~ 0.9경 사이로 제한된다.

Number.MAX_SAFE_INTEGER: 9,007,199,254,740,991 (약 0.9경)

반면 DB나 Java/NestJS에서 사용하는 64비트 Long(BigInt) 타입의 범위는 -922경 ~ 922경이다. 자바스크립트의 범위를 훨씬 초과한다.

2. 정밀도 손실이 부르는 에러

만약 서버가 안전 범위를 넘어서는 큰 숫자 ID를 그대로 보낸다면 어떻게 될까? 브라우저가 JSON을 파싱하는 순간 자바스크립트 엔진은 표현할 수 없는 하위 비트를 반올림하거나 버려버리게 된다.

서버가 보낸 값 = 9,223,372,036,854,775,807
브라우저가 받은 값 = 9,223,372,036,854,776,000 (값이 다름)

이러한 데이터 왜곡은 단순히 숫자가 틀리는 것을 넘어 잘못된 ID 참조로 인해 런타임 에러를 유발한다.

# 잘못된 ID로 인한 참조 에러 예시
Uncaught TypeError: Cannot read properties of null (reading 'id')

3. 해결 방법: 문자열 직렬화(Serialization)

이 문제를 방지하기 위해 가장 권장되는 설계 규약은 큰 숫자를 문자열로 변환하여 주고받는 것이다.

1. 데이터 무결성 유지: 문자열은 길이에 제한이 없어 서버의 64비트 정수를 1비트의 오차도 없이 그대로 보존한다.
2. 산술 연산의 불필요성: 고유 ID(PK)는 식별을 위한 값일 뿐 더하거나 빼는 등 산술 연산이 필요하지 않으므로 문자열이어도 기능상 문제가 없다.
3. 타입 안정성 확보: API 명세에 ID를 string으로 규정하면 프론트엔드와 백엔드 간에 데이터가 변질될 가능성을 사전에 차단하고 일관된 타입을 유지할 수 있다.

*NestJS에서는 class-transformer를 활용해 응답 DTO 단계에서 아주 간단하게 이 규칙을 적용할 수 있다.

import { Transform } from 'class-transformer';

export class PostResponseDto {
  @Transform(({ value }) => value?.toString()) // BigInt를 문자열로 변환하여 전송
  id: bigint;
}

이렇게 처리하면 서버 내부에서는 효율적인 BigInt를 사용하면서도 클라이언트에는 안전한 string 타입을 전달할 수 있다.

[Tip] 모든 응답에서 BigInt를 자동으로 문자열로 바꾸는 법

매번 DTO에 @Transform을 붙이는 것이 번거롭다면 main.ts 상단에 toJSON 프로토타입을 정의하여 전역적으로 문제를 해결할 수 있다.

// main.ts
if (!(BigInt.prototype as any).toJSON) {
  Object.defineProperty(BigInt.prototype, 'toJSON', {
    value() {
      return String(this);
    },
    configurable: true,
    enumerable: false,
    writable: true,
  });
}

이렇게 하면 전역적으로 모든 BigInt가 JSON 직렬화 시 문자열로 변환되어 정밀도 유실 문제를 원천 봉쇄할 수 있다.

단, 서버에서 보낼 때는 문자열로 자동 변환되지만 프론트엔드에서 문자열로 보낸 ID를 서버에서 숫자로 계산해야 한다면 BigInt()를 통해 숫자로 변환하는 과정이 필요하다.