From 57752f9cd180f6a3e1d60173435e856710526f9d Mon Sep 17 00:00:00 2001 From: Goldman Kim Date: Tue, 18 Jun 2024 15:16:35 +0900 Subject: [PATCH] . --- README.md | 73 ++++++++------- .../static/html/com/app/sample/dev-guide.html | 91 ++++++++++--------- 2 files changed, 86 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index ee1ea54..cc65f51 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,16 @@ Natural-JS Boot === + +## 소개 + Natural-JS Boot 는 [Natural-JS](https://bbalganjjm.github.io/natural_js) 와 [Natural-TEMPLATE](https://bbalganjjm.github.io/natural_js/#html/naturaljs/template/documents/template-guide.html), Spring Boot 로 구성된 기업용 웹 애플리케이션 개발을 위한 아키텍처 프레임워크 패키지 입니다. Natural-JS Boot 는 Front-end / Back-end 프레임워크와 더불어 기업용 웹 애플리케이션에 필요한 다양한 유틸리티와 개인정보보호, 웹 취약점 보완, 파일 관리, 엑셀 업/다운로드 등의 공통 라이브러리를 제공합니다. > Natural-JS Boot 에는 Material Design 2 가 적용되어 있습니다. -개발 가이드 -=== +## 목차 -목차 -=== - [프로젝트 구성](#user-content-프로젝트-구성) - [**Front-End 개발**](#user-content-front-end-개발) @@ -61,8 +61,7 @@ Natural-JS Boot 는 Front-end / Back-end 프레임워크와 더불어 기업용 - [6.3. 최대 조회건수 제한](#user-content-63-최대-조회건수-제한) - [6.4. XSS 공격 차단](#user-content-64-xss-공격-차단) - -# 프로젝트 구성 +## 프로젝트 구성 샘플 프로젝트의 기술 요소는 다음과 같습니다. @@ -76,11 +75,11 @@ Natural-JS Boot 는 Front-end / Back-end 프레임워크와 더불어 기업용 - 프레임워크 : Spring Boot 3.1.5 - DB : HSQLDB(Sample DB) -# Front-End 개발 +## Front-End 개발 -#### Front-End 개발을 위해 HTML, CSS, Javascript, [jQuery](https://jquery.com), [Natural-JS](https://bbalganjjm.github.io/natural_js)에 대한 학습이 선행되어야 합니다. +#### Front-End 개발을 위해 HTML, CSS, Javascript, [jQuery](https://jquery.com), [Natural-JS](https://bbalganjjm.github.io/natural_js) 에 대한 학습이 선행되어야 합니다. -## 페이지 소스코드 작성 규칙 +### 페이지 소스코드 작성 규칙 기본적으로 Natural-JS 의 블록 페이지들의 소스코드는 다음과 같이 구성해야 됩니다. @@ -110,11 +109,11 @@ Natural-JS Boot 는 Front-end / Back-end 프레임워크와 더불어 기업용 ``` -## Controller object(N.cont) 의 속성명 작성 규칙 +### Controller object(N.cont) 의 속성명 작성 규칙 Natural-TEMPLATE 의 기능은 Controller object 프로퍼티명의 명명규칙으로 실행할 수 있습니다. 컴포넌트를 초기화하거나 이벤트를 바인딩하는 등의 반복적인 작업들을 자동화해 줍니다. -### 1. "p." 으로 시작 - UI 컴포넌트 생성 +#### 1. "p." 으로 시작 - UI 컴포넌트 생성 아래와 같이 선언하면 Natural-UI 의 컴포넌트를 지정한 요소에 생성하고 생성된 컴포넌트 인스턴스를 반환 해 줍니다. 컴포넌트를 선언하는 Controller object 의 속성명은 다음과 같이 조합하여 사용할 수 있습니다. @@ -165,7 +164,7 @@ var cont = N(".page-id").cont({ 컴포넌트 옵션은 Natural-UI의 컴포넌트별 기본 옵션 외에 해당 컴포넌트의 용도를 지정하거나 초기화 후 바로 실행할 함수 등을 지정할 수 있는 옵션이 더 추가되어 있습니다. Natural-TEMPLATE 에서만 사용 가능한 컴포넌트 별 추가 옵션은 다음과 같습니다. -### 1.1. N.select - 공통코드 데이터 바인딩 +#### 1.1. N.select - 공통코드 데이터 바인딩 **이 기능을 사용하려면 공통코드 데이터를 제공하는 서비스 URL 과 공통코드 분류코드 컬럼명을 [Config(natural.config.js)](#html/naturaljs/refr/refr0102.html) 의 N.context.attr("template").codes 속성에 설정해 주어야 합니다.** @@ -203,7 +202,7 @@ Natural-TEMPLATE 에서만 사용 가능한 컴포넌트 별 추가 옵션은 ... ``` -### 1.2. N.select - 일반 목록 데이터를 선택요소(select, radio, checkbox)에 바인딩 +#### 1.2. N.select - 일반 목록 데이터를 선택요소(select, radio, checkbox)에 바인딩 | 속성 | 옵션명 | 타입 | 필수 여부 | 속성 값 | 설명 | | :--: | :--: | :--: | :--: | :--: | -- | @@ -239,7 +238,7 @@ Natural-TEMPLATE 에서만 사용 가능한 컴포넌트 별 추가 옵션은 ... ``` -### 1.3. N.form +#### 1.3. N.form | 속성 | 옵션명 | 타입 | 필수 여부 | 속성 값 | 설명 | | :--: | :--: | :--: | :--: | :--: | -- | @@ -298,7 +297,7 @@ Natural-TEMPLATE 에서만 사용 가능한 컴포넌트 별 추가 옵션은 ... ``` -### 1.4. 다른 모든 컴포넌트 +#### 1.4. 다른 모든 컴포넌트 | 속성 | 옵션 | 타입 | 필수 여부 | 속성 값 | 설명 | | :--: | :--: | :--: | :--: | :--: | -- | @@ -348,7 +347,7 @@ Natural-TEMPLATE 에서만 사용 가능한 컴포넌트 별 추가 옵션은 ... ``` -### 1.5. 엑셀 데이터 바인딩 +#### 1.5. 엑셀 데이터 바인딩 N.grid 의 bindExcel 메서드를 통해 엑셀 파일(Xlsx)의 데이터를 그리드에 바인딩할 수 있습니다. @@ -378,7 +377,7 @@ bindExcel 메서드의 인수는 다음과 같습니다. - after : 엑셀 데이터 추출 완료 후 실행할 콜백 함수(함수의 첫 번째 인수로 추출된 JSON 타입의 엑셀 데이터가 반환 됨) >Excel 데이터 추출을 브라우저에서 javascript 로 처리하려면 "/natural_js_egov/src/main/webapp/js/lib/xlsx.full.min.js" 파일을 임포트해야 합니다. -### 1.6. 파일관리 공통 팝업 +#### 1.6. 파일관리 공통 팝업 Controller 오브젝트에 "p.popup.file" 속성을 정의하면 파일관리 공통 팝업을 인스턴스를 생성해 줍니다. @@ -433,7 +432,7 @@ Controller 오브젝트에 "p.popup.file" 속성을 정의하면 파일관리 ``` -## 2. "c." 으로 시작 - Communicator(N.comm) 선언 +### 2. "c." 으로 시작 - Communicator(N.comm) 선언 서버와 통신하는 모든 [Communicator(N.comm)](#html/naturaljs/refr/refr0203.html) 를 Controller object 의 멤버 변수로 선언할 수 있습니다. Communicator 를 미리 선언해 놓으면 데이터의 흐름을 한눈에 확인할 수 있고 선언된 Communicator 에 AOP 를 적용할 수 있습니다. Communicator 선언하는 Controller object 의 속성명은 다음과 같이 조합하여 사용할 수 있습니다. @@ -473,7 +472,7 @@ var cont = N(".page-id").cont({ Communicator 선언은 직접 오브젝트나 값을 대입하는것이 아닌 실행 함수를 지정하는 방식으로, 사용 시 `cont["c.{서비스명}"]().submit` 와 같이 함수 실행 구문 `()`을 추가하는것에 유의 바랍니다. N.comm 의 파라미터를 위 예제와 같이 N.form 이나 N.grid, N.list 등의 데이터 관련 컴포넌트의 data() 메서드에 연결해 놓으면 컴포넌트의 최신 데이터가 요청 파라미터로 자동으로 지정됩니다. -### 2.1. 엑셀 다운로드 +#### 2.1. 엑셀 다운로드 N.comm 의 excelDownload 메서드를 통해 서버에서 데이터를 엑셀파일로 받을 수 있습니다. @@ -535,7 +534,7 @@ SELECT FROM TABLE ``` -### 2.2. 엑셀 대용량(Streaming) 다운로드 +#### 2.2. 엑셀 대용량(Streaming) 다운로드 N.comm 의 excelStreaming 메서드를 통해 서버에서 대용량 데이터를 엑셀파일로 받을 수 있습니다. @@ -550,7 +549,7 @@ if (cont["p.form.search"].validate()) { } ``` -## 3. "e." 으로 시작 - 이벤트 바인딩 +### 3. "e." 으로 시작 - 이벤트 바인딩 view 안에 있는 요소들에 이벤트 바인딩을 Controller object 에 선언하고 이벤트 핸들러를 정의 할 수 있습니다. @@ -659,7 +658,7 @@ var cont = N(".page-id").cont({ ... ``` -## 4. 유틸리티 +### 4. 유틸리티 샘플 프로젝트의 공통 유틸리티입니다. @@ -840,13 +839,13 @@ fileId로 서버에서 업로드된 파일을 조회 후 파일 요약 목록을 자세한 사용법은 [2.1. 엑셀 다운로드](#21)를 참고 바랍니다. -# Back-End 개발 +## Back-End 개발 #### Back-End 개발을 위해 JAVA 와 Spring MVC 에 대한 학습이 선행되어야 합니다. -## 1. 네이밍(Naming) +### 1. 네이밍(Naming) -### 1.1. 패키지 구조 +#### 1.1. 패키지 구조 이 예제의 JAVA 기본 패키지는 framework.naturaljs.app.sample 이고 Sample 패키지를 예를 들어 패키지 구조를 설명하면 다음과 같습니다. - framework.naturaljs.app.sample : Spring MVC 의 Controller 소스코드들이 담겨 있는 패키지 @@ -856,7 +855,7 @@ fileId로 서버에서 업로드된 파일을 조회 후 파일 요약 목록을 >VO(Value Object) 객체는 get/set Bean 으로 처리하지 않고 파라미터부터 리턴되는 데이터까지 모두 `Map` 나 `List>`로 처리됩니다. >그러나 Bean 타입의 VO 객체가 필요하면 빈을 만들어서 써도 상관없습니다. -### 1.2. @RequestMapping +#### 1.2. @RequestMapping Controller 의 @RequestMapping 은 Camel Case 문자열 형태로 다음과 같이 정의되어 있습니다. - 단건 조회 : `get` + `MethodName` + `.json` @@ -873,7 +872,7 @@ Controller, ServiceImpl, Mapper 클래스의 메서드명이나 Mapper XML 의 i >목록 조회와 엑셀 다운로드는 URL 의 확장자로만 구분하고 같은 Controller, ServiceImpl, Mapper 클래스를 사용합니다. -## 2. Controller 개발 +### 2. Controller 개발 Controller 는 기본적으로 다음 예제와 같이 구성되어 있습니다. @@ -943,7 +942,7 @@ Controller 클래스 개발 방법은 다음과 같습니다. 8. 컨트롤러 메서드 선언이 끝났으면 service 클래스를 이용하여 데이터를 반환하는등의 컨트롤러 메서드의 로직을 채워 줍니다. -## 3. ServiceImpl(Service) 개발 +### 3. ServiceImpl(Service) 개발 Service 는 기본적으로 다음 예제와 같이 구성되어 있습니다. @@ -1021,7 +1020,7 @@ ServiceImpl 클래스의 개발 방법은 다음과 같습니다. > save 메서드는 그리드(N.grid)나 리스트(N.list)에서 넘어온 다건의 입력/수정/삭제를 처리하는 메서드입니다. 위 예제의 구문을 그대로 복사하여 사용하거나 rowStatus 별로 관련 로직을 더 채워 사용하면 됩니다. -## 4. MyBatis Mapper XML 개발 +### 4. MyBatis Mapper XML 개발 MyBatis Mapper XML 파일은 기본적으로 다음 예제와 같이 구성되어 있습니다. @@ -1079,7 +1078,7 @@ MyBatis Mapper XML 의 개발 방법은 다음과 같습니다. [MyBatis Mapper XML 매뉴얼](html/com/app/sample/mybatis-mapper-xml.pdf) 과 [MyBatis 동적 SQL 매뉴얼](html/com/app/sample/mybatis-dynamic-sql.pdf)을 참고 바랍니다. -### 4.1. DB 페이징 +#### 4.1. DB 페이징 페이징은 Natural-JS의 N.pagination 컴포넌트를 사용합니다. N.pagination 의 사용방법은 [조회폼+그리드+DB페이징](#dHlwZTAzMDElMjQlRUMlQTElQjAlRUQlOUElOEMlRUQlOEYlQkMlMkIlRUElQjclQjglRUIlQTYlQUMlRUIlOTMlOUMlMkJEQiVFRCU4RSU5OCVFQyU5RCVCNCVFQyVBNyU5NSUyNGZhbHNl) 템플릿과 [Natural-UI API Document 의 Pagination 탭](naturaljs/index.html#refr/refr0105)을 참고 바랍니다. @@ -1111,7 +1110,7 @@ OFFSET #{startRowIndex} ROWS FETCH NEXT #{countPerPage} ROWS ONLY -- 페이징 ``` -## 5. Mapper Interface 개발 +### 5. Mapper Interface 개발 Mapper Interface 는 기본적으로 다음 예제와 같이 구성되어 있습니다. @@ -1147,9 +1146,9 @@ Mapper 인터페이스의 개발 방법은 다음과 같습니다. > 리턴타입은 java.util.Map 도 Map 인터페이스를 상속하여 구현된 객체이므로 `List>`로 선언합니다. 단건 조회도 UI 개발의 편의성을 위해 `List>`로 선언 바랍니다(Natural-JS는 단건이든 다건이든 Array 타입으로 컴포넌트에 바인딩 함). -## 6. 기타 +### 6. 기타 -### 6.1. 예외처리(Exception) +#### 6.1. 예외처리(Exception) 서버에서 BizException 을 던지면 화면에 N.alert 컴포넌트로 던진 메시지가 표시됩니다. @@ -1189,7 +1188,7 @@ if(Condition) { -30003={0}는 {1} 보다 이전 날짜를 지정해 주세요. ``` -### 6.2. 마스킹 +#### 6.2. 마스킹 마스킹은 DB의 스키마나 테이블 상관없이 대상 컬럼명들을 src/main/resources/egovframework/egovProps/globals.properties 파일의 masking.columns 속성 값으로 다음과 같이 정의해 주면 됩니다. @@ -1224,14 +1223,14 @@ masking.exclude.urls=/**/sample/getSampleList.json, /**/sample/getSampleBigList. @RequestMapping(value = { "getSampleList", "getAdminSampleList" }) ``` -### 6.3. 최대 조회건수 제한 +#### 6.3. 최대 조회건수 제한 쾌적한 서버 운영환경을 유지하기 위해 DB 데이터의 최대 행(row) 수를 제한할 수 있습니다. src/main/resources/egovframework/egovProps/globals.properties 파일의 max.rows.limit 속성 값에 최대 행 수를 지정 가능하고 max.rows.exclude.urls 속성에 예외 URL 들을 등록 가능합니다. >엑셀 다운로드 요청은 최대 조회 건수 제한에 걸리지 않고 모든 데이터를 내려 받습니다. -### 6.4. XSS 공격 차단 +#### 6.4. XSS 공격 차단 Cross Site Scripting(XSS) 공격을 차단하기 위해 서버에는 XSS 공격 문자열을 HTML 특수문자 코드로 변환해 주는 필터가 걸려 있습니다. @@ -1253,7 +1252,7 @@ Controller 메서드들의 Map 이나 List 타입의 인수로 변환되면서 X src/main/resources/egovframework/egovProps/globals.properties 파일의 xss.exclude.urls 속성에 URL 들을 등록하면 등록된 URL(요청) 은 XSS 공격 문자열을 필터링하지 않습니다. -# Supports +## Supports ### Support browsers diff --git a/src/main/resources/static/html/com/app/sample/dev-guide.html b/src/main/resources/static/html/com/app/sample/dev-guide.html index f25fd95..17a10ee 100644 --- a/src/main/resources/static/html/com/app/sample/dev-guide.html +++ b/src/main/resources/static/html/com/app/sample/dev-guide.html @@ -10,8 +10,18 @@ Natural-JS Boot 개발 가이드 === -목차 -=== +이 가이드는 Natural-JS Boot 의 코드 작성 규칙과 사용법을 설명합니다. + +## 소개 + +Natural-JS Boot 는 [Natural-JS](https://bbalganjjm.github.io/natural_js) 와 [Natural-TEMPLATE](https://bbalganjjm.github.io/natural_js/#html/naturaljs/template/documents/template-guide.html), Spring Boot 로 구성된 기업용 웹 애플리케이션 개발을 위한 아키텍처 프레임워크 패키지 입니다. + +Natural-JS Boot 는 Front-end / Back-end 프레임워크와 더불어 기업용 웹 애플리케이션에 필요한 다양한 유틸리티와 개인정보보호, 웹 취약점 보완, 파일 관리, 엑셀 업/다운로드 등의 공통 라이브러리를 제공합니다. + +> Natural-JS Boot 에는 Material Design 2 가 적용되어 있습니다. + +## 목차 + - [프로젝트 구성](#-1) - [**Front-End 개발**](#frontend) @@ -62,8 +72,7 @@ - [6.3. 최대 조회건수 제한](#63) - [6.4. XSS 공격 차단](#64xss) - -# 프로젝트 구성 +## 프로젝트 구성 샘플 프로젝트의 기술 요소는 다음과 같습니다. @@ -77,11 +86,11 @@ - 프레임워크 : Spring Boot 3.1.5 - DB : HSQLDB(Sample DB) -# Front-End 개발 +## Front-End 개발 -#### Front-End 개발을 위해 HTML, CSS, Javascript, [jQuery](https://jquery.com), [Natural-JS](https://bbalganjjm.github.io/natural_js)에 대한 학습이 선행되어야 합니다. +#### Front-End 개발을 위해 HTML, CSS, Javascript, [jQuery](https://jquery.com), [Natural-JS](https://bbalganjjm.github.io/natural_js) 에 대한 학습이 선행되어야 합니다. -## 페이지 소스코드 작성 규칙 +### 페이지 소스코드 작성 규칙 기본적으로 Natural-JS 의 블록 페이지들의 소스코드는 다음과 같이 구성해야 됩니다. 먼저 [Controller](#html/naturaljs/refr/refr0201.html) 메뉴에서 N.cont 의 사용법과 유의사항을 참고 하세요. @@ -112,11 +121,11 @@ ``` -## Controller object(N.cont) 의 속성명 작성 규칙 +### Controller object(N.cont) 의 속성명 작성 규칙 Natural-TEMPLATE 의 기능은 Controller object 프로퍼티명의 명명규칙으로 실행할 수 있습니다. 컴포넌트를 초기화하거나 이벤트를 바인딩하는 등의 반복적인 작업들을 자동화해 줍니다. -### 1. "p." 으로 시작 - UI 컴포넌트 생성 +#### 1. "p." 으로 시작 - UI 컴포넌트 생성 아래와 같이 선언하면 Natural-UI 의 컴포넌트를 지정한 요소에 생성하고 생성된 컴포넌트 인스턴스를 반환 해 줍니다. 컴포넌트를 선언하는 Controller object 의 속성명은 다음과 같이 조합하여 사용할 수 있습니다. @@ -167,7 +176,7 @@ 컴포넌트 옵션은 Natural-UI의 컴포넌트별 기본 옵션 외에 해당 컴포넌트의 용도를 지정하거나 초기화 후 바로 실행할 함수 등을 지정할 수 있는 옵션이 더 추가되어 있습니다. Natural-TEMPLATE 에서만 사용 가능한 컴포넌트 별 추가 옵션은 다음과 같습니다. -### 1.1. N.select - 공통코드 데이터 바인딩 +#### 1.1. N.select - 공통코드 데이터 바인딩 **이 기능을 사용하려면 공통코드 데이터를 제공하는 서비스 URL 과 공통코드 분류코드 컬럼명을 [Config(natural.config.js)](#html/naturaljs/refr/refr0102.html) 의 N.context.attr("template").codes 속성에 설정해 주어야 합니다.** @@ -205,7 +214,7 @@ ... ``` -### 1.2. N.select - 일반 목록 데이터를 선택요소(select, radio, checkbox)에 바인딩 +#### 1.2. N.select - 일반 목록 데이터를 선택요소(select, radio, checkbox)에 바인딩 | 속성 | 옵션명 | 타입 | 필수 여부 | 속성 값 | 설명 | | :--: | :--: | :--: | :--: | :--: | -- | @@ -241,7 +250,7 @@ ... ``` -### 1.3. N.form +#### 1.3. N.form | 속성 | 옵션명 | 타입 | 필수 여부 | 속성 값 | 설명 | | :--: | :--: | :--: | :--: | :--: | -- | @@ -300,7 +309,7 @@ ... ``` -### 1.4. 다른 모든 컴포넌트 +#### 1.4. 다른 모든 컴포넌트 | 속성 | 옵션 | 타입 | 필수 여부 | 속성 값 | 설명 | | :--: | :--: | :--: | :--: | :--: | -- | @@ -351,7 +360,7 @@ ... ``` -### 1.5. 엑셀 데이터 바인딩 +#### 1.5. 엑셀 데이터 바인딩 N.grid 의 bindExcel 메서드를 통해 엑셀 파일(Xlsx)의 데이터를 그리드에 바인딩할 수 있습니다. @@ -381,7 +390,7 @@ - after : 엑셀 데이터 추출 완료 후 실행할 콜백 함수(함수의 첫 번째 인수로 추출된 JSON 타입의 엑셀 데이터가 반환 됨) >Excel 데이터 추출을 브라우저에서 javascript 로 처리하려면 "/natural_js_egov/src/main/webapp/js/lib/xlsx.full.min.js" 파일을 임포트해야 합니다. -### 1.6. 파일관리 공통 팝업 +#### 1.6. 파일관리 공통 팝업 Controller 오브젝트에 "p.popup.file" 속성을 정의하면 파일관리 공통 팝업을 인스턴스를 생성해 줍니다. @@ -436,7 +445,7 @@ ``` -## 2. "c." 으로 시작 - Communicator(N.comm) 선언 +### 2. "c." 으로 시작 - Communicator(N.comm) 선언 서버와 통신하는 모든 [Communicator(N.comm)](#html/naturaljs/refr/refr0203.html) 를 Controller object 의 멤버 변수로 선언할 수 있습니다. Communicator 를 미리 선언해 놓으면 데이터의 흐름을 한눈에 확인할 수 있고 선언된 Communicator 에 AOP 를 적용할 수 있습니다. Communicator 선언하는 Controller object 의 속성명은 다음과 같이 조합하여 사용할 수 있습니다. @@ -476,7 +485,7 @@ Communicator 선언은 직접 오브젝트나 값을 대입하는것이 아닌 실행 함수를 지정하는 방식으로, 사용 시 `cont["c.{서비스명}"]().submit` 와 같이 함수 실행 구문 `()`을 추가하는것에 유의 바랍니다. N.comm 의 파라미터를 위 예제와 같이 N.form 이나 N.grid, N.list 등의 데이터 관련 컴포넌트의 data() 메서드에 연결해 놓으면 컴포넌트의 최신 데이터가 요청 파라미터로 자동으로 지정됩니다. -### 2.1. 엑셀 다운로드 +#### 2.1. 엑셀 다운로드 N.comm 의 excelDownload 메서드를 통해 서버에서 데이터를 엑셀파일로 받을 수 있습니다. @@ -538,7 +547,7 @@ FROM TABLE ``` -### 2.2. 엑셀 대용량(Streaming) 다운로드 +#### 2.2. 엑셀 대용량(Streaming) 다운로드 N.comm 의 excelStreaming 메서드를 통해 서버에서 대용량 데이터를 엑셀파일로 받을 수 있습니다. @@ -553,7 +562,7 @@ } ``` -## 3. "e." 으로 시작 - 이벤트 바인딩 +### 3. "e." 으로 시작 - 이벤트 바인딩 view 안에 있는 요소들에 이벤트 바인딩을 Controller object 에 선언하고 이벤트 핸들러를 정의 할 수 있습니다. @@ -662,11 +671,11 @@ ... ``` -## 4. 유틸리티 +### 4. 유틸리티 샘플 프로젝트의 공통 유틸리티입니다. -### 콘솔 로그 및 에러 처리 +#### 콘솔 로그 및 에러 처리 Natural-CORE 패키지에는 console 객체에서 제공하는 log, warn, info 등의 함수들을 Wrapping 하여 로그레벨을 중앙에서 컨트롤할 수 있는 기능을 제공합니다. 이 기능을 사용하기 위해서는 다음과 같은 명령어로 로그와 에러등을 처리해야 합니다. - N.log : 브라우저 콘솔에 LOG(DEBUG) 메시지를 표시합니다. 사용법은 Javascript 의 console.log 와 동일하고 `N.log("디버그 메시지");` 와 같이 간단하게 사용할 수 있습니다. @@ -681,7 +690,7 @@ - N.error : 에러객체를 생성하고 에러 메시지와 Error stack trace 를 브라우저 콘솔에 표시해 줍니다. 기본적인 사용법은 Javascript 의 console.error 와 동일 하나 N.error 함수는 에러 객체를 생성해 주므로 `throw N.error("에러 메시지");`와 같이 선언하면 에러메시지를 표시하고 에러를 발생시켜 이후 로직들이 중단됩니다. -### APP.comm.utils.del +#### APP.comm.utils.del N.grid 나 N.list 에서 체크되거나 선택된 행들을 삭제하기 위한 함수 - 삭제 전 동의 메시지 다이얼로그 표시 후 remove 함수 호출 등의 반복적인 루틴들을 한 번에 처리해 줍니다. @@ -713,7 +722,7 @@ ... ``` -### APP.comm.utils.save +#### APP.comm.utils.save 추가, 수정, 삭제된 데이터를 저장하는 함수 - 저장 전 데이터 검증, 변경된 데이터 확인, 저장 메시지 다이얼로그 표시등 데이터 저장에 대한 반복적인 루틴들을 한 번에 처리해 줍니다. @@ -749,7 +758,7 @@ ... ``` -### APP.comm.utils.selectNBind +#### APP.comm.utils.selectNBind N.grid 나 N.list 의 행을 선택했을 때(onSelect 이벤트 핸들러 함수 이용) N.form 컴포넌트에 같은 데이터를 연동하기 위한 반복적인 루틴들을 한 번에 처리해 줍니다. @@ -777,7 +786,7 @@ ... ``` -### APP.comm.utils.createFileSummaryList +#### APP.comm.utils.createFileSummaryList 파일 요약 목록을 만들어 줍니다. @@ -803,7 +812,7 @@ ... ``` -### APP.comm.utils.getFileSummaryList +#### APP.comm.utils.getFileSummaryList fileId로 서버에서 업로드된 파일을 조회 후 파일 요약 목록을 만들어 줍니다. @@ -829,7 +838,7 @@ ... ``` -### APP.comm.utils.excelDownload +#### APP.comm.utils.excelDownload 데이터를 엑셀 파일로 다운로드합니다. @@ -843,13 +852,13 @@ 자세한 사용법은 [2.1. 엑셀 다운로드](#21)를 참고 바랍니다. -# Back-End 개발 +## Back-End 개발 #### Back-End 개발을 위해 JAVA 와 Spring MVC 에 대한 학습이 선행되어야 합니다. -## 1. 네이밍(Naming) +### 1. 네이밍(Naming) -### 1.1. 패키지 구조 +#### 1.1. 패키지 구조 이 예제의 JAVA 기본 패키지는 framework.naturaljs.app.sample 이고 Sample 패키지를 예를 들어 패키지 구조를 설명하면 다음과 같습니다. - framework.naturaljs.app.sample : Spring MVC 의 Controller 소스코드들이 담겨 있는 패키지 @@ -859,7 +868,7 @@ >VO(Value Object) 객체는 get/set Bean 으로 처리하지 않고 파라미터부터 리턴되는 데이터까지 모두 `Map` 나 `List>`로 처리됩니다. >그러나 Bean 타입의 VO 객체가 필요하면 빈을 만들어서 써도 상관없습니다. -### 1.2. @RequestMapping +#### 1.2. @RequestMapping Controller 의 @RequestMapping 은 Camel Case 문자열 형태로 다음과 같이 정의되어 있습니다. - 단건 조회 : `get` + `MethodName` + `.json` @@ -876,7 +885,7 @@ >목록 조회와 엑셀 다운로드는 URL 의 확장자로만 구분하고 같은 Controller, ServiceImpl, Mapper 클래스를 사용합니다. -## 2. Controller 개발 +### 2. Controller 개발 Controller 는 기본적으로 다음 예제와 같이 구성되어 있습니다. @@ -946,7 +955,7 @@ 8. 컨트롤러 메서드 선언이 끝났으면 service 클래스를 이용하여 데이터를 반환하는등의 컨트롤러 메서드의 로직을 채워 줍니다. -## 3. ServiceImpl(Service) 개발 +### 3. ServiceImpl(Service) 개발 Service 는 기본적으로 다음 예제와 같이 구성되어 있습니다. @@ -1024,7 +1033,7 @@ > save 메서드는 그리드(N.grid)나 리스트(N.list)에서 넘어온 다건의 입력/수정/삭제를 처리하는 메서드입니다. 위 예제의 구문을 그대로 복사하여 사용하거나 rowStatus 별로 관련 로직을 더 채워 사용하면 됩니다. -## 4. MyBatis Mapper XML 개발 +### 4. MyBatis Mapper XML 개발 MyBatis Mapper XML 파일은 기본적으로 다음 예제와 같이 구성되어 있습니다. @@ -1082,7 +1091,7 @@ [MyBatis Mapper XML 매뉴얼](html/com/app/sample/mybatis-mapper-xml.pdf) 과 [MyBatis 동적 SQL 매뉴얼](html/com/app/sample/mybatis-dynamic-sql.pdf)을 참고 바랍니다. -### 4.1. DB 페이징 +#### 4.1. DB 페이징 페이징은 Natural-JS의 N.pagination 컴포넌트를 사용합니다. N.pagination 의 사용방법은 [조회폼+그리드+DB페이징](#dHlwZTAzMDElMjQlRUMlQTElQjAlRUQlOUElOEMlRUQlOEYlQkMlMkIlRUElQjclQjglRUIlQTYlQUMlRUIlOTMlOUMlMkJEQiVFRCU4RSU5OCVFQyU5RCVCNCVFQyVBNyU5NSUyNGZhbHNl) 템플릿과 [Natural-UI API Document 의 Pagination 탭](naturaljs/index.html#refr/refr0105)을 참고 바랍니다. @@ -1114,7 +1123,7 @@ ``` -## 5. Mapper Interface 개발 +### 5. Mapper Interface 개발 Mapper Interface 는 기본적으로 다음 예제와 같이 구성되어 있습니다. @@ -1150,9 +1159,9 @@ > 리턴타입은 java.util.Map 도 Map 인터페이스를 상속하여 구현된 객체이므로 `List>`로 선언합니다. 단건 조회도 UI 개발의 편의성을 위해 `List>`로 선언 바랍니다(Natural-JS는 단건이든 다건이든 Array 타입으로 컴포넌트에 바인딩 함). -## 6. 기타 +### 6. 기타 -### 6.1. 예외처리(Exception) +#### 6.1. 예외처리(Exception) 서버에서 BizException 을 던지면 화면에 N.alert 컴포넌트로 던진 메시지가 표시됩니다. @@ -1192,7 +1201,7 @@ -30003={0}는 {1} 보다 이전 날짜를 지정해 주세요. ``` -### 6.2. 마스킹 +#### 6.2. 마스킹 마스킹은 DB의 스키마나 테이블 상관없이 대상 컬럼명들을 src/main/resources/egovframework/egovProps/globals.properties 파일의 masking.columns 속성 값으로 다음과 같이 정의해 주면 됩니다. @@ -1227,14 +1236,14 @@ @RequestMapping(value = { "getSampleList", "getAdminSampleList" }) ``` -### 6.3. 최대 조회건수 제한 +#### 6.3. 최대 조회건수 제한 쾌적한 서버 운영환경을 유지하기 위해 DB 데이터의 최대 행(row) 수를 제한할 수 있습니다. src/main/resources/egovframework/egovProps/globals.properties 파일의 max.rows.limit 속성 값에 최대 행 수를 지정 가능하고 max.rows.exclude.urls 속성에 예외 URL 들을 등록 가능합니다. >엑셀 다운로드 요청은 최대 조회 건수 제한에 걸리지 않고 모든 데이터를 내려 받습니다. -### 6.4. XSS 공격 차단 +#### 6.4. XSS 공격 차단 Cross Site Scripting(XSS) 공격을 차단하기 위해 서버에는 XSS 공격 문자열을 HTML 특수문자 코드로 변환해 주는 필터가 걸려 있습니다.