[Spring] - @JsonProperty, @JsonNaming

📎  Spring - @JsonProperty, @JsonNaming

안녕하세요, 이번에 정리할 내용은 스프링에서 @JsonProperty, @JsonNaming 어노테이션 입니다.

REST API 방식으로 서버와 클라이언트가 데이터를 통신을 할 때 JSON 형식을 주로 사용합니다.

서버단에서는 카멜 케이스(Camel Case) 방식을, 클라이언트단에서는 스네이크 케이스(Snake Case) 방식을 사용합니다.

카멜 케이스(Camel Case)
  - 첫 글자는 소문자로, 중간 글자들은 대문자로 시작하는 표기법
  - ex) phoneNumber, postMapping

스네이크 케이스(Snake Case)
  - 언더바(_)가 포함된 표현 방식
  - ex) phone_number, post_mapping

보통 자바는 카멜 케이스를, JSON형식은 스테이크 케이스 방식으로 표편을 하는게 원칙입니다.

위 네모박스처럼 클라이언트와 서버단의 표현 방식이 다름에 따라 데이터의 Key가 달라지는 경우가 존재합니다.

이러한 문제를 해결할 때 @JsonProperty, @JsonNaming 어노테이션을 사용할 수 있습니다.

 

 

 

🎯  Kotlin REST API 코드

예제는 Kotlin 기반으로 작성을 하였습니다.

예제 코드는 깃허브 에서 확인할 수 있습니다 :)

 

 

UserRequest

package org.juhyun.kotlinspringboot.model

data class UserRequest (
        var name:String?=null,
        var age:Int?=null,
        var email:String?=null,
        var address:String?=null,
        var phoneNumber:String?=null
)

UserRequest 객체는 클라이언트와 서버에서 통신을 할 때 사용되는 객체입니다.

해당 변수는 카멜 케이스 표기법을 따르고 있습니다.

 

 

Controller

package org.juhyun.kotlinspringboot.controller

import org.juhyun.kotlinspringboot.model.UserRequest
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@RequestMapping("/api")
class PostApiController {

    @PostMapping("/post-mapping")
    fun postMapping(): String {
        return "post-mapping"
    }

    @PostMapping("/post-mapping/object")
    fun postMappingObject(@RequestBody userRequest: UserRequest): UserRequest {
        println(userRequest) // json -> object
        return userRequest   // object -> json
    }

}

컨트롤러에는 postMappingObject() 메소드에서 UserRequest 객체를 받아서 사용하고 있습니다.

Talend API Tester를 통해 위 API를 테스트해보겠습니다.

 

 

Talend API Tester

위 API의 결과에서 확인하듯 phoneNumber 변수에는 데이터가 저장이 되지 않았는데요, 이는 API의 key와 응답 객체의 필드명이 다르기 때문에 발생하는 문제입니다.

실제 서버에서의 결과에도 null로 출력이 됩니다.

 

이제 @JsonProperty 어노테이션과 @JsonNaming 어노테이션을 통해 문제를 해결해보겠습니다.

 

 

 

@JsonProperty

package com.fasterxml.jackson.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Marker annotation that can be used to define a non-static
 * method as a "setter" or "getter" for a logical property
 * (depending on its signature),
 * or non-static object field to be used (serialized, deserialized) as
 * a logical property.
 *<p>
 * Default value ("") indicates that the field name is used
 * as the property name without any modifications, but it
 * can be specified to non-empty value to specify different
 * name. Property name refers to name used externally, as
 * the field name in JSON objects.
 *<p>
 * Starting with Jackson 2.6 this annotation may also be
 * used to change serialization of <code>Enum</code> like so:
 *<pre>
public enum MyEnum {
    {@literal @JsonProperty}("theFirstValue") THE_FIRST_VALUE,
    {@literal @JsonProperty}("another_value") ANOTHER_VALUE;
}
</pre>
 * as an alternative to using {@link JsonValue} annotation.
 *<p>
 * Starting with Jackson 2.12 it is also possible to specify {@code namespace}
 * of property: this property is only used by certain format backends (most
 * notably XML).
 */
