네이밍 컨벤션 - KimGyuBek/Threadly GitHub Wiki

네이밍 컨벤션

개요

Threadly 프로젝트 전체에 일관된 네이밍 규칙을 정의하여 협업 효율과 유지보수를 높이는것을 목표로 한다.

목차

핵심 원칙

  1. 일관성: 모든 프로젝트에서 동일한 규칙 적용
  2. 명확성: 클래스 이름만으로 역할과 책임을 파악 가능
  3. 아키텍처 반영: CQRS와 Hexagonal Architecture 패턴 준수
  4. 타입 안전성: 적절한 suffix로 타입 구분 (Entity, Dto, Command, Query 등)

1. 패키지 구조

1.1 패키지 네이밍

패키지 경로 예시:

  • 도메인: com.threadly.core.domain.post
  • In Port: com.threadly.core.port.post.in.command
  • Out Port: com.threadly.core.port.post.out
  • 서비스: com.threadly.core.service.post
  • Adapter: com.threadly.adapter.persistence.post

2. 클래스 네이밍

2.1 도메인 모델

규칙: 순수한 명사, suffix 없음

예시

Post.java                  // 게시글 도메인
PostComment.java          // 게시글 댓글 도메인
Notification.java         // 알림 도메인

2.2 엔티티

규칙: [도메인]Entity (JPA), [도메인]Doc (MongoDB)

예시

PostEntity.java           // 게시글 엔티티
PostCommentEntity.java    // 게시글 댓글 엔티티
UserEntity.java           // 사용자 엔티티
NotificationDoc.java      // 알림 문서 (MongoDB)

Base 엔티티 클래스: 예시

BaseEntity.java           // 공통 필드 (createdAt, modifiedAt)
BaseImageEntity.java      // 이미지 공통 필드

2.3 레파지토리

규칙: [도메인][기술]Repository / [도메인]CustomRepository

예시

PostJpaRepository.java
PostLikeJpaRepository.java
NotificationMongoRepository.java
NotificationCustomRepository.java

2.4 서비스

Port.in.*UseCase의 구현체

규칙: [도메인][Command/Query]Service

CQRS 패턴을 따라 Command(쓰기)와 Query(읽기)를 분리한다.

참고: CQRS 설계 문서

예시

// Command Service (쓰기)
PostCommandService.java
FollowCommandService.java
NotificationCommandService.java

// Query Service (읽기)
PostQueryService.java
UserQueryService.java
NotificationQueryService.java

2.5 컨트롤러

규칙: [도메인]Controller

예시

PostController.java
PostCommentController.java
PostLikeController.java
NotificationController.java

2.6 UseCase (Port - In)

CQRS 패턴을 따라 Command(쓰기)와 Query(읽기)를 분리한다.

참고: CQRS 설계 문서

규칙: [도메인][Command/Query]UseCase

예시

PostCommandUseCase.java
PostQueryUseCase.java
FollowCommandUseCase.java

2.7 Port (Port - Out)

CQRS 패턴을 따라 Command(쓰기)와 Query(읽기)를 분리한다.

참고: CQRS 설계 문서

규칙: [도메인][Command/Query]Port

예시

PostCommandPort.java
NotificationCommandPort.java

2.8 어댑터

Port.out.*Port의 구현체

규칙: [도메인][기술]Adapter

예시

PostPersistenceAdapter.java
LocalImageUploadAdapter.java

2.9 매퍼

규칙: [도메인]Mapper

예시

PostMapper.java
NotificationMapper.java

메서드 네이밍:

  • toDomain(): Entity/Doc → Domain
  • toEntity(): Domain → Entity
  • to[TargetType](): 특정 타입으로 변환

2.10 DTO 및 커맨드/쿼리

API Request (Controller Layer)

규칙: [Action][도메인]Request

예시

CreatePostRequest.java
CreatePostCommentRequest.java

