API 날짜 필터가 꼬일 때 먼저 볼 것

API에서 날짜를 다루다 보면 자주 꼬인다. 타임존, 형식, 요청/응답의 불일치 같은 것들. 한 번 터지면 원인을 좁히기가 정말 어렵다.

처음부터 정답을 맞히려고 하면 오히려 시간이 더 걸린다. 차라리 눈으로 확인할 수 있는 값부터 모아서 천천히 좁혀나가는 게 낫다.

먼저 요청/응답 흐름을 끊어서 본다

클라이언트가 보내는 쿼리 문자열을 먼저 확인하자.

# 클라이언트가 실제로 보낸 요청 보기
curl -i 'https://api.example.com/events?startDate=2024-01-15T00:00:00Z&endDate=2024-01-20T23:59:59Z'
# 응답 헤더와 body를 모두 본다

요청 시점에 보낸 날짜 문자열 그대로를 확인해야 한다. 브라우저 DevTools에서도 Network 탭을 보면 된다. 중요한 건 "추측"하지 말고 "실제 값"을 기록하는 것.

데이터베이스에 들어간 값을 직접 확인한다

그다음은 DB에 저장된 데이터를 본다.

# 해당 레코드의 날짜 컬럼을 ISO 문자열로 뽑기
SELECT id, created_at::text, updated_at::text FROM events
WHERE id = 'abc123' LIMIT 1;

# 또는 타임존 정보까지 본다
SELECT id, created_at AT TIME ZONE 'UTC' AS utc_time FROM events LIMIT 1;

로그에만 의존하지 말고 직접 쿼리를 날려서 값을 본다. DB가 저장한 값과 API가 응답한 값이 같은지 확인하자.

응답 형식을 체크한다

응답 body에서 날짜가 어떤 형식인지 본다.

{
  "id": "event-1",
  "createdAt": "2024-01-15T14:30:00Z",
  "startDate": "2024-01-20T00:00:00.000Z",
  "endDate": "2024-01-25T23:59:59.999Z"
}

형식이 뒤바뀌거나, 타임존 정보가 빠져있거나, 밀리초 자릿수가 다르면 클라이언트에서 파싱할 때 문제가 생긴다.

같은 데이터를 로컬에서 재현해본다

# 정상적인 필터 조건이라고 알려진 값으로 요청해본다
POST /api/events/filter
Content-Type: application/json

{
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-01-31T23:59:59Z"
}

로컬 개발 환경에서는 같은 조건으로 정상 응답이 나오는데 배포 환경에서만 다르게 나온다면, 환경 설정(타임존, 데이터베이스 인코딩)을 의심해봐야 한다.

체크리스트

1. 요청 쿼리 문자열을 curl로 그대로 복사해서 테스트한다
2. DB에 저장된 실제 값(타임존 포함)을 직접 SELECT로 확인한다
3. API 응답의 날짜 포맷을 확인한다(Z인지, +00:00인지, 밀리초 있는지)
4. 로컬과 배포 환경의 시스템 타임존이 같은지 확인한다
5. ORM이 날짜를 변환할 때 설정을 확인한다

날짜 버그는 한 번에 여러 계층이 엮여있어서 원인 추적이 어렵다. 하지만 요청-DB-응답 흐름을 명확히 기록해두면 다음 번에는 훨씬 빠르게 해결할 수 있다.