명명 패턴보다 애너테이션을 사용하라 - [6장. 열거 타입과 애너테이션(아이템39)]

📙 명명 패턴의 문제점

  전통적으로 도구나 프레임워크가 특별히 다뤄야 할 프로그램 요소에는 딱 구분되는 명명 패턴을 적용해 왔다.

  예를 들어, 테스트 프레임워크인 JUnit은 버전 3까지 테스트 메서드 이름을 test로 시작하게끔 했다. 효과적인 방법이지만 아래와 같은 3가지 큰 단점이 있다.

1. 오타가 나면 안 된다.
   실수로 이름을 tsetSafetyOverride로 지으면 이 메서드는 무시된다.
2. 올바른 프로그램 요소에서만 사용되리라 보증할 방법이 없다.
   클래스 이름을 TestSafetyMechanisms로 지어 이 클래스에 정의된 테스트 메서드들을 수행하길 바라지만 JUnit은 클래스 이름에는 관심이 없다.
3. 프로그램 요소를 매개변수로 전달할 마땅한 방법이 없다.
   특정 예외를 던져야만 성공하는 테스트가 있다고 할 때, 기대하는 예외 타입을 테스트에 매개변수로 전달할 수 없다.

 

 

📙 예시 1 - 마커(marker) 애너테이션

  애너테이션은 위의 문제를 해결해 주는데, JUnit도 버전 4부터 전면 도입하였다. 직접 제작한 작은 테스트 프레임워크를 이용하여 애너테이션의 동작 방식을 살펴보자.

