본문으로 건너뛰기

데이터 타입 가이드라인

1. 시간 데이터 처리​

1.1 데이터베이스 저장​

모든 시간 관련 필드는 PostgreSQL의 timestamptz (timestamp with time zone) 타입을 사용합니다.

CREATE TABLE example (
  id UUID PRIMARY KEY,
  created_at TIMESTAMPTZ NOT NULL,
  updated_at TIMESTAMPTZ NOT NULL
);

장점:

  • 시간대 정보 보존
  • 일광 절약 시간(DST) 자동 처리
  • 시간대 변환 용이
  • 데이터 정확성 보장

1.2 애플리케이션 레벨​

TypeScript/JavaScript에서는 Date 타입으로 처리합니다.

interface BaseEntity {
  createdAt: Date;
  updatedAt: Date;
}

처리 방식:

  • 데이터베이스에서는 UTC로 저장
  • 애플리케이션에서 필요한 시간대로 변환하여 사용
  • 시간대 변환은 가능한 표시 계층(Presentation Layer)에서 처리

1.3 API 응답​

클라이언트와의 호환성을 위해 모든 시간 데이터는 13자리 Unix timestamp (밀리초)로 변환하여 전송합니다.

interface ApiResponse {
  createdAt: number; // 13자리 Unix timestamp (밀리초)
  updatedAt: number; // 13자리 Unix timestamp (밀리초)
}

예시:

{
  "createdAt": 1711929600000,
  "updatedAt": 1711929600000
}

1.4 시간대 처리​

  • 서버 시간대: UTC 사용
  • 클라이언트 표시: 사용자의 로컬 시간대로 변환
  • API 문서: 모든 시간값은 Unix timestamp (밀리초) 형식으로 명시

2. 구현 가이드​

2.1 데이터베이스 모델 (Prisma)​

model Example {
  id        String   @id @default(uuid())
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

2.2 API 응답 변환​

import { Exclude, Expose, Transform } from 'class-transformer';

export class BaseResponseDto {
  @Transform(({ value }) => value.getTime())
  createdAt: Date;

  @Transform(({ value }) => value.getTime())
  updatedAt: Date;
}

2.3 시간 변환 유틸리티​

export const dateUtils = {
  toUnixTimestamp: (date: Date): number => date.getTime(),
  fromUnixTimestamp: (timestamp: number): Date => new Date(timestamp),
  toUserTimezone: (date: Date, timezone: string): Date => {
    // 사용자 시간대로 변환하는 로직
    return new Date(date.toLocaleString('en-US', { timeZone: timezone }));
  }
};

3. 주의사항​

  • 시간 데이터를 문자열로 저장하지 않습니다.
  • 클라이언트에서 시간 변환 시 라이브러리(예: moment.js, date-fns) 사용을 권장합니다.
  • 백엔드에서는 항상 UTC 기준으로 처리하고, 표시용 변환은 프론트엔드에 위임합니다.
  • 배치 작업 등에서 시간 비교 시 시간대를 반드시 고려합니다.