ISO 8601 기준으로 특정 날짜의 N월 N주차를 Java 8 날짜 API로 구하기

ISO 8601 란 ?

ISO 8601은 날짜와 시간에 관련된 국제 표준으로써, 정의된 바에 따르면 매주의 시작일은 월요일이 됩니다.
또한, 매월의 첫 주는 과반수 이상의 요일이 포함된 주가 기준이 됩니다.
 

ISO 8601 기준으로 주차 계산 예시

2024년 12월 예시

• 2024년 12월 30일, 31일은 다음과 같은 규칙을 따릅니다.
  • 2025년 1월 1~5일(총 5일)은 7일 중 과반수를 넘으므로 1월 1주차입니다
  • 따라서, 2024년 12월 30일, 31일은 2025년 1월 1주차에 포함됩니다

2024년 12월 달력

12월 2일 ~ 12월 8일 -> 12월 1주차
12월 9일 ~ 12월 15일 -> 12월 2주차
12월 16일 ~ 12월 22일 -> 12월 3주차
12월 23일 ~ 12월 29일 -> 12월 4주차
12월 30일 ~ 1월 5일 -> 1월 1주차

 
2026년 12월 예시

• 2027년 1월의 첫 주는 1~3일(총 3일)로 구성되며, 이는 7일 중 과반수가 되지 않으므로 12월 5주차에 포함됩니다.
• 그래서, 12월 28일 ~ 1월 3일까지는 12월 5주차이며 1월 4일(월요일)부터 1월 1주차가 됩니다.

2026년 12월 달력

 
 

특정 날짜의 N월 N주차 구하는 방법

ISO 8601 기준에서 매주 월요일이 시작일, 일요일이 마지막 날로 고정됩니다.
그래서, 특정 날짜가 포함된 주의 중간일(목요일)이 어떤 달에 속하는지 알면 특정 날짜의 주차를 구할 수 있다고 생각했습니다.

• 주의 중간일(목요일)이 해당 월에 속하면 그 주는 해당 월의 마지막 주차로 판단합니다.
• 반대로 중간일(목요일)이 다음 월에 속하면 그 주는 다음 월의 첫 주차로 판단합니다.

그래서, 몇월 몇주차를 다음과 같은 방법으로 구했습니다.
 
1. 특정 날짜가 포함된 주의 월요일 구하기

• TemporalAdjusters.previousOrSame()를 사용하여 해당 주의 월요일(LocalDate)을 구합니다.

2. 중간일(목요일) 구하기

• 구한 월요일에 plusDays(3)를 더해 중간일(목요일)을 계산합니다.

3. 중간일(목요일)에 해당하는 월 확인하기

• LocalDate.getMonthValue()로 중간일의 월을 확인합니다.

4. 중간일이 ISO 기준 몇 주차인지 확인

• WeekFields.ISO.weekOfMonth()를 사용해 ISO 기준 주차를 구합니다.
• WeekFields.ISO는 WeekFields.of(DayOfWeek.MONDAY, 4)로 구현되어 있습니다.

전체 테스트 코드입니다.

@DisplayName("2024년 12월 31일은 ISO 기준으로 1월 1주차이다.")
@Test
void ISO_기준으로_특정날짜에대해_몇월_몇주차를_구한다() {
    // given
    LocalDate target = LocalDate.of(2024, 12, 31);
    LocalDate startOfWeek = target.with(TemporalAdjusters.previousOrSame(DayOfWeek.MONDAY)); // 해당 주 월요일
    LocalDate endOfWeek = target.with(TemporalAdjusters.nextOrSame(DayOfWeek.SUNDAY)); // 해당 주 일요일
    LocalDate middleOfWeek = startOfWeek.plusDays(3);  // 해당 주의 중간일

    // when
    int monthValue = middleOfWeek.getMonthValue();
    int isoWeekValue = middleOfWeek.get(WeekFields.ISO.weekOfMonth());

    //then
    Assertions.assertThat(startOfWeek).isEqualTo(LocalDate.of(2024, 12, 30));
    Assertions.assertThat(endOfWeek).isEqualTo(LocalDate.of(2025, 1, 5));
    Assertions.assertThat(monthValue).isEqualTo(1);
    Assertions.assertThat(isoWeekValue).isEqualTo(1);

    System.out.println("해당 날짜가 포함된 주의 월요일: " + startOfWeek);  // 12월 30일
    System.out.println("해당 날짜가 포함된 주의 일요일: " + endOfWeek);    // 1월 5일
    System.out.println("해당 날짜의 몇 월: " + monthValue);        // 1월
    System.out.println("해당 날짜의 몇 주차: " + isoWeekValue);    // 월 기준으로 1주차 (1~5의 값 중 하나)
    System.out.println(target.get(WeekFields.ISO.weekOfWeekBasedYear()));  // 년 기준으로 N주차 (1~53의 값 중 하나)
}

 
이를 응용해서 2024년 11월 16일을 기준으로 전 4개 주차의 시작일, 마지막일, N월, N주차를 구해보겠습니다.

