Project Metamorphosis

"어느 날 아침, 불안한 잠에서 깨어난 JSON은 자신이 거대한 Java 객체로 변해버린 것을 발견했다."

Metamorthoses

Project Metamorphosis는 Java POJO 객체를 다양한 텍스트 포맷으로 상호 변환하는 경량 라이브러리입니다. 현재 지원 포맷은 JSON, YAML, TOML, XML, CSV, Java Properties 입니다.

핵심 목표는 다음과 같습니다.

• 리플렉션 기반으로 POJO 필드와 데이터 키를 매핑합니다.
• 포맷별 구현을 분리해 유지보수성을 높입니다.
• @Property, @PropertyIgnore, @PropertyComment 어노테이션으로 매핑을 제어합니다.
• 기본 타입, 래퍼 타입, 날짜/시간 타입, List, Set, Map, Enum, Optional을 지원합니다.
• 지원하지 않는 타입은 Morpher로 확장할 수 있습니다.

프로젝트 구조

• com.elex_project.metamorphosis 공통 어노테이션, 옵션, 베이스 엔진, 변환 엔진
• com.elex_project.metamorphosis.json JSON 직렬화/역직렬화
• com.elex_project.metamorphosis.yaml YAML 직렬화/역직렬화
• com.elex_project.metamorphosis.toml TOML 직렬화/역직렬화
• com.elex_project.metamorphosis.xml XML 직렬화/역직렬화
• com.elex_project.metamorphosis.csv CSV/TSV 직렬화/역직렬화
• com.elex_project.metamorphosis.properties Java Properties 직렬화/역직렬화

빠른 시작

Morphosis<Options.JSON> morphosis = Morphosis.ofJson();

String json = morphosis.serialize(user);
User user2 = morphosis.deserialize(json, User.class);

포맷별 생성

Morphosis<Options.JSON> json = Morphosis.ofJson();
Morphosis<Options.YAML> yaml = Morphosis.ofYaml();
Morphosis<Options.TOML> toml = Morphosis.ofToml();
Morphosis<Options.XML> xml = Morphosis.ofXml();
Morphosis<Options.CSV> csv = Morphosis.ofCsv();
Morphosis<Options.PROPS> props = Morphosis.ofProperties();

예시

JSON

Morphosis<Options.JSON> morphosis = Morphosis.ofJson();
morphosis.options()
    .setIndentEnabled(true)
    .setIndentSize(4)
    .setSortKeysAlphabetically(true);

String output = morphosis.serialize(user);
User parsed = morphosis.deserialize(output, User.class);

YAML

Morphosis<Options.YAML> morphosis = Morphosis.ofYaml();
morphosis.options()
    .setIndentSize(2)
    .setSortFieldsAlphabetically(true)
    .setChompingStrategy(Chomping.CLIP);

TOML

Morphosis<Options.TOML> morphosis = Morphosis.ofToml();
morphosis.options()
    .setPreferLiteralStrings(true)
    .setSerializeListAsArrayOfTables(true);

XML

Morphosis<Options.XML> morphosis = Morphosis.ofXml();
morphosis.options()
    .setRootTagName("configuration")
    .setCaseInsensitive(true);

CSV / TSV

Morphosis<Options.CSV> morphosis = Morphosis.ofCsv();
morphosis.options().useTabDelimiter();

Properties

Morphosis<Options.PROPS> morphosis = Morphosis.ofProperties();
morphosis.options()
    .setListDelimiter("|")
    .setMapDelimiter(":");

지원 타입

기본 지원 타입은 다음과 같습니다.

• Primitive: boolean, char, byte, short, int, long, float, double
• Wrapper: Boolean, Character, Byte, Short, Integer, Long, Float, Double
• Date/Time: LocalDateTime, LocalDate, LocalTime, ZonedDateTime, OffsetDateTime, OffsetTime
• Collection: List, Set, Map
• Enum
• Optional

그 외의 타입은 Morpher<T>를 등록해 확장할 수 있습니다.

Morpher<Address> converter = new AddressMorpher();
morphosis.register(converter);

매핑 어노테이션

@Property

• value 데이터 키 이름을 지정합니다.
• defaultValue 누락 또는 null 값에 사용할 기본값을 지정합니다.
• isAttribute XML에서 속성으로 직렬화/역직렬화할지 지정합니다.
• order 필드 직렬화 순서를 지정합니다.

@PropertyIgnore

• 해당 필드를 직렬화/역직렬화 대상에서 제외합니다.

@PropertyComment

• TOML, Properties에서 주석을 생성합니다.
• inline=true이면 같은 줄 끝에 인라인 주석으로 출력합니다.

옵션

모든 포맷별 옵션은 morphosis.options()로 접근합니다.

옵션	설명	적용 포맷
failOnNullForPrimitives	primitive 필드에 null 대입 시 예외 발생	전체
failOnTypeMismatch	타입 변환 실패 시 예외 발생	전체
excludeNullFields	null 필드 직렬화 제외	전체
includeEmptyCollections	빈 컬렉션도 출력	전체
skipEmptyOptional	빈 Optional 생략	전체
failOnUnknownKeys	정의되지 않은 키 발견 시 예외 발생	전체
enumToLowerCase	Enum 출력 시 소문자 변환	전체
indentSize	들여쓰기 폭	JSON/YAML/TOML/XML
alwaysQuoteStrings	문자열 항상 따옴표 처리	JSON
sortKeysAlphabetically	Map 키 정렬	JSON
sortFieldsAlphabetically	필드 정렬	YAML/TOML
preferFoldedStrings	YAML 멀티라인 문자열을 > 스타일로 출력	YAML
chompingStrategy	YAML block scalar chomping 규칙	YAML
serializeListAsArrayOfTables	TOML 리스트를 [[table]]로 출력	TOML
preferLiteralStrings	TOML 리터럴 문자열 선호	TOML
rootTagName	XML 루트 태그 이름	XML
caseInsensitive	XML 태그 대소문자 무시	XML
comment	XML/Properties 헤더 주석	XML/Properties
columnDelimiter	CSV 구분자	CSV
nullValue	CSV null 표현 문자열	CSV
headerless	CSV 헤더 생략	CSV
listDelimiter	Properties 컬렉션 구분자	Properties
mapDelimiter	Properties Map 구분자	Properties

빌드 및 테스트

이 프로젝트는 Gradle로 관리됩니다.

./gradlew build
./gradlew test
./gradlew speedTest

speedTest는 기본 테스트와 분리된 non-default 실행 태스크입니다.

참고 사항

• 메인 라이브러리 코드는 외부 파서 라이브러리에 의존하지 않습니다.
• 벤치마크용 SpeedTest만 테스트 전용 Jackson 의존성을 사용합니다.
• 각 파서는 경계 검사와 malformed 입력에 대한 방어 로직을 포함합니다.

라이선스

Apache License 2.0

---

© 2026 Elex Co., Pte. All rights reserved.