feat: custom exception 추가

.github/workflows/deploy.yml

@@ -0,0 +1,63 @@
+name: Deploy Auth to ECS
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+env:
+  AWS_REGION: ap-northeast-2
+  AWS_ACCOUNT_ID: 727452759104
+  ECR_REPOSITORY: momentlit/auth
+  ECS_CLUSTER: default
+  ECS_SERVICE: momentlit-auth-service
+  IMAGE_TAG: latest
+
+jobs:
+  deploy:
+    name: Build and Deploy Auth
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v4
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v5
+        with:
+          aws-region: ${{ env.AWS_REGION }}
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+
+      - name: Login to Amazon ECR
+        uses: aws-actions/amazon-ecr-login@v2
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push Docker image
+        run: |
+          IMAGE_URI=${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/${ECR_REPOSITORY}:${IMAGE_TAG}
+
+          docker buildx build \
+            --platform linux/amd64 \
+            --provenance=false \
+            -t $IMAGE_URI \
+            . \
+            --push
+
+      - name: Force new ECS deployment
+        run: |
+          aws ecs update-service \
+            --cluster $ECS_CLUSTER \
+            --service $ECS_SERVICE \
+            --force-new-deployment \
+            --region $AWS_REGION
+
+      - name: Wait for ECS service stable
+        run: |
+          aws ecs wait services-stable \
+            --cluster $ECS_CLUSTER \
+            --services $ECS_SERVICE \
+            --region $AWS_REGION

API_SPEC.yaml

@@ -9,6 +9,54 @@ servers:
 tags: []
 paths: {}
 components:
-  schemas: {}
-  responses: {}
+  schemas:
+    ErrorResponse:
+      type: object
+      properties:
+        message:
+          type: string
+          example: "[ERROR: Request/BadRequest] Refresh Token을 입력해주세요."
+        data:
+          nullable: true
+          example: null
+      required:
+        - message
+        - data
+  responses:
+    BadRequestError:
+      description: "Invalid request input."
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          example:
+            message: "[ERROR: Request/BadRequest] Refresh Token을 입력해주세요."
+            data: null
+    UnauthorizedError:
+      description: "Authentication failed or token is invalid."
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          example:
+            message: "[ERROR: Auth/Unauthorized] 유효하지 않은 Refresh Token입니다."
+            data: null
+    GoogleOauthError:
+      description: "Google OAuth request failed."
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          example:
+            message: "[ERROR: Auth/Oauth/Google] Google Access Token을 발급받을 수 없습니다."
+            data: null
+    InternalServerError:
+      description: "Unexpected server error."
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          example:
+            message: "[ERROR: ?/?] 서버 내부 오류가 발생했습니다."
+            data: null
   securitySchemes: {}

docs/service-overview.md

@@ -43,7 +43,8 @@ No repository or persistence component is visible. Build dependencies include Sp
 
 ## Exception Handling
 
-No project-specific exception handling is visible.
+Project-specific exception handling is implemented under `com.example.auth.global.exception`.
+Auth-specific exceptions extend `AuthException` and are handled by `GlobalExceptionHandler`.
 
 ## Test Structure
 

docs/service-policy.md

@@ -31,7 +31,15 @@ State transitions are documented only where visible in entity or service methods
 
 ## Exception Cases
 
-No project-specific exception handling is visible. HTTP status mapping for these exceptions is Needs confirmation unless explicitly handled in code.
+Project-specific exception handling is visible under `com.example.auth.global.exception`.
+Visible mappings:
+
+- `BadRequestException`: `400 Bad Request`
+- `UnauthorizedException`: `401 Unauthorized`
+- `TokenNotFoundException`: `401 Unauthorized`
+- `GoogleOauthException`: `502 Bad Gateway`
+- Other `AuthException`: `500 Internal Server Error`
+- Other `Exception`: `500 Internal Server Error`
 
 ## API Behavior Policy
 

src/main/java/com/example/auth/global/client/UserServiceClient.java

@@ -4,8 +4,10 @@
 import com.example.auth.global.client.dto.response.GoogleUserInfoResponse;
 import com.example.auth.global.client.dto.response.UserAuthResponse;
 import com.example.auth.global.client.dto.request.UserGoogleOauthRequest;
+import com.example.auth.global.exception.UnauthorizedException;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.stereotype.Component;
+import org.springframework.web.client.HttpClientErrorException;
 import org.springframework.web.client.RestClient;
 
 @Component
@@ -22,11 +24,16 @@ public UserServiceClient(
     }
 
     public UserAuthResponse authenticate(SignInRequest request) {
-        return restClient.post()
-                .uri("/internal/users/authenticate")
-                .body(request)
-                .retrieve()
-                .body(UserAuthResponse.class);
+        try {
+            return restClient.post()
+                    .uri("/internal/users/authenticate")
+                    .body(request)
+                    .retrieve()
+                    .body(UserAuthResponse.class);
+
+        } catch (HttpClientErrorException.Unauthorized e) {
+            throw new UnauthorizedException("이메일 또는 비밀번호가 일치하지 않습니다.");
+        }
     }
 
     public UserAuthResponse authenticateGoogle(GoogleUserInfoResponse request) {

src/main/java/com/example/auth/global/dto/ApiResponse.java

@@ -3,4 +3,8 @@
 public record ApiResponse<T> (
     String message,
     T data
-){}
+){
+    public static <T> ApiResponse<T> fail(String message) {
+        return new ApiResponse<>(message, null);
+    }
+}

src/main/java/com/example/auth/global/exception/AuthException.java

@@ -0,0 +1,7 @@
+package com.example.auth.global.exception;
+
+public class AuthException extends RuntimeException {
+    public AuthException(String message) {
+        super(message);
+    }
+}

src/main/java/com/example/auth/global/exception/BadRequestException.java

@@ -0,0 +1,7 @@
+package com.example.auth.global.exception;
+
+public class BadRequestException extends AuthException {
+    public BadRequestException(String message) {
+        super(message);
+    }
+}

src/main/java/com/example/auth/global/exception/GlobalExceptionHandler.java

@@ -0,0 +1,61 @@
+package com.example.auth.global.exception;
+
+import com.example.auth.global.dto.ApiResponse;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+@Slf4j
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler(TokenNotFoundException.class)
+    public ResponseEntity<ApiResponse<String>> tokenNotFoundHandleException(TokenNotFoundException e) {
+        log.warn("TokenNotFoundException: {}", e.getMessage());
+
+        return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                .body(ApiResponse.fail("[ERROR: Auth/Token/NotFound] " + e.getMessage()));
+    }
+
+    @ExceptionHandler(UnauthorizedException.class)
+    public ResponseEntity<ApiResponse<String>> unauthorizedHandleException(UnauthorizedException e) {
+        log.warn("UnauthorizedException: {}", e.getMessage());
+
+        return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                .body(ApiResponse.fail("[ERROR: Auth/Unauthorized] " + e.getMessage()));
+    }
+
+    @ExceptionHandler(BadRequestException.class)
+    public ResponseEntity<ApiResponse<String>> badRequestHandleException(BadRequestException e) {
+        log.warn("BadRequestException: {}", e.getMessage());
+
+        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                .body(ApiResponse.fail("[ERROR: Request/BadRequest] " + e.getMessage()));
+    }
+
+    @ExceptionHandler(GoogleOauthException.class)
+    public ResponseEntity<ApiResponse<String>> googleOauthHandleException(GoogleOauthException e) {
+        log.error("GoogleOauthException", e);
+
+        return ResponseEntity.status(HttpStatus.BAD_GATEWAY)
+                .body(ApiResponse.fail("[ERROR: Auth/Oauth/Google] " + e.getMessage()));
+    }
+
+    @ExceptionHandler(AuthException.class)
+    public ResponseEntity<ApiResponse<String>> authHandleException(AuthException e) {
+        log.error("AuthException", e);
+
+        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                .body(ApiResponse.fail("[ERROR: Auth/?] " + e.getMessage()));
+    }
+
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<ApiResponse<String>> globalHandleException(Exception e) {
+        log.error("Unhandled exception", e);
+
+        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                .body(ApiResponse.fail("[ERROR: ?/?] 서버 내부 오류가 발생했습니다."));
+    }
+}

