diff --git a/docs/DOC-000-CHANGELOG-VER2.md b/docs/DOC-000-CHANGELOG-VER2.md deleted file mode 100644 index 6725f170..00000000 --- a/docs/DOC-000-CHANGELOG-VER2.md +++ /dev/null @@ -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 attachments; - -// Metamodel 적용 후 -@OneToMany(mappedBy = ExBoardAttachment_.EX_BOARD, ...}) -private Set attachments; -``` - -정적 Metamodel 클래스는 maven compile 단계에서 생성되며 IDE 에서 어플리케이션 구동 시 빌드과정에서 자동으로 수행됩니다. - -생성된 모델을 참조하기 위해서는 `target/generated-sources` 경로가 IDE 의 **classpath** 에 추가되어야 합니다. - -인텔리제이의 경우, File > Project Structure > Modules > target\generated-sources 우클릭 후 Sources 체크 해주면 됩니다. diff --git a/docs/DOC-002-FILE_UPLOAD.md b/docs/DOC-002-FILE_UPLOAD.md deleted file mode 100644 index 2cae7807..00000000 --- a/docs/DOC-002-FILE_UPLOAD.md +++ /dev/null @@ -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\| ... - - -## 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) diff --git a/docs/DOC-004-HANDLE_EXCEPTION.md b/docs/DOC-004-HANDLE_EXCEPTION.md deleted file mode 100644 index a3f37ada..00000000 --- a/docs/DOC-004-HANDLE_EXCEPTION.md +++ /dev/null @@ -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) diff --git a/docs/Logging.md b/docs/Logging.md deleted file mode 100644 index 030dd5e1..00000000 --- a/docs/Logging.md +++ /dev/null @@ -1,43 +0,0 @@ -# Logging (logback) 가이드 - -로깅 설정은 구동중인 인스턴스의 `logback-spring.xml`과 `application-${spring.profiles.active}.properties` 에 기술되어 있습니다. - -logback-spring.xml -```xml - - ... - - ... - -``` - -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` 을 확인하세요. diff --git a/docs/Menu.md b/docs/Menu.md deleted file mode 100644 index 806ebe16..00000000 --- a/docs/Menu.md +++ /dev/null @@ -1,37 +0,0 @@ -# Menu 관리 - -Menu 는 관리자 - Settings - Menu 관리 화면을 통해 관리됩니다. - -Tree View UI 를 통해 부모/자식 노드 관계를 유용하게 적용할 수 있습니다. - -### SEO (검색엔진 최적화) - -ogTitle, ogDesc, ogKeywords, ogImage 등 속성값 입력을 통해 현재 메뉴의 meta 및 og 정보가 화면에 노출됩니다. - -```thymeleafexpressions - - - - - - - - - - -``` - -경우에 따라 특정 페이지에서 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 에 넣어주면 됩니다. diff --git a/docs/arch/ADR-001-AUTHENTICATION_POLICY.md b/docs/arch/ADR-001-AUTHENTICATION_POLICY.md deleted file mode 100644 index 53d66588..00000000 --- a/docs/arch/ADR-001-AUTHENTICATION_POLICY.md +++ /dev/null @@ -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` diff --git a/docs/arch/ADR-002-FILE_UPLOAD_POLICY.md b/docs/arch/ADR-002-FILE_UPLOAD_POLICY.md deleted file mode 100644 index e92a9ceb..00000000 --- a/docs/arch/ADR-002-FILE_UPLOAD_POLICY.md +++ /dev/null @@ -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` 업로드 경로를 -연결해주면 된다. `` 선언을 추가해서 웹서버가 해당 디렉토리로 접근할 수 있는 권한을 부여한다. - -``` -JkUnMount /content-disposition/inline/* [워커 이름] -Alias /content-disposition/inline "[Public 업로드 경로]" - - - Options FollowSymLinks - AllowOverride All - Require all granted - Allow from all - -``` -* `JkUnMount` 를 지정해 해당 경로의 자원을 WAS 가 아닌 웹서버가 전달하도록 설정한다. - -### WAS 의 `ATTACHMENT` 참조 방식 설정 - -`ATTACHMENT` 참조 방식은 웹서버가 아닌 WAS 에서만 처리 가능하다. -`GetAttachmentController` 가 해당 역할을 담당한다. \ No newline at end of file diff --git a/docs/arch/ADR-003-AWS_S3_UPLOAD_STRATEGY.md b/docs/arch/ADR-003-AWS_S3_UPLOAD_STRATEGY.md deleted file mode 100644 index 63d14fcb..00000000 --- a/docs/arch/ADR-003-AWS_S3_UPLOAD_STRATEGY.md +++ /dev/null @@ -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 - - app.module - aws - 0.0.1-SNAPSHOT - -``` - -`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/{파일아이디} diff --git a/docs/diy/DIY-001-ADD_JAR_TO_SPRINGBOOT_MAVEN.md b/docs/diy/DIY-001-ADD_JAR_TO_SPRINGBOOT_MAVEN.md deleted file mode 100644 index 7c85a42c..00000000 --- a/docs/diy/DIY-001-ADD_JAR_TO_SPRINGBOOT_MAVEN.md +++ /dev/null @@ -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 - - ... - ${basedir}/src/main/webapp/WEB-INF/lib - - - - ... - - external - external - 1.0 - system - ${webapp.lib}/INIpaySample_v1.3.jar - - - - - - - org.springframework.boot - spring-boot-maven-plugin - 2.6.3 - - true - - - - -``` - -**중요** -위 예제에서 인클루드된 jar 파일은 `system` 스코프를 가진다. `system`은 `provided`와 동일하게 -runtime 실행 시 JDK 혹은 외부 Container 에서 제공된다는 의미기에 최종 빌드과정에서는 포함되지 않는다. -하지만 src/main/webapp 이라는 maven 규약 경로에 WEB-INF/lib 을 만들 었기에 최종 빌드 결과물의 WEB-INF/lib 에 담기게 된다. diff --git a/docs/img/port-adapter.jpg b/docs/img/port-adapter.jpg deleted file mode 100644 index ca1d9f76..00000000 Binary files a/docs/img/port-adapter.jpg and /dev/null differ diff --git a/docs/img/validation.png b/docs/img/validation.png deleted file mode 100644 index a7327547..00000000 Binary files a/docs/img/validation.png and /dev/null differ diff --git a/docs/validation.md b/docs/validation.md deleted file mode 100644 index b5b7bbee..00000000 --- a/docs/validation.md +++ /dev/null @@ -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` 를 통해 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 선언을 통한 명시적인 분기처리를 권장합니다.