[트러블 슈팅] Json 구조 복잡성으로 인한 가독성 문제 해결

문제 상황

목요일에 급하게 보고서 계산 로직을 구현한 이후, 계산 결과 데이터를 회차별, 장비별, 항목별 등으로 정리하여 JSON으로 전달해야 하는 상황에서 복잡한 JSON 구조가 만들어졌습니다.

List<Map<String, Map<String, Object>>> reportData;

이 구조는 작성자 본인조차 구조를 파악하고 디버깅하기 어려울 정도로 복잡해졌습니다.

원인 분석

• 보고서에서 각 장비의 평가 항목을 회차 별로 결과 값을 구분하여 전달해야 했음
• 이를 모두 동적으로 Map 구조로 처리한 결과, 중첩된 키 구조와 비정형 데이터로 인해 유지보수가 어려움
• DTO 없이 Map과 List로 처리할 경우, IDE의 자동 완성, 타입 검증, 명확한 구조가 사라짐

 

해결 방법

• 각 장비별로 전달해야 하는 평가 항목과 구조를 명확히 분석하여 전용 DTO(Data Transfer Object) 클래스를 정의함
• 예를 들어

@Getter
@Setter
@JsonInclude(JsonInclude.Include.NON_NULL)
public class RFScannerDTO {
    @JsonProperty("cycle")
    private Integer cycle;

    @JsonProperty("최대탐지거리")
    private BigDecimal maxDetectionRange;

    public RFScannerDTO() {}
}

• 레이더, EO/IR 카메라, 재머 등 다른 장비들도 각각의 평가 항목에 맞는 DTO를 설계
• 서비스 로직에서도 작성된 DTO에 맞게 코드 수정

 

개선할 점

• 초기 설계 시 DTO 없이 빠르게 개발에 집중한 결과, 결과물의 구조가 복잡하고 혼란스러워졌음
• JSON 응답 구조는 단순히 백엔드에서 보내는 데이터가 아니라 프론트엔드와의 계약임을 다시 인식
• 앞으로 복잡한 응답 구조가 예상되면, 먼저 DTO 설계를 진행하고 명세서를 작성한 뒤 개발을 진행하는 것이 바람직함