project-base

목차

버전 정보

[자바] java : 1.8
[스프링 부트] org.springframework.boot : 2.7.12
[전자정부 프레임워크] org.egovframework : 4.2 

의존성

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-web'
	implementation 'org.springframework.boot:spring-boot-starter-webflux'
	implementation 'org.springframework.boot:spring-boot-starter-security'
 implementation("org.egovframe.rte:org.egovframe.rte.bat.core:4.2.0") {
		exclude group: 'org.egovframe.rte', module: 'org.egovframe.rte.fdl.logging'
	}
	implementation 'org.apache.commons:commons-collections4:4.4'
	implementation 'org.apache.commons:commons-text:1.10.0'
	implementation 'org.apache.poi:poi-ooxml:5.2.4'
	compileOnly 'org.projectlombok:lombok'
	annotationProcessor 'org.projectlombok:lombok'
	testImplementation 'org.springframework.boot:spring-boot-starter-test'
	testImplementation 'org.springframework.security:spring-security-test'
	testImplementation 'io.projectreactor:reactor-test'
	testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

라이브러리 생성

plugins {
	id 'java'
	id 'org.springframework.boot' version '2.7.12'
	id 'io.spring.dependency-management' version '1.0.15.RELEASE'
	id 'maven-publish'
	id 'com.github.johnrengelman.shadow' version '7.1.2'
}
...(중략)
shadowJar {
 archiveFileName.set('project-base-0.0.1-all.jar')
}
publishing {
	publications {
		mavenJava(MavenPublication) {
			artifact shadowJar
		}
	}
}

./gradlew shadowJar 

프레임워크 모듈

API

/**
 * {@link WebClient}를 사용하여 웹 API 호출을 수행하는 클라이언트입니다.
 */
@Slf4j
@Component
public class WebApiClient {
 private final WebClient webClient;
 
 ...(중략)
 /**
 * 주어진 API 요청을 동기적으로 호출하고 응답을 반환합니다.
 *
 * @param <T> 응답 본문의 타입
 * @param request 호출할 API 요청
 * @return API 요청의 응답 본문
 */
 public <T> T callReturn(ApiRequest<T> request) {
 return retrieve(request).block();
 }
 /**
 * 주어진 API 요청을 비동기적으로 호출합니다.
 *
 * @param <T> 응답 본문의 타입
 * @param request 호출할 API 요청
 */
 public <T> void call(ApiRequest<T> request) {
 retrieve(request).subscribe(request::subscribe, request::error);
 }
 
 ...(중략)
}

/**
 * API 요청을 표현하는 인터페이스입니다.
 *
 * @param <T> 응답 타입
 */
public interface ApiRequest<T> {
 /**
 * HTTP 메서드를 반환합니다.
 *
 * @return 요청에 사용될 HTTP 메서드
 */
 HttpMethod getMethod();
 /**
 * 요청할 URL을 반환합니다.
 *
 * @return 요청할 URL
 */
 String getUrl();
 /**
 * 요청 본문을 반환합니다.
 *
 * @return 요청 본문
 */
 Object getBody();
 /**
 * 응답 타입을 반환합니다.
 *
 * @return 응답 타입 클래스
 */
 Class<T> getResponseType();
 
 ...(중략)
}

공통

/**
 * 키-값 쌍을 보관하고 조작하는 데 사용되는 DTO 맵 클래스입니다.
 * 기본적으로 키를 camelCase로 변환합니다.
 */
public class BaseMap extends HashMap<String, Object> {
 ...(중략)
}

/**
 * BaseMap 클래스에 대한 테스트 클래스입니다.
 */
