트러블 슈팅

Category 테이블 관리 전략

문제

ERD 설계 단계에서 Enum Category 를 엔티티화 하여 따로 Category 테이블로 분리하여 관리하기로 결정. (룩업 테이블)

• 룩업 테이블 이란?
  • 미리 정의된 값들을 테이블로 분리하여 관리하는 방식
  • 각 엔티티에서 참조하여 사용하는 정적 데이터
  • Enum으로 관리하던 것을 DB 테이블에 저장함으로써 유연하게 관리하고, 연관관게 설정 용이해짐
    
    

• 변동이 가능성 있음
• 미리 정의된 값들
• 자주 참조함

➡️상수처럼 사용할 것이므로 미리 초기값을 세팅하여 넣어줄 필요가 있음.

그렇다면 초기화는 어떻게, 어디서 해줄 것인가?

해결

1️⃣DB 초기화 단계에 sql 문 넣기

• 코드 변경 없이(중간에 어플리케이션 실행 중단 없이) DB 삽입 만으로 추가 가능
• enum과 코드 불일치 가능성

2️⃣✅어플리케이션 실행 시점에 초기화하도록 코드에 작성

2번 방식을 선택

• Enum 값이 코드에 정의되어 있으므로 관리 용이
• 클라이언트 요청 시, 값 검증 편리 (DB 조회 없이)
• 코드 내에서도 상수처럼 직관적으로 사용 가능
  
  

초기화 방법

@PostConstruct 어노테이션을 사용하여 초기화

@PostConstruct 어노테이션

• 해당 어노테이션이 붙은 메소드는 스프링 빈 초기화 직후 자동으로 호출
• 어플리케이션 실행 시 단 한번만 호출됨 --> 초기화용 메소드에 적절
• 단, 실제 배포 환경에서는 사용이 제한적일 수 있으므로, 실행 환경에 따라 실행 여부를 결정하려면 @Profile 어노테이션으로 개발 환경에 맞는 application.properties 파일 설정을 할 필요가 있음.

➡️@Component+@PreConstuct 조합하여 CategoryInitializer 컴포넌트 생성

@Component
@RequiredArgsConstructor
class CategoryInitializer {

  private final PostCategoryRepository postCategoryRepository;

  // 스프링 어플리케이션 실행 시 단 한번 실행하여 카테고리 DB에 초기값 생성
  @PostConstruct
  public void initCategories() {
    if(postCategoryRepository.count() == 0) {
      for(CategoryType type:CategoryType.values()) {
        // 중복 저장이 아니라면
        if(!postCategoryRepository.existsByCategoryType(type)) {
          postCategoryRepository.save(new Category(type));
        }
      }
    }
  }
}

결론

• 기존 enum보다 높은 확장성과 유연성
• 코드 내부에서도 값 검증, 상수값으로 사용하기 용이
• 값 추가 필요하여도 enum에 추가하면 자동으로 DB에도 반영됨 (어플리케이션 실행 중단 필요)
• DB와 코드 불일치 문제 해결

---

Enum의 엔티티화

Enum만 사용할 때 vs Entity로 사용할 때

기능	Enum만 사용	Entity 사용
DB에서 JOIN	❌ 안 됨	✅ 가능
Category 이름 외의 부가 정보 사용 (e.g. displayName)	❌ 불가	✅ 가능
Category 통계 쿼리 (e.g. GROUP BY)	❌ 어렵고 비효율적	✅ 깔끔하게 가능
Category ID로 참조 (Foreign Key)	❌ 불가	✅ 가능
JPA 관계 (FK 매핑)	❌ 없음	✅ @ManyToOne 등으로 매핑 가능
추후 카테고리 확장성 (e.g. 카테고리 설명 추가 등)	❌ 어렵거나 Enum 변경 필요	✅ 유연하게 컬럼 추가 가능

✅데이터 간 관계가(연관 관계) 필요하거나 확장이 예상되면 Entity로 관리하는 것이 훨씬 유리

ERD 설계

피드백

• 여러개면 복수 s 붙여주기
• is_deleted --> deleted_at (NULL/Timestamp)으로 변경
  • 언제 탈퇴했는지, 더 많은 정보를 표현할 수 있음