Command (Use Case Layer)

규칙: [Action][도메인]Command

예시

CreatePostCommand.java
LikePostCommand.java

Query (Use Case Layer)

규칙: Get[Domain/Info]Query

예시

GetPostQuery.java
GetNotificationsQuery.java

API Response (API Layer)

규칙: [Action][도메인]ApiResponse

예시

CreatePostApiResponse.java
GetNotificationDetailsApiResponse.java

Projection (Query Results)

규칙: [도메인][목적]Projection

예시

PostDetailProjection.java
PostEngagementProjection.java

2.11 예외

도메인 예외

규칙: Cannot[Action][도메인]Exception

예시

CannotLikePostException.java
CannotFollowUserException.java

애플리케이션 예외

규칙: [도메인]Exception

예시

PostException.java
TokenException.java

2.12 Configuration

규칙: [기술/목적]Config

예시

KafkaConfig.java
JpaAuditConfig.java
SecurityConfig.java
WebSocketConfig.java
RedisConfig.java

2.13 Properties

규칙: [목적]Properties

TtlProperties.java        // Time To Live 설정
UploadProperties.java     // 업로드 설정
RetentionProperties.java  // 보관 기간 설정

2.14 Enum

규칙: [도메인][Property]Type 또는 [도메인]Status

예시

// *Status 
UserStatus.java
PostStatus.java
FollowStatus.java

//*Type 
UserRoleType.java
NotificationType.java     
MailType.java

2.15 Consumer Listener

규칙: [도메인]Consumer 또는 [도메인][목적]Listener

예시

NotificationConsumer.java
NotificationEventListener.java
PostCascadeCleanupListener.java

2.16 Validator 및 Handler

규칙: [도메인][목적]Validator 또는 [도메인][목적]Handler

Validator:

예시

ImageUploadValidator.java
UserStatusValidator.java

Handler:

예시

GlobalExceptionHandler.java
KafkaErrorHandler.java

3. 변수 네이밍

3.1 일반 변수

camelCase 사용

예시

userId
    postId
createdAt
    likeCount

3.2 상수

UPPER_SNAKE_CASE 사용

예시

ACTIVE_POST_ID
    MAX_UPLOAD_SIZE
DEFAULT_PAGE_SIZE

3.3 Boolean 변수

규칙: is[형용사]

예시

isRead
    isLiked
isDeleted
    isPublic

4. 테스트 네이밍

4.1 테스트 클래스

단위 테스트:

규칙: [테스트 대상 클래스명]Test

예시

PostTest.java
PostCommandServiceTest.java
PostPersistenceAdapterTest.java

통합 테스트 (API): 규칙:: [행위][도메인]ApiTest

예시

LikePostApiTest.java
CreatePostCommentApiTest.java
MarkAsReadNotificationApiTest.java
DeleteAllNotificationsApiTest.java

4.2 테스트 메서드

규칙: [메서드 명]_should[기대]_when[조건]()

예시


@Test
void likePost_shouldReturnCreated_whenUserLikesActivePost() {
}

@Test
void likePost_shouldBeIdempotent_whenUserLikesSamePostMultipleTimes() {
}

@Test
void likePost_shouldReturnBadRequest_whenPostDeleted() {
}

@Test
void createComment_shouldReturnCreated_whenUserCommentsOnActivePost() {
}

4.3 테스트 픽스처

규칙: [도메인]FixtureDto

예시

PostFixtureDto.java
PostFixtureMapper.java

5. 파일 및 디렉토리 네이밍

5.1 디렉토리

  • 모두 소문자
  • kebab-case사용

예시

adapter-persistence/
adapter-kafka/
app-api/
app-batch/
core-domain/

5.2 테스트 리소스

규칙: /fixtures/[도메인]/[feature]/[file].json

예시

/fixtures/posts/likes/like-post/user.json
/fixtures/users/profiles/active-user.json

관련 문서