Skip to content

README.md

Latest commit

 

History

History
145 lines (107 loc) · 4.43 KB

README.md

File metadata and controls

145 lines (107 loc) · 4.43 KB

Module bluetape4k-json

개요

bluetape4k-json은 JSON 직렬화/역직렬화를 위한 공통 인터페이스를 정의하는 모듈입니다.

다양한 JSON 라이브러리(Jackson, Fastjson2 등)를 동일한 API로 사용할 수 있도록 JsonSerializer 인터페이스를 제공하며, Kotlin reified 타입을 활용한 편의 확장 함수도 포함합니다.

주요 기능

JsonSerializer 인터페이스

모든 JSON 직렬화 구현체가 준수해야 하는 공통 인터페이스입니다.

import io.bluetape4k.json.JsonSerializer
import io.bluetape4k.json.deserialize
import io.bluetape4k.json.deserializeFromString

val serializer: JsonSerializer = JacksonSerializer() // 또는 FastjsonSerializer()

// 바이트 배열 직렬화/역직렬화
val bytes = serializer.serialize(data)
val restored = serializer.deserialize<Data>(bytes)

// 문자열 직렬화/역직렬화
val jsonText = serializer.serializeAsString(data)
val restored2 = serializer.deserializeFromString<Data>(jsonText)

지원 메서드

메서드 설명
serialize(graph) 객체를 JSON ByteArray로 직렬화
deserialize(bytes, clazz) ByteArray를 지정 타입으로 역직렬화
serializeAsString(graph) 객체를 JSON 문자열로 직렬화
deserializeFromString(text, clazz) JSON 문자열을 지정 타입으로 역직렬화

실패 정책

  • serialize(null)은 빈 ByteArray를 반환합니다.
  • deserialize(null) / deserializeFromString(null)은 null을 반환합니다.
  • 그 외 직렬화/역직렬화 실패는 JsonSerializationException 예외를 던집니다.

Kotlin reified 확장 함수

클래스를 명시하지 않고 타입 추론으로 역직렬화할 수 있습니다:

// Class 파라미터 불필요
val user = serializer.deserialize<User>(bytes)
val user2 = serializer.deserializeFromString<User>(jsonText)

구현체 목록

구현체 모듈 기반 라이브러리
JacksonSerializer bluetape4k-jackson2 Jackson 2.x
JacksonSerializer bluetape4k-jackson3 Jackson 3.x
FastjsonSerializer bluetape4k-fastjson2 Fastjson2 (JSONB)

의존성

dependencies {
    implementation(project(":bluetape4k-json"))
}

모듈 구조

io.bluetape4k.json
└── JsonSerializer.kt    # 공통 인터페이스 및 reified 확장 함수

아키텍처 다이어그램

JsonSerializer 인터페이스와 구현체

classDiagram
    class JsonSerializer {
        <<interface>>
        +serialize(graph: Any?) ByteArray
        +deserialize(bytes: ByteArray?, clazz: Class~T~) T?
        +serializeAsString(graph: Any?) String
        +deserializeFromString(text: String?, clazz: Class~T~) T?
    }

    class JsonSerializationException {
        +message: String
        +cause: Throwable?
    }

    class JacksonSerializer_2 {
        Jackson 2.x 기반
        bluetape4k-jackson2
    }

    class JacksonSerializer_3 {
        Jackson 3.x 기반
        bluetape4k-jackson3
    }

    class FastjsonSerializer {
        Fastjson2 JSONB 기반
        bluetape4k-fastjson2
    }

    JsonSerializer <|.. JacksonSerializer_2
    JsonSerializer <|.. JacksonSerializer_3
    JsonSerializer <|.. FastjsonSerializer
    JsonSerializer ..> JsonSerializationException : 실패 시 throw
Loading

구현체 선택 흐름

flowchart TD
    시작([JsonSerializer 선택]) --> 요구사항{요구사항?}
    요구사항 -->|Spring/표준 호환| J2[JacksonSerializer<br/>Jackson 2.x]
    요구사항 -->|Spring Boot 4 / 최신 API| J3[JacksonSerializer<br/>Jackson 3.x]
    요구사항 -->|최고 성능 + 바이너리| FJ[FastjsonSerializer<br/>Fastjson2 JSONB]

    J2 -->|serialize| BA[ByteArray]
    J3 -->|serialize| BA
    FJ -->|serialize JSONB| BA

    J2 -->|serializeAsString| STR[JSON String]
    J3 -->|serializeAsString| STR
    FJ -->|serializeAsString| STR

    BA -->|deserialize| OBJ[Kotlin 객체]
    STR -->|deserializeFromString| OBJ
Loading

참고