api2/CLAUDE.md

CLAUDE.md - alist API 프로젝트

프로젝트 개요

• 프로젝트명: alist API
• 그룹: com.alist
• 포트: 8106
• 빌드 결과물: api.jar

기술 스택

• Java: 21
• Framework: Spring Boot 3.5.10
• 빌드 도구: Gradle
• DB: MariaDB
• ORM: MyBatis (mapper XML: classpath:mapper/**/*.xml)
• 인증: JWT (jjwt 0.11.5) + Spring Security
• API 문서: Swagger (springdoc-openapi 2.6.0)
• 기타: Lombok, Validation, Actuator, log4jdbc

패키지 구조

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

프로파일

프로파일	설명
local	로컬 개발 환경
pjt	프로젝트(운영) 환경

보안 구조

• Swagger: /v3/api-docs/**, /swagger-ui/** → HTTP Basic 인증 (InMemory)
• API: JWT Bearer 토큰 인증 (Stateless)
• 공개 경로: /, /actuator/health, /auth/**, /api/user/signup

빌드 및 실행

# 빌드
./gradlew bootJar

# 로컬 실행
./gradlew bootRun --args='--spring.profiles.active=local'

# JAR 실행
java -jar build/libs/api.jar --spring.profiles.active=local

Swagger 접속

• URL: http://localhost:8106/swagger-ui.html
• 인증: swagger.login.id / swagger.login.password (환경별 yaml에 설정)

코드 작성 규칙

• 응답은 ApiResponse<T> 래퍼 사용
• 응답 코드는 ApiResponseCode enum 사용
• MyBatis Mapper XML은 src/main/resources/mapper/ 하위에 작성
• 카멜케이스 자동 변환 활성화 (map-underscore-to-camel-case: true)
• 새 모듈은 modules/{도메인}/ 하위에 Controller, Service, Mapper, DTO 구성

CI/CD

• Jenkins: Jenkinsfile.pjt
• Docker: Dockerfile
• 배포 스크립트: deploy/ 디렉토리