class BaseMapTest {
 /**
 * JSON 문자열 파싱을 테스트하는 메서드입니다.
 * JSON 문자열을 BaseMap 객체로 변환하고,
 * 변환된 BaseMap 객체의 값을 확인합니다.
 */
 @Test
 void jsonParsing() {
 String json = "{\n" +
 " \"search_map\": {\n" +
 " \"string_value\": \"formal_contents\",\n" +
 " \"long_value\": 1203405603,\n" +
 " \"double_value\": 1.2,\n" +
 " \"integer_value\": 10,\n" +
 " \"map_value\" : {\n" +
 " \"hello_world\" : \"I'm project base\"\n" +
 " },\n" +
 " \"list_string_value\": [\n" +
 " \"one\",\n" +
 " \"two\"\n" +
 " ],\n" +
 " \"list_map_value\": [\n" +
 " {\n" +
 " \"key\": \"value\"\n" +
 " }\n" +
 " ]\n" +
 " }\n" +
 "}";
 BaseMap baseMap = BaseMap.of(json);
 System.out.println("baseMap = " + baseMap);
 assertThat(baseMap).isNotNull();
 assertThat(baseMap.getMap("searchMap")).isNotNull();
 assertThat(baseMap.getMap("searchMap").getString("stringValue")).isEqualTo("formal_contents");
 assertThat(baseMap.getMap("searchMap").getLong("longValue")).isEqualTo(1203405603);
 assertThat(baseMap.getMap("searchMap").getDouble("doubleValue")).isEqualTo(1.2);
 assertThat(baseMap.getMap("searchMap").getInteger("integerValue")).isEqualTo(10);
 assertThat(baseMap.getMapByKeys("searchMap", "mapValue").getString("helloWorld")).isEqualTo("I'm project base");
 assertThat(baseMap.getMap("searchMap").getList("listStringValue").get(0)).isEqualTo("one");
 List<BaseMap> list = baseMap.getMap("searchMap").getMapList("listMapValue");
 assertThat(list.size()).isEqualTo(1);
 BaseMap item = list.get(0);
 assertThat(item.getString("key")).isEqualTo("value");
 }
}

/**
 * API 응답을 위한 클래스입니다.
 * <p>
 * 이 클래스는 API 요청에 대해 반환할 데이터 규격을 정의합니다.
 */
@Data
@Builder
@JsonInclude(NON_NULL)
public class ApiResponse<T> {
 /**
 * 응답 코드
 */
 private final int code;
 /**
 * 응답 메시지
 */
 private final String message;
 /**
 * API 응답의 결과 데이터를 포함
 */
 private final T result;
 /**
 * 실패 응답을 생성하는 메소드.
 *
 * @param code 응답 코드
 * @param message 응답 메시지
 */
 public static ApiResponse<?> fail(int code, String message) {
 return ApiResponse.builder()
 .code(code)
 .message(message)
 .build();
 }
 /**
 * 성공 응답을 생성하는 메소드.
 *
 * @param result 결과 데이터
 */
 public static <T> ApiResponse<T> success(T result) {
 return ApiResponse.<T>builder()
 .code(HttpStatus.OK.value())
 .message(HttpStatus.OK.getReasonPhrase())
 .result(result)
 .build();
 }
 /**
 * 결과 데이터 없는 성공 응답을 생성하는 메소드.
 */
 public static <T> ApiResponse<T> success() {
 return ApiResponse.<T>builder()
 .code(HttpStatus.OK.value())
 .message(HttpStatus.OK.getReasonPhrase())
 .build();
 }
}

{
 "code" : (int),
 "message" : (String),
 "result" : (T)
}

예외 처리

public interface ErrorCode {
 int getCode();
 String getMessage();
}

/**
 * ErrorCode는 예외 처리에 사용되는 오류 코드를 정의하는 열거형 클래스입니다.
 * 각 열거 상수는 오류 코드와 메시지를 가지고 있습니다.
 */
@Getter
@RequiredArgsConstructor
public enum BaseErrorCode implements ErrorCode {
 /**
 * HTTP 40x 코드 기반 5자리
 */
 BAD_REQUEST(40000, "잘못된 요청 값 입니다."),
 REQUIRED(40001, "%s 값은 필수입니다."),
 VALIDATE(40002, "%s 값이 올바르지 않습니다."),
 /**
 * HTTP 50x 코드 기반 5자리
 */
 UNKNOWN(50000, "알 수 없는 에러입니다."),
 ;
 private final int code;
 private final String message;
}

