feat(configuration): 파일 API 공통 응답 규약 및 예외 처리 #26

systems/configuration/configuration-adapter-in/deps.bzl

@@ -7,6 +7,9 @@ KOTLIN_DEPS = [
     "@maven//:com_google_protobuf_protobuf_kotlin",
     "@maven//:javax_annotation_javax_annotation_api",
     "@maven//:org_springframework_boot_spring_boot_starter",
+    "@maven//:org_springframework_boot_spring_boot_starter_web",
+    "@maven//:org_springframework_boot_spring_boot_starter_validation",
+    "@maven//:com_fasterxml_jackson_module_jackson_module_kotlin",
     "//contracts:configuration_grpc_java",
     "//contracts:configuration_java_proto",
     "//systems/configuration/configuration-domain:main",

systems/configuration/configuration-adapter-in/src/main/kotlin/hs/kr/entrydsm/configuration/adapterin/common/ApiResponse.kt

@@ -0,0 +1,32 @@
+package hs.kr.entrydsm.configuration.adapterin.common
+
+import com.fasterxml.jackson.annotation.JsonInclude
+import java.time.Instant
+
+data class ApiResponse<T>(
+    val success: Boolean,
+    val data: T? = null,
+    val error: ErrorResponse? = null,
+    @get:JsonInclude(JsonInclude.Include.NON_NULL)
+    val timestamp: Instant? = null,
+) {
+    companion object {
+        fun <T> success(data: T) = ApiResponse(success = true, data = data)
+
+        fun failure(errorCode: ErrorCode, message: String? = null) = ApiResponse<Nothing>(
+            success = false,
+            error = ErrorResponse(
+                code = errorCode.name,
+                message = message ?: errorCode.message,
+                status = errorCode.status.value(),
+            ),
+            timestamp = Instant.now(),
+        )
+    }
+}
+
+data class ErrorResponse(
+    val code: String,
+    val message: String,
+    val status: Int,
+)

systems/configuration/configuration-adapter-in/src/main/kotlin/hs/kr/entrydsm/configuration/adapterin/common/DocumentExceptionHandler.kt

@@ -0,0 +1,63 @@
+package hs.kr.entrydsm.configuration.adapterin.common
+
+import hs.kr.entrydsm.configuration.domain.document.exception.FileDocumentNotFoundException
+import hs.kr.entrydsm.configuration.domain.document.exception.FileTooLargeException
+import hs.kr.entrydsm.configuration.domain.document.exception.InvalidFileFormatException
+import hs.kr.entrydsm.configuration.domain.document.exception.InvalidFileNameException
+import hs.kr.entrydsm.configuration.domain.document.exception.PresignFailedException
+import hs.kr.entrydsm.configuration.domain.document.exception.StorageUploadFailedException
+import org.slf4j.LoggerFactory
+import org.springframework.http.ResponseEntity
+import org.springframework.web.bind.MissingServletRequestParameterException
+import org.springframework.web.bind.MethodArgumentNotValidException
+import org.springframework.web.bind.annotation.ExceptionHandler
+import org.springframework.web.bind.annotation.RestControllerAdvice
+import org.springframework.web.multipart.MaxUploadSizeExceededException
+
+@RestControllerAdvice
+class DocumentExceptionHandler {
+
+    private val log = LoggerFactory.getLogger(javaClass)
+
+    @ExceptionHandler(InvalidFileFormatException::class)
+    fun handleInvalidFileFormat(e: InvalidFileFormatException) =
+        respond(ErrorCode.INVALID_FILE_FORMAT, e)
+
+    @ExceptionHandler(FileTooLargeException::class, MaxUploadSizeExceededException::class)
+    fun handleFileTooLarge(e: Exception) =
+        respond(ErrorCode.FILE_TOO_LARGE, e)
+
+    @ExceptionHandler(FileDocumentNotFoundException::class)
+    fun handleFileNotFound(e: FileDocumentNotFoundException) =
+        respond(ErrorCode.FILE_NOT_FOUND, e)
+
+    @ExceptionHandler(
+        InvalidFileNameException::class,
+        MissingServletRequestParameterException::class,
+        MethodArgumentNotValidException::class,
+        IllegalArgumentException::class,
+    )
+    fun handleInvalidRequestParam(e: Exception) =
+        respond(ErrorCode.INVALID_REQUEST_PARAM, e)
+
+    @ExceptionHandler(StorageUploadFailedException::class)
+    fun handleStorageUploadFailed(e: StorageUploadFailedException) =
+        respond(ErrorCode.STORAGE_UPLOAD_FAILED, e)
+
+    @ExceptionHandler(PresignFailedException::class)
+    fun handlePresignFailed(e: PresignFailedException) =
+        respond(ErrorCode.PRESIGN_FAILED, e)
+
+    @ExceptionHandler(Exception::class)
+    fun handleUnexpected(e: Exception): ResponseEntity<ApiResponse<Nothing>> {
+        log.error("Unhandled exception", e)
+        return ResponseEntity
+            .status(ErrorCode.INTERNAL_SERVER_ERROR.status)
+            .body(ApiResponse.failure(ErrorCode.INTERNAL_SERVER_ERROR))
+    }
+
+    private fun respond(errorCode: ErrorCode, e: Exception): ResponseEntity<ApiResponse<Nothing>> {
+        log.warn("{}: {}", errorCode.name, e.message)
+        return ResponseEntity.status(errorCode.status).body(ApiResponse.failure(errorCode))
+    }
+}

systems/configuration/configuration-adapter-in/src/main/kotlin/hs/kr/entrydsm/configuration/adapterin/common/ErrorCode.kt

@@ -0,0 +1,13 @@
+package hs.kr.entrydsm.configuration.adapterin.common
+
+import org.springframework.http.HttpStatus
+
+enum class ErrorCode(val status: HttpStatus, val message: String) {
+    INVALID_REQUEST_PARAM(HttpStatus.BAD_REQUEST, "요청 파라미터가 올바르지 않습니다."),
+    INVALID_FILE_FORMAT(HttpStatus.BAD_REQUEST, "지원하지 않는 파일 형식입니다."),
+    FILE_NOT_FOUND(HttpStatus.NOT_FOUND, "파일을 찾을 수 없습니다."),
+    FILE_TOO_LARGE(HttpStatus.CONTENT_TOO_LARGE, "허용 용량을 초과했습니다."),
+    STORAGE_UPLOAD_FAILED(HttpStatus.BAD_GATEWAY, "파일 저장에 실패했습니다."),
+    PRESIGN_FAILED(HttpStatus.BAD_GATEWAY, "다운로드 URL 발급에 실패했습니다."),
+    INTERNAL_SERVER_ERROR(HttpStatus.INTERNAL_SERVER_ERROR, "서버 내부 오류가 발생했습니다."),
+}

systems/configuration/configuration-adapter-in/src/main/kotlin/hs/kr/entrydsm/configuration/adapterin/document/FileReferenceId.kt

@@ -0,0 +1,14 @@
+package hs.kr.entrydsm.configuration.adapterin.document
+
+import hs.kr.entrydsm.configuration.domain.document.FileCategory
+
+object FileReferenceId {
+
+    fun of(category: FileCategory, id: Long): String = "${prefixOf(category)}$id"
+
+    fun parse(category: FileCategory, value: String): Long =
+        value.removePrefix(prefixOf(category)).toLongOrNull()
+            ?: throw IllegalArgumentException("Invalid ${category.name.lowercase()} id: $value")
+
+    private fun prefixOf(category: FileCategory) = "${category.name.lowercase()}_"
+}

systems/configuration/configuration-adapter-in/src/main/kotlin/hs/kr/entrydsm/configuration/adapterin/document/MultipartFileExtensions.kt

@@ -0,0 +1,20 @@
+package hs.kr.entrydsm.configuration.adapterin.document
+
+import hs.kr.entrydsm.configuration.domain.document.FileCategory
+import hs.kr.entrydsm.configuration.domain.document.FileExtension
+import hs.kr.entrydsm.configuration.domain.document.command.UploadFileCommand
+import hs.kr.entrydsm.configuration.domain.document.exception.InvalidFileFormatException
+import org.springframework.web.multipart.MultipartFile
+
+fun MultipartFile.requireExtension(category: FileCategory): FileExtension =
+    FileExtension.fromFileName(originalName())
+        ?: throw InvalidFileFormatException(originalName(), category)
+
+fun MultipartFile.toUploadCommand(category: FileCategory, fileName: String) = UploadFileCommand(
+    category = category,
+    originalName = originalName(),
+    fileName = fileName,
+    sizeBytes = size,
+)
+
+private fun MultipartFile.originalName(): String = originalFilename.orEmpty()

systems/configuration/configuration-adapter-in/src/main/kotlin/hs/kr/entrydsm/configuration/adapterin/document/dto/FileResponses.kt

@@ -0,0 +1,49 @@
+package hs.kr.entrydsm.configuration.adapterin.document.dto
+
+import hs.kr.entrydsm.configuration.domain.document.DownloadUrl
+import hs.kr.entrydsm.configuration.domain.document.FileDocument
+
+data class UploadFileResponse(
+    val key: String,
+    val fileName: String,
+) {
+    companion object {
+        fun from(fileDocument: FileDocument) = UploadFileResponse(
+            key = fileDocument.objectKey,
+            fileName = fileDocument.fileName,
+        )
+    }
+}
+
+data class UploadPhotoResponse(
+    val key: String,
+    val fileName: String,
+    val url: String,
+)
+
+data class UploadAttachmentResponse(
+    val attachmentId: String,
+    val key: String,
+    val fileName: String,
+    val size: Long,
+)
+
+data class DownloadUrlResponse(
+    val fileName: String,
+    val downloadUrl: String,
+    val expiresIn: Long,
+) {
+    companion object {
+        fun from(downloadUrl: DownloadUrl) = DownloadUrlResponse(
+            fileName = downloadUrl.fileName,
+            downloadUrl = downloadUrl.downloadUrl,
+            expiresIn = downloadUrl.expiresIn,
+        )
+    }
+}
+
+data class FileMetadataResponse(
+    val key: String,
+    val fileName: String,
+    val exists: Boolean,
+)