Spring Boot에서 예외 메시지에 대한 현지화를 처리하는 가장 좋은 방법

전 세계 사용자에게 서비스를 제공하기 위해 애플리케이션이 성장함에 따라 현지화는 소프트웨어 개발의 중요한 측면이 되었습니다. 지역화를 통해 애플리케이션은 다양한 언어와 지역에 적응하여 사용자 친화적인 환경을 제공할 수 있습니다. 

이 기사에서는 Spring Boot 애플리케이션에서 지역화된 예외를 처리하는 가장 좋은 방법을 공유하겠습니다.

예외 메시지에 대한 현지화가 필요한 이유는 무엇입니까?

백엔드 측에서 예외 메시지를 현지화하는 것은 특히 전 세계 사용자를 대상으로 하는 애플리케이션에서 원활한 사용자 경험을 만드는 데 필수적입니다. 

백엔드에서 이러한 메시지를 현지화하여 프런트엔드로 직접 전송함으로써 우리는 프런트엔드 개발자의 어깨에서 벗어나 여러 언어를 관리하는 책임을 맡을 수 있습니다. 이 접근 방식을 사용하면 모든 플랫폼과 언어에서 오류 메시지가 일관되게 유지되므로 프런트엔드 개발자는 오류 토스트와 같이 사용자 친화적인 방식으로 이러한 메시지를 표시하는 데 집중할 수 있습니다. 

결과적으로 프런트엔드에서 각 언어에 대한 사용자 정의 예외 메시지를 처리할 필요가 없으므로 중복된 노력과 오류 가능성이 줄어들고 모든 사용자가 선호하는 언어로 명확하고 관련성이 높은 피드백을 받을 수 있습니다.

백엔드에서 목표를 편리하게 달성하는 방법은 무엇입니까?

목표를 달성하려면 아래 단계를 따르세요. 

일반 예외 클래스

RuntimeException에서 확장되는 클래스를 생성하고 이름을 ResponseException으로 지정하는 것으로 시작합니다. 이 사용자 정의 예외를 사용하면 애플리케이션별 오류를 보다 통제된 방식으로 처리할 수 있습니다.

public class ResponseException extends RuntimeException {

}

응답 오류 클래스

예외 발생 시 응답으로 반환될 별도의 클래스를 만듭니다. 이 클래스에는 메시지, 타임스탬프, errorCode와 같은 필드와 프런트엔드에 전달하려는 기타 관련 정보가 포함될 수 있습니다.

public record ErrorResponse(int status, String message) {

}

전역 예외 처리기

Spring의 @ControllerAdvice 주석을 사용하여 GlobalExceptionHandler를 구현합니다. 이 클래스에서는 ResponseException을 포착하고 이를 사용자의 로케일에 따라 적절하게 현지화된 메시지에 매핑할 수 있습니다.

@Slf4j
@RestControllerAdvice
@RequiredArgsConstructor
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

  @ExceptionHandler(value = ResponseException.class)
  public ResponseEntity<errorresponse> handleResponseStatusException(
      ResponseException ex
  ) {
    log.error("ResponseException: {}", ex.getMessage());

    String message = ex.getMessage();

    var errorResponse = new ErrorResponse(ex.getStatus().value(), message);

    return new ResponseEntity(errorResponse, ex.getStatus());
  }
}
</errorresponse>

언어별 속성 파일

현지화된 메시지를 관리하려면 지원되는 각 언어에 대한 속성 파일을 만듭니다(예: 영어의 경우 message_en.properties, 아제르바이잔의 경우 message_az.properties 등). 이 파일에는 각 예외 메시지에 대한 키-값 쌍이 포함되어 있어 Spring이 사용자의 로케일을 기반으로 올바른 메시지를 자동으로 해결할 수 있습니다.

src/main/resources 폴더에 해당 속성 파일을 생성하세요.

err.username_already_exists.msg=User with username: {0} is already exists.

현지화 부분 구현

Spring Boot에서 예외 처리를 위한 최소한의 항목을 만들었습니다. 위 내용은 이미 잘 알고 계시리라 생각합니다. 계속해서 번역부분을 추가해보겠습니다.

ResponseException 클래스 수정:

