[SpringBoot] 일관된 API 응답을 위한 JsonResult 구현 및 활용

웹 개발 수업에서 강사님께 API 응답의 일관성에 대해 배웠다. 강사님은 프론트엔드와 백엔드 간의 효율적인 통신을 위해 표준화된 응답 구조의 중요성을 강조하셨다. 수업에서 배운 내용을 실제 프로젝트에 적용하여 JsonResult 유틸리티 클래스를 구현하게 되었다.

 

JsonResult 클래스 구현

클래스 구조 설계

public class JsonResult {
    private String result;     // 요청 성공 여부 ("success" or "fail")
    private Object apiData;    // 성공 시 반환할 데이터
    private String message;    // 실패 시 반환할 메시지
}

클래스의 핵심 목표는 다음과 같다.

• 모든 API 응답에 일관된 구조 제공
• 성공/실패 상황을 명확하게 구분
• 추가 데이터나 오류 메시지 전달

 

생성자와 정적 팩토리 메서드

// 성공 시 생성자
private JsonResult(Object apiData) {
    result = "success";
    this.apiData = apiData;
    message = null;
}

// 실패 시 생성자
private JsonResult(String message) {
    result = "fail";
    apiData = null;
    this.message = message;
}

// 정적 팩토리 메서드
public static JsonResult success(Object data) {
    return new JsonResult(data);
}

public static JsonResult fail(String message) {
    return new JsonResult(message);
}

주요 특징

• 생성자를 private로 선언하여 외부에서 직접 생성 방지
• 정적 팩토리 메서드로 객체 생성의 유연성 확보
• 성공/실패 상황에 맞는 메서드 제공

 

API 응답 예시

실제 프로젝트에서 JsonResult를 활용한 구체적인 예시를 살펴보겠다.

케이크 디자인 총 개수 조회 컨트롤러

@GetMapping("/api/user/cakeDesign/board/count")
public JsonResult getCakeDesignTotalCount() {
    int totalCount = juUserCakeDesignService.getCakeDesignTotalCount();
    
    // 결과 맵 생성
    Map<String, Object> resultMap = new HashMap<>();
    resultMap.put("totalCount", totalCount);
    
    // 조회 결과에 따른 응답
    if (totalCount > 0) {
        return JsonResult.success(resultMap);
    } else {
        return JsonResult.fail("도안 리스트를 가져오지 못했습니다.");
    }
}

이 코드에서 주목할 점은 다음과 같다.

• 총 개수를 Map에 담아 유연하게 데이터 전달
• 성공/실패 상황에 따라 다른 JsonResult 메서드 호출
• 실패 시 명확한 오류 메시지 제공

응답 JSON 예시

성공 시

{
    "result": "success",
    "apiData": {
        "totalCount": 10
    },
    "message": null
}

실패 시

{
    "result": "fail",
    "apiData": null,
    "message": "도안 리스트를 가져오지 못했습니다."
}
 

이러한 방식으로 모든 API 엔드포인트에서 일관된 응답 구조를 유지할 수 있었다.

장점

1. 일관된 응답 구조: 모든 API 엔드포인트에서 동일한 형식 유지
2. 명확한 상태 구분: result 필드로 성공/실패 즉시 판단 가능
3. 유연한 데이터 전달: 성공 시 다양한 형태의 데이터 전송 가능
4. 친절한 오류 메시지: 실패 원인을 명확히 전달

 

마무리

JsonResult 유틸리티 클래스를 통해 프론트엔드와의 통신을 더욱 명확하고 일관되게 만들 수 있었다. 이러한 접근은 코드의 가독성을 높이고, 클라이언트 개발자가 API를 더 쉽게 이해하고 사용할 수 있게 해준다.