You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
726 lines
27 KiB
Markdown
726 lines
27 KiB
Markdown
# XIT Framework 개발 가이드
|
|
|
|
## 목차
|
|
- [1. 프로젝트 개요](#1-프로젝트-개요)
|
|
- [2. 기술 스택 및 라이브러리 버전](#2-기술-스택-및-라이브러리-버전)
|
|
- [2.1 핵심 기술 스택](#tech-stack)
|
|
- [2.2 주요 라이브러리](#main-libraries)
|
|
- [3. 프로젝트 구조](#3-프로젝트-구조)
|
|
- [3.1 디렉토리 구조](#directory-structure)
|
|
- [3.2 패키지 구조](#package-structure)
|
|
- [4. 주요 설정 파일](#4-주요-설정-파일)
|
|
- [4.1 application.yml](#application-yml)
|
|
- [4.2 application-local.yml](#application-local-yml)
|
|
- [4.3 application-dev.yml](#application-dev-yml)
|
|
- [4.4 application-prd.yml](#application-prd-yml)
|
|
- [4.5 build.gradle](#build-gradle)
|
|
- [4.6 logback-spring.xml](#logback-spring-xml)
|
|
- [4.7 mybatis-config.xml](#mybatis-config-xml)
|
|
- [4.8 데이터베이스 스키마](#database-schema)
|
|
- [5. 주요 기능 및 사용법](#5-주요-기능-및-사용법)
|
|
- [5.1 프로젝트 구조 패턴](#project-structure-pattern)
|
|
- [5.2 핵심 기능 흐름](#user-management-example)
|
|
- [5.3 공통 유틸리티](#common-utilities)
|
|
- [5.4 레이아웃 구성](#layout-configuration)
|
|
- [5.5 보안 기능](#security-features)
|
|
- [5.6 배치 작업 관리](#batch-management)
|
|
- [6. 개발 가이드라인](#6-개발-가이드라인)
|
|
- [6.1 코드 작성 규칙](#code-writing-rules)
|
|
- [6.2 디렉토리 구조 가이드](#directory-structure-guide)
|
|
- [6.3 UI 컴포넌트 가이드](#ui-component-guide)
|
|
- [7. 배포 가이드](#7-배포-가이드)
|
|
- [7.1 빌드 방법](#build-method)
|
|
- [7.2 프로필 설정](#profile-settings)
|
|
- [7.3 외부 WAS를 이용한 배포](#external-was-deployment)
|
|
- [7.4 WAR로 배포 및 실행](#war-deployment-execution)
|
|
- [7.5 배포 환경 설정](#deployment-environment-settings)
|
|
- [7.6 배포 체크리스트](#deployment-checklist)
|
|
- [8. 참고 자료](#8-참고-자료)
|
|
|
|
## 1. 프로젝트 개요
|
|
|
|
XIT Framework는 Spring Boot 기반의 웹 애플리케이션 프레임워크로, 전자정부 프레임워크를 확장하여 개발된 프로젝트입니다. 이 문서는 XIT Framework의 구조, 기술 스택, 주요 기능 및 사용법에 대한 종합적인 가이드를 제공합니다.
|
|
|
|
## 2. 기술 스택 및 라이브러리 버전
|
|
|
|
<h3 id="tech-stack">2.1 핵심 기술 스택</h3>
|
|
|
|
| 기술 | 버전 | 설명 |
|
|
|------|------|------|
|
|
| Java | 개발: 1.8, 배포: 1.8 | 자바 개발 및 실행 환경 |
|
|
| Spring Boot | 2.7.18 | 스프링 기반 애플리케이션 개발 프레임워크 |
|
|
| 전자정부 프레임워크 | 4.3.0 | 한국 정부 표준 웹 개발 프레임워크 |
|
|
| Servlet | 3.1 | 웹 애플리케이션 표준 |
|
|
| Gradle | - | 빌드 및 의존성 관리 도구 |
|
|
| MariaDB | - | 관계형 데이터베이스 |
|
|
|
|
<h3 id="main-libraries">2.2 주요 라이브러리</h3>
|
|
|
|
| 라이브러리 | 버전 | 설명 |
|
|
|------------|------|------|
|
|
| MyBatis | 2.3.1 | SQL 매핑 프레임워크 |
|
|
| Apache Tiles | 3.0.8 | 레이아웃 템플릿 엔진 |
|
|
| TOAST UI Grid | 4.19.2 | 자바스크립트 그리드 라이브러리 |
|
|
| Lombok | - | 자바 코드 생성 라이브러리 |
|
|
| Apache Commons Text | 1.10.0 | 텍스트 처리 유틸리티 |
|
|
| Apache POI | 5.3.0 | 엑셀 파일 처리 라이브러리 |
|
|
| Quartz | - | 배치 스케줄링 라이브러리 |
|
|
| jsqlparser | 4.5 | SQL 파싱 라이브러리 |
|
|
|
|
## 3. 프로젝트 구조
|
|
|
|
<h3 id="directory-structure">3.1 디렉토리 구조</h3>
|
|
|
|
```
|
|
xit-framework/
|
|
├── DB-DDL/ # 데이터베이스 스크립트
|
|
│ └── maria/ # MariaDB 스크립트
|
|
│ ├── ddl/ # 테이블 정의 스크립트
|
|
│ └── dml/ # 샘플 데이터 스크립트
|
|
├── src/
|
|
│ ├── main/
|
|
│ │ ├── java/ # 자바 소스 코드
|
|
│ │ │ ├── egovframework/ # 전자정부 프레임워크 확장 코드
|
|
│ │ │ └── go/kr/project/ # 프로젝트 소스 코드
|
|
│ │ ├── resources/ # 리소스 파일
|
|
│ │ │ ├── mybatis/ # MyBatis 설정 및 매퍼
|
|
│ │ │ └── application.yml # 애플리케이션 설정 파일
|
|
│ │ └── webapp/ # 웹 리소스
|
|
│ │ ├── resources/ # 정적 리소스 (CSS, JS, 이미지 등)
|
|
│ │ └── WEB-INF/views/ # JSP 뷰 파일
|
|
│ └── test/ # 테스트 코드
|
|
└── build.gradle # Gradle 빌드 스크립트
|
|
```
|
|
|
|
<h3 id="package-structure">3.2 패키지 구조</h3>
|
|
|
|
```
|
|
go.kr.project/
|
|
├── batch/ # 배치 작업 관련 기능
|
|
├── bbs/ # 게시판 관련 기능
|
|
├── common/ # 공통 컴포넌트
|
|
├── login/ # 로그인 관련 기능
|
|
├── main/ # 메인 페이지 관련 기능
|
|
├── mypage/ # 마이페이지 관련 기능
|
|
├── system/ # 시스템 관리 기능
|
|
│ ├── auth/ # 권한 관리
|
|
│ ├── code/ # 코드 관리
|
|
│ ├── group/ # 그룹 관리
|
|
│ ├── menu/ # 메뉴 관리
|
|
│ ├── role/ # 역할 관리
|
|
│ └── user/ # 사용자 관리
|
|
└── template/ # 템플릿 관련 기능 (예: Excel)
|
|
|
|
egovframework/
|
|
├── config/ # 프레임워크 설정
|
|
├── exception/ # 예외 처리
|
|
├── filter/ # 필터
|
|
├── interceptor/ # 인터셉터
|
|
└── util/ # 유틸리티 클래스
|
|
```
|
|
|
|
## 4. 주요 설정 파일
|
|
|
|
<h3 id="application-yml">4.1 application.yml</h3>
|
|
|
|
애플리케이션의 공통 설정을 정의합니다.
|
|
|
|
```yaml
|
|
# 공통 설정
|
|
spring:
|
|
profiles:
|
|
active: local # 활성화 프로필 (local, dev, prd)
|
|
mvc:
|
|
view:
|
|
prefix: /WEB-INF/views/
|
|
suffix: .jsp
|
|
|
|
# 서버 설정
|
|
server:
|
|
port: 8080
|
|
servlet:
|
|
context-path: /
|
|
|
|
# 데이터베이스 및 MyBatis 설정
|
|
Globals:
|
|
DbType: maria # DB 종류
|
|
mybatis:
|
|
config-location: classpath:mybatis/mybatis-config.xml
|
|
mapper-locations: classpath:mybatis/mapper/**/*_${Globals.DbType}.xml
|
|
|
|
# Swagger UI 경로
|
|
springdoc:
|
|
swagger-ui:
|
|
path: /swagger-ui.html
|
|
|
|
# 로그인 페이지 URL
|
|
login:
|
|
url: /login/login.do
|
|
```
|
|
|
|
<h3 id="application-local-yml">4.2 application-local.yml</h3>
|
|
|
|
로컬 개발 환경(`local` 프로필)의 설정을 정의합니다.
|
|
|
|
```yaml
|
|
# 로컬 프로필 활성화
|
|
spring:
|
|
config:
|
|
activate:
|
|
on-profile: local
|
|
# 데이터베이스 연결
|
|
datasource:
|
|
url: jdbc:mariadb://[HOST]:[PORT]/[DB_NAME]?characterEncoding=UTF-8&serverTimezone=Asia/Seoul
|
|
username: [USER]
|
|
password: [PASSWORD]
|
|
|
|
# 로깅 설정
|
|
logging:
|
|
file:
|
|
path: d:/data/xit-framework/logs # 로그 파일 경로
|
|
level:
|
|
go.kr.project: DEBUG # 프로젝트 패키지 로그 레벨
|
|
|
|
# 파일 업로드 경로
|
|
file:
|
|
upload:
|
|
path: D:\xit-framework-file
|
|
```
|
|
|
|
<h3 id="application-dev-yml">4.3 application-dev.yml</h3>
|
|
|
|
개발 서버 환경(`dev` 프로필)의 설정을 정의합니다.
|
|
|
|
```yaml
|
|
# 개발 프로필 활성화
|
|
spring:
|
|
config:
|
|
activate:
|
|
on-profile: dev
|
|
# 데이터베이스 연결
|
|
datasource:
|
|
url: jdbc:mariadb://[DEV_HOST]:[PORT]/[DB_NAME]?characterEncoding=UTF-8&serverTimezone=Asia/Seoul
|
|
username: [USER]
|
|
password: [PASSWORD]
|
|
|
|
# 로깅 설정
|
|
logging:
|
|
file:
|
|
path: /data/logs/xit-framework # 로그 파일 경로
|
|
level:
|
|
go.kr.project: DEBUG
|
|
|
|
# 파일 업로드 경로
|
|
file:
|
|
upload:
|
|
path: /data/upload/xit-framework-file
|
|
```
|
|
|
|
<h3 id="application-prd-yml">4.4 application-prd.yml</h3>
|
|
|
|
운영 서버 환경(`prd` 프로필)의 설정을 정의합니다.
|
|
|
|
```yaml
|
|
# 운영 프로필 활성화
|
|
spring:
|
|
config:
|
|
activate:
|
|
on-profile: prd
|
|
# 데이터베이스 연결
|
|
datasource:
|
|
url: jdbc:mariadb://[PRD_HOST]:[PORT]/[DB_NAME]?characterEncoding=UTF-8&serverTimezone=Asia/Seoul
|
|
username: [USER]
|
|
password: [PASSWORD]
|
|
|
|
# 서버 세션 타임아웃
|
|
server:
|
|
servlet:
|
|
session:
|
|
timeout: 60m
|
|
|
|
# 로깅 설정 (WARN 레벨)
|
|
logging:
|
|
file:
|
|
path: /data/logs/xit-framework # 로그 파일 경로
|
|
level:
|
|
go.kr.project: WARN
|
|
org.springframework: WARN
|
|
|
|
# 파일 업로드 경로
|
|
file:
|
|
upload:
|
|
path: /data/upload/xit-framework-file
|
|
```
|
|
|
|
<h3 id="build-gradle">4.5 build.gradle</h3>
|
|
|
|
프로젝트의 빌드 및 주요 의존성을 정의합니다.
|
|
|
|
```gradle
|
|
// 1. 플러그인 설정
|
|
plugins {
|
|
id 'org.springframework.boot' version '2.7.18'
|
|
id 'io.spring.dependency-management' version '1.0.15.RELEASE'
|
|
id 'java'
|
|
id 'war'
|
|
}
|
|
|
|
// 2. 기본 정보
|
|
group = 'go.kr.project'
|
|
version = '0.0.1-SNAPSHOT'
|
|
java {
|
|
sourceCompatibility = JavaVersion.VERSION_1_8
|
|
}
|
|
|
|
// 3. 라이브러리 버전 관리
|
|
ext {
|
|
tomcatVersion = '9.0.78'
|
|
tilesVersion = '3.0.8'
|
|
mybatisVersion = '2.3.1'
|
|
egovFrameVersion = '4.3.0'
|
|
}
|
|
|
|
// 4. 주요 의존성
|
|
dependencies {
|
|
// 스프링 부트
|
|
implementation 'org.springframework.boot:spring-boot-starter-web'
|
|
implementation 'org.springframework.boot:spring-boot-starter-validation'
|
|
implementation 'org.springframework.boot:spring-boot-starter-quartz' // Quartz 스케줄러
|
|
|
|
// 전자정부 프레임워크
|
|
implementation "org.egovframe.rte:org.egovframe.rte.ptl.mvc:${egovFrameVersion}"
|
|
|
|
// 데이터베이스
|
|
implementation "org.mybatis.spring.boot:mybatis-spring-boot-starter:${mybatisVersion}"
|
|
implementation 'org.mariadb.jdbc:mariadb-java-client'
|
|
|
|
// 뷰 (JSP & Tiles)
|
|
implementation 'javax.servlet:jstl'
|
|
implementation "org.apache.tiles:tiles-jsp:${tilesVersion}"
|
|
|
|
// 유틸리티
|
|
implementation 'org.apache.commons:commons-text:1.10.0'
|
|
implementation 'org.apache.poi:poi:5.3.0' // Excel
|
|
implementation 'org.springdoc:springdoc-openapi-ui:1.7.0' // Swagger
|
|
|
|
// 개발용
|
|
compileOnly 'org.projectlombok:lombok'
|
|
developmentOnly 'org.springframework.boot:spring-boot-devtools'
|
|
|
|
// 테스트
|
|
testImplementation 'org.springframework.boot:spring-boot-starter-test'
|
|
|
|
// 배포용
|
|
providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'
|
|
}
|
|
|
|
// 5. 빌드 결과물 설정
|
|
war {
|
|
archiveFileName = 'xit-framework.war'
|
|
}
|
|
bootWar {
|
|
archiveFileName = 'xit-framework-boot.war'
|
|
}
|
|
```
|
|
|
|
<h3 id="logback-spring-xml">4.6 logback-spring.xml</h3>
|
|
|
|
애플리케이션의 로깅 정책을 설정합니다. `logback-spring.xml`은 Spring Profiles (`local`, `dev`, `prd`)와 연동하여 환경별로 다른 로깅 전략을 사용합니다.
|
|
|
|
**주요 로깅 전략:**
|
|
|
|
1. **Appenders (로그 출력 위치):**
|
|
* `CONSOLE_COLOR`: 로컬/개발 환경에서 색상이 적용된 로그를 콘솔에 출력합니다.
|
|
* `CONSOLE`: 운영 환경에서 표준 콘솔 출력을 담당합니다.
|
|
* `ASYNC_FILE`: 모든 환경에서 비동기적으로 파일에 로그를 기록하여 성능 저하를 최소화합니다. 로그 파일은 `application-{profile}.yml`에 정의된 경로에 저장됩니다.
|
|
|
|
2. **Log Pattern (로그 형식):**
|
|
* 로그는 `시간 [스레드] 로그레벨 로거 - 메시지` 형식으로 기록됩니다.
|
|
* 예: `2025-08-13 10:00:00.123 [http-nio-8080-exec-1] INFO go.kr.project.main.MainController - Main page access`
|
|
|
|
3. **Rolling Policy (로그 파일 관리):**
|
|
* 로그 파일은 `10MB`에 도달하면 분할됩니다.
|
|
* 로그 파일은 최대 30일 동안 보관됩니다.
|
|
|
|
4. **Profile-specific Levels (환경별 로그 레벨):**
|
|
* **local, dev:** `INFO` 레벨을 기본으로 사용하며, `go.kr.project` 패키지는 `DEBUG` 레벨로 설정하여 상세한 디버깅이 가능합니다.
|
|
* **prd:** `WARN` 레벨을 기본으로 사용하여, 경고 및 오류 로그만 기록합니다.
|
|
|
|
**예시 (Appender 설정 부분):**
|
|
```xml
|
|
<!-- 콘솔(컬러) Appender 예시 -->
|
|
<appender name="CONSOLE_COLOR" class="ch.qos.logback.core.ConsoleAppender">
|
|
<encoder>
|
|
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %highlight(%-5level) [%thread] %cyan(%logger{36}) - %msg%n</pattern>
|
|
</encoder>
|
|
</appender>
|
|
|
|
<!-- 파일 Appender 예시 -->
|
|
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
|
|
<file>${LOG_PATH}/${LOG_FILE}.log</file> <!-- yml 파일의 속성 사용 -->
|
|
<encoder>
|
|
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
|
|
</encoder>
|
|
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
|
|
<!-- 10MB 마다 롤링 -->
|
|
<maxFileSize>${MAX_FILE_SIZE}</maxFileSize>
|
|
<!-- 30일 보관 -->
|
|
<maxHistory>${MAX_HISTORY}</maxHistory>
|
|
</rollingPolicy>
|
|
</appender>
|
|
```
|
|
|
|
<h3 id="mybatis-config-xml">4.7 mybatis-config.xml</h3>
|
|
|
|
MyBatis 설정을 정의하는 파일입니다.
|
|
|
|
```xml
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN" "http://mybatis.org/dtd/mybatis-3-config.dtd">
|
|
<configuration>
|
|
<settings>
|
|
<!-- Java 속성은 camelCase, 데이터베이스 컬럼은 snake_case 사용 -->
|
|
<setting name="mapUnderscoreToCamelCase" value="true"/>
|
|
<setting name="useColumnLabel" value="true"/>
|
|
<!-- PreparedStatement 캐시 -->
|
|
<setting name="defaultExecutorType" value="REUSE"/>
|
|
<!-- 지연 로딩 비활성화 -->
|
|
<setting name="lazyLoadingEnabled" value="false"/>
|
|
<setting name="cacheEnabled" value="false"/>
|
|
<!-- SQL 로깅 -->
|
|
<setting name="logImpl" value="SLF4J"/>
|
|
</settings>
|
|
|
|
<typeAliases>
|
|
<!-- Type aliases는 application.yml의 type-aliases-package에서 정의 -->
|
|
</typeAliases>
|
|
</configuration>
|
|
```
|
|
|
|
<h3 id="database-schema">4.8 데이터베이스 스키마</h3>
|
|
|
|
주요 테이블 및 시퀀스 생성 스크립트는 `DB-DDL/maria/ddl/xitframework/` 디렉토리에 각 객체별 파일로 정의되어 있습니다:
|
|
|
|
- **tb_user**: 사용자 정보
|
|
- **tb_group**: 그룹 정보
|
|
- **tb_role**: 역할 정보
|
|
- **tb_menu**: 메뉴 정보
|
|
- **tb_group_role**: 그룹-역할 매핑
|
|
- **tb_role_menu**: 역할-메뉴 매핑
|
|
- **tb_code_group**: 코드 그룹
|
|
- **tb_code_detail**: 코드 상세
|
|
- **tb_bbs_config**: 게시판 설정
|
|
- **tb_bbs_post**: 게시물
|
|
- **tb_bbs_file**: 게시판 파일
|
|
- **tb_user_session**: 사용자 세션
|
|
- **tb_login_log**: 로그인 로그
|
|
|
|
MyBatis 매퍼 파일은 `src/main/resources/mybatis/mapper/` 디렉토리에 모듈별로 구성되어 있습니다.
|
|
|
|
## 5. 주요 기능 및 사용법
|
|
|
|
<h3 id="project-structure-pattern">5.1 프로젝트 구조 패턴</h3>
|
|
|
|
XIT Framework는 MVC(Model-View-Controller) 패턴을 기반으로 하며, 각 기능은 **Controller, Service, Mapper, Model** 계층으로 명확하게 분리됩니다.
|
|
|
|
- **Controller**: HTTP 요청을 처리하고, Service를 호출한 뒤, 결과를 View 또는 JSON으로 응답합니다.
|
|
- **Service**: 비즈니스 로직을 구현합니다.
|
|
- **Mapper**: MyBatis를 통해 데이터베이스 SQL 쿼리를 실행합니다.
|
|
- **Model (VO)**: 데이터의 구조를 정의하는 객체입니다.
|
|
|
|
<h3 id="user-management-example">5.2 핵심 기능 흐름</h3>
|
|
|
|
대부분의 기능은 '사용자 관리'와 유사한 흐름을 따릅니다.
|
|
|
|
1. **Controller**: `@RequestMapping`으로 URL을 정의하고, 사용자 입력을 `VO`에 바인딩하여 Service로 전달합니다.
|
|
- `@PostMapping("/list.ajax")`: 목록 조회
|
|
- `@PostMapping("/register.ajax")`: 등록/수정 처리
|
|
2. **Service**: 비즈니스 로직을 처리하고, 필요한 경우 Mapper를 호출하여 DB와 상호작용합니다.
|
|
3. **Mapper**: XML에 정의된 SQL을 실행하여 결과를 반환합니다.
|
|
|
|
<h3 id="common-utilities">5.3 공통 유틸리티</h3>
|
|
|
|
<h4 id="api-response-util">5.3.1 API 응답 유틸리티</h4>
|
|
|
|
일관된 형식의 Ajax 응답을 위해 `ApiResponseUtil`을 사용합니다.
|
|
|
|
- **성공**: `ApiResponseUtil.success(data, "메시지");`
|
|
- **성공 (그리드)**: `ApiResponseUtil.successWithGrid(list, pagingVO);`
|
|
- **실패**: `ApiResponseUtil.error("에러 메시지");`
|
|
|
|
<h3 id="layout-configuration">5.4 레이아웃 구성</h3>
|
|
|
|
UI 레이아웃은 **Apache Tiles**를 사용하여 관리합니다.
|
|
|
|
- **기본 레이아웃**: `src/main/webapp/WEB-INF/views/layouts/base/default.jsp`
|
|
- **주요 구성 요소**: `menu_header`, `menu`, `main_header`, `main` 등의 속성으로 페이지의 각 부분을 조립합니다.
|
|
- **주요 UI 라이브러리**: Bootstrap, TOAST UI Grid, DataTables 등이 사용되며, `xit-common.js`, `xit-tui-grid.js` 등 공통 스크립트에서 제어됩니다.
|
|
|
|
<h3 id="security-features">5.5 보안 기능</h3>
|
|
|
|
- **XSS 필터 (`XssFilter.java`)**: 모든 요청에 대해 XSS 공격을 방지하기 위해 파라미터를 필터링합니다.
|
|
- **리퍼러 체크 및 권한 관리 (`AuthInterceptor.java`)**:
|
|
- 허용되지 않은 외부 도메인에서의 요청을 차단합니다.
|
|
- 사용자 세션과 권한을 체크하여 인가되지 않은 페이지 접근을 막습니다.
|
|
- **권한 구조**: **사용자 > 그룹 > 역할 > 메뉴**의 계층적 구조를 통해 유연하고 세밀한 권한 관리를 지원합니다. 권한 정보는 DB 테이블(`TB_USER`, `TB_GROUP`, `TB_ROLE`, `TB_MENU` 등)을 통해 관리됩니다.
|
|
|
|
<h3 id="batch-management">5.6 배치 작업 관리</h3>
|
|
|
|
**Quartz 스케줄러**를 기반으로 배치 작업을 관리합니다.
|
|
|
|
- **주요 기능**: DB에 등록된 배치 작업의 조회, 즉시 실행, 스케줄 변경, 일시정지/재개, 실행 이력 및 로그 관리가 가능합니다.
|
|
- **구현**: `Job` 인터페이스를 구현하여 새로운 배치 작업을 작성하고, DB(`TB_BATCH_JOB_INFO`)에 등록하여 사용합니다.
|
|
- **API**: `BatchJobController`를 통해 REST API 형식으로 배치 제어 기능을 제공합니다.
|
|
|
|
## 6. 개발 가이드라인
|
|
|
|
<h3 id="code-writing-rules">6.1 코드 작성 규칙</h3>
|
|
|
|
1. **Java 개발 및 수정**
|
|
- `src/main/java/go/kr/project/system` 하위에 있는 프로그램을 참조하여 구조, 패턴, 스타일을 사용합니다.
|
|
- 클래스, 메소드, 변수에 대한 주석을 작성합니다.
|
|
|
|
2. **JSP 개발 및 수정**
|
|
- `src/main/webapp/WEB-INF/views/system` 하위에 있는 프로그램을 참조하여 구조, 패턴, 스타일을 사용합니다.
|
|
- JSP 페이지에서 태그의 id 속성은 중복되지 않도록 합니다.
|
|
- 모든 URL은 `<c:url value="" />` 태그로 감싸줍니다.
|
|
|
|
3. **데이터베이스 관련**
|
|
- 신규로 생성되는 테이블은 `DB-DDL/maria/ddl.sql`에 등록합니다.
|
|
- `ON DELETE SET NULL`, `ON DELETE CASCADE` 등의 ON 구문은 사용하지 않고, 프로그램에서 직접 구현합니다.
|
|
|
|
4. **Ajax 처리**
|
|
- Ajax 요청 시 `src/main/java/egovframework/util/ApiResponseUtil.java`와 `src/main/java/egovframework/util/ApiResponseEntity.java`를 참조하여 응답을 처리합니다.
|
|
- Ajax 응답을 처리할 때는 `response.success` 대신 `response.result`를 사용합니다.
|
|
|
|
<h3 id="directory-structure-guide">6.2 디렉토리 구조 가이드</h3>
|
|
|
|
1. **컨트롤러 클래스**
|
|
- `go.kr.project.{모듈명}.controller` 패키지에 위치합니다.
|
|
- 클래스명은 `{기능명}Controller.java` 형식으로 작성합니다.
|
|
|
|
2. **서비스 클래스**
|
|
- `go.kr.project.{모듈명}.service` 패키지에 위치합니다.
|
|
- 인터페이스는 `{기능명}Service.java`, 구현체는 `{기능명}ServiceImpl.java` 형식으로 작성합니다.
|
|
|
|
3. **매퍼 인터페이스**
|
|
- `go.kr.project.{모듈명}.mapper` 패키지에 위치합니다.
|
|
- 클래스명은 `{기능명}Mapper.java` 형식으로 작성합니다.
|
|
|
|
4. **모델 클래스**
|
|
- `go.kr.project.{모듈명}.model` 패키지에 위치합니다.
|
|
- 클래스명은 `{기능명}VO.java` 형식으로 작성합니다.
|
|
|
|
5. **JSP 파일**
|
|
- `src/main/webapp/WEB-INF/views/{모듈명}/{기능명}` 디렉토리에 위치합니다.
|
|
- 파일명은 `{화면명}.{레이아웃명}.jsp` 형식으로 작성합니다.
|
|
|
|
<h3 id="ui-component-guide">6.3 UI 컴포넌트 가이드</h3>
|
|
|
|
1. **TOAST UI Grid**
|
|
- 데이터 그리드를 표시할 때 TOAST UI Grid를 사용합니다.
|
|
- 그리드 초기화 및 설정은 `xit-tui-grid.js`를 참조합니다.
|
|
|
|
2. **폼 유효성 검사**
|
|
- 폼 유효성 검사는 `xit-validation.js`를 사용합니다.
|
|
|
|
3. **공통 스타일**
|
|
- 공통 스타일은 `common.css`와 `xit-common.css`를 사용합니다.
|
|
|
|
## 7. 배포 가이드
|
|
|
|
<h3 id="build-method">7.1 빌드 방법</h3>
|
|
|
|
<h4 id="war-file-build">7.1.1 WAR 파일 빌드</h4>
|
|
|
|
```bash
|
|
# Gradle 빌드 (테스트 포함)
|
|
./gradlew clean build
|
|
|
|
# Gradle 빌드 (테스트 제외)
|
|
./gradlew clean build -x test
|
|
|
|
# WAR 파일만 생성
|
|
./gradlew war
|
|
```
|
|
|
|
<h4 id="bootwar-file-build">7.1.2 bootWar 파일 빌드</h4>
|
|
|
|
Spring Boot 애플리케이션은 실행 가능한 WAR 파일로 빌드할 수 있습니다.
|
|
|
|
```bash
|
|
# 실행 가능한 WAR 파일 생성
|
|
./gradlew bootWar
|
|
```
|
|
|
|
<h3 id="profile-settings">7.2 프로필 설정</h3>
|
|
|
|
XIT Framework는 다양한 환경에 맞게 설정할 수 있는 프로필 시스템을 제공합니다.
|
|
|
|
<h4 id="default-profile">7.2.1 기본 프로필</h4>
|
|
|
|
프로젝트는 다음과 같은 프로필을 제공합니다:
|
|
|
|
| 프로필 | 설명 | 주요 설정 |
|
|
|--------|------|-----------|
|
|
| local | 로컬 개발 환경 | 개발 도구 활성화, 로컬 경로 사용 |
|
|
| dev | 개발 서버 환경 | 개발 서버 설정, 세션 타임아웃 30분 |
|
|
| prd | 운영 서버 환경 | 운영 서버 설정, 리눅스 경로 사용 |
|
|
|
|
<h4 id="profile-activation">7.2.2 프로필 활성화 방법</h4>
|
|
|
|
<h5 id="application-property-settings">애플리케이션 속성 파일 설정</h5>
|
|
|
|
`application.yml` 파일에서 기본 프로필을 설정할 수 있습니다:
|
|
|
|
```yaml
|
|
spring:
|
|
profiles:
|
|
active: local # local, dev, prd 중 선택
|
|
```
|
|
|
|
<h5 id="command-line-profile-settings">명령행 인수로 프로필 설정</h5>
|
|
|
|
애플리케이션 실행 시 명령행 인수로 프로필을 지정할 수 있습니다:
|
|
|
|
```bash
|
|
# JAR 파일 실행 시
|
|
java -jar xit-framework.war --spring.profiles.active=dev
|
|
|
|
# Gradle로 실행 시
|
|
./gradlew bootRun --args='--spring.profiles.active=dev'
|
|
```
|
|
|
|
<h5 id="environment-variable-profile-settings">환경 변수로 프로필 설정</h5>
|
|
|
|
환경 변수를 통해 프로필을 설정할 수 있습니다:
|
|
|
|
```bash
|
|
# Windows
|
|
set SPRING_PROFILES_ACTIVE=dev
|
|
java -jar xit-framework.war
|
|
|
|
# Linux/macOS
|
|
export SPRING_PROFILES_ACTIVE=dev
|
|
java -jar xit-framework.war
|
|
```
|
|
|
|
<h3 id="external-was-deployment">7.3 외부 WAS를 이용한 배포</h3>
|
|
|
|
<h4 id="tomcat-war-deployment">7.3.1 Tomcat에 WAR 파일 배포</h4>
|
|
|
|
1. `build/libs` 디렉토리에 생성된 `xit-framework.war` 파일을 Tomcat의 `webapps` 디렉토리에 복사합니다.
|
|
2. Tomcat을 재시작합니다.
|
|
|
|
<h4 id="external-was-profile-settings">7.3.2 외부 WAS에서 프로필 설정</h4>
|
|
|
|
<h5 id="tomcat-profile-settings">Tomcat에서 프로필 설정</h5>
|
|
|
|
Tomcat의 `setenv.bat`(Windows) 또는 `setenv.sh`(Linux/macOS) 파일에 다음 내용을 추가합니다:
|
|
|
|
**Windows (setenv.bat)**:
|
|
```batch
|
|
set "JAVA_OPTS=%JAVA_OPTS% -Dspring.profiles.active=dev"
|
|
```
|
|
|
|
**Linux/macOS (setenv.sh)**:
|
|
```bash
|
|
export JAVA_OPTS="$JAVA_OPTS -Dspring.profiles.active=dev"
|
|
```
|
|
|
|
<h5 id="jvm-option-settings">WAS의 JVM 옵션으로 설정</h5>
|
|
|
|
대부분의 WAS에서는 JVM 옵션을 통해 시스템 속성을 설정할 수 있습니다:
|
|
|
|
```
|
|
-Dspring.profiles.active=dev
|
|
```
|
|
|
|
<h5 id="web-xml-settings">web.xml에 시스템 속성 설정</h5>
|
|
|
|
`web.xml` 파일에 다음과 같이 시스템 속성을 설정할 수 있습니다:
|
|
|
|
```xml
|
|
<context-param>
|
|
<param-name>spring.profiles.active</param-name>
|
|
<param-value>dev</param-value>
|
|
</context-param>
|
|
```
|
|
|
|
<h3 id="war-deployment-execution">7.4 WAR로 배포 및 실행</h3>
|
|
|
|
Spring Boot 애플리케이션은 bootWar로 빌드된 실행 가능한 WAR 파일로 배포할 수 있습니다.
|
|
|
|
<h4 id="bootwar-execution">7.4.1 bootWar 파일 실행</h4>
|
|
|
|
bootWar로 빌드된 WAR 파일은 내장 서버를 포함하고 있어 JAR 파일처럼 직접 실행할 수 있습니다:
|
|
|
|
```bash
|
|
# 기본 프로필로 실행
|
|
java -jar build/libs/xit-framework-boot.war
|
|
|
|
# 특정 프로필로 실행
|
|
java -jar build/libs/xit-framework-boot.war --spring.profiles.active=dev
|
|
|
|
# 포트 변경하여 실행
|
|
java -jar build/libs/xit-framework-boot.war --server.port=9090
|
|
|
|
# 메모리 설정을 추가하여 실행
|
|
java -Xms512m -Xmx1024m -jar build/libs/xit-framework-boot.war
|
|
|
|
# 로컬 테스트
|
|
java -jar build/libs/xit-framework-boot.war --spring.profiles.active=local --server.port=9090
|
|
```
|
|
|
|
<h4 id="external-was-execution">7.4.2 외부 WAS에 배포하여 실행</h4>
|
|
|
|
bootWar로 빌드된 WAR 파일은 외부 WAS(Tomcat, JBoss, WebLogic 등)에 배포하여 실행할 수도 있습니다:
|
|
|
|
1. `build/libs` 디렉토리에 생성된 `xit-framework.war` 파일을 WAS의 배포 디렉토리에 복사합니다.
|
|
- Tomcat: `webapps` 디렉토리
|
|
- JBoss/WildFly: `deployments` 디렉토리
|
|
- WebLogic: 관리 콘솔을 통해 배포
|
|
|
|
2. WAS를 시작하거나 재시작합니다.
|
|
|
|
<h4 id="background-execution">7.4.3 백그라운드 실행 (Linux/macOS)</h4>
|
|
|
|
내장 서버로 실행할 경우, 백그라운드에서 실행할 수 있습니다:
|
|
|
|
```bash
|
|
# nohup을 사용하여 백그라운드 실행
|
|
nohup java -jar build/libs/xit-framework.war > app.log 2>&1 &
|
|
|
|
# 실행 중인 프로세스 확인
|
|
ps -ef | grep java
|
|
```
|
|
|
|
<h4 id="windows-service-registration">7.4.4 Windows 서비스로 등록</h4>
|
|
|
|
Windows에서는 [winsw](https://github.com/winsw/winsw)와 같은 도구를 사용하여 Spring Boot 애플리케이션을 Windows 서비스로 등록할 수 있습니다.
|
|
|
|
<h3 id="deployment-environment-settings">7.5 배포 환경 설정</h3>
|
|
|
|
1. **Java 버전**: 배포 환경에서는 Java 1.8을 사용합니다.
|
|
2. **서버**:
|
|
- 내장 서버(bootWar 직접 실행): 내장된 Tomcat 9.0.78 사용
|
|
- 외부 서버(bootWar 배포): Tomcat 9.0.78 이상 권장
|
|
3. **데이터베이스**: MariaDB를 사용합니다.
|
|
4. **메모리 설정**: 애플리케이션 크기와 사용자 수에 따라 적절한 JVM 메모리 설정이 필요합니다.
|
|
|
|
<h3 id="deployment-checklist">7.6 배포 체크리스트</h3>
|
|
|
|
1. **프로필 설정 확인**: 배포 환경에 맞는 프로필이 활성화되었는지 확인합니다.
|
|
2. **데이터베이스 연결 확인**: 데이터베이스 연결 정보가 올바르게 설정되었는지 확인합니다.
|
|
3. **파일 업로드 경로 확인**: 파일 업로드 경로가 존재하고 쓰기 권한이 있는지 확인합니다.
|
|
4. **로그 경로 확인**: 로그 파일 경로가 존재하고 쓰기 권한이 있는지 확인합니다.
|
|
5. **메모리 설정 확인**: JVM 메모리 설정이 적절한지 확인합니다.
|
|
6. **포트 충돌 확인**: 사용할 포트가 다른 애플리케이션과 충돌하지 않는지 확인합니다.
|
|
|
|
## 8. 참고 자료
|
|
|
|
- [Spring Boot 공식 문서](https://docs.spring.io/spring-boot/docs/2.7.18/reference/html/)
|
|
- [전자정부 프레임워크 가이드](https://www.egovframe.go.kr/wiki/doku.php)
|
|
- [MyBatis 공식 문서](https://mybatis.org/mybatis-3/ko/index.html)
|
|
- [TOAST UI Grid 공식 문서](https://ui.toast.com/tui-grid)
|
|
- [TOAST UI Editor 공식 문서](https://ui.toast.com/tui-editor) |