@DisplayName("24년 11월 16일 기준으로 4주차의 시작일,마지막일,몇월,몇주차 를 구한다.")
@Test
void test() {
    // given
    LocalDate today = LocalDate.of(2024, 11, 16);

    List<WeeklyDate> weeklyDates = IntStream.rangeClosed(1, 4)
           .mapToObj(i -> {
               LocalDate minusDate = today.minusDays((long) i * 7);
               LocalDate firstOfWeek = 
                                  minusDate.with(TemporalAdjusters.previousOrSame(DayOfWeek.MONDAY));
               LocalDate lastOfWeek = minusDate.with(TemporalAdjusters.nextOrSame(DayOfWeek.SUNDAY));
               LocalDate middleOfWeek = firstOfWeek.plusDays(3);

              return new WeeklyDate(
                       firstOfWeek,
                       lastOfWeek,
                       middleOfWeek.getMonthValue(),
                       middleOfWeek.get(WeekFields.ISO.weekOfMonth())
               );
           })
           .sorted()
           .collect(Collectors.toList());

    for (WeeklyDate weeklyDate : weeklyDates) {
        System.out.println("weeklyDate = " + weeklyDate);
    }
}

static class WeeklyDate implements Comparable<WeeklyDate> {
   LocalDate startDate;
   LocalDate endDate;
   int monthValue;
   int weekNumber;

   public WeeklyDate(LocalDate startDate, LocalDate endDate, int monthValue, int weekNumber) {
       this.startDate = startDate;
       this.endDate = endDate;
       this.monthValue = monthValue;
       this.weekNumber = weekNumber;
   }

   @Override
   public int compareTo(@NotNull WeeklyTest.WeeklyDate o) {
        return startDate.compareTo(o.startDate);
   }

   @Override
   public String toString() {
        return "WeeklyDate{" +
               "startDate=" + startDate +
               ", endDate=" + endDate +
               ", month=" + month +
               ", weekNumber=" + weekNumber +
               '}';
   }
}

 
시작일은 월요일, 마지막일은 일요일, 몇월 몇주차에 해당하는 값이 총 4개가 잘 나온것을 확인할 수 있습니다.

 
 

WeekFields 클래스 설명

WeekFields 클래스는 Java 8에서 도입된 클래스이며, 특정 문화권 또는 표준에 따라 주(week)를 정의하고 관리하기 위한 클래스입니다.
 

• 지역화된 주 정의(Localization)
  • 서로 다른 문화권에서는 주의 시작 요일과 첫 번째 주를 정의하는 방식이 다릅니다.
  • WeekFields는 이러한 차이를 반영하여 주의 정의를 맞춤 설정할 수 있도록 합니다.
  • WeekFields.of(new Locale("ko", "KR") 을 사용하면 한국 문화권에서의 시작 요일과 첫번째 주 규칙을 따릅니다.
  • ko 와 KR 같이 정의하고 싶은 언어와 나라를 알고 싶다면 Locale[] locales = Locale.getAvailableLocales(); 을 사용하면 됩니다.
• Thread-Safe 및 Immutable
  • 이 클래스는 불변(Immutable)이며, 다중 스레드 환경에서도 안전하게 사용할 수 있습니다.
• ISO-8601 표준과의 호환성
  • ISO-8601 표준에서 주의 시작 요일은 월요일이며, 첫 번째 주는 최소 4일을 포함해야 한다는 기준을 따릅니다.
  • WeekFields를 통해 이러한 기준뿐만 아니라 다른 기준도 정의할 수 있습니다.
  • 예를 들어, 일요일부터 최소 3일을 포함하면 유효한 주라고 보고싶다면 WeekFields.of(DayOfWeek.SUNDAY, 3) 로 생성한다음 LocalDate.get() 의 파라미터에 주입하면 됩니다.

TemporalAdjuster 클래스 설명

TemporalAdjuster는 Java8의 java.time 패키지에 속하며, 날짜와 시간을 조정하기 위한 인터페이스입니다.
이를 통해 Temporal 객체(예: LocalDate, LocalDateTime)를 다양한 방식으로 수정할 수 있습니다.

• previous(DayOfWeek): 항상 이전 주의 요일이 필요한 경우 사용합니다.
  • 현재 날짜가 토요일일 때, previous(DayOfWeek.SATURDAY) 를 하면 저번 주 토요일을 반환합니다.
• previsoueOrSame(DayOfWeek): 현재 날짜가 조건을 만족할 경우 이를 그대로 유지하고, 그렇지 않으면 이전 요일로 이동합니다.
  • ex) 현재 날짜가 토요일일 때, previouseOrSame(DayOfWeek.SATURDAY) 를 하면 현재 날짜를 반환합니다.
  • 현재 날짜가 토요일 일때, previousOrSame(DayOfWeek.MONDAY) 를 하면 해당 주의 월요일을 반환합니다. 
• firstDayOfMonth(): 달의 첫 번째 날
• lastDayOfMonth(): 달의 마지막 날
• next(DayOfWeek): 다음 특정 요일
• firstInMonth(DayOfWeek): 월 내 특정 요일의 첫 번째 날

 
마치며.
비사이드 프로젝트를 하면서 해당 날짜가 몇월 몇주차이며, 월요일~일요일까지의 날짜를 구하는 요구사항이 있어서 날짜API를 사용해봤는데요.
 
처음에는 Baeldung 의 자료만을 참고했다가 테스트 코드를 돌려보니 Baeldung에서 나온 코드가 ISO 기준이 아님을 알았습니다.
역시 처음 사용해보는 API는 테스트 코드로 확인하는 자세는 필수인것 같습니다.
여러분도 날짜와 시간 관련 로직을 다룰 때 꼭 테스트 코드로 확인해보시길 추천드리며 마무리 하겠습니다!
 
 

참고
- Baeldung 의 Getting the Week Number From Any Date
- stackoverflow 의 How to get dates of a week (I know week number)?