커스텀 어노테이션의 필요성
기업급 애플리케이션 개발 시 표준 라이브러리의 어노테이션만으로는 다양한 비즈니스 요구사항을 충족하기 어렵습니다. 이러한 상황에서 프레임워크 자체를 확장하여 도메인에 맞는 어노테이션을 직접 정의하고 적용하는 기술이 필수적입니다.
어노테이션은 주로 선언된 위치인 필드 (Field), 메서드 (Method), 그리고 클래스 (Class) 레벨에 따라 다른 목적과 구현 전략을 가집니다. 이번 글에서는 각 영역별 커스텀 어노테이션을 작성하고 적용하는 과정을 실습 코드와 함께 다룹니다.
1. 필드 단위 커스텀 어노테이션
데이터 바디를 검증할 때 기존 hibernate-validator 와 같은 라이브러리 어노테이션 (@NotNull, @Size 등) 은 유용하지만, 특정 값 집합 허용 여부 등 특수한 비즈니스 규칙에는 대응하지 못합니다. 이때는 @Constraint 을 활용한 커스텀 유효성 검사기를 만들어야 합니다.
① 커스텀 어노테이션 정의
@interface 키워드를 사용하여 어노테이션 타입을 생성합니다. 주요 설정 요소는 다음과 같습니다.
@Target: 어디에 이 어노테이션을 붙일지 지정 (예: 필드).@Retention: 어노테이션이 소스 파일, 클래스 파일, 혹은 런타임 중에 유지되는지 정의.@Constraint: 유효성 검사를 수행할 실제 로직을 가진 클래스를 연결합니다.
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = ValueRangeValidator.class)
public @interface AllowedValue {
/**
* 허용된 값들의 목록
*/
String[] allowedItems();
String message() default "허용되지 않은 입력값입니다.";
}
@Target({ElementType.FIELD}): 해당 어노테이션은 변수 선언문에만 적용 가능합니다.@Constraint:validatedBy속성에 실제 검증 로직을 담당할 Validator 클래스를 등록합니다.@Retention(RetentionPolicy.RUNTIME): 실행 시간에도 어노테이션 정보가 유지되도록 설정하여, 런타임 주사 및 리플렉션을 통해 읽어야 하는 경우 필수입니다.
② 검증 로직 구현 (Validator)
Jakarta Bean Validation (JSR 380) 규약에 따라 ConstraintValidator 인터페이스를 구현해야 합니다.
public class ValueRangeValidator implements ConstraintValidator<AllowedValue, Object> {
private List<String>> targetValues;
@Override
public void initialize(AllowedValue constraintAnnotation) {
// 어노테이션에서 매개변수 값을 초기화합니다.
Collections.addAll(targetValues, constraintAnnotation.allowedItems());
}
@Override
public boolean isValid(Object value, ConstraintValidatorContext context) {
if (value == null) return true; // Null 은 별도로 처리하지 않는 경우
String strVal = value.toString();
return targetValues.contains(strVal);
}
}
제네릭 제 1 인자는 생성한 어노테이션 타입이며, 제 2 인자는 검증 대상 데이터 타입입니다. isValid 메서드는 검사가 성공하면 true, 실패하면 false 를 반환해야 하며, 오류 메시지나 로직 흐름은 ConstraintValidatorContext 를 통해 커스터마이징 할 수 있습니다.
③ 실제 사용 및 테스트
엔티티 클래스나 DTO 에 어노테이션을 부착합니다.
@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserRequestDTO {
private String username;
@AllowedValue(allowedItems = {"ADMIN", "USER", "GUEST"})
private String userType;
}
컨트롤러 레벨에서 요청을 받는 시점에 @Validated 또는 @Valid 어노테이션을 적용하여 자동으로 유효성 검사가 트리거됩니다.
@RestController
@RequestMapping("/api")
public class UserController {
@PostMapping("/user")
public ResponseEntity<Result> saveUser(@Validated @RequestBody UserRequestDTO dto) {
// 검증 통과 후 비즈니스 로직 진행
return ResponseEntity.ok("Success");
}
}
@Validated 는 클래스 레벨에서도 유효성을 검사할 수 있어 @Valid 보다 더 강력한 기능이 제공되므로 권장됩니다.
2. 메서드 및 클래스 레벨 커스텀 어노테이션
필드 검증을 넘어 비즈니스 로직 제어나 성능 최적화를 위해 메서드 레벨이나 클래스 레벨에서도 커스텀 어노테이션을 자주 사용합니다.
① 인터셉터를 이용한 권한 체크 (Permission)
특정 자원 접근에 대한 권한 검증을 어노테이션으로 간소화합니다. Spring MVC 의 필터체인 중 하나인 Handler Interceptor 를 이용합니다.
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface SecureResource {
String resourceKey() default "";
}
어노테이션을 읽기 위한 핸들러 인터셉터를 구현합니다. preHandle 메서드에서 컨트롤러가 호출되기 전에 어노테이션 정보를 추출하여 검증을 수행합니다.
public class AuthCheckInterceptor implements HandlerInterceptor {
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
throws Exception {
if (!(handler instanceof HandlerMethod)) return true;
HandlerMethod handlerMethod = (HandlerMethod) handler;
// 메서드 어노테이션 확인
SecureResource methodAnno = handlerMethod.getMethodAnnotation(SecureResource.class);
// 어노테이션이 없다면 다음 단계로 진행
if (methodAnno == null) {
SecureResource classAnno = handlerMethod.getBeanType().getAnnotation(SecureResource.class);
if (classAnno != null) {
methodAnno = classAnno;
} else {
return true;
}
}
String key = methodAnno.resourceKey();
// TODO: 실제 보안 시스템 연동 (RBAC 등)
if (!checkPermission(key)) {
response.setStatus(HttpStatus.FORBIDDEN.value());
return false;
}
return true;
}
private boolean checkPermission(String key) {
return "REQUIRED_KEY".equals(key);
}
}
등록된 어노테이션이 있는지 판단하고, 없는 경우 바로 다음 처리로 넘어갑니다. 있으면서도 권한이 없을 때는 응답 코드를 변경하고 false 를 반환하여 프로세스를 중단시킵니다.
② AOP 를 이용한 캐싱 구현 (Caching)
메서드 실행 전후의 동작 제어가 필요한 경우 (예: DB 조회 대신 캐시 반환) 인터셉터 보다는 AOP(Automatic Programmatic Operation) 를 활용하는 것이 유리합니다.
커스텀 캐시 어노테이션을 정의합니다.
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface CachedData {
String cacheKey();
}
AspectJ 를 사용하여 around 조언 (Advice) 을 작성합니다.
@Aspect
@Component
public class CacheManagementAspect {
@Autowired
private MapCacheService cacheService;
@Around("execution(* ..*(..)) && @annotation(CachedData)")
public Object handleCachedMethod(ProceedingJoinPoint joinPoint, CachedData cacheAnno) throws Throwable {
String key = cacheAnno.cacheKey();
// 1. 먼저 캐시에서 데이터 가져오기
Object cachedResult = cacheService.get(key);
if (cachedResult != null) {
return cachedResult;
}
// 2. 캐시가 없으면 원본 메서드 실행
Object actualResult = joinPoint.proceed();
// 3. 결과 저장
cacheService.put(key, actualResult);
return actualResult;
}
}
@Around 애노테이션을 사용하여 타겟 메서드가 실행되는 시점 주변에서 로직을 삽입합니다. 만약 targetResult 가 있다면 즉시 반환하고, 없으면 joinPoint.proceed() 를 호출하여 원본 로직을 수행한 뒤 결과를 저장합니다.
@GetMapping("/data")
@CachedData(cacheKey = "global_config")
public ConfigData fetchConfig() {
// 실제 DB 쿼리 실행
return dbClient.getConfig();
}
위와 같이 설정하면 해당 메서드가 호출될 때마다 반복적인 데이터 조회 비용을 줄일 수 있습니다.