• 게시글/댓글 좋아요: id 는 사실상 쓰는 곳이 없으니 복합키(사용자, 댓글 식별자)로 사용하는 걸 추천
• 복합키(사용자, 댓글 식별자)를 기준으로 조회하는 일이 많을 텐데 그걸로 하면 조회 성능이 더 좋을 것.

API 설계

• path variable은 보통 식별자가 될 수 있는 유니크값으로 사용
• 성공 메세지는 크게 의미가 없다면 보내지 않아도 된다. 에러 메세지가 더 중요
• 사용자 조회 시 유저 네임보다는 자동생성 ID (PK) 기반으로 리소스 조회하는게 더 좋을 것 같다.
  • 리소스 식별 명확함
  • 신뢰성 있음
• PK 기반 조회가 DB 성능 측면에서도 더 빠름
  
  

Github Branch 전략

• 이슈 번호 기반 브랜치 관리
  • 추적 및 구분 편리
• PR은 최소 2명 승인, 리뷰어는 팀원 중 그때그때 시간 나는 사람

List ➡️ String Converter

@Entity
public class Post extends BaseEntity{
  ...

  private List<String> imgUrls;
}

• List와 같은 컨테이너 타입은 그대로 JPA에 저장이 되지 않는다.
• 따라서 ListToStringConverter를 통해 String으로 변환 후 저장해야함.

@Converter
public class StringListConverter implements AttributeConverter<List<String>, String> {
    private final ObjectMapper mapper = new ObjectMapper();

    @Override
    public String convertToDatabaseColumn(List<String> dataList) {
        try {
            return mapper.writeValueAsString(dataList);
        } catch (JsonProcessingException e) {
            throw new RuntimeException(e);
        }
    }

    @Override
    public List<String> convertToEntityAttribute(String data) {
        try {
            return mapper.readValue(data, List.class);
        } catch (JsonProcessingException e) {
            throw new RuntimeException(e);
        }
    }
}

convertToDatabaseColumn : List를 DB에 저장될 수 있도록 String으로 변환.

• 예시) List.of("a", "b", "c") → "["a","b","c"]"

convertToEntityAttribute : DB에 저장된 String을 List으로 변환.

• 예시) "["a","b","c"]" → List.of("a", "b", "c")

@Convert(converter = StringListConverter.class)
  private List<String> imgUrls; // 이미지 URLs

• Converter 작성 후 적용할 엔티티의 리스트 필드에 @Convert 어노테이션과 converter를 지정해주면 DB에 의도한대로 저장된다.
  
  
  

JPA enum 저장방법

@Column(nullable = false)
@Enumerated(EnumType.STRING)
private Visibility visibility;

@Enumberated 어노테이션을 사용하여 enum 타입을 어떻게 DB에 저장할 지 지정할 수 있다.

• EnumType.STRING : enum의 이름(string)으로 저장.
  • Enum WEATHER {SUNNY, CLOUDY, RAINY, STORMY}
  • 저장값: "SUNNY", "CLOUDY", "RAINY", "STORMY"

• EnumType.ORDINAL : enum의 순서값(int)으로 저장.
  • Enum WEATHER {SUNNY, CLOUDY, RAINY, STORMY}
  • 저장값: SUNNY → 0, CLOUDY → 1, RAINY → 2, STORMY → 3

어떤 값인지, 어떤 상태를 의미하는지 파악하기 쉽도록 EnumType.STRING을 사용하여 저장하도록 하였다.

Enum validation 어노테이션

Java에서는 기본 타입들에 대한 다양한 Validation 어노테이션을 제공하지만, Enum 타입에 대해서는 기본 제공되는 Validation 어노테이션이 없다.

• 요청 바디에서 Enum 타입을 제대로 검증하지 않으면 json 매핑 시 JsonMappingException 또는 IllegalArgumentException이 발생할 수 있으므로, 적절한 Validation이 필요.

방법1️⃣

• 컨트롤러에 검증 메소드 구현

방법2️⃣

• ✅ 커스텀 validation 어노테이션
  
  

• 여러 도메인에서 Enum 값 검증이 필요할 수 있으므로 재사용 가능한 범용 어노테이션으로 구현함.

• 기존에는 DTO에서 Enum 타입으로 직접 받아 사용했지만, 파싱 오류(JsonParsingException 등) 가 발생할 수 있어 Validation 단계까지 도달하지 못하는 문제가 발생 할 수 있음.