src/main/java/com/example/auth/global/exception/GoogleOauthException.java

@@ -0,0 +1,7 @@
+package com.example.auth.global.exception;
+
+public class GoogleOauthException extends AuthException {
+    public GoogleOauthException(String message) {
+        super(message);
+    }
+}

src/main/java/com/example/auth/global/exception/TokenNotFoundException.java

@@ -0,0 +1,7 @@
+package com.example.auth.global.exception;
+
+public class TokenNotFoundException extends AuthException {
+    public TokenNotFoundException(String message) {
+        super(message);
+    }
+}

src/main/java/com/example/auth/global/exception/UnauthorizedException.java

@@ -0,0 +1,7 @@
+package com.example.auth.global.exception;
+
+public class UnauthorizedException extends AuthException {
+    public UnauthorizedException(String message) {
+        super(message);
+    }
+}

src/main/java/com/example/auth/service/AuthService.java

@@ -11,6 +11,7 @@
 import com.example.auth.global.client.dto.response.GoogleTokenResponse;
 import com.example.auth.global.client.dto.response.GoogleUserInfoResponse;
 import com.example.auth.global.client.dto.response.UserAuthResponse;
+import com.example.auth.global.exception.GoogleOauthException;
 import java.net.URI;
 import org.springframework.stereotype.Service;
 import org.springframework.util.StringUtils;
