트러블 슈팅

트러블 슈팅(실제 장애/버그)

1. Swagger /v3/api-docs 500(배포 환경)

• 증상: /v3/api-docs 호출 시 500 발생.
• 원인: Spring Boot(Framework)와 springdoc-openapi 버전 호환 문제로 NoSuchMethodError 발생.
• 해결: Boot 3.5.x 호환 버전으로 springdoc-openapi-starter-webmvc-ui 버전을 조정하여 해결했습니다. (2.8.5 적용)

2. 선택 입력 필드 공백("") 저장 문제

• 증상: 회원가입 시 선택 필드(department, position)에 빈 문자열("")이 저장되는 문제.
• 원인: 프론트에서 빈 문자열이 전달되고, 가입 단계에서 문자열 정규화가 부족했던 케이스.
• 해결:
  • 엔티티 생성 시 StringUtils.hasText() 기반으로 공백/빈 문자열을 null로 정규화하여 데이터 정합성을 확보했습니다.
  • (선택) 프론트에서도 미입력은 null로 전달하도록 명세를 맞췄습니다.
• 결과: 불필요한 공백 데이터가 누적되지 않아 조회/검색/필터링 시 예외 케이스가 줄었습니다.

3. N+1 문제(조회 성능 저하) 개선

• 증상: 대시보드/내 근태 조회 등 “리스트 + 연관 엔티티” 조회 API에서 요청당 쿼리 수가 과도하게 발생하여 응답이 느려지는 문제가 있었습니다.
• 원인: JPA 기본 지연로딩(LAZY) 상태에서 반복적으로 연관 엔티티에 접근하면서 N+1 쿼리가 발생했습니다.
• 해결:
  1. 문제 엔드포인트를 대상으로 쿼리 카운팅을 붙여 재현하고, 요청당 쿼리 수를 기준치로 기록했습니다.
  2. 조회 로직을 “한 번에 가져오는 방식”으로 변경했습니다. (필요한 연관 데이터를 fetch join 또는 DTO 조회로 한 번에 조회)
  3. 개선 후 동일 요청에서 쿼리 수가 기준치 대비 감소했는지 확인했습니다.
• 결과: 엔드포인트별 쿼리 수가 감소해 응답 시간이 개선되었고, 성능 회귀 여부를 숫자로 확인할 수 있게 되었습니다.