2025-07-18 14:55:04 +09:00
2025-07-18 14:00:16 +09:00
2025-05-27 16:34:20 +09:00
2025-07-18 14:00:16 +09:00
2025-07-17 16:55:17 +09:00
2025-05-27 16:34:20 +09:00
2025-06-23 17:32:25 +09:00
2025-05-27 16:34:20 +09:00
2025-05-27 16:34:20 +09:00
2025-05-27 16:34:20 +09:00
2025-07-10 09:18:15 +09:00

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 어플리케이션으로 구성되어 있다.

.
|-- README.md
|-- admin # 관리자 어플리케이션
|   |-- pom.xml
|   |-- src
|   `-- target
|-- core # 공통 모듈
|   |-- pom.xml
|   |-- src
|   `-- target
|-- front # 프론트 어플리케이션
|   |-- pom.xml
|   |-- src
|   `-- target
`-- pom.xml
`-- README.md

⚡ AWS S3 업로드를 이용하지 않는다면, pom.xml 에서 aws모듈 관련 내용을 삭제하면 된다.
⚡ admin, front, api 중 실제 프로젝트에서 사용할 모듈만 남기고 삭제해주세요.

✔️ Dockerfile 과 .gitlab-ci.yml 은 삭제해주세요 : ) recycle demo 용이기에 여려분의 프로젝트에서는 의미가 없습니다.

recycle 의 demo 가 궁금하다면 아래 URL 에서 확인 해주세요.

각 모듈의 내부 구조(헥사고날 아키텍처 예시)

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/public) N
-Dpath.upload.tmpdir 임시 파일 업로드 경로 기본값 (~/upload/tmpdir) N
-Dlogging.file.path 로그 파일 생성 경로 기본값 (~/logs) N
-Dfile.encoding JVM 속성 UTF-8 Y
-Djava.net.preferIPv4Stack JVM 속성. 클라이언트 IP체크시 IPv4 형식을 사용하기 위함. true Y
-Dcom.amazonaws.sdk.disableEc2Metadata aws 모듈의 ec2 metadata 전송 끄기 true N
-Dserver.port (2023-03-25 추가) 서버 포트 (없다면 기본 8080) 원하는 port N
-Dserver.forward-headers-strategy (2023-03-25 추가) 프록시 서버(nginx, apache)에 정의된 X-Forward-For, X-Forwarded-Proto 설정값을 이용하려면 native 로 설정해주면 된다. (내장 컨테이너를 사용하는 경우에만 유효) native N
-Dspring.datasource.driver-class-name (2023-03-25 추가) JDBC Driver. 없다면 JDBC URL을 기준으로 JPA가 판단한다. jdbc 드라이버 Y
-Dspring.datasource.url (2023-03-25 추가) JDBC URL jdbc url N
-Dspring.datasource.username (2023-03-25 추가) DB Username DB 사용자 Y
-Dspring.datasource.password (2023-03-25 추가) DB Password DB 패스워드 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
-Dcom.amazonaws.sdk.disableEc2Metadata=true
-Dserver.port=8080
-Dserver.forward-headers-strategy=native
-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
-Dspring.datasource.hikari.maximum-pool-size=10 
-Dspring.datasource.hikari.minimum-idle=5 
-Dspring.datasource.hikari.idle-timeout=120000 
-Dspring.datasource.hikari.max-lifetime=900000 
-Dspring.datasource.hikari.connection-timeout=5000 
-Dspring.datasource.hikari.leak-detection-threshold=30000 

** 주의 : 운영서버일 경우 vm옵션 추가 -Dspring.profiles.active=prod -Dpath.upload.storage=SFTP -Djasypt.encryptor.password=ko-research -Djasypt.encryptor.algorithm=PBEWITHHMACSHA512ANDAES_256

JDBC 및 데이터 핸들링 구성 옵션

app.initData.core

-Dapp.initData.core=true # true | false

어플리케이션 초기 구동에 필요한 필수 데이터 생성여부. 공통코드, 메뉴 정보 및 개발에 필요한 기반 데이터 등이 여기에 해당한다.
InitAdminData, InitUriFrontData 등 ApplicationRunner 구현체에서 내용을 확인할 수 있다.

spring.sql.init.mode

-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

-Dlogging.file.path=~/logs # 기본값 ${user.home}/logs

로그 파일 생성 경로를 지정한다. 지정된 경로에 아래와 같은 로그 파일이 생성된다.

admin-app.log       # 어드민 전체 로그
admin-app-ERROR.log # 어드민 로그 중 ERROR 부분 필터링
front-app.log       # 프론트 전체 로그
front-app-ERROR.log # 프론트 로그 중 ERROR 부분 필터링

File 구성 옵션

파일 업로드

-Dpath.upload.public=~/upload/public # 파일 업로드 경로
-Dpath.upload.tmpdir=~/upload/tmpdir # tmp 디렉토리 경로

파일 업로드 경로가 지정되면 사용자가 업로드한 파일은 이 경로를 기준으로 주제/년월일 폴더 아래에 저장됩니다.
tmpdir 은 서블릿 컨테이너가 multipart 파일 업로드 시 대용량 처리를 위해 임시파일을 저장하는 공간입니다.

파일 시스템 외에 AWS S3 로도 업로드해야 한다면, 아래 AWS CLI 를 이용하기 위한 정보를 제공해주어야 합니다.

-Dapp.aws.s3.accessKey=AKIAZF27HETWNITZBZOF # AMI 에서 발급한 사용자 엑세스 키
-Dapp.aws.s3.secretKey=IhnTG0X7Wav8ak3cbYR1l8UAjL+gbnXdWJRM11cx # AMI 에서 발급한 사용자 시크릿 키
-Dapp.aws.s3.bucketName=etribe # S3 버킷 이름
-Dapp.aws.s3.bucketFolder=/recycle/upload # S3 버킷 디렉토리
-Dapp.aws.s3.domain=dixjkmptx5pkm.cloudfront.net # S3 혹은 cloudfront 도메인

🔑 위 accessKey 정보는 제가 만든 임시 정보이며, recycle 데모용으로만 사용되니 참고해주세요.

💡 recycle 은 파일 시스템 업로드와 S3 업로드를 사용 목적에 맞게 선택할 수 있는 유연성을 제공합니다. FileUploadType은 파일 업로드가 필요한 주제 도메인들이 정의된 enum 객체입니다. 여기 기술된 FileStorageType 속성에 따라 파일 업로드 경로가 결정됩니다.

파일 참조

업로드된 파일은 참조될 수 있어야 합니다. fileUrlPortIn는 파일이 파일 시스템에 있든 S3 에 있든 정확한 참조 URL 을 전달해주는 인터페이스입니다.

// 참조 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 사용 예시

// 필수: AuditCommand 상속
public class UpdateCmd extends AuditCommand {
    private Long seq;
    ...
}

AuditCommand는 아래 메서드를 제공하며, 각각 생성/수정/삭제 작업에 필요한 필드를 자동으로 설정합니다.

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

어노테이션 사용 예시

@UpdateCommand
public void operate(UpdateCmd cmd) {
    mapper.update(cmd);
}

3. AOP 외 수동 적용이 필요한 경우: AuditUtil 사용

AOP 외에도, 하나의 DAO 메서드 내에서 여러 Insert/Delete 처리가 필요한 경우에는 아래처럼 직접 AuditUtil을 사용할 수 있습니다.

AuditUtil 사용 예시

// 관리자 등록
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 사용 예시

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 프로파일을 제공한다.

  • jar (default)
  • war Jeus, WebLogic, Tomcat 등 별도 외장 컨테이너 이용시 사용

maven 빌드 시 프로파일을 지정하지 않으면 기본 jar 프로파일로 동작하고, war 의 경우 명시적인 지정이 필요하다.

아래는 admin 빌드시 war 프로파일을 지정한 예시이다.

$ 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

개발 서버 환경

database - postgresql 14.17

URL: jdbc:postgresql://15.165.180.203:5432/korea_research
USERNAME: ko_research
PASSWORD: koresearch1@#4

🚀 ADMIN DEPLOY

deploy_dev_admin 브렌치로 merge! pipeline 실행 후 아래 URL 에서 확인가능.

🚀 FRONT DEPLOY

deploy_dev_front 브렌치로 merge! pipeline 실행 후 아래 URL 에서 확인가능.

Description
임가경제조사 일계부 시스템
Readme MIT 20 MiB
Languages
HTML 49.6%
JavaScript 31.5%
Java 18.6%
CSS 0.2%
PLpgSQL 0.1%