최초 커밋!
This commit is contained in:
61
docs/DOC-000-CHANGELOG-VER2.md
Normal file
61
docs/DOC-000-CHANGELOG-VER2.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# 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 체크 해주면 됩니다.
|
||||
93
docs/DOC-002-FILE_UPLOAD.md
Normal file
93
docs/DOC-002-FILE_UPLOAD.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# 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)
|
||||
69
docs/DOC-004-HANDLE_EXCEPTION.md
Normal file
69
docs/DOC-004-HANDLE_EXCEPTION.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# 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)
|
||||
43
docs/Logging.md
Normal file
43
docs/Logging.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# 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` 을 확인하세요.
|
||||
37
docs/Menu.md
Normal file
37
docs/Menu.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# 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 에 넣어주면 됩니다.
|
||||
39
docs/arch/ADR-001-AUTHENTICATION_POLICY.md
Normal file
39
docs/arch/ADR-001-AUTHENTICATION_POLICY.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# **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`
|
||||
66
docs/arch/ADR-002-FILE_UPLOAD_POLICY.md
Normal file
66
docs/arch/ADR-002-FILE_UPLOAD_POLICY.md
Normal file
@@ -0,0 +1,66 @@
|
||||
# **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` 가 해당 역할을 담당한다.
|
||||
41
docs/arch/ADR-003-AWS_S3_UPLOAD_STRATEGY.md
Normal file
41
docs/arch/ADR-003-AWS_S3_UPLOAD_STRATEGY.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# **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/{파일아이디}
|
||||
71
docs/diy/DIY-001-ADD_JAR_TO_SPRINGBOOT_MAVEN.md
Normal file
71
docs/diy/DIY-001-ADD_JAR_TO_SPRINGBOOT_MAVEN.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# 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 에 담기게 된다.
|
||||
BIN
docs/img/port-adapter.jpg
Normal file
BIN
docs/img/port-adapter.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
BIN
docs/img/validation.png
Normal file
BIN
docs/img/validation.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 61 KiB |
127
docs/validation.md
Normal file
127
docs/validation.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# 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`)를 연결할 수 있습니다.
|
||||
아래는 검증 실패 메세지가 표현된 화면입니다.
|
||||
|
||||

|
||||
|
||||
|
||||
## 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 선언을 통한 명시적인 분기처리를 권장합니다.
|
||||
Reference in New Issue
Block a user