최초 커밋!

This commit is contained in:
kangsunlee
2025-05-27 16:34:20 +09:00
parent 3b8247ecd9
commit 5a66c0542b
1445 changed files with 65703 additions and 65 deletions

346
README.md
View File

@@ -1,93 +1,309 @@
# korea research
## Getting started
To make it easy for you to get started with GitLab, here's a list of recommended next steps.
Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
## Add your files
- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command:
```
cd existing_repo
git remote add origin http://code.etribe.co.kr/korea-research/korea-research.git
git branch -M main
git push -uf origin main
┬─┐┌─┐┌─┐┬ ┬┌─┐┬ ┌─┐
├┬┘├┤ │ └┬┘│ │ ├┤
┴└─└─┘└─┘ ┴ └─┘┴─┘└─┘ - 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.
```
## Integrate with your tools
## Prerequisites
- [ ] [Set up project integrations](http://code.etribe.co.kr/korea-research/korea-research/-/settings/integrations)
* JDK 17+
* Maven
## Collaborate with your team
## Structure
- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)
- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
- [ ] [Set auto-merge](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html)
recycle 은 `core` 모듈을 기반으로 한 `admin`, `front`, `api` 어플리케이션으로 구성되어 있다.
## Test and Deploy
```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
```
Use the built-in continuous integration in GitLab.
⚡ AWS S3 업로드를 이용하지 않는다면, pom.xml 에서 `aws`모듈 관련 내용을 삭제하면 된다.
⚡ `admin`, `front`, `api` 중 실제 프로젝트에서 사용할 모듈만 남기고 삭제해주세요.
- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html)
- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing (SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)
- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)
- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)
- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)
✔️ 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@#$)
# Editing this README
When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thanks to [makeareadme.com](https://www.makeareadme.com/) for this template.
## VM Options
## Suggestions for a good README
프레임워크 실행 시 필요한 자바 VM 옵션은 아래와 같다.
Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
| VM 변수 | 설명 | 설정 값 | 필수여부 |
|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|-------------------------|------|
| -Dspring.profiles.active | Spring active 프로파일 | local, dev, prod | Y |
| **-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 |
| -Dapp.initData.core | 어플리케이션 초기 구동에 필요한 필수 데이터 생성여부 | true, false | N |
| -Dspring.jpa.hibernate.ddl-auto | JPA DDL 옵션 | update, create 등등 | Y |
| -Dspring.jpa.properties.hibernate.show_sql | JPA SQL 로그 보이기 | true, false | N |
| -Dlogging.level.org.hibernate.orm.jdbc.bind | JPA 파라미터 바인딩 로그 보이기 | trace (로그보임), info(숨기기) | 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 |
## Name
Choose a self-explaining name for your project.
### VM Options 예시
#### `admin`, `front`, `api` 모두 사용가능합니다.
```
-Dspring.profiles.active=local
-Dapp.initData.core=false
-Dspring.jpa.hibernate.ddl-auto=update
-Dfile.encoding=UTF-8
-Djava.net.preferIPv4Stack=true
-Dcom.amazonaws.sdk.disableEc2Metadata=true
-Dspring.jpa.properties.hibernate.show_sql=true
-Dlogging.level.org.hibernate.orm.jdbc.bind=info
-Dserver.port=8080
-Dserver.forward-headers-strategy=native
-Dlogging.level.org.springframework.security=DEBUG
-Dspring.datasource.url=jdbc:h2:~/h2/app-h2;AUTO_SERVER=TRUE
-Dspring.datasource.username=sa
-Dspring.datasource.password=
```
## Description
Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
## JDBC 및 데이터 핸들링 구성 옵션
## Badges
On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
### JDBC 연결 설정
## Visuals
Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
스프링부트의 JDBC 설정 방식을 그대로 이용한다. JDBC 연결을 맺을 DB Vendor 와 JNDI 이용여부 등은 프로젝트 상황에 맞게 설정하면 된다.
## Installation
Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
recycle 은 `H2`를 기본으로 탑재하고 있다. `H2` 를 이용하면 로컬 개발환경에서 아래와 같은 장점을 얻는다.
## Usage
Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
* 설치 과정이 필요없다. (Maven dependency 에 기술되어 각자 환경에 이미 탑재됨)
* 가볍고 빠르며 JDBC API 를 지원하는 오픈소스이다.
* ANSI SQL 을 지원하기에 범용성이 뛰어남.
## Support
Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
```
-Dspring.datasource.url=jdbc:h2:~/h2/app-h2;AUTO_SERVER=TRUE
-Dspring.datasource.username=sa
-Dspring.datasource.password=
```
## Roadmap
If you have ideas for releases in the future, it is a good idea to list them in the README.
recycle 이 구동되면서 사용자 홈디렉토리에 밑에 /h2/app-h2.mv 파일을 생성합니다. 생성된 파일을 db 클라이언트 툴에서 접속하는 법은
이 [문서](https://javanitto.tistory.com/37) 를 참고하세요.
## Contributing
State if you are open to contributions and what your requirements are for accepting them.
⚡️ recycle 은 로컬 개발 환경에서 각자의 DB를 이용한 작업을 지향합니다. 테이블과 데이터를 마음대로 삭제/추가하며 개발할 수 있고, 개발/스테이징/운영 환경 같은 공용 공간에 필요한 정보만 커밋할
수 있기
때문입니다 : )
For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
### ddl-auto
You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
```shell
-Dspring.jpa.hibernate.ddl-auto=update # update | create | none | validate
```
## Authors and acknowledgment
Show your appreciation to those who have contributed to the project.
**JPA**가 ddl 을 다루는 방식을 정의한다. 엔티티 변경이 많은 개발 시점에는 `update`, `create`를,
엔티티 혹은 데이터가 함부로 변경되서는 안되는 운영 환경에서는 `none`, `validate` 등을 지정해준다. (
참고: [ddl-auto 옵션 설명](https://smpark1020.tistory.com/140?category=857916))
## License
For open source projects, say how it is licensed.
### show_sql
```shell
-Dspring.jpa.properties.hibernate.show_sql=true # true | false
```
JPA SQL 로그 보이기 여부
### descriptor.sql
```shell
-Dlogging.level.org.hibernate.orm.jdbc.bind=trace # trace | info | debug and etc
```
JPA 파라미터 바인딩 로그 보이기. trace 일 때 where 조건절 등 바인딩된 파라미터 정보 확인이 가능.
### 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
```
## Project status
If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.