/**
 * BusinessException은 비즈니스 로직에서 발생할 수 있는 예외를 나타내는 클래스입니다.
 * RuntimeException을 상속받아 unchecked 예외로 정의되어 있습니다.
 */
@Getter
public class BusinessException extends RuntimeException {
 private final ErrorCode errorCode;
 /**
 * 주어진 메시지를 가지고 기본적인 UNKNOWN 에러 코드로 BusinessException을 생성합니다.
 *
 * @param message 예외 메시지
 */
 public BusinessException(String message) {
 super(message);
 this.errorCode = BaseErrorCode.UNKNOWN;
 }
 /**
 * 주어진 에러 코드로 BusinessException을 생성합니다.
 *
 * @param errorCode 에러 코드
 */
 public BusinessException(ErrorCode errorCode) {
 super(errorCode.getMessage());
 this.errorCode = errorCode;
 }
 /**
 * 주어진 에러 코드와 추가적인 인자를 사용하여 BusinessException을 생성합니다.
 * 에러 메시지는 포맷팅된 형태로 제공됩니다.
 *
 * @param errorCode 에러 코드
 * @param args 포맷팅에 사용될 인자들
 */
 public BusinessException(ErrorCode errorCode, Object... args) {
 super(String.format(errorCode.getMessage(), args));
 this.errorCode = errorCode;
 }
}

/**
 * ApiExceptionHandler는 Spring Web MVC에서 발생하는 예외를 처리하는 클래스입니다.
 * RestControllerAdvice 애노테이션을 사용하여 모든 @RestController에서 발생하는 예외를 처리합니다.
 * 각 예외에 따라 적절한 HTTP 상태 코드와 메시지를 반환합니다.
 */
@Slf4j
@RestControllerAdvice(annotations = RestController.class)
public class ApiExceptionHandler {
 /**
 * BusinessException을 처리하는 메서드입니다.
 *
 * @param e 발생한 BusinessException 객체
 * @return ApiResponse 객체 (실패 응답)
 */
 @ExceptionHandler(BusinessException.class)
 public ApiResponse<?> buisnessException(BusinessException e) {
 log.error("ApiException buisnessException", e);
 return ApiResponse.fail(e.getErrorCode().getCode(), e.getMessage());
 }
 
 ...(중략)
}

파일 처리

/**
 * FileManager 인터페이스는 파일 관리 기능을 정의하는 인터페이스입니다.
 * 구현 클래스에서 파일 업로드, 다운로드, 파일명 생성 등의 기능을 제공합니다.
 */
public interface FileManager {
 /**
 * 파일이 저장될 디렉토리 경로를 반환합니다.
 *
 * @return 파일이 저장될 디렉토리 경로
 */
 String getDirectory();
 ...(중략)
 /**
 * 주어진 MultipartFile을 업로드하고 AttachUploadFile 객체로 반환합니다.
 *
 * @param file 업로드할 MultipartFile 객체
 * @return AttachUploadFile 객체
 */
 default AttachUploadFile upload(MultipartFile file) {
 validate(file);
 String originalFileName = file.getOriginalFilename();
 String storedFileName = createStoredFileName(originalFileName);
 FileUtils.upload(file, getFullPath(storedFileName));
 return AttachUploadFile.of(originalFileName, storedFileName);
 }
 /**
 * DownloadFile 객체를 사용하여 파일을 다운로드합니다.
 *
 * @param downloadFile 다운로드할 파일 정보를 포함한 DownloadFile 객체
 * @param <T> 응답 바디 타입
 * @return ResponseEntity 객체로 감싼 다운로드 결과
 */
 default <T> ResponseEntity<T> download(DownloadFile<T> downloadFile) {
 return ResponseEntity.ok().headers(downloadFile.getHeaders()).body(downloadFile.getBody());
 }
}

