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

@@ -1,32 +1,57 @@
 package com.example.auth.global.client;
 
 import com.example.auth.dto.request.SignInRequest;
+import com.example.auth.global.client.dto.request.UserGoogleOauthRequest;
 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.DownstreamServiceException;
+import com.example.auth.global.exception.UnauthorizedException;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.HttpStatusCode;
 import org.springframework.stereotype.Component;
 import org.springframework.web.client.RestClient;
+import org.springframework.web.client.RestClientException;
+import org.springframework.web.client.RestClientResponseException;
 
+@Slf4j
 @Component
 public class UserServiceClient {
 
+    private static final String SERVICE_NAME = "USER";
+
     private final RestClient restClient;
+    private final ObjectMapper objectMapper = new ObjectMapper();
 
     public UserServiceClient(
-            @Value("${user-service.base-url:http://localhost:8081}") String userServiceBaseUrl //임시
+            @Value("${user-service.base-url:http://localhost:8081}") String userServiceBaseUrl
     ) {
         this.restClient = RestClient.builder()
                 .baseUrl(userServiceBaseUrl)
                 .build();
     }
 
     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 (RestClientResponseException e) {
+            if (e.getStatusCode().isSameCodeAs(HttpStatus.UNAUTHORIZED)) {
+                throw new UnauthorizedException("이메일 또는 비밀번호가 일치하지 않습니다.");
+            }
+
+            throw convertToDownstreamException(e);
+
+        } catch (RestClientException e) {
+            throw convertToConnectionException(e);
+        }
     }
 
     public UserAuthResponse authenticateGoogle(GoogleUserInfoResponse request) {
@@ -38,10 +63,72 @@ public UserAuthResponse authenticateGoogle(GoogleUserInfoResponse request) {
                 request.imageUrl()
         );
 
-        return restClient.post()
-                .uri("/internal/users/oauth/google")
-                .body(userRequest)
-                .retrieve()
-                .body(UserAuthResponse.class);
+        try {
+            return restClient.post()
+                    .uri("/internal/users/oauth/google")
+                    .body(userRequest)
+                    .retrieve()
+                    .body(UserAuthResponse.class);
+
+        } catch (RestClientResponseException e) {
+            throw convertToDownstreamException(e);
+
+        } catch (RestClientException e) {
+            throw convertToConnectionException(e);
+        }
+    }
+
+    private DownstreamServiceException convertToDownstreamException(RestClientResponseException e) {
+        String responseBody = e.getResponseBodyAsString();
+        String message = extractMessage(responseBody);
+        HttpStatusCode statusCode = e.getStatusCode();
+
+        if (statusCode.is4xxClientError()) {
+            log.warn(
+                    "{} service client error. status={}, body={}",
+                    SERVICE_NAME,
+                    statusCode,
+                    responseBody
+            );
+        } else {
+            log.error(
+                    "{} service server error. status={}, body={}",
+                    SERVICE_NAME,
+                    statusCode,
+                    responseBody
+            );
+        }
+
+        return new DownstreamServiceException(
+                SERVICE_NAME,
+                statusCode,
+                message,
+                responseBody
+        );
+    }
+
+    private DownstreamServiceException convertToConnectionException(RestClientException e) {
+        log.error("{} service connection failed", SERVICE_NAME, e);
+
+        return new DownstreamServiceException(
+                SERVICE_NAME,
+                HttpStatus.SERVICE_UNAVAILABLE,
+                "USER 서비스에 연결할 수 없습니다.",
+                null
+        );
+    }
+
+    private String extractMessage(String responseBody) {
+        try {
+            JsonNode jsonNode = objectMapper.readTree(responseBody);
+
+            if (jsonNode.has("message")) {
+                return jsonNode.get("message").asText();
+            }
+
+            return "USER 서비스 호출 중 오류가 발생했습니다.";
+        } catch (Exception e) {
+            return "USER 서비스 호출 중 오류가 발생했습니다.";
+        }
     }
-}
+}

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/DownstreamServiceException.java

@@ -0,0 +1,24 @@
+package com.example.auth.global.exception;
+
+import lombok.Getter;
+import org.springframework.http.HttpStatusCode;
+
+@Getter
+public class DownstreamServiceException extends RuntimeException {
+
+  private final String serviceName;
+  private final HttpStatusCode statusCode;
+  private final String responseBody;
+
+  public DownstreamServiceException(
+          String serviceName,
+          HttpStatusCode statusCode,
+          String message,
+          String responseBody
+  ) {
+    super(message);
+    this.serviceName = serviceName;
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+  }
+}