450 lines
17 KiB
Markdown
450 lines
17 KiB
Markdown
|
|
# KOREA-RESEARCH
|
|
|
|
```
|
|
┬─┐┌─┐┌─┐┬ ┬┌─┐┬ ┌─┐
|
|
├┬┘├┤ │ └┬┘│ │ ├┤
|
|
┴└─└─┘└─┘ ┴ └─┘┴─┘└─┘ - framework for spring developers exploring JPA
|
|
|
|
_____\ _______
|
|
/ \ | /\
|
|
/_______/ |_____/ \
|
|
| \ / / /
|
|
\ \ \/ /
|
|
\ / \__/_
|
|
\/ ____ /\
|
|
/ \ / \
|
|
/\ \ / /
|
|
\ \/ /
|
|
\___\__/
|
|
|
|
GNU GENERAL PUBLIC LICENSE
|
|
Version 3, 29 June 2007
|
|
|
|
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
of this license document, but changing it is not allowed.
|
|
```
|
|
|
|
## 프로젝트 개요
|
|
|
|
본 프로젝트는 **헥사고날 아키텍처(Ports & Adapters)** 기반의 Spring Boot 멀티모듈 시스템입니다.
|
|
도메인 로직과 외부 시스템(웹, DB, 파일 등)을 명확히 분리하여 유지보수성과 확장성을 극대화하였습니다.
|
|
|
|
## Prerequisites
|
|
|
|
* JDK 17+
|
|
* Maven
|
|
* PostgreSQL
|
|
|
|
## Structure
|
|
|
|
recycle 은 `core` 모듈을 기반으로 한 `admin`, `front`, `api` 어플리케이션으로 구성되어 있다.
|
|
|
|
```shell
|
|
.
|
|
|-- README.md
|
|
|-- admin # 관리자 어플리케이션
|
|
| |-- pom.xml
|
|
| |-- src
|
|
| `-- target
|
|
|-- core # 공통 모듈
|
|
| |-- pom.xml
|
|
| |-- src
|
|
| `-- target
|
|
|-- front # 프론트 어플리케이션
|
|
| |-- pom.xml
|
|
| |-- src
|
|
| `-- target
|
|
`-- pom.xml
|
|
`-- README.md
|
|
```
|
|
|
|
### 각 모듈의 내부 구조(헥사고날 아키텍처 예시)
|
|
|
|
```
|
|
usecase/
|
|
└── daily/
|
|
└── expense/
|
|
├── ports/
|
|
│ ├── application/
|
|
│ │ └── DailyExpenseService.java
|
|
│ ├── DailyExpensePortIn.java
|
|
│ └── DailyExpensePortOut.java
|
|
└── adapters/
|
|
├── persistence/
|
|
│ └── DailyExpenseDao.java
|
|
└── web/
|
|
└── DailyExpenseController.java
|
|
```
|
|
- **ports/**: 도메인 서비스 및 인터페이스(Port)
|
|
- **adapters/**: 외부 시스템(웹, DB 등) 연결 어댑터
|
|
|
|
|
|
## VM Options
|
|
|
|
프레임워크 실행 시 필요한 자바 VM 옵션은 아래와 같다.
|
|
|
|
| VM 변수 | 설명 | 설정 값 | 필수여부 |
|
|
|---------------------------------------------|---------------------------------------|-------------------------|------|
|
|
| -Dspring.profiles.active | Spring active 프로파일 | local, dev, prod | Y |
|
|
| -Dapp.initData.core | 어플리케이션 초기 구동에 필요한 필수 데이터 생성여부 | true, false | N |
|
|
| -Dspring.sql.init.mode | SQL 초기화 모드를 설정 | always, embedded, never | N |
|
|
| -Dpath.upload.public | 파일 업로드 경로 | 기본값 (~/upload/tmpdir) | N |
|
|
| -Dfile.encoding | JVM 속성 | `UTF-8` | Y |
|
|
| -Djava.net.preferIPv4Stack | JVM 속성. 클라이언트 IP체크시 IPv4 형식을 사용하기 위함. | true | Y |
|
|
| -Dlogging.level.org.springframework.security | 디버깅 레벨 | true | Y |
|
|
| -Daes.secret-key | 암호화 시크릿 키 | true | Y |
|
|
| **-Dserver.port** | 서버 포트 (없다면 기본 8080) | 원하는 port | Y |
|
|
| **-Dpath.upload.storage** | 파일 저장 방법 | jdbc 드라이버 | Y |
|
|
| **-Dpath.upload.sftp.public** | sftp 파일 경로 | jdbc url | Y |
|
|
| **-Dfile.upload.sftp.ip** | sftp 아이피 | SFTP 아이피 | Y |
|
|
| **-Dfile.upload.sftp.id** | sftp 아이디 | SFTP 사용자 | Y |
|
|
| **-Dfile.upload.sftp.password** | DB Password | SFTP 패스워드 | Y |
|
|
| **-Dfile.upload.sftp.port** | DB Port | SFTP 포트 | Y |
|
|
|
|
|
|
### VM Options 예시
|
|
#### `admin`, `front` 모두 사용가능합니다.
|
|
```
|
|
-Dspring.profiles.active=local
|
|
-Dapp.initData.core=false
|
|
-Dspring.sql.init.mode=never
|
|
-Dfile.encoding=UTF-8
|
|
-Djava.net.preferIPv4Stack=true
|
|
-Dserver.port=8081
|
|
-Dlogging.level.org.springframework.security=DEBUG
|
|
-Daes.secret-key=092HW829O0A0AVR0
|
|
-Dpath.upload.storage=LOCAL
|
|
-Dpath.upload.sftp.public=/home/etribe/data/upload
|
|
-Dfile.upload.sftp.ip=115.68.193.117
|
|
-Dfile.upload.sftp.id=etribe
|
|
-Dfile.upload.sftp.password=Etribe@3415
|
|
-Dfile.upload.sftp.port=22
|
|
-Djasypt.encryptor.password=ko-research (변경 필요)
|
|
-Djasypt.encryptor.algorithm=PBEWITHHMACSHA512ANDAES_256
|
|
|
|
```
|
|
** 주의 : 현재 코리아 리서치의 운영서버밖에 존재하지않으므로 개발서버의 세팅 필요 **
|
|
```
|
|
-Dspring.profiles.active=local
|
|
-Dpath.upload.storage=LOCAL
|
|
-Djasypt.encryptor.password=ko-research
|
|
-Djasypt.encryptor.algorithm=PBEWITHHMACSHA512ANDAES_256
|
|
```
|
|
|
|
|
|
|
|
|
|
## DB 설정
|
|
### admin
|
|
kri DB, mms DB(문자 발송) 두개의 DB 커넥션 존재
|
|
|
|
### front
|
|
kri DB 한개의 DB 커넥션 존재
|
|
|
|
datasource:
|
|
kri:
|
|
driver-class-name: org.postgresql.Driver
|
|
jdbc-url: ENC(mF3Z0fgCagFruOk/F2Z2PYzXhwGedE1secfYDgci+ke9z8xFEZ/GWbgXA4XeSq5D+k9/oRLOxzwx/D24tswdoHdQugHmGb0UqrW4vGBa7YFJvcnWylOpd5ppUeEIUJGv)
|
|
username: ENC(cNXntROGOeM115QfLlVhhBz8+qY70eTWwmwLM+7AMslWmfWTq9ZPl4pVnDopJauM)
|
|
password: ENC(kUIzqWTu0+bqjYH4Jq9TFOOh3UwY+XVvA2OlT4VXJvxWCas66UNdGRmWDQKri5fI)
|
|
mms:
|
|
driver-class-name: org.postgresql.Driver
|
|
jdbc-url: ENC(TZ7H8DIFZDbsNp3PRWbz3bkJbjsx3580ljmELMJInASgpiEH66Lb8adpjt5WGXoIdZbHetlgtEFo8F+U8XUa9fjYWNOpiZ+D99XoXJUOP3s=)
|
|
username: ENC(cNXntROGOeM115QfLlVhhBz8+qY70eTWwmwLM+7AMslWmfWTq9ZPl4pVnDopJauM)
|
|
password: ENC(kUIzqWTu0+bqjYH4Jq9TFOOh3UwY+XVvA2OlT4VXJvxWCas66UNdGRmWDQKri5fI)
|
|
maximum-pool-size: 2
|
|
minimum-idle: 1
|
|
app.module.admin.config.application.bean.JasyptConfig
|
|
|
|
|
|
## JDBC 및 데이터 핸들링 구성 옵션
|
|
|
|
### app.initData.core
|
|
|
|
```shell
|
|
-Dapp.initData.core=true # true | false
|
|
```
|
|
|
|
어플리케이션 초기 구동에 필요한 필수 데이터 생성여부. 공통코드, 메뉴 정보 및 개발에 필요한 기반 데이터 등이 여기에 해당한다.
|
|
InitAdminData, InitUriFrontData 등 *ApplicationRunner* 구현체에서 내용을 확인할 수 있다.
|
|
|
|
### spring.sql.init.mode
|
|
|
|
```shell
|
|
-Dspring.sql.init.mode=never # always | embedded | never
|
|
```
|
|
어플리케이션 초기 구동 시, schema.sql, data.sql 등 SQL 초기화 스크립트 실행 여부를 제어하는 설정.
|
|
|
|
* always : 애플리케이션 구동 시 항상 SQL 스크립트를 실행
|
|
* embedded : 내장 DB(H2 등)일 경우에만 실행
|
|
* never : SQL 스크립트를 실행하지 않음
|
|
|
|
## 데이터 호출 및 응답 처리 방식 가이드
|
|
> BO(Back Office)와 FO(Front Office) 화면에서는 기능에 따라 **Ajax 호출 방식**과 **서버 렌더링 방식(Server-Side Rendering, SSR)을** 구분하여 사용합니다.
|
|
|
|
### BO (Back Office: 관리자 화면)
|
|
- #### 📡 Ajax 호출 방식 (REST API, JSON 응답)
|
|
다음 기능은 Ajax를 통해 REST API(JSON)를 호출합니다
|
|
|
|
| 기능 | 메서드 | URI | 예시 |
|
|
|----------|----------|------------------------------------|------------------------|
|
|
| 목록 조회 | GET | `/api/{resource-name}/list` | `/api/articles/list` |
|
|
| 등록 | POST | `/api/{resource-name}/create` | `/api/articles/create` |
|
|
| 수정 | PUT/PATCH | `/api/{resource-name}/update` | `/api/articles/update` |
|
|
| 삭제 | DELETE | `/api/{resource-name}/remove` | `/api/articles/remove` |
|
|
| 등록 & 수정 |POST | `/api/{resource-name}/save` | `/api/articles/save` |
|
|
|
|
|
|
- #### 🖥️ 서버 렌더링 방식 (SSR)
|
|
상세 조회(view) 화면은 SSR 방식으로 처리합니다.
|
|
|
|
| 기능 | 메서드 | URI | 예시 |
|
|
|------------|--------|------------------------|---------------|
|
|
| 상세 조회 | GET | `/{resource-name}/{id}` | `/articles/1` |
|
|
|
|
---
|
|
### FO (Front Office: 사용자 화면)
|
|
- #### 📡 Ajax 호출 방식 (REST API, JSON 응답)
|
|
다음 기능은 Ajax 기반 REST API 호출로 처리합니다.
|
|
|
|
| 기능 | 메서드 | URI | 예시 |
|
|
|------|------------|-------------------------|--------------------------|
|
|
| 등록 | POST | `/api/{resource-name}/create` | `/api/articles/create` |
|
|
| 수정 | PUT/PATCH | `/api/{resource-name}/update` | `/api/articles/update` |
|
|
| 삭제 | DELETE | `/api/{resource-name}/remove` | `/api/articles/remove` |
|
|
|
|
- #### 🖥️ 서버 렌더링 방식 (SSR)
|
|
목록 및 상세 화면은 SSR 방식으로 처리할 수 있으며, 상황에 따라 선택적으로 사용합니다.
|
|
|
|
| 기능 | 메서드 | URI | 예시 |
|
|
|------------|--------|------------------------------|------------------------|
|
|
| 목록 조회 | GET | `/{resource-name}/list` | `/articles/list` |
|
|
| 상세 조회 | GET | `/{resource-name}/{id}` | `/articles/1` |
|
|
|
|
## LOG 생성 옵션
|
|
|
|
### logging.file.path
|
|
|
|
```shell
|
|
-Dlogging.file.path=~/logs # 기본값 ${user.home}/logs
|
|
```
|
|
|
|
로그 파일 생성 경로를 지정한다. 지정된 경로에 아래와 같은 로그 파일이 생성된다.
|
|
|
|
```shell
|
|
admin-app.log # 어드민 전체 로그
|
|
admin-app-ERROR.log # 어드민 로그 중 ERROR 부분 필터링
|
|
front-app.log # 프론트 전체 로그
|
|
front-app-ERROR.log # 프론트 로그 중 ERROR 부분 필터링
|
|
```
|
|
|
|
## File 구성 옵션
|
|
|
|
### 파일 업로드
|
|
|
|
```shell
|
|
-Dpath.upload.public=~/upload/public # 파일 업로드 경로
|
|
```
|
|
|
|
파일 업로드 경로가 지정되면 사용자가 업로드한 파일은 이 경로를 기준으로 `주제`/`년월일` 폴더 아래에 저장됩니다.
|
|
|
|
🔑 위 accessKey 정보는 제가 만든 임시 정보이며, recycle 데모용으로만 사용되니 참고해주세요.
|
|
|
|
💡
|
|
`FileUploadType`은 파일 업로드가 필요한 주제 도메인들이 정의된 enum 객체입니다. 여기 path.upload.storage 옵션에 따라 파일 업로드 경로가 결정됩니다.
|
|
|
|
### 파일 참조
|
|
|
|
업로드된 파일은 참조될 수 있어야 합니다. `fileUrlPortIn`는 파일이 파일 시스템에 있든 S3 에 있든 정확한 참조 URL 을 전달해주는 인터페이스입니다.
|
|
|
|
```java
|
|
// 참조 URL 전달 - inline 방식
|
|
fileUrlPortIn.getInline(
|
|
uploadFile.getType().getFileStorageType(),
|
|
uploadFile.getPath(),
|
|
uploadFile.getName());
|
|
|
|
// 참조 URL 전달 - attachment 방식
|
|
fileUrlPortIn.getAttachment(
|
|
uploadFile.getType().getFileStorageType(),
|
|
uploadFile.getId());
|
|
```
|
|
|
|
`inline` 과 `attachment` 는 응답 헤더의 content-disposition 속성 값을 의미합니다.
|
|
업로드된 파일은 사용자에게 전달할 때 `inline` 과 `attachment` 두 방식 중 요건에 맞게 사용하면 됩니다.
|
|
|
|
## 공통 필드(Audit) 자동 주입 방법 (AOP기반)
|
|
createdAt, createdBy, updatedAt, updatedBy, deletedAt, deletedBy, isDeleted 와 같은 공통 이력 필드는
|
|
매번 수동으로 설정하지 않아도 되도록, AOP를 활용해 자동으로 주입되도록 구성했습니다.
|
|
|
|
### 1. 기본 구조
|
|
create, update, delete 시 Command 객체에 AuditCommand를 상속합니다.
|
|
#### AuditCommand 사용 예시
|
|
``` java
|
|
// 필수: AuditCommand 상속
|
|
public class UpdateCmd extends AuditCommand {
|
|
private Long seq;
|
|
...
|
|
}
|
|
```
|
|
AuditCommand는 아래 메서드를 제공하며, 각각 생성/수정/삭제 작업에 필요한 필드를 자동으로 설정합니다.
|
|
``` java
|
|
public class AuditCommand {
|
|
private LocalDateTime createdAt;
|
|
private String createdBy;
|
|
private LocalDateTime updatedAt;
|
|
private String updatedBy;
|
|
private LocalDateTime deletedAt;
|
|
private String deletedBy;
|
|
|
|
public void create() { ... }
|
|
public void update() { ... }
|
|
public void delete() { ... }
|
|
}
|
|
```
|
|
|
|
### 2. AOP 기반 어노테이션 자동 주입
|
|
service 또는 dao 내에
|
|
@CreateCommand, @UpdateCommand, @DeleteCommand 어노테이션을 통해
|
|
AOP가 자동으로 해당 메서드의 파라미터(AuditCommand 상속 객체)에 공통 필드를 주입합니다.
|
|
|
|
| 어노테이션 | 자동 설정되는 필드 |
|
|
| ---------------- | -------------------------------------------------- |
|
|
| `@CreateCommand` | `createdAt`, `createdBy`, `updatedAt`, `updatedBy` |
|
|
| `@UpdateCommand` | `updatedAt`, `updatedBy` |
|
|
| `@DeleteCommand` | `updatedAt`, `updatedBy`, `deletedAt`, `deletedBy` |
|
|
|
|
#### 어노테이션 사용 예시
|
|
```java
|
|
@UpdateCommand
|
|
public void operate(UpdateCmd cmd) {
|
|
mapper.update(cmd);
|
|
}
|
|
```
|
|
### 3. AOP 외 수동 적용이 필요한 경우: AuditUtil 사용
|
|
AOP 외에도, 하나의 DAO 메서드 내에서 여러 Insert/Delete 처리가 필요한 경우에는 아래처럼 직접 AuditUtil을 사용할 수 있습니다.
|
|
#### AuditUtil 사용 예시
|
|
```java
|
|
// 관리자 등록
|
|
mapper.insertAdmin(AuditUtil.create(cmd));
|
|
|
|
// 관리자의 역할 매핑
|
|
mapper.insertAdminHasRoles(
|
|
AuditUtil.create(new SaveAdminHasRoleParam(cmd.getSeq(), cmd.getRoleIds()))
|
|
);
|
|
```
|
|
|
|
### 4. XML에서 공통 필드 include로 재사용
|
|
SQL 작성 시 공통필드의 반복 작성을 피하기 위해 `<sql>` 태그로 분리하여 `<include>` 방식으로 재사용합니다.
|
|
자세한 정의는 `CommonFieldsMapper.xml` 파일에서 확인할 수 있습니다.
|
|
|
|
| SQL ID | 설명 | 사용 예시 |
|
|
| ---------------------------- | -------------------------------------- | -------------------------------------------------------------- |
|
|
| `CreateUpdateBaseColumns` | `INSERT` 시 공통 컬럼 정의 | `<include refid="common.fields.CreateUpdateBaseColumns" />` |
|
|
| `CreateUpdateBaseValues` | `INSERT` 시 공통 컬럼의 값 정의 | `<include refid="common.fields.CreateUpdateBaseValues" />` |
|
|
| `CreateUpdateListBaseValues` | `다건 INSERT` 시 공통 값 정의 (e.g. `foreach`) | `<include refid="common.fields.CreateUpdateListBaseValues" />` |
|
|
| `UpdateBaseSet` | `UPDATE` 시 공통 `SET` 구문 | `<include refid="common.fields.UpdateBaseSet" />` |
|
|
| `DeleteBaseSet` | `삭제 처리용 UPDATE` 시 공통 `SET` 구문 | `<include refid="common.fields.DeleteBaseSet" />` |
|
|
|
|
#### include 사용 예시
|
|
```xml
|
|
UPDATE household
|
|
SET
|
|
owner_name = #{ownerName},
|
|
owner_age = #{ownerAge},
|
|
tel = #{tel},
|
|
phone = #{phone},
|
|
region = #{region},
|
|
city = #{city},
|
|
address_detail = #{addressDetail},
|
|
<include refid="common.fields.UpdateBaseSet" /> <!-- 공통 필드 include -->
|
|
WHERE seq = ${seq}
|
|
```
|
|
|
|
|
|
## PACKAGING
|
|
|
|
배포방식 설정을 위해 두가지 maven 프로파일을 제공한다.
|
|
|
|
* `war` Jeus, WebLogic, Tomcat 등 별도 외장 컨테이너 이용시 사용
|
|
|
|
maven 빌드 시 프로파일을 지정하지 않으면 기본 `jar` 프로파일로 동작하고, `war` 의 경우 명시적인 지정이 필요하다.
|
|
|
|
아래는 admin 빌드시 `war` 프로파일을 지정한 예시이다.
|
|
|
|
```shell
|
|
$ mvn --projects admin --also-make clean package -DskipTests -P war
|
|
|
|
# 빌드 후, admin/target 디렉토리에 war 가 생성된걸 확인할 수 있다.
|
|
$ ll admin/target
|
|
-rw-r--r-- 1 user 197121 94905770 4월 22 09:59 admin-0.0.1-SNAPSHOT.war
|
|
```
|
|
|
|
### 운영서버 배포 스크립트
|
|
|
|
## SFTP 접근
|
|
```
|
|
sftp로 접속 가능
|
|
IP: 115.68.193.117
|
|
ID: etribe
|
|
PW: Etribe@3415
|
|
```
|
|
### 1. war 파일 생성
|
|
```
|
|
mvn clean package -P war
|
|
```
|
|
### 2. SFTP 파일 업로드
|
|
```
|
|
/home/etribe/data/upload/tmp
|
|
```
|
|
### 3. putty 접속 : root 계정으로 변경
|
|
```
|
|
sudo su-
|
|
```
|
|
### 4. war 파일 옮기기
|
|
```
|
|
sudo mv /home/etribe/data/upload/tmp/admin/ROOT.war /opt/admin-tomcat/webapps/
|
|
sudo mv /home/etribe/data/upload/tmp/front/ROOT.war /opt/front-tomcat/webapps/
|
|
```
|
|
### 5. 파일 소유자 변경
|
|
```
|
|
sudo chown -R root:root /opt/admin-tomcat
|
|
sudo chown -R root:root /opt/front-tomcat
|
|
```
|
|
### 6. 권한 확인
|
|
```
|
|
ls -l /opt/admin-tomcat/webapps/
|
|
ls -l /opt/front-tomcat/webapps/
|
|
```
|
|
### 7. 톰캣 shutdown
|
|
```
|
|
sudo /opt/admin-tomcat/bin/shutdown.sh
|
|
sudo /opt/front-tomcat/bin/shutdown.sh
|
|
or
|
|
sudo netstat -tulnp | grep 3415
|
|
sudo netstat -tulnp | grep 3416
|
|
sudo kill -9 <PID>
|
|
```
|
|
### 8. 배포 되었던 ROOT 파일 백업본으로
|
|
```
|
|
sudo mv /opt/admin-tomcat/webapps/ROOT /opt/admin-tomcat/webapps/ROOT.bak
|
|
sudo mv /opt/front-tomcat/webapps/ROOT /opt/front-tomcat/webapps/ROOT.bak
|
|
```
|
|
|
|
### 9. 기존 war 파일 삭제
|
|
```
|
|
rm -r /opt/admin-tomcat/webapps/ROOT.war
|
|
rm -r /opt/front-tomcat/webapps/ROOT.war
|
|
```
|
|
### 10. 톰캣 start
|
|
```
|
|
sudo /opt/admin-tomcat/bin/startup.sh
|
|
sudo /opt/front-tomcat/bin/startup.sh
|
|
```
|
|
## vm option
|
|
```
|
|
sudo vi /opt/admin-tomcat/bin/setenv.sh
|
|
sudo vi /opt/front-tomcat/bin/setenv.sh
|
|
``` |