/**
 * UploadFile 인터페이스는 업로드된 파일의 원본 파일명과 저장된 파일명을 제공하는 메서드를 정의합니다.
 */
public interface UploadFile {
 /**
 * 업로드된 파일의 원본 파일명을 반환합니다.
 *
 * @return 원본 파일명
 */
 String getOriginalFileName();
 /**
 * 업로드된 파일의 저장된 파일명을 반환합니다.
 *
 * @return 저장된 파일명
 */
 String getStoredFileName();
}

/**
 * DownloadFile 인터페이스는 파일 다운로드 정보를 정의하는 인터페이스입니다.
 * 구현 클래스에서는 다운로드할 파일명, HTTP 헤더, 응답 바디를 제공해야 합니다.
 *
 * @param <T> 다운로드할 데이터의 타입
 */
public interface DownloadFile<T> {
 /**
 * 다운로드할 파일명을 반환합니다.
 *
 * @return 다운로드할 파일명
 */
 String getDownloadFileName();
 /**
 * 다운로드할 파일에 대한 HTTP 헤더를 반환합니다.
 *
 * @return HTTP 헤더 객체
 */
 HttpHeaders getHeaders();
 /**
 * 다운로드할 데이터의 본문을 반환합니다.
 *
 * @return 다운로드할 데이터의 본문
 */
 T getBody();
}

/**
 * ExcelWriter 인터페이스는 Excel 파일 작성을 위한 기능을 정의합니다.
 * <p>
 * 구현체는 Excel 파일의 헤더 스타일, 헤더 이름 및 값을 작성하기 위한 메서드를 포함합니다.
 * </p>
 *
 * @param <T> Excel 파일에 작성할 객체의 타입
 */
public interface ExcelWriter<T> {
 /**
 * Excel 파일에 작성할 데이터 리스트를 반환합니다.
 *
 * @return Excel 파일에 작성할 데이터 리스트
 */
 List<?> getList();
 /**
 * Excel 파일에 작성할 객체의 클래스 타입을 반환합니다.
 *
 * @return Excel 파일에 작성할 객체의 클래스 타입
 */
 Class<T> getType();
 
 ...(중략)
}

로깅

/**
 * ApiLoggingAspect는 REST 컨트롤러의 HTTP 요청을 로깅하기 위한 Aspect입니다.
 * <p>
 * 이 클래스는 @RestController 어노테이션이 붙은 클래스 내에서 메서드 호출 전에 HTTP 요청을 로깅합니다.
 * 로깅할 정보로는 IP 주소, HTTP 메서드, 요청 URL, 쿼리 스트링, 요청 바디가 포함됩니다.
 */
@Slf4j
@Aspect
@Component
public class ApiLoggingAspect {
 /**
 * {@link org.springframework.web.bind.annotation.RestController} 어노테이션이 붙은 클래스
 * 내의 모든 메서드를 포인트컷으로 설정합니다.
 */
 @Pointcut("within(@org.springframework.web.bind.annotation.RestController *)")
 public void restController() {
 }
 /**
 * 포인트컷에서 지정한 메서드 호출 전에 HTTP 요청을 로깅하는 메서드입니다.
 *
 * @param joinPoint 조인 포인트 객체로, 호출된 메서드와 그 파라미터 등을 추출하는 데 사용됩니다.
 */
 @Before("restController()")
 public void httpLogging(JoinPoint joinPoint) {
 String remoteAddr = getRemoteAddr();
 String method = getMethod();
 String requestURL = getRequestURL();
 String queryString = getQueryString();
 String requestBody = getRequestBody(joinPoint);
 log.info("HTTP Logging IP : {} | Method : {} | URL : {} | Query : {} | Body {}",
 remoteAddr, method, requestURL, queryString, requestBody);
 }
 
 ...(중략)
}

HTTP Logging IP : {} | Method : {} | URL : {} | Query : {} | Body {}

샘플 프로젝트

이슈