JSON DTO Converter (0) - Overview & 전체 구조

hwangsoojin 2025. 11. 24. 16:31

"JSON → 스키마 → 타입 추론 → 클래스 그래프 → Java DTO 생성"까지의 전체 흐름 정리

우아한테크코스 프리코스(4–5주차) 오픈 미션
이 글은 JSON DTO Converter의 아키텍처 전체 구조,
그리고 이 도구가 어떤 방식으로 JSON을 분석해 Java DTO를 생성하는지를
기초 설계 관점에서 overview로 설명하는 글이다.

실제 내부 구조(ArgumentParser, JsonAnalyzer, TypeInferencer, ModelGraph, ClassGenerator 등)의
세부 분석은 다음 글들(CLI 분석 / JSON 분석 / Generator 분석 / Exception 분석)에서 다루고,
이 글에서는 먼저 전체 그림을 이해하기 위해 시스템 전체를 위에서 아래로 관찰한다.

1. 프로젝트의 목적과 배경

JSON DTO Converter는 단순한 자동화 스크립트가 아니라,
외부 API의 복잡한 JSON 구조를 분석하여 완전한 Java 클래스 세트(DTO)를 자동 생성하는 도구형 프로젝트다.

💡 왜 필요한가?

외부 REST API 응답(JSON)은 종종 중첩 구조가 깊다.
모든 필드를 손으로 DTO로 만들면 반복 작업 + 실수 위험 ↑
특히 프리코스 미션에서 API 연결 실습이 증가하면서 객체 설계의 부담도 증가
DTO를 자동으로 생성하면 비즈니스 로직 구현에 집중 가능

2. 도구의 전체 처리 파이프라인

JSON DTO Converter는 단순 파일 파서가 아니다.
전체 동작 구조는 작은 컴파일러(Compiler)에 가깝다.

전체 파이프라인 한눈에 보기

[1] CLI 입력 
       ↓
[2] JsonValidator 
       ↓
[3] JsonNode 트리 (Jackson)
       ↓
[4] SchemaNode 트리 (내부 스키마 모델)
       ↓
[5] TypeInferencer (자바 타입 추론)
       ↓
[6] ModelGraph (클래스 설계도 생성)
       ↓
[7] ClassSpec (코드 생성 계획)
       ↓
[8] ClassGenerator + Template (Java 코드 생성)
       ↓
[9] CodeFormatter (LF 정리 + 공백 제거)
       ↓
[10] FileWriter (.java 파일 저장)

즉,

JSON → 추상화된 스키마 → 타입 정보 → 클래스 구조 → Java 소스 코드

로 흐르는 구조다.

3. 전체 디렉터리 구조

프로젝트는 다음과 같은 구조로 설계되어 있다:

org.example
 ├─ Main.java                      ← 실행 진입점
 ├─ cli                            ← CLI 파싱/검증 계층
 │   ├─ ArgumentParser.java
 │   ├─ CommandLineOption.java
 │   ├─ FileValidator.java
 │   └─ ParsedArguments.java
 │
 ├─ json                           ← JSON 처리 및 타입 추론 계층
 │   ├─ JsonValidator.java
 │   ├─ JsonAnalyzer.java
 │   ├─ NameConverter.java
 │   ├─ DefaultNameConverter.java
 │   ├─ SchemaNode / Object / Array / Primitive / Union
 │   ├─ TypeInferencer.java
 │   └─ ModelGraph.java
 │
 ├─ generator                      ← 코드 생성 계층
 │   ├─ Template.java
 │   ├─ ClassGenerator.java
 │   ├─ CodeFormatter.java
 │   └─ FileWriter.java
 │
 └─ exception                      ← 예외 처리 계층
     ├─ UserException.java
     └─ InternalException.java

4. 설계 철학 - "SRP(단일 책임 원칙)"을 끝까지 지키기

이 프로젝트는 SRP(Single Responsibility Principle) 위에서 설계되었다.
어떤 클래스든 "딱 하나의 책임만" 가지도록 나누었다.

클래스	책임
ArgumentParser	CLI 옵션 파싱
JsonValidator	JSON 파일 검증 + BOM 제거
JsonAnalyzer	JsonNode → SchemaNode 트리 변환
TypeInferencer	SchemaNode → Java 타입 추론
ModelGraph	DTO 클래스 구조 결정
ClassGenerator	ClassSpec → Java 코드 생성
CodeFormatter	코드의 형식 정리
FileWriter	.java 파일로 저장