@@ -80,7 +81,7 @@ public OauthGoogleCallbackResponse loginWithGoogle(String code, String state) {
                 googleOauthClient.requestToken(code);
 
         if (googleToken == null || !StringUtils.hasText(googleToken.accessToken())) {
-            throw new IllegalArgumentException("Google Access Token을 발급받을 수 없습니다.");
+            throw new GoogleOauthException("Google Access Token을 발급받을 수 없습니다.");
         }
 
         GoogleUserInfoResponse googleUser =

src/main/java/com/example/auth/service/AuthValidator.java

@@ -4,38 +4,40 @@
 import com.example.auth.dto.request.SignInRequest;
 import com.example.auth.dto.request.SignOutRequest;
 import com.example.auth.global.client.dto.response.UserAuthResponse;
+import com.example.auth.global.exception.BadRequestException;
+import com.example.auth.global.exception.UnauthorizedException;
 import org.springframework.stereotype.Component;
 import org.springframework.util.StringUtils;
 
 @Component
 public class AuthValidator {
     public void validateLoginRequest(SignInRequest request) {
         if (request == null || !StringUtils.hasText(request.email()) || !StringUtils.hasText(request.password())) {
-            throw new IllegalArgumentException("아이디와 비밀번호를 입력해주세요.");
+            throw new BadRequestException("아이디와 비밀번호를 입력해주세요.");
         }
     }
 
     public void validateRefreshRequest(RefreshRequest request) {
         if (request == null || !StringUtils.hasText(request.refreshToken())) {
-            throw new IllegalArgumentException("Refresh Token을 입력해주세요.");
+            throw new BadRequestException("Refresh Token을 입력해주세요.");
         }
     }
 
     public void validateGoogleAuthorizationCode(String code) {
         if (!StringUtils.hasText(code)) {
-            throw new IllegalArgumentException("Google Authorization Code를 입력해주세요.");
+            throw new BadRequestException("Google Authorization Code를 입력해주세요.");
         }
     }
 
     public void validateSignOutRequest(SignOutRequest request) {
         if (request == null || !StringUtils.hasText(request.refresh_token())) {
-            throw new IllegalArgumentException("Refresh Token을 입력해주세요.");
+            throw new BadRequestException("Refresh Token을 입력해주세요.");
         }
     }
 
     public void validateAuthenticatedUser(UserAuthResponse user) {
         if (user == null || user.userId() == null) {
-            throw new IllegalArgumentException("사용자 인증 정보를 확인할 수 없습니다.");
+            throw new UnauthorizedException("사용자 인증 정보를 확인할 수 없습니다.");
         }
     }
 }

src/main/java/com/example/auth/service/TokenService.java

@@ -1,7 +1,10 @@
 package com.example.auth.service;
 
 import com.example.auth.global.security.JwtProvider;
+import com.example.auth.global.exception.TokenNotFoundException;
+import com.example.auth.global.exception.UnauthorizedException;
 import com.example.auth.infra.RefreshTokenRepository;
+import io.jsonwebtoken.JwtException;
 import org.springframework.stereotype.Service;
 
 @Service
@@ -46,12 +49,16 @@ public long accessTokenExpiresInSeconds() {
     }
 
     public String getValidRefreshTokenSubject(String refreshToken) {
-        jwtProvider.validateToken(refreshToken);
+        try {
+            jwtProvider.validateToken(refreshToken);
+        } catch (JwtException | IllegalArgumentException exception) {
+            throw new UnauthorizedException("유효하지 않은 Refresh Token입니다.");
+        }
 
         String subject = jwtProvider.getSubject(refreshToken);
 
         if (!refreshTokenRepository.existsBySubjectAndToken(subject, refreshToken)) {
-            throw new IllegalArgumentException(
+            throw new TokenNotFoundException(
                     "저장된 Refresh Token과 일치하지 않습니다."
             );
         }