155 lines
4.1 KiB
Markdown
155 lines
4.1 KiB
Markdown
# alist API
|
|
|
|
Spring Boot 기반의 RESTful API 서버
|
|
|
|
## 프로젝트 정보
|
|
|
|
- **그룹**: com.alist
|
|
- **포트**: 8106
|
|
- **빌드 결과물**: `api.jar`
|
|
- **GitLab**: https://gitlab.pjt.kr/alist/api
|
|
|
|
## 기술 스택
|
|
|
|
- **Java**: 21
|
|
- **Framework**: Spring Boot 3.5.10
|
|
- **빌드 도구**: Gradle
|
|
- **데이터베이스**: MariaDB
|
|
- **ORM**: MyBatis
|
|
- **인증**: JWT (jjwt 0.11.5) + Spring Security
|
|
- **API 문서**: Swagger (springdoc-openapi 2.6.0)
|
|
- **기타**: Lombok, Validation, Actuator, log4jdbc
|
|
|
|
## 주요 기능
|
|
|
|
- JWT 기반 인증/인가
|
|
- MyBatis XML Mapper를 통한 데이터 액세스
|
|
- 표준화된 API 응답 (`ApiResponse<T>`)
|
|
- Swagger API 문서 (HTTP Basic 인증)
|
|
- 파일 업로드/다운로드
|
|
- Actuator 헬스 체크
|
|
|
|
## 빌드 및 실행
|
|
|
|
### 빌드
|
|
```bash
|
|
./gradlew bootJar
|
|
```
|
|
|
|
### 로컬 실행
|
|
```bash
|
|
./gradlew bootRun --args='--spring.profiles.active=local'
|
|
```
|
|
|
|
### JAR 실행
|
|
```bash
|
|
java -jar build/libs/api.jar --spring.profiles.active=local
|
|
```
|
|
|
|
## 환경 설정
|
|
|
|
### 프로파일
|
|
|
|
| 프로파일 | 설명 | 설정 파일 |
|
|
|---------|------|----------|
|
|
| `local` | 로컬 개발 환경 | `application-local.yml` |
|
|
| `pjt` | 프로젝트(개발) 환경 | `application-pjt.yml` |
|
|
|
|
### 환경별 접속 정보
|
|
|
|
#### 로컬 (local)
|
|
- **API**: http://localhost:8106
|
|
- **Swagger**: http://localhost:8106/swagger-ui.html
|
|
|
|
#### 개발 서버 (pjt)
|
|
- **API**: https://api-alist.pjt.kr
|
|
- **파일**: https://file-alist.pjt.kr
|
|
- **Swagger**: https://api-alist.pjt.kr/swagger-ui/index.html
|
|
|
|
## API 문서
|
|
|
|
Swagger UI를 통해 API 문서를 확인할 수 있습니다.
|
|
|
|
- **접속**: `/swagger-ui.html`
|
|
- **인증**: HTTP Basic (환경별 yaml에 설정된 ID/PW 사용)
|
|
|
|
## 패키지 구조
|
|
|
|
```
|
|
com.alist.api
|
|
├── common
|
|
│ ├── response/ # ApiResponse, ApiResponseCode
|
|
│ └── utils/ # 공통 유틸리티
|
|
├── config
|
|
│ ├── jwt/ # JWT 필터, 핸들러, Provider
|
|
│ ├── exception/ # GlobalExceptionHandler
|
|
│ ├── properties/ # JwtProperties 등
|
|
│ ├── SecurityConfig.java
|
|
│ └── OpenApiConfig.java
|
|
└── modules
|
|
└── {도메인}/ # Controller, Service, Mapper, DTO
|
|
```
|
|
|
|
## 보안
|
|
|
|
### 인증 방식
|
|
- **Swagger**: HTTP Basic 인증 (InMemory)
|
|
- **API**: JWT Bearer 토큰 인증 (Stateless)
|
|
|
|
### 공개 경로
|
|
- `/` - 루트
|
|
- `/actuator/health` - 헬스 체크
|
|
- `/auth/**` - 인증 관련 API
|
|
- `/api/user/signup` - 회원가입
|
|
|
|
## 응답 코드
|
|
|
|
API 응답은 `ApiResponseCode` enum으로 표준화되어 있습니다.
|
|
|
|
### 주요 응답 코드
|
|
|
|
| 코드 | 메시지 | HTTP Status | 용도 |
|
|
|------|--------|-------------|------|
|
|
| `CODE_200` | 성공 | 200 OK | 일반 성공 |
|
|
| `CODE_2001` | {0} 정보 조회에 성공하였습니다. | 200 OK | 단건 조회 성공 |
|
|
| `CODE_2002` | {0} 등록 되었습니다. | 201 Created | 등록 성공 |
|
|
| `CODE_2003` | 조회된 정보가 없습니다. | 200 OK | 조회 결과 없음 |
|
|
| `CODE_2004` | 중복된 {0} 정보 입니다. | 409 Conflict | 중복 데이터 |
|
|
| `CODE_4001` | 입력값을 확인해주세요. | 400 Bad Request | Validation 오류 |
|
|
| `CODE_4003` | 필수 요청 파라미터가 누락되었습니다. | 400 Bad Request | 필수 파라미터 누락 |
|
|
|
|
## 배포
|
|
|
|
### Docker
|
|
```bash
|
|
# 이미지 빌드
|
|
docker build -t registry.pjt.kr/alist/api .
|
|
|
|
# 컨테이너 실행
|
|
docker run -d -p 8106:8106 --name alist-api registry.pjt.kr/alist/api
|
|
```
|
|
|
|
### CI/CD
|
|
- **Jenkins**: `Jenkinsfile.pjt`
|
|
- **Docker Registry**: registry.pjt.kr
|
|
- **배포 스크립트**: `deploy/` 디렉토리
|
|
|
|
## 개발 가이드
|
|
|
|
상세한 개발 가이드는 [CLAUDE.md](./CLAUDE.md)를 참고하세요.
|
|
|
|
### 코드 작성 규칙
|
|
- 응답은 `ApiResponse<T>` 래퍼 사용
|
|
- 응답 코드는 `ApiResponseCode` enum 사용
|
|
- MyBatis Mapper XML은 `src/main/resources/mapper/` 하위에 작성
|
|
- 새 모듈 추가 시: `modules/{moduleName}/` 구조로 생성
|
|
|
|
### MyBatis 규칙
|
|
- Mapper XML 위치: `src/main/resources/mapper/**/*.xml`
|
|
- 카멜케이스 자동 변환 활성화 (`map-underscore-to-camel-case: true`)
|
|
- Mapper 인터페이스와 XML의 namespace, id 일치 필수
|
|
|
|
## 라이선스
|
|
|
|
Proprietary
|