[FEAT] 닉네임 중복 방지 API 구현 (#321)

src/main/java/com/example/RealMatch/oauth/service/AuthService.java

@@ -10,6 +10,7 @@
 import com.example.RealMatch.oauth.code.OAuthErrorCode;
 import com.example.RealMatch.oauth.dto.OAuthTokenResponse;
 import com.example.RealMatch.oauth.dto.request.SignupCompleteRequest;
+import com.example.RealMatch.user.application.util.NicknameValidator;
 import com.example.RealMatch.user.domain.entity.ContentCategory;
 import com.example.RealMatch.user.domain.entity.SignupPurpose;
 import com.example.RealMatch.user.domain.entity.Term;
@@ -41,6 +42,7 @@ public class AuthService {
     private final ContentCategoryRepository contentCategoryRepository;
     private final UserContentCategoryRepository userContentCategoryRepository;
     private final JwtProvider jwtProvider;
+    private final NicknameValidator nicknameValidator;
 
     public OAuthTokenResponse completeSignup(Long userId, String providerId, SignupCompleteRequest request) {
         // 유저 조회
@@ -53,7 +55,7 @@ public OAuthTokenResponse completeSignup(Long userId, String providerId, SignupC
         }
 
         // ⭐ 닉네임 중복 체크 추가
-        validateNickname(request.nickname());
+        nicknameValidator.validate(request.nickname());
 
         // 유저 정보 업데이트
         user.completeSignup(
@@ -113,28 +115,6 @@ private String extractToken(String header) {
         return header;
     }
 
-    private void validateNickname(String nickname) {
-        // 1. null/빈 문자열 체크
-        if (nickname == null || nickname.trim().isEmpty()) {
-            throw new CustomException(OAuthErrorCode.INVALID_NICKNAME);
-        }
-
-        // 2. 길이 체크 (2~10자)
-        if (nickname.length() < 2 || nickname.length() > 10) {
-            throw new CustomException(OAuthErrorCode.INVALID_NICKNAME_LENGTH);
-        }
-
-        // 3. 형식 체크 (한글, 영문, 숫자만)
-        if (!nickname.matches("^[가-힣a-zA-Z0-9]+$")) {
-            throw new CustomException(OAuthErrorCode.INVALID_NICKNAME_FORMAT);
-        }
-
-        // 4. 중복 체크
-        if (userRepository.existsByNickname(nickname)) {
-            throw new CustomException(OAuthErrorCode.DUPLICATE_NICKNAME);
-        }
-    }
-
     private void saveTermAgreements(User user, List<SignupCompleteRequest.TermAgreementDto> terms) {
         // 요청 데이터 존재 여부 확인
         if (terms == null || terms.isEmpty()) {

src/main/java/com/example/RealMatch/user/application/service/UserService.java

@@ -7,6 +7,7 @@
 
 import com.example.RealMatch.global.exception.CustomException;
 import com.example.RealMatch.match.domain.repository.MatchCampaignHistoryRepository;
+import com.example.RealMatch.user.application.util.NicknameValidator;
 import com.example.RealMatch.user.domain.entity.AuthenticationMethod;
 import com.example.RealMatch.user.domain.entity.User;
 import com.example.RealMatch.user.domain.entity.UserContentCategory;
@@ -39,6 +40,7 @@ public class UserService {
     private final AuthenticationMethodRepository authenticationMethodRepository;
     private final UserMatchingDetailRepository userMatchingDetailRepository;
     private final UserContentCategoryRepository userContentCategoryRepository;
+    private final NicknameValidator nicknameValidator;
 
     public MyPageResponseDto getMyPage(Long userId) {
         // 유저 조회 (존재하지 않거나 삭제된 유저 예외 처리)
@@ -166,4 +168,9 @@ public MyLoginResponseDto getSocialLoginInfo(Long userId) {
         // DTO 변환 및 반환
         return MyLoginResponseDto.from(linkedProviders);
     }
+
+    @Transactional(readOnly = true)
+    public boolean isNicknameAvailable(String nickname) {
+        return nicknameValidator.isAvailable(nickname);
+    }
 }

src/main/java/com/example/RealMatch/user/application/util/NicknameValidator.java

@@ -0,0 +1,103 @@
+package com.example.RealMatch.user.application.util;
+
+import org.springframework.stereotype.Component;
+
+import com.example.RealMatch.global.exception.CustomException;
+import com.example.RealMatch.user.domain.repository.UserRepository;
+import com.example.RealMatch.user.presentation.code.UserErrorCode;
+
+import lombok.RequiredArgsConstructor;
+/**
+ * 닉네임 검증을 위한 공통 유틸리티 클래스
+ * - 형식, 길이, 중복 검증을 한 곳에서 처리
+ */
+@Component
+@RequiredArgsConstructor
+public class NicknameValidator {
+
+    private final UserRepository userRepository;
+
+    private static final int MIN_LENGTH = 2;
+    private static final int MAX_LENGTH = 10;
+    private static final String NICKNAME_PATTERN = "^[가-힣a-zA-Z0-9]+$";
+
+    /**
+     * 닉네임 사용 가능 여부 확인 (중복 체크만)
+     * - 형식/길이 검증 후 중복 여부 반환
+     * - 검증 실패 시 예외 발생
+     *
+     * @param nickname 검증할 닉네임
+     * @return 사용 가능하면 true, 중복이면 false
+     * @throws CustomException 형식/길이가 잘못된 경우
+     */
+    public boolean isAvailable(String nickname) {
+        validateFormat(nickname);
+        return !userRepository.existsByNickname(nickname.trim());
+    }
+
+    /**
+     * 닉네임 검증 (형식, 길이, 중복 모두 체크)
+     * - 검증 실패 시 예외 발생
+     *
+     * @param nickname 검증할 닉네임
+     * @throws CustomException 검증 실패 시
+     */
+    public void validate(String nickname) {
+        validateFormat(nickname);
+        validateDuplicate(nickname);
+    }
+
+    /**
+     * 닉네임 변경 시 검증 (기존 닉네임과 비교)
+     * - 기존 닉네임과 같으면 검증 통과
+     * - 다르면 형식, 길이, 중복 체크
+     *
+     * @param newNickname 새 닉네임
+     * @param currentNickname 현재 닉네임
+     * @throws CustomException 검증 실패 시
+     */
+    public void validateForUpdate(String newNickname, String currentNickname) {
+        // 기존 닉네임과 동일하면 검증 통과
+        if (newNickname.equals(currentNickname)) {
+            return;
+        }
+
+        // 형식 검증
+        validateFormat(newNickname);
+
+        // 중복 검증
+        validateDuplicate(newNickname);
+    }
+
+    /**
+     * 닉네임 형식 및 길이 검증
+     */
+    private void validateFormat(String nickname) {
+        // null 체크
+        if (nickname == null || nickname.trim().isEmpty()) {
+            throw new CustomException(UserErrorCode.INVALID_NICKNAME_FORMAT);
+        }
+
+        String trimmedNickname = nickname.trim();
+
+        // 길이 체크 (2~10자)
+        int length = trimmedNickname.codePointCount(0, trimmedNickname.length());
+        if (length < MIN_LENGTH || length > MAX_LENGTH) {
+            throw new CustomException(UserErrorCode.INVALID_NICKNAME_LENGTH);
+        }
+
+        // 형식 체크 (한글, 영문, 숫자만)
+        if (!trimmedNickname.matches(NICKNAME_PATTERN)) {
+            throw new CustomException(UserErrorCode.INVALID_NICKNAME_FORMAT);
+        }
+    }
+
+    /**
+     * 닉네임 중복 검증
+     */
+    private void validateDuplicate(String nickname) {
+        if (userRepository.existsByNickname(nickname.trim())) {
+            throw new CustomException(UserErrorCode.DUPLICATE_NICKNAME);
+        }
+    }
+}

src/main/java/com/example/RealMatch/user/presentation/controller/UserController.java

@@ -21,6 +21,7 @@
 import com.example.RealMatch.user.presentation.dto.response.MyPageResponseDto;
 import com.example.RealMatch.user.presentation.dto.response.MyProfileCardResponseDto;
 import com.example.RealMatch.user.presentation.dto.response.MyScrapResponseDto;
+import com.example.RealMatch.user.presentation.dto.response.NicknameAvailableResponseDto;
 import com.example.RealMatch.user.presentation.swagger.UserSwagger;
 
 import io.swagger.v3.oas.annotations.tags.Tag;
@@ -107,4 +108,13 @@ public CustomResponse<Void> updateMyFeature(
         userFeatureService.updateMyFeatures(userDetails.getUserId(), request);
         return CustomResponse.ok(null);
     }
+
+    @Override
+    @GetMapping("/nickname/available")
+    public CustomResponse<NicknameAvailableResponseDto> checkNicknameAvailable(
+            @RequestParam String nickname
+    ) {
+        boolean available = userService.isNicknameAvailable(nickname);
+        return CustomResponse.ok(new NicknameAvailableResponseDto(available));
+    }
 }

src/main/java/com/example/RealMatch/user/presentation/dto/response/NicknameAvailableResponseDto.java

@@ -0,0 +1,4 @@
+package com.example.RealMatch.user.presentation.dto.response;
+
+public record NicknameAvailableResponseDto(boolean available) {
+}

src/main/java/com/example/RealMatch/user/presentation/swagger/UserSwagger.java

@@ -15,6 +15,7 @@
 import com.example.RealMatch.user.presentation.dto.response.MyPageResponseDto;
 import com.example.RealMatch.user.presentation.dto.response.MyProfileCardResponseDto;
 import com.example.RealMatch.user.presentation.dto.response.MyScrapResponseDto;
+import com.example.RealMatch.user.presentation.dto.response.NicknameAvailableResponseDto;
 
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
@@ -115,4 +116,30 @@ CustomResponse<Void> updateMyFeature(
             @Parameter(hidden = true) @AuthenticationPrincipal CustomUserDetails userDetails,
             @RequestBody MatchRequestDto request
     );
+
+    @Operation(
+            summary = "닉네임 중복 체크 API",
+            description = """
+                회원가입 및 닉네임 변경 시 사용할 닉네임 중복 체크 API입니다.
+
+                user 테이블의 nickname 컬럼에서 닉네임이 있으면 "available": false 반환
+                없으면 "available": true 반환
+
+                닉네임 형식 및 길이 조건
+                - 형식: 한글, 영문, 숫자만 허용 (특수문자 및 공백 불가)
+                - 길이: 2자 이상 10자 이하 허용 
+                """
+    )
+    @ApiResponses({
+            @ApiResponse(responseCode = "200", description = "중복 체크 성공"),
+            @ApiResponse(responseCode = "400", description = "닉네임 형식 또는 길이 오류")
+    })
+    CustomResponse<NicknameAvailableResponseDto> checkNicknameAvailable(
+            @Parameter(
+                    description = "중복 여부를 확인할 닉네임",
+                    required = true,
+                    example = "비비"
+            )
+            @RequestParam String nickname
+    );
 }