• 이를 해결하기 위해, 요청은 String으로 받고, 검증 후 Entity 변환 시 Enum으로 매핑하는 구조로 변경함.
  
  
  

@ValidEnum

@Target({ElementType.FIELD, ElementType.PARAMETER}) // 검증 대상 (필드, 파라미터)
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = {EnumValidator.class, EnumListValidator.class})    // 검증 구현체
public @interface ValidEnum {
  String message() default "지원하는 값은 [{enumValues}] 입니다.";

  Class<?>[] groups() default {};     // 유효성 검사 적용 대상 구분할 때 사용

  Class<? extends Payload>[] payload() default {};

  Class<? extends Enum<?>> target();    // 검증 대상 enum 설정

  boolean ignoreCase() default true;    // 대소문자 무시 여부
}

• 커스텀 어노테이션
• @Target : 적용 대상 지정 (필드, 파라미터)
• @Constraint : 해당 어노테이션의 유효성 검사 로직을 구현한 클래스를 명시 (ConstraintValidator<어노테이션, 타입> 구현체)
  
  
  

EnumValidator

public class EnumValidator implements ConstraintValidator<ValidEnum, String> {
  private Set<String> allowedValues;    // enum 내 유효값
  private String messageTemplate;

  // 검증 실행 시 처음 한번만 실행
  // parameter : 어노테이션으로 들어오는 메타정보
  @Override
  public void initialize(ValidEnum constraintAnnotation) {
    Enum<?>[] enumValues = constraintAnnotation.target().getEnumConstants();  // enum 내 정의된 상수 목록 가져오기
    allowedValues = Arrays.stream(enumValues).map(Enum::name).collect(Collectors.toSet());
    messageTemplate = convertMessageTemplate(constraintAnnotation.message());
  }

  // 단일 Enum 유효값 검증 메소드
  @Override
  public boolean isValid(String value, ConstraintValidatorContext constraintValidatorContext) {
    if(value == null) {
      return true;
    }
    String convertedValue = checkIgnoreCase(value);  // 대소문자 무시

    // 유효값 검증
    if(allowedValues.contains(convertedValue)) {
      return true;
    }
    // 커스텀 메세지
    constraintValidatorContext.disableDefaultConstraintViolation();
    constraintValidatorContext.buildConstraintViolationWithTemplate(messageTemplate)
        .addConstraintViolation();
    return false;
  }

  // 대소문자 무시
  private String checkIgnoreCase(String value) {
    return value.toUpperCase();
  }

  // 커스텀 메시지
  private String convertMessageTemplate(String message) {
    return message.replace("{enumValues}", String.join(" | ", allowedValues));
  }
}

• 단일 String 필드에 대하여 검증 수행
• initialize : 필드값 초기화
• isValid : 검증 수행 메소드
• checkIgnoreCase : 선택. 대소문자를 무시하는 메소드.
• convertMessageTemplate : 선택. 커스텀 메세지 출력 메소드.

적용

@ValidEnum(target = Visibility.class)
private final String visibility;

적용 대상 필드나 파라미터에 어노테이션을 붙여 검증을 수행한다.

RESTful API 설계

• 친구 삭제 API 의 HTTP 메소드 Method를 PATCH➡️DELETE로 변경하였다.
• 내부 로직으로는 친구 관계를 삭제하는 것이 아닌, 친구 요청 상태를 변경하는 것이므로 PATCH르 사용하였음.
• 그러나 내부 로직 보다는 비즈니스 관점에서 메소드를 정하는 것이므로, (클라이언트가 내부 동작을 알필요 없으니) DELETE로 수정하였음.
  
  
  

@RequestParam

• 요청 파라미터 중 리스트가 있을 시
• categories == null, categories.isEmpty 둘 다 사용하여 검사
• categories == null : 요청 파라미터가 아예 안 왔을 때
• categories.isEmpty : 빈 값으로 왔을 때

예시

• /posts : null
• /posts?categories= : 빈 리스트 ([])
  
  
  

게시글-카테고리 연관관계 설계 변경

• 기존에는는 게시글(Post)과 카테고리(Category) 사이를 1:N 단방향 연관 관계로 매핑했으나, 테스트 중 게시글을 여러 개 생성할 수 없는 문제가 발생.