SRP를 지키면 다음과 같은 장점이 있다:

테스트 작성이 쉽다 (계층별 단위 테스트 가능)
유지보수성 증가
역할이 명확해서 코드 리뷰가 편하다
특정 기능 변경 시 관련된 클래스만 수정하면 된다

5. JSON → Java 클래스 생성 과정 요약

이 도구의 핵심은 "JSON을 어떻게 분석하고 Java 타입으로 매핑하는가?"이다.

여기서는 전체 흐름만 가볍게 소개한다.
상세 분석은 "JSON 분석" 글에서 다룬다.

5-1. JsonValidator — 파일 레벨 검증

파일 존재 여부
디렉터리 입력 여부
파일 크기 제한(5MB)
BOM(UTF-8) 검사 및 제거
JSON 문법 검사

예외는 UserException으로 전환하여 사용자 친화적으로 출력한다.

5-2. JsonNode 트리(Jackson)

JSON 파일을 읽으면 다음과 같은 트리 구조가 된다:

{
  "employee": {
    "id": "A01",
    "age": 20
  }
}

트리:

ObjectNode
 └─ employee : ObjectNode
        ├─ id  : TextNode("A01")
        └─ age : IntNode(20)

트리 기반 접근을 통해 JSON 구조를 자유롭게 순회하며 분석할 수 있다.

5-3. SchemaNode 트리 — 스키마 정의

JsonAnalyzer는 JsonNode를 기반으로 SchemaNode 트리를 만든다.

SchemaNode는 내부적으로 다음 타입으로 구성된다:

SchemaPrimitive
SchemaObject
SchemaArray
SchemaUnion (혼합 타입 처리)

이 스키마 트리는 언어에 독립적인 형태로 JSON 구조를 표현한다.
TypeInferencer가 이 스키마를 기반으로 Java 타입을 추론한다.

5-4. TypeInferencer — 자바 타입 추론

예시)

JSON 타입	Java 타입
"text"	String
123	int
12.3	double
true	boolean
[1,2,3]	List<Integer>
{…}	DTO 클래스

optional 필드는 wrapper 타입으로 변경된다.

5-5. ModelGraph — 클래스 구조 생성

ModelGraph는 전체 JSON 스키마를 분석해
어떤 DTO 클래스를 만들어야 하는지 결정한다.

예시)

RootDto
 ├─ User user
 └─ Address address

User
 ├─ String name
 └─ int age

Address
 ├─ String city
 └─ String zip

명령어 옵션 중 inner-classes가 true라면 RootDto 내부에 static class로 만든다.

6. 최종 출력 — Java 코드 생성 & 파일 출력

1) ClassGenerator

ClassSpec 기반으로 Java 코드 문자열 생성

2) CodeFormatter

LF 통일
trailing whitespace 제거
연속 빈 줄 축소

3) FileWriter

.java 파일 생성

7. 예시 — Weather API JSON → DTO 결과 (한눈에 보기)

입력 JSON:

{
  "location": {
    "name": "Seoul",
    "country": "KR"
  },
  "current": {
    "tempC": 12.3,
    "humidity": 77,
    "isDay": true
  }
}

출력 (inner-classes true일 때):

public class WeatherApiResponse {

    private Location location;
    private Current current;

    public static class Location {
        private String name;
        private String country;
    }

    public static class Current {
        private double tempC;
        private int humidity;
        private boolean isDay;
    }
}

8. Overview 마무리 — 왜 이런 구조였을까?

이 프로젝트는 다음을 체화하기 위한 도구였다:

구조 먼저 설계하기
메서드는 하나의 일만 하도록 만들기
예외를 “사용자 오류 vs 시스템 오류”로 분리하기
테스트 가능한 구조 만들기
JSON을 언어 독립적 스키마로 바라보는 시선 기르기

결과적으로 JSON DTO Converter는
단순 파일 변환기가 아니라,

JSON → 분석 → 타입 추론 → 클래스 구성 → 코드 생성이라는 전 과정이
단일 책임 원칙 아래 깔끔하게 모듈화된 하나의 시스템이 되었다.

다음 글에서는, 이 프로젝트의 첫 진입점인

CLI 설계와 ArgumentParser 내부 구조를 깊이 있게 해부한다.

👉 JSON DTO Converter (1) - CLI 분석