/**
 * 테스트 메서드임을 선언하는 애너테이션이다.
 * 매개변수 없는 정적 메서드 전용이다.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Test {
}

  @Test 애너테이션 선언 자체에도 두 가지의 다른 애너테이션이 달려 있는데, 이처럼 애너테이션 선언에 다른 애너테이션을 메타애너테이션(meta-annotation)이라 한다.

2가지 메타애너테이션은 다음을 의미한다.

1. @Retention(RetentionPolicy.RUNTIME)
   @Test가 런타임에도 유지되어야 한다.
2. @Target(ElementType.METHOD)
   @Test가 반드시 메서드 선언에서만 사용돼야 한다.

  @Test 애너테이션은 마커(marker) 애너테이션이라 한다. 이 애너테이션을 사용하면 프로그래머가 Test 이름에 오타를 내거나 메서드 선언 외의 프로그램 요소에 달면 컴파일 오류를 내준다.

 

  주석으로 "매개변수 없는 정적 메서드 전용이다"라고 쓰여있다. 이 제약을 컴파일러가 강제할 수 없어서, 컴파일은 잘 되겠지만 테스트 도구를 실행할 때 문제가 된다.
  컴파일러가 강제하도록 하려면 javax.annotation.processing API 문서를 참고 적절한 애너테이션 처리기를 직접 구현해야 한다.

 

@Test를 실제 사용한 코드는 아래와 같다.

public class Sample {
    @Test
    public static void m1() {
        // 성공해야 한다.
    }

    public static void m2() { }

    @Test
    public static void m3() {
        // 실패해야 한다.
        throw new RuntimeException("실패");
    }

    public static void m4() { }

    @Test
    public void m5() {
        // 잘못 사용한 예: 정적 메서드가 아니다.
    }

    public static void m6() { }

    @Test
    public static void m7() {
        // 실패해야 한다.
        throw new RuntimeException("실패");
    }

    public static void m8() { }
}

public static void main(String[] args) throws Exception {
    int tests = 0;
    int passed = 0;
    Class<?> testClass = Class.forName("com.example.demo.item39.Sample");
    for(Method m : testClass.getDeclaredMethods()) {
        if(m.isAnnotationPresent(Test.class)) {
            tests++;
            try {
                m.invoke(null);
                passed++;
            } catch (InvocationTargetException wrappedExc) {
                Throwable exc = wrappedExc.getCause();
                System.out.println(m + " 실패: " + exc);
            } catch (Exception exc) {
                System.out.println("잘못 사용한 @Test: " + m);
            }
        }
    }

    System.out.printf("성공: %d, 실패: %d%n",
                        passed, tests - passed);
    // 출력 결과
    // public static void com.example.demo.item39.Sample.m3() 실패: java.lang.RuntimeException: 실패
    // public static void com.example.demo.item39.Sample.m7() 실패: java.lang.RuntimeException: 실패
    // 잘못 사용한 @Test: public void com.example.demo.item39.Sample.m5()
    // 성공: 1, 실패: 3
}

  InvocationTargetException은 m3()과 m7()에서 발생한다.

  @Test 애너테이션을 잘 못 사용한 경우 InvocationTargetException 외의 예외가 발생하는데, m5()에서 발생한다.

 

 

📙 예시 2 - 매개변수 하나를 받는 애너테이션

  특정 예외를 던져야만 성공하는 테스트를 살펴보자.

/**
 * 명시한 예외를 던저야만 성공하는 테스트 메서드용 애너테이션
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
    Class<? extends Throwable> value();
}

  이 애너테이션의 매개변수 타입은 Class<? extends Throwable>이다.

public class Sample2 {
    @ExceptionTest(ArithmeticException.class)
    public static void m1() {
        // 성공해야 한다.
        int i = 0;
        i = i / i;
    }

    @ExceptionTest(ArithmeticException.class)
    public static void m2() {
        // 실패해야 한다. (다른 예외 발생)
        int[] a = new int[0];
        int i = a[1];
    }

    @ExceptionTest(ArithmeticException.class)
    public static void m3() {
        // 실패해야 한다. (예외가 발생하지 않음)
    }
}

public static void main(String[] args) throws Exception {
    int tests = 0;
    int passed = 0;
    Class<?> testClass = Class.forName("com.example.demo.item39.Sample2");
    for(Method m : testClass.getDeclaredMethods()) {
        if(m.isAnnotationPresent(ExceptionTest.class)) {
            tests++;
            try {
                m.invoke(null);
                System.out.printf("테스트 %s 실패: 예외를 던지지 않음%n", m);
            } catch (InvocationTargetException wrappedExc) {
                Throwable exc = wrappedExc.getCause();
                Class<? extends Throwable> excType =
                    m.getAnnotation(ExceptionTest.class).value();
                if(excType.isInstance(exc)) {
                    passed++;
                } else {
                    System.out.printf(
                        "테스트 %s 실패: 기대한 예외 %s,%n    발생한 예외 %s%n",
                            m, excType.getName(), exc);
                }
            } catch (Exception exc) {
                System.out.println("잘못 사용한 @ExceptionTest: " + m);
            }
        }
    }

    System.out.printf("성공: %d, 실패: %d%n",
        passed, tests - passed);

    // 출력 결과
    // 테스트 public static void com.example.demo.item39.Sample2.m2() 실패: 기대한 예외 java.lang.ArithmeticException,
    //    발생한 예외 java.lang.ArrayIndexOutOfBoundsException: Index 1 out of bounds for length 0
    // 테스트 public static void com.example.demo.item39.Sample2.m3() 실패: 예외를 던지지 않음
    // 성공: 1, 실패: 2
}

  이 코드는 애너테이션 매개변수의 값을 추출하여 테스트 메서드가 올바른 예외를 던지는지 확인한다. Sample2 클래스의 주석에서 확인할 수 있듯이 1개가 성공하고, 2개가 실패한다.

 

 

📙 예시 3 - 배열 매개변수를 받는 애너테이션 타입

🔎 1. 배열을 이용하는 방법

  지금까지 예외 1개를 받는 애너테이션을 살펴보았다. 아래 애너테이션과 같이 '예외를 여러 개 명시하고 그중 하나가 발생하면 성공'하게 만들 수도 있다.

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
    Class<? extends Throwable>[] value();
}

 

public class Sample2 {
    @ExceptionTest(ArithmeticException.class)
    public static void m1() {
        // 성공해야 한다.
        int i = 0;
        i = i / i;
    }

    @ExceptionTest(ArithmeticException.class)
    public static void m2() {
        // 실패해야 한다. (다른 예외 발생)
        int[] a = new int[0];
        int i = a[1];
    }

    @ExceptionTest(ArithmeticException.class)
    public static void m3() {
        // 실패해야 한다. (예외가 발생하지 않음)
    }

    // 배열 매개변수
    @ExceptionTest({ IndexOutOfBoundsException.class,
                        NullPointerException.class})
    public static void doubleBad() {
        // 성공해야 한다.
        List<String> list = new ArrayList<>();

        // 자바 API 명세에 따르면 다음 메서드는 IndexOutOfBoundsException이나
        // NullPointerException을 던질 수 있다.
        list.addAll(5, null);
    }
}

public static void main(String[] args) throws Exception {
    int tests = 0;
    int passed = 0;
    Class<?> testClass = Class.forName("com.example.demo.item39.Sample2");
    for(Method m : testClass.getDeclaredMethods()) {
        if(m.isAnnotationPresent(ExceptionTest.class)) {
            tests++;
            try {
                m.invoke(null);
                System.out.printf("테스트 %s 실패: 예외를 던지지 않음%n", m);
            } catch (Throwable wrappedExc) {
                Throwable exc = wrappedExc.getCause();
                int oldPassed = passed;
                Class<? extends Throwable>[] excTypes =
                    m.getAnnotation(ExceptionTest.class).value();
                for(Class<? extends Throwable> excType : excTypes) {
                    if(excType.isInstance(exc)) {
                        passed++;
                        break;
                    }
                }
                if (passed == oldPassed) {
                    System.out.printf("테스트 %s 실패: %s %n", m, exc);
                }
            }
        }
    }

    System.out.printf("성공: %d, 실패: %d%n",
        passed, tests - passed);

    // 테스트 public static void com.example.demo.item39.Sample2.m2() 실패: java.lang.ArrayIndexOutOfBoundsException: Index 1 out of bounds for length 0
    // 테스트 public static void com.example.demo.item39.Sample2.m3() 실패: 예외를 던지지 않음
    // 성공: 2, 실패: 2
}

  원소가 여럿인 배열을 지정할 때는 위와 같이 원소들을 중괄호로 감싸고 쉼표로 구분해주기만 하면 된다.

 

🔎 2. @Repeatable 메타애너테이션을 이용하는 방법

  자바 8에서는 여러 개의 값을 받는 애너테이션을 배열 매개변수 대신 @Repeatable 메타애너테이션을 이용하여 구현할 수 있다. 하나의 프로그램 요소에 @Repeatable을 단 애너테이션을 여러 개 달 수 있도록 하는 것이다.

 

  @Repeatable을 가진 애너테이션을 구현할 때는 아래의 내용을 주의해서 만들어야 한다.

1. @Repeatable을 단 애너테이션을 반환하는 '컨테이너 애너테이션'을 하나 더 정의하고, @Repeatable에 이 컨테이너 애너테이션의 class 객체를 매개변수로 전달해야 한다.
2. 컨테이너 애너테이션은 내부 애너테이션 타입의 배열을 반환하는 value 메서드를 정의해야 한다.
3. 컨테이너 애너테이션 타입에는 적절한 보존 정책(@Retention)과 적용 대상(@Target)을 명시해야 한다.

// 반복 가능한 애너테이션
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Repeatable(ExceptionTestContainer.class)
public @interface ExceptionTest {
    Class<? extends Throwable> value();
}

// 컨테이너 애너티이션
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTestContainer {
    ExceptionTest[] value();
}

  isAnnotationPresent로 컨테이너 애너테이션이 달렸는지 검사한다면 반복 가능 애너테이션을 한 번만 단 메서드는 무시된다. 그래서 getAnnotationByType 메서드를 이용하여 반복 가능 애너테이션의 수와 상관없이 모두 검사하도록 해야 한다.

public class Sample2 {
    @ExceptionTest(ArithmeticException.class)
    public static void m1() {
        // 성공해야 한다.
        int i = 0;
        i = i / i;
    }

    @ExceptionTest(ArithmeticException.class)
    public static void m2() {
        // 실패해야 한다. (다른 예외 발생)
        int[] a = new int[0];
        int i = a[1];
    }

    @ExceptionTest(ArithmeticException.class)
    public static void m3() {
        // 실패해야 한다. (예외가 발생하지 않음)
    }

    // 반복 가능한 에너테이션 사용
    @ExceptionTest(IndexOutOfBoundsException.class)
    @ExceptionTest(NullPointerException.class)
    public static void doubleBad() {
        // 성공해야 한다.
        List<String> list = new ArrayList<>();

        // 자바 API 명세에 따르면 다음 메서드는 IndexOutOfBoundsException이나
        // NullPointerException을 던질 수 있다.
        list.addAll(5, null);
    }
}

public static void main(String[] args) throws Exception {
    int tests = 0;
    int passed = 0;
    Class<?> testClass = Class.forName("com.example.demo.item39.Sample2");
    for(Method m : testClass.getDeclaredMethods()) {
        if(m.isAnnotationPresent(ExceptionTest.class)
            || m.isAnnotationPresent(ExceptionTestContainer.class)) {
            tests++;
            try {
                m.invoke(null);
                System.out.printf("테스트 %s 실패: 예외를 던지지 않음%n", m);
            } catch (Throwable wrappedExc) {
                Throwable exc = wrappedExc.getCause();
                int oldPassed = passed;
                ExceptionTest[] excTests =
                    m.getAnnotationsByType(ExceptionTest.class);

                for(ExceptionTest excTest : excTests) {
                    if(excTest.value().isInstance(exc)) {
                        passed++;
                        break;
                    }
                }
                if (passed == oldPassed) {
                    System.out.printf("테스트 %s 실패: %s %n", m, exc);
                }
            }
        }
    }

    System.out.printf("성공: %d, 실패: %d%n",
        passed, tests - passed);

    // 출력 결과
    // 테스트 public static void com.example.demo.item39.Sample2.m2() 실패: java.lang.ArrayIndexOutOfBoundsException: Index 1 out of bounds for length 0 
    // 테스트 public static void com.example.demo.item39.Sample2.m3() 실패: 예외를 던지지 않음
    // 성공: 2, 실패: 2
}

  반복 가능 애너테이션을 사용하면 코드의 가독성을 높일 수 있다.

  하지만 애너테이션을 선언하고 이를 처리하는 부분에서는 코드 양이 늘어나며, 특히 처리 코드가 복잡해져 오류가 날 가능성이 커짐을 명심해야 한다.

 

---

  애너테이션으로 할 수 있는 일을 명명 패턴으로 처리할 이유는 없다.

  다른 프로그래머가 소스코드에 추가 정보를 제공할 수 있는 도구를 만드는 일을 한다면 적당한 애너테이션 타입도 함께 정의해 제공하도록 하자.

 

해당 글은 Joshua Block 님의 'Effective Java 3/E'를 참고하였습니다.