이 파일은 Claude Code가 solid-connect-server 저장소에서 작업할 때 참고하는 가이드입니다.
해당 지시문서가 위치한 폴더에 CLAUDE.local.md 문서 파일이 있다면 해당 파일을 읽어 Claude Code 개인 지침을 확인하세요.
Solid Connect Server는 교환학생 준비생을 위해 대학 정보, 멘토 매칭, 모의지원 기능 등을 제공하는 교환학생 지원 통합 플랫폼입니다.
- 언어: Java 21
- 프레임워크: Spring Boot 3.5.11
- 빌드 도구: Gradle
- 데이터베이스: MySQL (주), Redis (캐싱)
- 마이그레이션: Flyway
# 전체 빌드
./gradlew build
# 테스트 실행
./gradlew test
# 특정 테스트만 실행
./gradlew test --tests ChatServiceTest
# 애플리케이션 실행
./gradlew bootRun
# 로컬 개발 환경 시작 (MySQL, Redis)
docker-compose -f docker-compose.local.yml up -d# 로컬 개발 환경
./gradlew bootRun --args='--spring.profiles.active=local'
# 개발 환경
./gradlew bootRun --args='--spring.profiles.active=dev'
# 운영 환경
./gradlew bootRun --args='--spring.profiles.active=prod'solid-connect-server/
├── src/
│ ├── main/
│ │ ├── java/com/example/solidconnection/
│ │ │ ├── [domain]/ # 도메인별 폴더
│ │ │ │ ├── controller/ # REST API 엔드포인트
│ │ │ │ ├── service/ # 비즈니스 로직
│ │ │ │ ├── domain/ # JPA Entity
│ │ │ │ ├── repository/ # 데이터 접근 계층
│ │ │ │ └── dto/ # DTO (Request/Response)
│ │ │ └── common/ # 공통 기능
│ │ │ ├── exception/ # 커스텀 예외
│ │ │ ├── config/ # Spring 설정
│ │ │ └── util/ # 유틸리티
│ │ └── resources/
│ │ ├── db/migration/ # Flyway 마이그레이션
│ │ └── application*.yml # 설정 파일
│ └── test/
│ └── java/com/example/solidconnection/
│ ├── [domain]/fixture/ # 테스트 Fixture
│ ├── [domain]/service/ # 서비스 테스트
│ ├── support/ # 테스트 설정
│ └── ...
├── docker-compose.local.yml # 로컬 컨테이너
├── docker-compose.dev.yml # 개발 컨테이너
├── docker-compose.prod.yml # 운영 컨테이너
├── Dockerfile # 이미지 빌드
├── build.gradle # Gradle 설정
각 계층은 자신의 바로 아래 계층만 참조할 수 있습니다.
Controller → Service → Repository/Domain
각 계층의 역할:
- Controller: HTTP 요청 처리, 입력값 검증, 응답 포맷팅
- Service: 비즈니스 로직 처리, DTO 변환, 트랜잭션 관리
- Repository: 데이터 접근 계층, DB 쿼리 작성
- Domain (Entity): JPA 엔티티, 도메인 모델
주요 규칙:
- ✅ 역계층 참조 금지 (예: Repository에서 Service 참조 불가)
- ✅ Service는 Repository를 주입받아 사용
- ✅ Controller는 Service를 주입받아 사용
- ✅ Entity는 도메인 로직만 포함
- ✅ DTO는 요청/응답 시에만 사용
[domain]/
├── controller/ # REST API 엔드포인트
├── service/ # 비즈니스 로직 (Service)
├── domain/ # JPA Entity
├── repository/ # 데이터 접근 계층 (Repository)
└── dto/ # DTO (Request/Response)
프로젝트의 개발 컨벤션을 따릅니다: 개발-컨벤션-정리
주요 규칙:
- 클래스 선언 전 줄바꿈: 클래스 정의 앞에 빈 줄 필수
- 파일 끝 줄바꿈: 모든 파일은 개행 문자로 종료
- 와일드카드 import 금지: 명시적 import만 사용
- 파라미터 줄바꿈: Controller는 필수, 3개 이상의 파라미터가 있으면 줄바꿈
- private 메서드 위치: 호출하는 public 메서드 바로 아래 위치
- 원시 타입 사용: null이 아닌 값은
int,long등 원시 타입 사용, nullable은 Wrapper 사용 - JPA @Column: Entity의 모든 필드에
@Column속성과 필드명 지정
// DTO 변환
// 다중 파라미터: of() 메서드
public static UserDto of(User user, Profile profile) { ...}
// 단일 파라미터: from() 메서드
public static UserDto from(User user) { ...}
// API 요청/응답
// XXXRequest, XXXResponse 형식
public class UserCreateRequest { ...
}
public class UserCreateResponse { ...
}
// REST API 엔드포인트
// kebab-case 사용
@GetMapping("/user-profile") // O
@GetMapping("/userProfile") // X- Spring Boot 3.5.11: 스프링 부트
- Spring Security: JWT 기반 인증
- Spring Data JPA: ORM
- QueryDSL: 동적 쿼리 생성
- MySQL: 주 데이터베이스
- Redis: 캐싱 저장소
- Flyway: 데이터베이스 버전 관리
- Spring Boot Actuator: 애플리케이션 모니터링
- Prometheus: 메트릭 수집
- Sentry: 에러 추적
- JWT: JWT 토큰 관리
- Lombok: 보일러플레이트 코드 감소
- AWS S3 SDK: 파일 저장소
- WebSocket: 실시간 통신
- TestContainers: 통합 테스트용 컨테이너
테스트 작성 시 /test skill을 참고하세요. (테스트 관련 작업 시 자동으로 로드됩니다)
@TestContainerSpringBootTest기반 통합 테스트- FixtureBuilder + Fixture 패턴으로 테스트 데이터 생성
- 한국어 메서드명, Given-When-Then 구조, @Nested 그룹화
<type>: <description>
[optional body]
feat: 새로운 기능 추가
fix: 버그 수정
refactor: 코드 리팩토링 (기능 변경 없음)
docs: 문서 변경
test: 테스트 추가/수정
chore: 빌드 설정, 패키지 관리
perf: 성능 개선
# 기능 추가
feat: 대학 검색 기능 추가
# 버그 수정
fix: 채팅방 조회 시 정렬 버그 수정
# 리팩토링
refactor: ChatService 메서드 분리
# 테스트 추가
test: ChatService 테스트 케이스 추가
# 브랜치명
refactor/529-shortening-cd-time모든 DB 스키마 변경사항은 Flyway로 관리합니다.
위치: src/main/resources/db/migration/
파일명 형식: V{VERSION}__{DESCRIPTION}.sql
V1__init_schema.sql
V2__add_chat_table.sql
V3__add_user_role_column.sql
V{next_version}__{description}.sql파일 생성- SQL 작성
./gradlew build시 자동 검증 (flywayValidate)
주의: 한 번 배포된 마이그레이션은 수정 불가 (새 버전으로 생성)
@Entity
@Table(name = "chat_room")
public class ChatRoom {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
@Column(name = "id")
private Long id;
@Column(name = "is_group", nullable = false)
private boolean isGroup;
@Column(name = "mentoring_id", nullable = true)
private Long mentoringId;
}규칙:
@Column필수 (모든 필드)- 필드명과 DB 컬럼명 일치
- nullable 명시
public interface ChatRoomRepository extends JpaRepository<ChatRoom, Long> {
Optional<ChatRoom> findByMentoringId(Long mentoringId);
List<ChatRoom> findByIsGroup(boolean isGroup);
}| 파일/폴더 | 설명 |
|---|---|
src/main/java/com/example/solidconnection/ |
메인 소스 코드 |
src/test/java/com/example/solidconnection/ |
테스트 코드 |
src/main/resources/db/migration/ |
Flyway 마이그레이션 |
src/main/resources/application.yml |
공통 설정 |
docker-compose.*.yml |
환경별 도커 설정 |
build.gradle |
Gradle 빌드 설정 |
- local: Development with embedded Tomcat
- dev: Development server (stage.solid-connection.com)
- prod: Production server (solid-connection.com)
- Entity 생성 (
src/main/java/.../domain/) - Repository 작성 (
src/main/java/.../repository/) - Service 구현 (
src/main/java/.../service/) - Controller 작성 (
src/main/java/.../controller/) - DTO 정의 (
src/main/java/.../dto/) - Flyway 마이그레이션 작성
- 테스트 코드 작성
- FixtureBuilder 생성 (필요시)
- Fixture 편의 메서드 추가 (필요시)
- 테스트 클래스 작성 (
*Test.java) - @Nested로 테스트 그룹화
- Given-When-Then 구조로 작성
./gradlew test실행
V{next}__{description}.sql파일 생성- 마이그레이션 SQL 작성
- Entity 업데이트 (필요시)
- 테스트 실행
- 개발 컨벤션: https://github.com/solid-connection/solid-connect-server/wiki/개발-컨벤션-정리
- 테스트 가이드:
test.md파일 참고 - Spring Boot: https://spring.io/projects/spring-boot
- JPA: https://spring.io/projects/spring-data-jpa
- TestContainers: https://www.testcontainers.org/
- Flyway: https://flywaydb.org/
- Flyway 마이그레이션은 되돌릴 수 없음 - 신중하게 작성
- QueryDSL Q클래스는 자동 생성 - 수동 수정 금지
- 테스트는 독립적 - 테스트 간 데이터 공유 불가
- 환경별 설정 분리 - application-local.yml, application-dev.yml, application-prod.yml
- 한국어 메서드명 - 테스트 가독성 향상을 위해 사용