public class ResponseException extends RuntimeException {
  private final String messageTemplate;
  private final transient Object[] params;
  private final Locale locale;

  public static ResponseException notFound(String messageTemplate, Locale locale) {
    return new ResponseException(HttpStatus.NOT_FOUND, messageTemplate, null, locale);
  }

  public static ResponseException notFound(String messageTemplate, Object[] params, Locale locale) {
    return new ResponseException(HttpStatus.NOT_FOUND, messageTemplate, params, locale);
  }

  public static ResponseException forbidden(String messageTemplate, Locale locale) {
    return new ResponseException(HttpStatus.FORBIDDEN, messageTemplate, null, locale);
  }

  public static ResponseException forbidden(String messageTemplate, Object[] params, Locale locale) {
    return new ResponseException(HttpStatus.FORBIDDEN, messageTemplate, params, locale);
  }  
}

NOT_FOUND, FORBIDDEN.

과 같이 자주 사용되는 HttpStatus 코드에 대한 도우미 메서드를 만듭니다.

다음과 같은 방법으로 이러한 도우미 메서드를 사용할 수 있습니다.

// some code parts omitted ...
userService.findByUsername(username)
  .orElseThrow(() -> ResponseException.notFound("user_not_found", locale))

모든 속성 파일에 user_not_found 메시지 템플릿을 생성하세요.

// file: messages_en.properties
user_not_found=User not found

// file: messages_az.properties
user_not_found=İsdifadəçi tapılmadı

프런트엔드로 돌아가기 전에 자동으로 교체하려면 GlobalExceptionHandler 클래스의 메서드를 업데이트하세요.

@Slf4j
@RestControllerAdvice
@RequiredArgsConstructor
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

  private final MessageSource messageSource;

  @ExceptionHandler(value = ResponseException.class)
  public ResponseEntity<errorresponse> handleResponseStatusException(
      ResponseException ex
  ) {
    log.error("ResponseException: {}", ex.getMessage());

    String message = ex.getMessage();

    String messageTemplate = ex.getMessageTemplate();
    if (StringUtils.isNotBlank(messageTemplate)) {
      message = messageSource.getMessage(messageTemplate, ex.getParams(), ex.getLocale());
    }

    var errorResponse = new ErrorResponse(ex.getStatus().value(), message);

    return new ResponseEntity(errorResponse, ex.getStatus());
  }
}
</errorresponse>

예외 메시지에서 동적 값을 사용하는 방법

예외를 처리하는 이 방법은 특히 예외 메시지에 대한 동적 값을 설정해야 하는 경우에 유용합니다. 예를 들어

// file: messages_en.properties
err.invalid_phone_number.msg=The phone: {0} is invalid

{0}을 동적 값으로 대체하려면

public static ResponseException badRequest(
      String messageTemplate, 
      Locale locale,
      String... params
) {
  return new ResponseException(
        HttpStatus.BAD_REQUEST, 
        messageTemplate, 
        params, 
        locale
  );
}

매번 새로운 메소드를 만들지 않고도 여러 개의 동적 매개변수를 전달할 수 있도록 varargs 매개변수를 마지막에 넣었습니다.

동적 값이 포함된 메시지에 대한 전용 기사가 있습니다.

사용자의 로케일을 어디서 얻을 수 있나요?

로케일을 가져오는 데는 두 가지 접근 방식이 있습니다.

1. UI 기본 설정에 따라 데이터베이스에 저장되는 사용자의 로캘입니다.

2. 일부 컨트롤러 메소드는 선택적 lang 요청 매개변수를 허용합니다. 이는 프런트엔드 개발자가 UI가 다른 언어로 어떻게 표시되는지 확인하려는 경우 테스트하는 데 유용할 수 있습니다. 언어마다 문장 길이가 다르기 때문이죠.

결론

오늘은 여기까지입니다. 즐거웠기를 바랍니다.

소스 코드는 내 GitHub 계정의 저장소에서 확인할 수 있습니다.

궁금한 점이 있으시면 언제든지 LinkedIn을 통해 연락주세요.

위 내용은 Spring Boot에서 예외 메시지에 대한 현지화를 처리하는 가장 좋은 방법의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!