docs 삭제

This commit is contained in:
주수현
2025-07-30 10:52:51 +09:00
parent 6d208e0e74
commit 0d8afa0f01
12 changed files with 0 additions and 647 deletions

View File

@@ -1,61 +0,0 @@
# Recycle 2 버전의 가장 큰 변화
## model mapper 에서 생성자 패턴으로의 전환
> "자바를 보다 더 컴파일 언어스럽게"
컴파일 언어의 가장 큰 장점은 compile 시점에 발생할 수 있는 모든 오류를 작성자에게 알려주어 runtime 시 사용자가 마주하게 되는 버그를 최소화 시켜 준다는 점입니다.
엔티티 속성이 변경되거나 추가될 때 이를 사용하는 모든 곳에서 컴파일 에러가 발생한다면 코드 수정자의 입장에서 가장 이상적인 환경이됩니다.
model mapper 는 이러한 변경의 파급효과를 runtime 시점으로 미뤄버리기에 수정 및 리펙토링 환경에서 매우 해로운 기술입니다. JPA 관점에서도 연관 엔티티간의 조회 및 참조에서 원치않은 동작을
유발시키며 이를 제어하기는 무척 까다롭습니다.
새로운 프레임워크 버전 부터 **model mapper 가 제거**되었고, 생성자 패턴을 이용해 엔티티 및 인자, 결과 객체를 교환합니다. 생성자 패턴 적용예는 **예제 게시판**에서 확인 가능합니다.
## JPA Metamodel 도입
JPA 를 이용할 때 엔터티 클래스의 속성을 문자열로 참조해야 하는 경우가 발생합니다 (예: mappedBy="속성명").
프로젝트 진행 과정에서 해당 속성이 변경(혹은 삭제)되는 경우, 컴파일러는 이를 인지하지 못합니다. 즉, type safe 하지 않습니다.
이름이 사용되는 곳을 찾아 수작업으로 변경해주어야 하며, 이를 놓친 경우 runtime 과정에서 예상치 못한 에러를 만나게 됩니다.
JPA 메타모델은 이러한 단점을 피하고 관리되는 엔터티 클래스의 메타데이터에 대한 정적 액세스를 제공하기 위해 도입되었습니다.
`hibernate-jpamodelgen` maven 모듈을 통해 `target/generated-sources/annotations` 로 정적 JPA Metamodel 클래스들이 생성됩니다.
```
$ tree core/target/generated-sources/annotations/
core/target/generated-sources/annotations/
`-- app
`-- module
`-- core
`-- config
`-- adapter
`-- persistence
`-- entity
|-- ExBoardAttachment_.java
|-- ExBoard_.java
|-- FrontUser_.java
|-- LoggedInUserEmbeddable_.java
...
```
JPA 사양에 따라 생성된 클래스는 해당 엔티티 클래스와 동일한 패키지에 상주하며 끝에 "_"(언더스코어)가 추가된 동일한 이름을 갖습니다.
이제 Metamodel 클래스를 이용해 type safe 프로그래밍을 해봅시다.
```java
// Metamodel 적용 전
@OneToMany(mappedBy = "exBoard", ...})
private Set<ExBoardAttachment> attachments;
// Metamodel 적용 후
@OneToMany(mappedBy = ExBoardAttachment_.EX_BOARD, ...})
private Set<ExBoardAttachment> attachments;
```
정적 Metamodel 클래스는 maven compile 단계에서 생성되며 IDE 에서 어플리케이션 구동 시 빌드과정에서 자동으로 수행됩니다.
생성된 모델을 참조하기 위해서는 `target/generated-sources` 경로가 IDE 의 **classpath** 에 추가되어야 합니다.
인텔리제이의 경우, File > Project Structure > Modules > target\generated-sources 우클릭 후 Sources 체크 해주면 됩니다.

View File

@@ -1,93 +0,0 @@
# DOC-002: 파일 업로드
## Introduction
파일을 업로드하는데 `LOCAL`과 `S3` 두가지 전략이 있다. `LOCAL`은 WAS 가 접근가능한 저장공간을 제어하는 정책(기본)이며,
`S3`는 AWS의 저장 스토리지를 다루는 전략이다.
어떤 전략을 취하든 우리는 동일한 인터페이스를 이용하면 된다.
## Interface
**SaveToStorageService** 의 operate 메서드를 호출해 파일 업로드를 수행한다.
|Arguments|Description
|---|---
|FileUploadType| 파일 타입과 업로드 전략 등 파일 업로드에 필요한 정보를 담은 enum 객체
|MultipartFile| 업로드 Multipart File
* FileUploadType 에 정의한 FileStorageType 설정값(`Local` or `S3`) 을 통해 업로드 공간이 결정된다.
|반환 타입|설명
|---|---
|Optional\<SaveToStorage\>| ...
## Set up
파일 업로드에 관한 공통 설정은 `core.properties` 에 선언했다.
```properties
spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=50MB
spring.servlet.multipart.file-size-threshold=1MB
```
스프링 profile 별로 차별화된 설정은 `core-${spring.profiles.active}.properties` 에 기술한다.
(예) core-local.properties
```properties
# `Public` 업로드 경로
path.upload.public=${user.home}/upload/public
# file-size-threshold 용량이 넘는 파일 업로드시 사용할 임시 디렉토리
path.upload.tmpdir=${user.home}/upload/tmpdir
spring.servlet.multipart.location=${path.upload.tmpdir}
```
* `path.upload.tmpdir`는 multipart 용량이 `file-size-threshold`을 초과할 때
임시적으로 파일을 저장 할 수 있는 공간이다.
## How to use
파일 업로드는 `SaveToStorageService` 를 이용한다.
```java
// 예제 게시판 업로드
SaveToStorageService.operate(FileUploadType.EXAMPLE_PUBLIC, multipartFile);
```
* `FileUploadType` 은 파일 업로드 타입과 저장 경로, 그리고 외부 공개여부에 대한 정보를 정의한 enum 객체이다.
* `multipartFile` 사용자가 선택한 파일 객체.
FileUploadType 객체는 파일 업로드와 관한 필수 정보를 담고 있다.
**추후 새로운 파일 업로드 기능이 추가 될때 마다 이곳에 관련 정보를 기술**해야합니다.
```java
// FileUploadType.EXAMPLE_PUBLIC 에 정의된 정보
...
EXAMPLE_PUBLIC(
FileStorageType.LOCAL, // fileStorageType
"/exampleBoard", // sub 디렉토리
Set.of( // 허용 타입
AcceptableFileType.IMAGE,
AcceptableFileType.EXCEL,
AcceptableFileType.PPT,
AcceptableFileType.HWP,
AcceptableFileType.WORD,
AcceptableFileType.CSV,
AcceptableFileType.TXT,
AcceptableFileType.PDF,
AcceptableFileType.ZIP)),
```
* `fileStorageType`은 파일이 저장될 공간. `LOCAL`과 `S3`가 제공된다.
* `subPath`는 게시판에 따른 분류 등으로 사용할 때 이용. 공지사항 게시물의 업로드 파일이기에 /exampleBoard 서브 경로에 담도록 지정했다.
* `acceptableFileTypes` 에 허용할 파일 타입을 명시. 지정된 파일 타입과 다른 파일이 업로드 될때 `UnAcceptableFileExceoption` 이 발생한다.
### acceptableFileTypes
`SaveToStorageService`는 `acceptableFileTypes` 에 기술된
FileType 을 기준으로 검증작업을 수행한다. multipartFile 을 inputstream 으로 읽어 MIME Type 적합성 여부를 판단한다.
## References
[파일 업로드 시 MIME 타입 확인](https://github.com/devheedoo/TIW/blob/master/%5BJava%5D%20%ED%8C%8C%EC%9D%BC%20%EC%97%85%EB%A1%9C%EB%93%9C%20%EC%8B%9C%20MIME%20%ED%83%80%EC%9E%85%20%ED%99%95%EC%9D%B8.md)

View File

@@ -1,69 +0,0 @@
# DOC-004: 예외처리 가이드
## Introduction
예외를 처리하는데 공통되고 일관된 처리 방식이 필요하다.
프로그램 수행 중 발생하는 모든 예외처리는 @ControllerAdvice 객체인 `GlobalControllerAdvice.java` 가 담당합니다.
@ControllerAdvice 는 @Controller 에서 발생된 모든 예외를 처리하지만,
Interceptor 에서 발생한 예외(스프링 시큐리티 권한체크 포함)는 처리하지 못한다는 점에 유의하세요.
이에 대한 예외 또한 커스터마이징 하고 싶다면 ErrorController 를 구현해주면 됩니다. 아래 문서를 참고하세요.
[Spring Boot 에서 에러 페이지 처리하기](https://eblo.tistory.com/50)
[스프링부트 커스텀 error](https://juyoungkim223.github.io/springboot/error/ErrorController/)
## Runtime 예외처리
프로그램 수행 중 발생하는 모든 예외처리는 @ControllerAdvice 객체인 `GlobalControllerAdvice.java` 가 담당합니다.
코드 실행 시 발생하는 예측불가한 에러뿐 아니라 코드 작성자가 발생시키는 Runtime 예외 또한 해당 Advice 객체가 처리합니다.
프레임워크는 사용자에게 정확한 정보전달을 위해 명시적으로 예외를 발생시키는 방식을 **적극적으로 권장**합니다.
아래 예제는 잘못된 adminId 전달 시 이를 사용자에게 알리는 예외처리 코드입니다.
```java
public Admin getItem(String adminId) {
return adminRepository
.findById(adminId)
.orElseThrow(
() -> new NoSuchElementException(String.format("%s 는 존재하지 않는 아이디입니다.", adminId)));
}
```
발생된 예외는 `GlobalControllerAdvice.java` 에 의해 일반 요청인지 Ajax 요청인지를 판단 후 적절한 형식으로 반환합니다.
* 일반 요청: 에러 정보를 model 객체에 담은 뒤 에러 페이지 전달
* AJAX 요청: 에러 정보를 JSON 응답 형식으로 전달
사용자는 에러 메세지를 통해 에러 발생 원인을 파악해 볼 수 있습니다.
코드 작성자가 이용할 수 있는 예외 객체로 NoSuchElementException, IllegalArgumentException 등 자바 혹은 사용중인 모듈에서
제공하는 기본 RuntimeException 예외객체를 이용하는걸 추천합니다. 물론 코드 작성자가 임의로 만든 커스텀 예외객체를 이용해도 됩니다.
### AJAX(비동기) 예외 처리 시 권장사항
Ajax 요청에 대한 예외처리시 `GlobalControllerAdvice.java` 는 HTTP 상태코드로 400 (HttpStatus.BAD_REQUEST) 을 전달합니다.
jQuery 를 이용한 ajax 호출 방식에서 응답 status code 에 따른 처리를 선언하는 것을 **적극적으로 권장**합니다.
```javascript
$.ajax({
type: 'GET',
url: '/api/uri/get/' + f.appType.value + '/' + data.id,
statusCode: {
// 400 - BAD_REQUEST
400: function (response) {
alert(response.responseJSON.message);
}
},
```
응답을 처리하는 Javascript 는 message 속성을 alert 로 보여주는 등의 방식으로 사용자에게 에러 내용을 보여줄 수 있습니다.
$.ajax 의 fail 콜백함수를 사용해도 되지만,
예외 처리 이외에도 validation 실패 시 422 를 전달하는 등 다른 부가기능들도 프레임워크가 제공하기에
statusCode 선언을 통한 처리방식이 효율적입니다.
## 참고문서
[Spring 의 다양한 예외 처리 방법](https://mangkyu.tistory.com/204)
[DispatcherServlet 의 예외처리 전략 (Interceptor 예외처리 전략)](https://velog.io/@gillog/Java-HandlerInterceptor%EB%8B%A8-Exception-Handling%ED%95%98%EA%B8%B0HandlerExceptionResolver-ExceptionHandler)

View File

@@ -1,43 +0,0 @@
# Logging (logback) 가이드
로깅 설정은 구동중인 인스턴스의 `logback-spring.xml`과 `application-${spring.profiles.active}.properties` 에 기술되어 있습니다.
logback-spring.xml
```xml
<configuration>
...
<property name="APP_LOG_FILE" value="admin-app"/>
...
</configuration>
```
application-local.properties
```properties
#
# █████╗ ██████╗ ██████╗ ██╗ ██████╗ ██████╗ ██████╗ ██╗███╗ ██╗ ██████╗
# ██╔══██╗██╔══██╗██╔══██╗ ██║ ██╔═══██╗██╔════╝ ██╔════╝ ██║████╗ ██║██╔════╝
# ███████║██████╔╝██████╔╝ ██║ ██║ ██║██║ ███╗██║ ███╗██║██╔██╗ ██║██║ ███╗
# ██╔══██║██╔═══╝ ██╔═══╝ ██║ ██║ ██║██║ ██║██║ ██║██║██║╚██╗██║██║ ██║
# ██║ ██║██║ ██║ ███████╗╚██████╔╝╚██████╔╝╚██████╔╝██║██║ ╚████║╚██████╔╝
# ╚═╝ ╚═╝╚═╝ ╚═╝ ╚══════╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝
logging.file.path=${user.home}/logs
#
# application 의 기본 패키지(app.module) 와 로깅 레벨(DEBUG) 설정
# 기본 패키지 변경 시 app.module 부분을 반드시 치환해 주어야 application 로그가 출력되니 유의
logging.level.app.module=DEBUG
```
* `logging.file.path` 로그파일이 생성될 위치
* `logging.level`.app.module 여러분의 어플리케이션 기본 패키지. 해당 패키지 하부의 로그 출력 Level을 설정합니다.
### 생성 로그 파일
`logging.file.path` 경로에 두가지 파일이 생성됩니다.
|로그파일|설명|
|---|---|
|`APP_LOG_FILE`.log| 전체 로그 파일|
|`APP_LOG_FILE`-ERROR.log| 에러 로그 파일|
에러 로그 파일에는 전체 로그 파일에서 ERROR 부분을 필터링해 별도로 생성한 파일입니다. 이는 운영관점에서 큰 이점을 가져다줍니다.
로그 보관 주기나 파일 Rolling 정책 등은 /src/main/resources/`logback-spring.xml` 을 확인하세요.

View File

@@ -1,37 +0,0 @@
# Menu 관리
Menu 는 관리자 - Settings - Menu 관리 화면을 통해 관리됩니다.
Tree View UI 를 통해 부모/자식 노드 관계를 유용하게 적용할 수 있습니다.
### SEO (검색엔진 최적화)
ogTitle, ogDesc, ogKeywords, ogImage 등 속성값 입력을 통해 현재 메뉴의 meta 및 og 정보가 화면에 노출됩니다.
```thymeleafexpressions
<!-- layout.html -->
<title th:text="${currentURI.ogTitle}"></title>
<meta name="title" th:content="${currentURI.ogTitle}"/>
<meta name="description" th:content="${currentURI.ogDesc}"/>
<meta name="keywords" th:content="${currentURI.ogKeywords}"/>
<meta property="og:title" th:content="${currentURI.ogTitle}"/>
<meta property="og:description" th:content="${currentURI.ogDesc}"/>
<meta property="og:keywords" th:content="${currentURI.ogKeywords}"/>
<meta property="og:image" th:content="${currentURI.ogImage}"/>
```
경우에 따라 특정 페이지에서 SEO 관련 정보를 변경하고 싶을 때가 있습니다.
예를들어, 제품 상세 페이지는 해당 상품의 고유값에 따라 동적으로 정보가 생성됩니다.
각 제품별로 SEO 정보를 다르게 보여주고 싶다면 Controller 단에서 변경작업을 해주면 됩니다.
```java
// title, seo 속성 변경 예제
Menu currentURI = ((Menu) request.getAttribute("currentURI")).toBuilder().build();
currentURI.setOgTitle("modified - exBoardEntity title");
currentURI.setOgKeywords("modified - exBoardEntity keywords");
currentURI.setOgDesc("modified - description");
model.addAttribute("currentURI", currentURI);
```
request 에서 조회된 currentURI 를 기반으로 새로운 Menu 를 생성(toBuilder)한 후 속성을 갱신해 model 에 넣어주면 됩니다.

View File

@@ -1,39 +0,0 @@
# **ADR-001:** 사용자 인증 및 정보 보안 정책
## Context
스프링 시큐리티를 이용하는 것만으로도 실제 업계에서 요구하는 주요 보안점검 항목들이 상당부분 충족된다.
보안을 중시하는 기업형 어플리케이션을 제작하는데 필요한 몇가지 추가 요구조건들을 구현해 놓으면, 추후 프로젝트를 수행하는데 큰 도움이 된다.
## Decision
스프링 시큐리티의 기본 정책 이외에 필드에서 요구되는 주요한 요구 항목을 아래와 같이 정의한다.
* 패스워드 유효기간은 사용자 설정을 따른다.
* 패스워드 만료 몇일전 부터 안내 메시지를 보여줄지는 사용자 설정을 따른다.
* 관리자는 disabled 필드를 이용해 특정 사용자의 비활성화 여부를 관리한다.
* 패스워드 5회 이상 오류 시 locked 필드를 이용해 사용자는 잠김처리 된다.
* 중복 로그인 허용 횟수는 사용자 설정을 따른다.
* 로그인 세션 유지 기간은 사용자 설정을 따른다.
## Status
`Accepted`
## Consequence
현재 구현된 항목은 아래와 같다.
* 패스워드 유효기간 설정 (90일)
- `app.admin.password.validity.period.days=90`
- -1 을 줄 경우 유효기간 체크를 하지 않는다.
* 패스워드 유효기간 만료 7일전 부터 안내 메시지 보이기
- `app.admin.password.change.notice.period.days=7`
* 관리자는 disabled 필드를 이용해 특정 사용자의 비활성화 여부를 관리한다.
* 패스워드 5회 이상 오류 시 locked 필드를 이용해 사용자는 잠김처리 된다.
- `app.admin.auth.fail.permit=5`
- 잠김 처리 시 사용자가 패스워드를 초기화하는 기능은 아직 구현되지 않았다. 현재는 관리자에게 문의하라는 메세지를 보여준다.
* 중복 로그인 허용 횟수는 유동적으로 조절이 가능하다.
- `app.admin.session.maximum.num=1`
- max 가 1인 경우 중복 로그인이 발생하면 이전 세션을 차단하고 로그인 한다는 메세지가 사용자에게 보여진다.
* 로그인 세션 유지 기간 설정이 가능하다.
- `app.admin.session.validity.period.seconds=3600`

View File

@@ -1,66 +0,0 @@
# **ADR-002:** 파일 업로드 및 참조 정책
## Context
사용자가 업로드한 파일은 전체 공개(public)를 목적으로 한다. 업로드한 파일을 참조하는데 두가지 방식이 있다. 파일 참조 시
브라우저 기본 기능이나 연결 프로그램을 통해 파일이 오픈되는 `INLINE` 방식과
외부 간섭없이 다이렉트 파일 다운로드를 수행하는 `ATTACHMENT` 방식이다.
## Decision
`path.upload.public` 설정을 통해 업로드 경로를 지정한다.
```properties
path.upload.public=${user.home}/upload/public
```
INLINE 파일 참조 URL 은 아래 형식으로 구성된다.
```
/content-disposition/inline/파일경로/파일명.확장자
```
ATTACHMENT 파일 참조 URL 은 아래 형식으로 구성된다.
```
/content-disposition/attachment/파일아이디
```
## Status
`Accepted`
## Consequence
### WAS 의 `Public` `INLINE` 참조 방식 설정
`Public` 공개 범위의 `INLINE` 업로드 경로를 리소스 핸들러로 지정했다.
```java
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry
.addResourceHandler("/content-disposition/inline/**")
.addResourceLocations("file:///" + publicPath + "/")
.setCachePeriod(20);
}
```
* 위 경로에 업로드된 파일은 스프링 @Controller 를 거치지 않고, URL 로 직접 참조가 가능하다.
* 웹서버가 없는 로컬 개발환경에서 테스트하기 적합하다.
### 웹서버의 `Public` `INLINE` 참조 방식 설정
웹서버의 경우, 가상 호스트 설정에서 Alias 를 이용해 `/content-disposition/inline` 경로와 `Public` 업로드 경로를
연결해주면 된다. `<Directory/>` 선언을 추가해서 웹서버가 해당 디렉토리로 접근할 수 있는 권한을 부여한다.
```
JkUnMount /content-disposition/inline/* [워커 이름]
Alias /content-disposition/inline "[Public 업로드 경로]"
<Directory "[Public 업로드 경로]">
Options FollowSymLinks
AllowOverride All
Require all granted
Allow from all
</Directory>
```
* `JkUnMount` 를 지정해 해당 경로의 자원을 WAS 가 아닌 웹서버가 전달하도록 설정한다.
### WAS 의 `ATTACHMENT` 참조 방식 설정
`ATTACHMENT` 참조 방식은 웹서버가 아닌 WAS 에서만 처리 가능하다.
`GetAttachmentController` 가 해당 역할을 담당한다.

View File

@@ -1,41 +0,0 @@
# **ADR-003:** AWS S3 파일 업로드 전략
## Context
로컬 스토리지를 이용해 파일을 업로드하는 기본 전략 (참고: [ADR-002-FILE_UPLOAD_POLICY.md](./ADR-002-FILE_UPLOAD_POLICY.md)) 이외에 AWS S3 로
파일을 올리고 CloudFront 를 통해 파일이 제공되는 새로운 전략이 필요했다.
## Decision
AWS S3 파일 업로드 기능 제공을 위해 새로운 전략을 구현한다.
새로운 전략은 기존과 동일한 파일 업로드 서비스 인터페이스를 이용하며,
`Public`, `Private` 공개범위를 가진다.
공개범위에 따른 `INLINE`, `ATTACHMENT` 응답 해더는 구현 가능한 범위 내에서 한정적으로 제공한다.
## Status
`Accepted`
## Consequence
`aws` maven 서브 모듈이 추가되었다. S3 파일 업로드 전략과 CloudFront 도메인으로 파일을 참조하는 전략을 담고 있다.
(훗날 새로운 AWS 기능이 필요하면 이 모듈에 추가될 것이다.)
S3 업로드가 필요하다면 `aws` 모듈을 종속성에 추가해주면 된다.
```xml
<dependency>
<groupId>app.module</groupId>
<artifactId>aws</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
```
`aws` 모듈의 `aws.properties` 와 `aws-{spring.active.profile}.properties` 에
S3와 CloudFront 를 이용하기 위한 설정 정보를 기입해야 한다.
`Content-Disposition` 은 `INLINE` 참조 방식만 제공한다.
| 공개 범위 | Content-Disposition | URL |
|---|---|---|
| `Public` | `INLINE` | ${app.aws.s3.domain}/파일경로/파일명.확장자
| | `ATTACHMENT` | /content-disposition/attachment/{파일아이디}

View File

@@ -1,71 +0,0 @@
# DIY-001: 스프링부트 Maven 프로젝트에 jar 라이브러리 추가하기
## Introduction
Maven 기반 스프링부트 프로젝트 구성에는 WEB-INF/lib 디렉토리가 없다.
외부 경로를 통해 얻은 jar 를 프로젝트에 포함시키려면 아래 작업이 필요하다.
이 예제는 front 모듈에 외부 jar 파일(INIpaySample_v1.3.jar)을 인식시키는 과정을 예로 든다.
## webapp/WEB-INF/lib 디렉토리 생성
src/main 밑에 `webapp/WEB-INF/lib` 디렉토리를 생성한다.
```shell
.
|-- pom.xml
|-- src
| |-- main
| | |-- java
| | |-- resources
| | `-- webapp
| | `-- WEB-INF
| | `-- lib
| | `-- INIpaySample_v1.3.jar
```
이 경로에 담긴 jar 파일은 패키징(`war` or `jar`) 결과물의 WEB-INF/lib 경로에 자동 포함된다.
물론 패키징 결과물을 만들기 위해서 빌드(`compile`)과정이 성공해야 한다.
이를 위해 spring-boot-maven-plugin 이 필요하다
## spring-boot-maven-plugin 플러그인
front/pom.xml 에 아래 내용을 추가한다.
```xml
<properties>
...
<webapp.lib>${basedir}/src/main/webapp/WEB-INF/lib</webapp.lib>
</properties>
<dependencies>
...
<dependency>
<groupId>external</groupId>
<artifactId>external</artifactId>
<version>1.0</version>
<scope>system</scope>
<systemPath>${webapp.lib}/INIpaySample_v1.3.jar</systemPath>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>2.6.3</version>
<configuration>
<includeSystemScope>true</includeSystemScope>
</configuration>
</plugin>
</plugins>
</build>
```
**중요**
위 예제에서 인클루드된 jar 파일은 `system` 스코프를 가진다. `system`은 `provided`와 동일하게
runtime 실행 시 JDK 혹은 외부 Container 에서 제공된다는 의미기에 최종 빌드과정에서는 포함되지 않는다.
하지만 src/main/webapp 이라는 maven 규약 경로에 WEB-INF/lib 을 만들 었기에 최종 빌드 결과물의 WEB-INF/lib 에 담기게 된다.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 61 KiB

View File

@@ -1,127 +0,0 @@
# Validation 가이드
자바 세계에서 파라미터를 검증하는 표준 기술은 Bean Validation API (https://beanvalidation.org) 입니다.
## step.1 - Bean Validation API 가능한한 많이 사용하기
javax.validation.constraints 패키지가 제공하는 @NotBlack, @Email 등 어노테이션을 적용하는 것 만으로도 기본적인 검증을 수행할 수 있습니다.
```java
public class SomeDto {
@NotBlank(message = "{valid.common.required}")
@Pattern(regexp = "^.*[^\\\\.]$", message = "{valid.admin.id.notEndWith.dot}")
private String id;
}
```
특히 @Pattern 은 정규표현식을 이용해 다양한 검증사례를 설계하는 강력한 어노테이션입니다.
## step.2 - Validator 로 검증하기
constraints 어노테이션만으로 부족하다면 `Validator` 인터페이스 사용을 고려해보세요.
다음 코드는 예제 게시판에서 글을 등록할 때 사용자 입력값을 검증하기위해 `Validator` 인터페이스를 구현한 검증객체입니다.
```java
@Component
@RequiredArgsConstructor
public class ExampleBoardFormValidator implements Validator {
@Override
public boolean supports(Class<?> clazz) {
return ExampleBoardFormDto.class.equals(clazz);
}
@Override
public void validate(Object target, Errors errors) {
ValidationUtils.rejectIfEmptyOrWhitespace(errors, "title", "valid.common.required");
ValidationUtils.rejectIfEmptyOrWhitespace(errors, "content", "valid.common.required");
}
}
```
`Controller` 메서드에 Validator 가 사용되는데 이때 메서드 인자로 DTO 객체와 BindingResult 객체를 나란히 선언(중요) 해주어야 합니다. (순서가 중요)
```java
@PostMapping("create")
public String createPost(
// ...
@ModelAttribute("formDto") ExampleBoardFormDto formDto,
BindingResult bindingResult)
throws IOException {
exampleBoardFormValidator.validate(formDto, bindingResult);
if (bindingResult.hasErrors()) {
return "board/exampleBoardForm";
}
// ...
}
```
이제 `bindingResult` 의 hasError 메서드를 통해 검증에 위배된 항목이 발견되면 메서드 수행을 멈추고 이전 입력폼 화면으로 리턴합니다.
`@ModelAttribute` 를 통해 DTO 객체는 formDto 속성명으로 model 에 담겨 자동 전달됩니다.
입력폼에서 검증 실패 메세지를 보여줄 때 Thymeleaf 의 `th:object` 와 `th:errors` 를 이용합니다.
```html
<form th:object="${formDto}">
<input th:field="*{id}"
th:classappend="${#fields.hasErrors('id')} ? 'is-invalid'"/>
<div class="invalid-feedback fw-bold" th:if="${#fields.hasErrors('id')}" th:errors="*{id}">
에러 메세지
</div>
</form>
```
form 태그에 매핑된 `th:object` 를 통해 form 필드(`th:field`)와 에러 메세지(`th:errors`)를 연결할 수 있습니다.
아래는 검증 실패 메세지가 표현된 화면입니다.
![캡쳐](./img/validation.png)
## step.3 - Ajax 요청일 경우 검증 처리
Ajax 비동기 요청의 요청 주체는 Javascript 이기에 validation 실패 메세지 또한 **JSON 응답 형식**으로 전달되야 합니다.
```java
@PostMapping("save")
@Transactional
public ResponseEntity<?> save(URIFormDto formDto, BindingResult bindingResult)
throws IOException {
ValidationUtils.invokeValidator(uriFormValidator, formDto, bindingResult);
if (bindingResult.hasErrors()) {
return commonUtil.getValidationFailResponseEntity(bindingResult);
}
// ...
```
`bindingResult.fieldErrors` 목록을 commonUtil 을 이용해 DTO 로 변환 후 응답객체 본문에 담고, HttpStatus 코드 422 와 함께 내려줍니다.
* 422 (HttpStatus.UNPROCESSABLE_ENTITY) 는 검증 실패와 관련해 가장 적합한 HTTP 상태코드입니다.
$.ajax 콜백에서 검증 실패시 처리를 위해 아래와 같이 **httpStatus 콜백을 명시적으로 선언**하는 것을 권장합니다.
```javascript
$.ajax({
type: 'POST',
url: '/api/uri/save',
statusCode: {
// validation 실패 시 처리
422: function (response) {
const fieldErrors = response.responseJSON;
let form = document.formDto;
$(fieldErrors).each(function (idx, error) {
$(form[error.field]).addClass('is-invalid');
$('.field-' + error.field).text(error.message);
});
}
}
});
```
json.fieldErrors 배열 loop 을 돌며, field 와 defaultMessage 를 alert 로 뛰울 수 있고, 위의 예처럼 bootstrap CSS 를 이용해 화면에 render 해주는 방식도 가능합니다.
$.ajax 의 fail 콜백함수를 사용해도 되지만,
validation 처리 외에 **예외 발생시 시 응답코드 400 를 전달**하는 등 다른 정책들도 있기에
statusCode 선언을 통한 명시적인 분기처리를 권장합니다.