@Target({ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotation
public @interface JsonProperty
{
    /**
     * Special value that indicates that handlers should use the default
     * name (derived from method or field name) for property.
     * 
     * @since 2.1
     */
    public final static String USE_DEFAULT_NAME = "";

    ...

}

@JsonProperty 어노테이션은 객체를 JSON 형식으로 변환할 때 Key의 이름을 설정할 수 있습니다.

위에서 클라이언트와 서버의 표기법이 달라서 발생하는 문제를 @JsonProperty 어노테이션을 통해 해결해보겠습니다.

 

package org.juhyun.kotlinspringboot.model

import com.fasterxml.jackson.annotation.JsonProperty

data class UserRequest (
        var name:String?=null,
        var age:Int?=null,
        var email:String?=null,
        var address:String?=null,
        
        @JsonProperty("phone_number")
        var phoneNumber:String?=null // json에서는 phone_number
)

phoneNumber 필드는 카멜 케이스로 작성을 하고, @JsonProperty 어노테이션을 통해 JSON 변환 시 받을 Key의 값을 설정합니다.

어노테이션을 적용한 후 API 테스트를 진행해보면 데이터가 정상적으로 넘어오는 걸 확인할 수 있습니다.

 

 

 

@JsonNaming

package com.fasterxml.jackson.databind.annotation;

import java.lang.annotation.*;

import com.fasterxml.jackson.databind.PropertyNamingStrategy;

/**
 * Annotation that can be used to indicate a {@link PropertyNamingStrategy}
 * to use for annotated class. Overrides the global (default) strategy.
 * Note that if the {@link #value} property is omitted, its default value
 * means "use default naming" (that is, no alternate naming method is used).
 * This can be used as an override with mix-ins.
 * 
 * @since 2.1
 */
@Target({ElementType.ANNOTATION_TYPE, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@com.fasterxml.jackson.annotation.JacksonAnnotation
public @interface JsonNaming
{
    /**
     * @return Type of {@link PropertyNamingStrategy} to use, if any; default value of
     *    <code>PropertyNamingStrategy.class</code> means "no strategy specified"
     *    (and may also be used for overriding to remove otherwise applicable
     *    naming strategy)
     */
    public Class<? extends PropertyNamingStrategy> value() default PropertyNamingStrategy.class;
}

현재 상황은 UserRequest 객체에서 하나의 필드만 설정을 했지만, 이러한 설정을 다양한 변수에서 설정하려면 모든 필드에 

@JsonProperty 어노테이션을 적용해주어야 하기 때문에 번거로운 작업이 될 수 있습니다.

 

이러한 문제는 @JsonNaming 어노테이션을 통해 클래스에 적용함으로써 해결할 수 있습니다.

package org.juhyun.kotlinspringboot.model

import com.fasterxml.jackson.databind.PropertyNamingStrategies
import com.fasterxml.jackson.databind.PropertyNamingStrategy
import com.fasterxml.jackson.databind.annotation.JsonNaming

// JSON 네이밍 전략
@JsonNaming(PropertyNamingStrategies.SnakeCaseStrategy::class)
// @JsonNaming(PropertyNamingStrategy.SnakeCaseStrategy::class) deprecated
data class UserRequest (
        var name:String?=null,
        var age:Int?=null,
        var email:String?=null,
        var address:String?=null,
        var phoneNumber:String?=null
)

※ 기존에 사용하던 PropertyNamingStrategy 클래스는 Deprecated가 되었습니다.

따라서 Kotlin에서 Jackson Module의 2.12 버전부터는 PropertyNamingStrategies 클래스의 사용을 권장하고 있습니다.

해당 문제에 대해 궁금하시면 링크 를 참고해주세요!

 

위와 같이 @JsonNaming 어노테이션을 적용하고 API 테스트를 해보면 phoneNumber 필드에 정상적으로 데이터가 들어온 걸 확인할 수 있습니다.

{
  "name": "JuHyun",
  "age": 20,
  "email": "a@a.com",
  "address": "Seoul",
  "phone_number": "010-1234-1234"
}

 

 

 

 

References

• https://www.inflearn.com/course/%EC%8A%A4%ED%94%84%EB%A7%81%EB%B6%80%ED%8A%B8-%EC%BD%94%ED%8B%80%EB%A6%B0/dashboard