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 헬스 체크

빌드 및 실행

빌드

./gradlew bootJar

로컬 실행

./gradlew bootRun --args='--spring.profiles.active=local'

JAR 실행

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

# 이미지 빌드
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를 참고하세요.

코드 작성 규칙

• 응답은 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