Files
korea-research/README.md
2025-05-27 19:19:32 +09:00

268 lines
13 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.
```
## Prerequisites
* JDK 17+
* Maven
* PostgreSQL
## Structure
recycle 은 `core` 모듈을 기반으로 한 `admin`, `front`, `api` 어플리케이션으로 구성되어 있다.
```shell
.
|-- README.md
|-- admin # 관리자 어플리케이션
| |-- pom.xml
| |-- src
| `-- target
|-- api # API 모듈 (JWT 토큰 기반 인증)
| |-- pom.xml
| |-- src
| `-- target
|-- aws # AWS 서비스 전략(strategy) 모듈
| |-- pom.xml
| |-- src
| `-- target
|-- core # 공통 모듈
| |-- pom.xml
| |-- src
| `-- target
|-- front # 프론트 어플리케이션
| |-- pom.xml
| |-- src
| `-- target
`-- pom.xml
```
⚡ AWS S3 업로드를 이용하지 않는다면, pom.xml 에서 `aws`모듈 관련 내용을 삭제하면 된다.
⚡ `admin`, `front`, `api` 중 실제 프로젝트에서 사용할 모듈만 남기고 삭제해주세요.
✔️ Dockerfile 과 .gitlab-ci.yml 은 삭제해주세요 : ) recycle demo 용이기에 여려분의 프로젝트에서는 의미가 없습니다.
recycle 의 demo 가 궁금하다면 아래 URL 에서 확인 해주세요.
- `recycle-admin` - https://recycle-admin.etribe.co.kr 계정정보 (recycle-super/recycle1@#$)
- `recycle-api` - https://recycle-api.etribe.co.kr/swagger-ui/index.html
- `recycle-front` - https://recycle-front.etribe.co.kr/ 계정정보 (generalUser/generalUser1@#$)
## VM Options
프레임워크 실행 시 필요한 자바 VM 옵션은 아래와 같다.
| VM 변수 | 설명 | 설정 값 | 필수여부 |
|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|-------------------------|------|
| -Dspring.profiles.active | Spring active 프로파일 | local, dev, prod | Y |
| -Dapp.initData.core | 어플리케이션 초기 구동에 필요한 필수 데이터 생성여부 | true, false | 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`, `api` 모두 사용가능합니다.
```
-Dspring.profiles.active=local
-Dapp.initData.core=false
-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
-Dspring.datasource.driver-class-name=org.postgresql.Driver
-Dspring.datasource.url=jdbc:postgresql://<DB_HOST>:5432/<DB_NAME>
-Dspring.datasource.username=<DB_USERNAME>
-Dspring.datasource.password=<DB_PASSWORD>
```
## JDBC 및 데이터 핸들링 구성 옵션
이 프로젝트는 PostgreSQL을 사용하며,
JDBC 연결은 위 VM Options에 포함된 아래 설정을 기준으로 동작합니다.
```
-Dspring.datasource.driver-class-name=org.postgresql.Driver
-Dspring.datasource.url=jdbc:postgresql://<DB_HOST>:5432/<DB_NAME>
-Dspring.datasource.username=<DB_USERNAME>
-Dspring.datasource.password=<DB_PASSWORD>
```
### app.initData.core
```shell
-Dapp.initData.core=true # true | false
```
어플리케이션 초기 구동에 필요한 필수 데이터 생성여부. 공통코드, 메뉴 정보 및 개발에 필요한 기반 데이터 등이 여기에 해당한다.
InitAdminData, InitUriFrontData 등 *ApplicationRunner* 구현체에서 내용을 확인할 수 있다.
## 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 # 파일 업로드 경로
-Dpath.upload.tmpdir=~/upload/tmpdir # tmp 디렉토리 경로
```
파일 업로드 경로가 지정되면 사용자가 업로드한 파일은 이 경로를 기준으로 `주제`/`년월일` 폴더 아래에 저장됩니다.
tmpdir 은 서블릿 컨테이너가 multipart 파일 업로드 시 대용량 처리를 위해 임시파일을 저장하는 공간입니다.
파일 시스템 외에 AWS S3 로도 업로드해야 한다면, 아래 AWS CLI 를 이용하기 위한 정보를 제공해주어야 합니다.
```shell
-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 을 전달해주는 인터페이스입니다.
```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` 두 방식 중 요건에 맞게 사용하면 됩니다.
## 코드 작성 규칙 (coding conventions)
기본 패키지 구조는 [포트 앤 어댑터 패턴](https://coco-log.tistory.com/205)에 기반해 구성됩니다.
![img](./docs/img/port-adapter.jpg)
getArticles 라는 주제(subject) 패키지 하부를 구성하는 ports 와 adapters 패키지를 주의깊게 봐주세요.
```
# 주제(subject)
getArticles
|-- adapters
| |-- persistence
| | |-- GetArticlesDao.java # 포트아웃 구현체
| `-- web
| |-- GetArticlesController.java
| `-- model
| `-- GetArticlesReqVO.java
`-- ports
|-- GetArticlesPortIn.java # 포트인 인터페이스
|-- GetArticlesPortOut.java # 포트아웃 인터페이스
`-- application
|-- GetArticlesService.java # 포트인 구현체
`-- domain
|-- GetArticles.java
`-- GetArticlesCmd.java
```
* ports 는 비지니스 로직을 담는 application 레이어가 위치한 곳입니다. application 은 `포트인` 인터페이스를 통해 호출되며 `포트아웃` 인터페이스를 호출해 결과를 얻습니다.
* application 은 누가 `포트인`을 호출하는지 신경쓰지 않습니다. **자신이 호출하는 `포트아웃`의 구현체에 대해서도 모릅니다.** 이를 통해 application 은 다른 계층(web,
persistence)과 관계없는 독립적인 레이어가 됩니다.
* adapters/web 은 사용자 요청을 처리하는 controller 레이어가 위치한 곳입니다. `포트인` 인터페이스를 호출하는 클라이언트로 해당 규격을 맞춘 어뎁터(adapter) 이며, *
*application 에 종속적입니다.**
* adapters/persistence 는 영속화(persistence) 레이어가 위치한 곳입니다. mybatis, jpa 등 다양한 ORM 기술을 이용하여 `포트아웃` 인터페이스를 구현합니다. `포트아웃` 규격을
맞춘 어뎁터이며, **application 에 종속적입니다.**
### 자동화 스캐폴딩 (scaffolding) 도구 소개
위 패키지 구조와 인터페이스 및 구현체를 일일이 타이핑하며 생성할 필요는 없습니다. [BASC](https://code.etribe.co.kr/core-architect/basc) 스캐폴팅 도구가 자동생성
해줍니다.
### Best Practices
코드 작성 규칙에 맞게 구현된 가장 좋은 예는 관리자의 **예제 게시판**입니다. 새로운 버전에 맞춰 모든 코드들이 재작성되었고 아래 고민들에 대한 해법이 녹아있습니다.
1. 패키지 구조 및 클래스 명칭을 어떻게 잡아야 할까?
2. 브라우저 history 를 잘 유지하면서 back 버튼 이슈를 발생시키지 않는 구현방식은 무엇일까?
3. form submit 과 ajax 호출. 어떤 방식이 더 유용할까?
4. 사용자 입력값을 검증하고 문제점을 표현하는 가장 좋은 방법은?
5. 어떻게 restfull 한 서비스를 구현할 수 있을까? (GET/POST/PUT/PATCH/DELETE)
6. 새로운 파일 업로드 방식.
## PACKAGING
배포방식 설정을 위해 두가지 maven 프로파일을 제공한다.
* `jar` (default)
* `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
```