[Jackson] API 필드명 @JsonProperty .araboja

외부 API를 연동하거나 JSON/XML 데이터를 다룰 때 '필드 이름 불일치' 문제를 해결해준다

 

필드 다 만들었는데, 왜 데이터가 안 들어오는거지 ?

SpringBoot로 이번 사이드 프로젝트를 개발하면서 RestTemplate 으로 외부 API를 호출하고 그 결과를 DTO 로 변환했다.
그런데 API 응답 데이터의 필드 이름과 내 DTO의 필드 이름이 미묘하게 달라서 데이터가 매핑되지 않고 null 값만 들어왔다

 API는 user_id라고 주는데  내 DTO에는 Java 스타일인 userId라고 선언하거나 
API가 offiNm처럼 알기 어려운 줄임말 ? 축약어 ? 를 사용하고 있을 때 문제가 발생한다

 

@JsonProperty , 데이터와 객체를 이어준다

"데이터(JSON/XML)의 필드 이름(Key)과 Java 객체의 필드 이름이 서로 다를 때, 이 둘을 정확하게 연결해주는 '매핑(Mapping) 정보' 역할을 합니다."

 

@JsonProperty 이럴 때 사용하자

• 명명 규칙(Naming Convention)이 다를 때
  데이터 형식과 프로그래밍 언어는 각자 선호하는 명명 규칙이 다르다
  • JSON/XML: snake_case (user_id), kebab-case (user-id) 등
    Java: camelCase (userId)
    이럴 때 @JsonProperty를 사용하면 나만의 Java 코딩 스타일을 해치지 않으면서 데이터를 매핑할 수 있다

public class UserDto {
    // JSON의 "user_id"를 Java의 "userId" 필드에 매핑
    @JsonProperty("user_id")
    private String userId;

    // JSON의 "user_name"을 Java의 "userName" 필드에 매핑
    @JsonProperty("user_name")
    private String userName;
}

 

• 2. API의 필드 이름이 모호하거나 마음에 안 들 때
  • 개인 프로젝트  rent-insight  에서 겪었던 문제다
  • 공공데이터 API는 그들만의 기준으로 필드 이름을 제공한다
  • excluUseAr: "전용 면적"이라는 뜻이지만, 처음 봤을때 이게 뭔가 ? 싶어서 API 문서를 까봤다
  • offiNm: "오피스텔 이름"이라는 뜻이지만, 너무 축약되어 가독성이 떨어졌다

// ApiRentDTO.java의 일부

// API의 모호한 'excluUseAr'를 'area'로 사용
@JsonProperty("excluUseAr")
private double area; // 전용면적

// API의 축약된 'offiNm'을 'name'으로 사용
@JsonProperty("offiNm")
private String name; // 오피스텔 이름

 

• 3. 필드 이름으로 사용할 수 없는 문자가 포함될 때
• JSON의 key는 문자열이므로 하이픈(-)이나 공백을 포함할 수 있지만, Java의 변수 이름은 사용불가
• @JsonProperty는 이럴 때 사용하자

public class ProductDto {
    @JsonProperty("product-id")
    private String productId;

    @JsonProperty("stock count")
    private int stockCount;
}

 

---

 rent-insight 프로젝트에서 공공데이터 API 응답을 받기 위해 만든 ApiRentDTO는 @JsonProperty 를 잘 써먹었다

@Data
@JsonIgnoreProperties(ignoreUnknown = true)
public class ApiRentDTO {

    @JsonProperty("buildYear")
    private Integer buildYear;

    // API의 'excluUseAr' ->'area'
    @JsonProperty("excluUseAr")
    private double area;

    // API의 'offiNm' -> 'name'
    @JsonProperty("offiNm")
    private String name;

    // API 응답에서 "18,000" 처럼 쉼표가 포함된 문자열로 오기 때문에
    // 일단 String으로 받은 뒤, 나중에 서비스 계층에서 숫자로 가공함
    @JsonProperty("deposit")
    private String deposit;

    @JsonProperty("monthlyRent")
    private String monthlyRent;

    // --- 나머지 필드들 ---
    @JsonProperty("contractTerm")
    private String contractTerm;

    @JsonProperty("contractType")
    private String contractType;

    @JsonProperty("dealDay")
    private Integer dealDay;

    @JsonProperty("dealMonth")
    private Integer dealMonth;

    @JsonProperty("dealYear")
    private Integer dealYear;

    @JsonProperty("floor")
    private Integer floor;

    @JsonProperty("jibun")
    private String jibun;

    @JsonProperty("sggCd")
    private String sggCd;

    @JsonProperty("sggNm")
    private String sggNm;

    @JsonProperty("umdNm")
    private String umdNm;

    @JsonProperty("preDeposit")
    private String preDeposit;

	// 여기도 하려했는데 귀찮음
    @JsonProperty("useRRRight")
    private String useRRRight;
}

 

 

• 가독성 향상: 내 코드에서는 내가 스스로 이해하기 쉽게 개발 할수 있다
• 유연성 확보: 외부 API의 필드명이 변경되더라도, DTO의 @JsonProperty 값만 수정하면 되므로 유지보수가 굿