feat: 공통 API 응답 형식 구현

build.gradle

@@ -20,7 +20,9 @@ repositories {
 dependencies {
 	implementation 'org.springframework.boot:spring-boot-starter-actuator'
 	implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
+	implementation 'org.springframework.boot:spring-boot-starter-validation'
 	implementation 'org.springframework.boot:spring-boot-starter-webmvc'
+	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:3.0.3'
 	compileOnly 'org.projectlombok:lombok'
 	developmentOnly 'org.springframework.boot:spring-boot-docker-compose'
 	runtimeOnly 'com.mysql:mysql-connector-j'

src/main/java/ject/official_qr_checkin_server/common/exception/BusinessException.java

@@ -0,0 +1,23 @@
+package ject.official_qr_checkin_server.common.exception;
+
+import java.io.Serial;
+import lombok.Getter;
+
+@Getter
+public class BusinessException extends RuntimeException {
+
+	@Serial
+	private static final long serialVersionUID = 1L;
+
+	private final ErrorCode errorCode;
+
+	public BusinessException(ErrorCode errorCode) {
+		this(errorCode, errorCode.getMessage());
+	}
+
+	public BusinessException(ErrorCode errorCode, String message) {
+		super(message);
+		this.errorCode = errorCode;
+	}
+
+}

src/main/java/ject/official_qr_checkin_server/common/exception/ErrorCode.java

@@ -0,0 +1,13 @@
+package ject.official_qr_checkin_server.common.exception;
+
+import java.io.Serializable;
+import org.springframework.http.HttpStatus;
+
+public interface ErrorCode extends Serializable {
+
+	HttpStatus getHttpStatus();
+
+	String getCode();
+
+	String getMessage();
+}

src/main/java/ject/official_qr_checkin_server/common/exception/GlobalErrorCode.java

@@ -0,0 +1,67 @@
+package ject.official_qr_checkin_server.common.exception;
+
+import org.springframework.http.HttpStatus;
+
+public enum GlobalErrorCode implements ErrorCode {
+
+	UNSUPPORTED_PARAMETER_TYPE(
+		HttpStatus.BAD_REQUEST,
+		"GLOBAL-001",
+		"요청 파라미터의 형식이 올바르지 않습니다."
+	),
+	MISSING_REQUEST_PARAMETER(
+		HttpStatus.BAD_REQUEST,
+		"GLOBAL-002",
+		"필수 요청 파라미터가 누락되었습니다."
+	),
+	MISSING_REQUEST_BODY(
+		HttpStatus.BAD_REQUEST,
+		"GLOBAL-003",
+		"요청 본문이 누락되었거나 형식이 올바르지 않습니다."
+	),
+	VALIDATION_FAILED(
+		HttpStatus.BAD_REQUEST,
+		"GLOBAL-004",
+		"요청 값 검증에 실패했습니다."
+	),
+	METHOD_NOT_ALLOWED(
+		HttpStatus.METHOD_NOT_ALLOWED,
+		"GLOBAL-005",
+		"지원하지 않는 HTTP 메서드입니다."
+	),
+	RESOURCE_NOT_FOUND(
+		HttpStatus.NOT_FOUND,
+		"GLOBAL-006",
+		"요청한 리소스를 찾을 수 없습니다."
+	),
+	INTERNAL_SERVER_ERROR(
+		HttpStatus.INTERNAL_SERVER_ERROR,
+		"GLOBAL-999",
+		"서버 내부 오류가 발생했습니다."
+	);
+
+	private final HttpStatus httpStatus;
+	private final String code;
+	private final String message;
+
+	GlobalErrorCode(HttpStatus httpStatus, String code, String message) {
+		this.httpStatus = httpStatus;
+		this.code = code;
+		this.message = message;
+	}
+
+	@Override
+	public HttpStatus getHttpStatus() {
+		return httpStatus;
+	}
+
+	@Override
+	public String getCode() {
+		return code;
+	}
+
+	@Override
+	public String getMessage() {
+		return message;
+	}
+}

src/main/java/ject/official_qr_checkin_server/common/exception/GlobalExceptionHandler.java

@@ -0,0 +1,126 @@
+package ject.official_qr_checkin_server.common.exception;
+
+import java.util.List;
+import java.util.Objects;
+import ject.official_qr_checkin_server.common.response.ApiResponse;
+import ject.official_qr_checkin_server.common.response.ErrorResponse;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.context.MessageSourceResolvable;
+import org.springframework.http.ResponseEntity;
+import org.springframework.http.converter.HttpMessageNotReadableException;
+import org.springframework.web.HttpRequestMethodNotSupportedException;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.MissingServletRequestParameterException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+import org.springframework.web.method.annotation.HandlerMethodValidationException;
+import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
+import org.springframework.web.servlet.resource.NoResourceFoundException;
+
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+	private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
+
+	@ExceptionHandler(BusinessException.class)
+	ResponseEntity<ApiResponse<List<String>>> handleBusinessException(BusinessException exception) {
+		ErrorCode errorCode = exception.getErrorCode();
+		logKnownException(exception, errorCode);
+		return createResponse(ErrorResponse.of(errorCode, exception.getMessage()));
+	}
+
+	@ExceptionHandler(MethodArgumentTypeMismatchException.class)
+	ResponseEntity<ApiResponse<List<String>>> handleMethodArgumentTypeMismatch(
+		MethodArgumentTypeMismatchException exception
+	) {
+		return handleKnownException(exception, GlobalErrorCode.UNSUPPORTED_PARAMETER_TYPE);
+	}
+
+	@ExceptionHandler(MissingServletRequestParameterException.class)
+	ResponseEntity<ApiResponse<List<String>>> handleMissingRequestParameter(
+		MissingServletRequestParameterException exception
+	) {
+		return handleKnownException(exception, GlobalErrorCode.MISSING_REQUEST_PARAMETER);
+	}
+
+	@ExceptionHandler(HttpMessageNotReadableException.class)
+	ResponseEntity<ApiResponse<List<String>>> handleMessageNotReadable(
+		HttpMessageNotReadableException exception
+	) {
+		return handleKnownException(exception, GlobalErrorCode.MISSING_REQUEST_BODY);
+	}
+
+	@ExceptionHandler({
+		MethodArgumentNotValidException.class,
+		HandlerMethodValidationException.class
+	})
+	ResponseEntity<ApiResponse<List<String>>> handleValidationException(Exception exception) {
+		GlobalErrorCode errorCode = GlobalErrorCode.VALIDATION_FAILED;
+		logKnownException(exception, errorCode);
+
+		List<String> messages = switch (exception) {
+			case MethodArgumentNotValidException methodArgumentNotValidException ->
+				extractMessages(methodArgumentNotValidException.getAllErrors(), errorCode);
+			case HandlerMethodValidationException handlerMethodValidationException ->
+				extractMessages(handlerMethodValidationException.getAllErrors(), errorCode);
+			default -> List.of(errorCode.getMessage());
+		};
+
+		return createResponse(ErrorResponse.of(errorCode, messages));
+	}
+
+	@ExceptionHandler(HttpRequestMethodNotSupportedException.class)
+	ResponseEntity<ApiResponse<List<String>>> handleMethodNotSupported(
+		HttpRequestMethodNotSupportedException exception
+	) {
+		return handleKnownException(exception, GlobalErrorCode.METHOD_NOT_ALLOWED);
+	}
+
+	@ExceptionHandler(NoResourceFoundException.class)
+	ResponseEntity<ApiResponse<List<String>>> handleResourceNotFound(NoResourceFoundException exception) {
+		return handleKnownException(exception, GlobalErrorCode.RESOURCE_NOT_FOUND);
+	}
+
+	@ExceptionHandler(Exception.class)
+	ResponseEntity<ApiResponse<List<String>>> handleUnexpectedException(Exception exception) {
+		GlobalErrorCode errorCode = GlobalErrorCode.INTERNAL_SERVER_ERROR;
+		log.error("Unhandled exception. responseCode={}", errorCode.getCode(), exception);
+		return createResponse(ErrorResponse.of(errorCode));
+	}
+
+	private ResponseEntity<ApiResponse<List<String>>> handleKnownException(
+		Exception exception,
+		ErrorCode errorCode
+	) {
+		logKnownException(exception, errorCode);
+		return createResponse(ErrorResponse.of(errorCode));
+	}
+
+	private List<String> extractMessages(
+		List<? extends MessageSourceResolvable> errors,
+		ErrorCode fallbackErrorCode
+	) {
+		List<String> messages = errors.stream()
+			.map(MessageSourceResolvable::getDefaultMessage)
+			.filter(Objects::nonNull)
+			.distinct()
+			.toList();
+
+		return messages.isEmpty() ? List.of(fallbackErrorCode.getMessage()) : messages;
+	}
+
+	private ResponseEntity<ApiResponse<List<String>>> createResponse(ErrorResponse errorResponse) {
+		return ResponseEntity
+			.status(errorResponse.httpStatus())
+			.body(errorResponse.toApiResponse());
+	}
+
+	private void logKnownException(Exception exception, ErrorCode errorCode) {
+		log.warn(
+			"Handled exception. type={}, responseCode={}",
+			exception.getClass().getSimpleName(),
+			errorCode.getCode()
+		);
+	}
+}

src/main/java/ject/official_qr_checkin_server/common/response/ApiResponse.java

@@ -0,0 +1,20 @@
+package ject.official_qr_checkin_server.common.response;
+
+import java.time.Instant;
+
+public record ApiResponse<T>(
+	String status,
+	T data,
+	Instant timestamp
+) {
+
+	private static final String SUCCESS_STATUS = "SUCCESS";
+
+	public static <T> ApiResponse<T> success(T data) {
+		return new ApiResponse<>(SUCCESS_STATUS, data, Instant.now());
+	}
+
+	public static <T> ApiResponse<T> error(String status, T data) {
+		return new ApiResponse<>(status, data, Instant.now());
+	}
+}

src/main/java/ject/official_qr_checkin_server/common/response/ApiResponseBodyAdvice.java

@@ -0,0 +1,71 @@
+package ject.official_qr_checkin_server.common.response;
+
+import java.util.List;
+import org.springframework.core.MethodParameter;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ProblemDetail;
+import org.springframework.http.converter.AbstractJacksonHttpMessageConverter;
+import org.springframework.http.converter.HttpMessageConverter;
+import org.springframework.http.server.ServerHttpRequest;
+import org.springframework.http.server.ServerHttpResponse;
+import org.springframework.http.server.ServletServerHttpResponse;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;
+
+@RestControllerAdvice
+public class ApiResponseBodyAdvice implements ResponseBodyAdvice<Object> {
+
+	private static final List<String> EXCLUDED_PATH_PREFIXES = List.of(
+		"/actuator",
+		"/v3/api-docs",
+		"/swagger-ui"
+	);
+
+	@Override
+	public boolean supports(
+		MethodParameter returnType,
+		Class<? extends HttpMessageConverter<?>> converterType
+	) {
+		return AbstractJacksonHttpMessageConverter.class.isAssignableFrom(converterType);
+	}
+
+	@Override
+	public Object beforeBodyWrite(
+		Object body,
+		MethodParameter returnType,
+		MediaType selectedContentType,
+		Class<? extends HttpMessageConverter<?>> selectedConverterType,
+		ServerHttpRequest request,
+		ServerHttpResponse response
+	) {
+		if (shouldSkip(body, request, response)) {
+			return body;
+		}
+
+		return ApiResponse.success(body);
+	}
+
+	private boolean shouldSkip(Object body, ServerHttpRequest request, ServerHttpResponse response) {
+		return body instanceof ApiResponse<?>
+			|| body instanceof ProblemDetail
+			|| isExcludedPath(request.getURI().getPath())
+			|| isNonSuccessfulOrEmptyResponse(response);
+	}
+
+	private boolean isExcludedPath(String path) {
+		return EXCLUDED_PATH_PREFIXES.stream().anyMatch(path::startsWith);
+	}
+
+	private boolean isNonSuccessfulOrEmptyResponse(ServerHttpResponse response) {
+		if (!(response instanceof ServletServerHttpResponse servletResponse)) {
+			return false;
+		}
+
+		int status = servletResponse.getServletResponse().getStatus();
+		return status < 200
+			|| status >= 300
+			|| status == HttpStatus.NO_CONTENT.value()
+			|| status == HttpStatus.RESET_CONTENT.value();
+	}
+}

src/main/java/ject/official_qr_checkin_server/common/response/ErrorResponse.java

@@ -0,0 +1,32 @@
+package ject.official_qr_checkin_server.common.response;
+
+import java.util.List;
+import ject.official_qr_checkin_server.common.exception.ErrorCode;
+import org.springframework.http.HttpStatus;
+
+public record ErrorResponse(
+	HttpStatus httpStatus,
+	String code,
+	List<String> messages
+) {
+
+	public ErrorResponse {
+		messages = List.copyOf(messages);
+	}
+
+	public static ErrorResponse of(ErrorCode errorCode) {
+		return of(errorCode, List.of(errorCode.getMessage()));
+	}
+
+	public static ErrorResponse of(ErrorCode errorCode, String message) {
+		return of(errorCode, List.of(message));
+	}
+
+	public static ErrorResponse of(ErrorCode errorCode, List<String> messages) {
+		return new ErrorResponse(errorCode.getHttpStatus(), errorCode.getCode(), messages);
+	}
+
+	public ApiResponse<List<String>> toApiResponse() {
+		return ApiResponse.error(code, messages);
+	}
+}