• 이는 관계 설정의 한계로, 예를 들어 팀과 멤버 관계처럼:

  • 멤버가 하나의 팀에만 속한다면 1:N으로 충분하지만,
  • 멤버가 여러 팀에 소속될 수 있다면 N:M 로 연관관계로 설정해야 함.

• 게시글-카테고리도 이와 마찬가지로
  • 하나의 게시글이 여러 카테고리를 가질 수 있고
  • 하나의 카테고리가 여러개의 게시글에 소속될 수 있으므로 @ManyToMany로 변경하여 해결.

그러나 여전히 현업에선 @ManyToMany는 잘 사용하지 않는다.

@ManyToMany의 문제점

• 조인 테이블 활용 불가
  • JPA에서 @ManyToMany 어노테이션으로 조인 테이블을 자동으로 생성
  • 그러나 추후 기능 확장 시 조인 테이블을 활용하여 추가 정보를 넣거나 비즈니스 로직을 적용할 때 확장성이 떨어진다는 단점 존재
• 성능 이슈
  • 자동으로 조인이 연쇄적으로 발생하므로 데이터베이스의 성능 저하

• 따라서, @OneToMany, @ManyToOne으로 풀어내고 조인 테이블을 엔티티로 승격하는 방식으로 처리하는 것을 권장.
• 추후 프로젝트에서는 이 방법을 적용해야겠다.
  
  
  

@Query 사용

public interface PostRepository extends JpaRepository<Post, Long> {
    // 모든 전체 공개 게시글을 생성일 순으로 조회
    List<Post> findAllByVisibilityOrderByCreatedAtDesc(Visibility visibility);

    // 모든 친구 공개 게시글을 생성일 순으로 조회
    List<Post> findAllByVisibilityAndUserInOrderByCreatedAtDesc(Visibility visibility, List<User> friends);

    // 사용자의 모든 전체 공개 게시글을 생성일 순으로 조회
    List<Post> findAllByUserAndVisibilityOrderByCreatedAtDesc(User user, Visibility visibility);

    // 유저의 모든 게시글을 생성일 순으로 조회
    List<Post> findAllByUserOrderByCreatedAtDesc(User user);

    // 공개 범위와 카테고리 별로 조회
    List<Post> findAllByVisibilityAndCategoryIdsIn(Visibility visibility, List<Category> categoryList);

}

• 검색 조건이 복잡해지다보니 JPA 메소드 명도 길어져서 오히려 가독성이 저하됨.

• @Query 어노테이션으로 직접 쿼리문을 작성하는 방식으로 변경.

// 모든 전체 공개 게시글을 생성일 순으로 조회
    @Query("SELECT p FROM Post p WHERE p.visibility = :visibility ORDER BY p.createdAt DESC")
    List<Post> findAllByVisibilityOrderByCreatedAtDesc(@Param("visibility") Visibility visibility);

• 쿼리문에 파라미터로 사용 시 @Param("파라미터명") 달아줘야하고 쓸 때는 :파라미터명 이렇게 넣어줘야 함.
  
  
  

연관관계 변경 시 주의점

• @OneToMany에서 @ManyToMany로 변경 후 DB에서 카테고리 값을 제대로 조회할 수 없는 문제 발생.
• FetchType.LAZY 로 설정한 문제인지, 다양한 원인을 찾아봤으나 결국
• 중간에 연관관계를 변경된 것이 DB에 제대로 반영이 안된 것이 문제였다.
• ddl-auto: create 설정으로 매 실행 시 DB를 새로 생성하도록 했지만, 다른 설정 또는 캐시 등으로 인해 변경이 정상적으로 적용되지 않았던 것으로 추정.
• 연관관계를 변경한 경우에는 기존 DB를 삭제하고 애플리케이션을 다시 실행하는 것이 안전하다.
  
  
  

참고

@PostConstruct

• https://jjangadadcodingdiary.tistory.com/entry/Spring-PostConstruct-%EC%96%B4%EB%85%B8%ED%85%8C%EC%9D%B4%EC%85%98%EC%9D%84-%ED%99%9C%EC%9A%A9%ED%95%9C-%EC%B4%88%EA%B8%B0%ED%99%94-%EB%A9%94%EC%84%9C%EB%93%9C-%EC%8B%A4%ED%96%89

ListToStringConverter

• https://khdscor.tistory.com/39

ManyToMany 주의점

• https://peace-developer.tistory.com/21