hwangsoojin 님의 블로그

SQLD 59회 합격 결과 – 첫 도전의 마무리

hwangsoojin — Tue, 6 Jan 2026 01:57:59 +0900

SQLD 59회 시험 결과가 발표되었고, 합격하였다.

이번 시험은 개인 일정이 매우 바쁜 시기와 겹쳐 준비 기간이 충분하지 않았고,
또한 첫 응시였기 때문에 결과에 대한 불확실성이 존재했다.
만약 불합격할 경우 다시 시험 일정을 고려해야 한다는 점도 부담으로 작용했다.

그럼에도 불구하고 최종적으로 합격 결과를 확인하면서,
짧은 준비 기간 안에서도 핵심 내용을 중심으로 학습한 방향이 유효했음을 확인할 수 있었다.
이번 SQLD 합격은 이후 자격증 학습을 이어가기 위한 하나의 기준점이 되었다.

앞으로의 자격증 취득 계획은 다음과 같다.

리눅스마스터 1급
AWS 관련 자격증

SQLD를 통해 다진 데이터베이스 기초를 바탕으로,
운영체제와 클라우드 영역까지 학습 범위를 확장해 나갈 예정이다.

리눅스 명령어는 언제 프로그램이고, 언제 프로세스가 될까?

hwangsoojin — Thu, 1 Jan 2026 16:13:30 +0900

리눅스를 처음 배우면 이런 말들을 자주 듣는다.

"ls는 프로그램이다."
"명령어를 실행하면 프로세스가 생긴다."
"cd는 프로세스가 아니라 쉘 내부 기능이다."

처음엔 다 비슷하게 들리는데, 사실 이 차이를 정확히 이해하면

리눅스/운영체제 공부가 훨씬 쉬워진다.

이 글에서는 cd , ls , cat , echo , rm 같은 대표 명령어를 예로 들어

명령어(command) / 프로그램(program) / 프로세스(process) 를

깔끔하게 정리해본다.

1. 명령어(command), 프로그램(program), 프로세스(process) 차이

1) 명령어(command)

사용자가 쉘(터미널)에 입력하는 문자열이다.

예를 들어 내가 터미널에 아래를 입력했다면,

ls -l

여기서 ls -l 은 사용자가 입력한 명령어다.

즉, 텍스트(문자열)로 된 "지시"다.

2) 프로그램(program)

디스크에 저장된 실행 파일이다. 예를 들어 ls 는 보통 아래 경로에 존재한다.

/usr/bin/ls

즉, ls 라는 이름의 명령어는

실제로는 /usr/bin/ls 라는 실행 파일(프로그램)을 가리킨다.

이 프로그램은 "코드와 데이터"가 파일 형태로 저장된 정적인 상태다.

실행하지 않으면 그저 파일일 뿐이다.

3) 프로세스(process)

프로그램이 메모리에 올라가 실행 중인 상태다.

ls -l 을 실행하면,

운영체제는 /usr/bin/ls 프로그램을 메모리에 적재하고 실행한다.

이때 생기는 실행 단위를 프로세스라고 한다.

프로세스는 보통 PID(Process ID)를 갖는다.

정리하면 이 흐름이 핵심이다.

명령어(문자열)를 입력하면
→ 쉘이 프로그램(실행 파일)을 찾아 실행하고
→ 실행 중인 프로그램은 프로세스가 된다.

2. "명령어가 실행될 때 프로세스가 된다"는 말의 정확한 의미

조금 더 엄밀히 말하면, "명령어"가 프로세스가 되는 게 아니라:

명령어가 가리키는 프로그램이
운영체제에 의해 실행되어
프로세스가 된다.

즉, 프로세스는 "실행된 프로그램"이다.

3. ls , cat , rm 은 보통 "외부 프로그램"이다

대표적으로 ls , cat , rm 은 대부분의 리눅스에서

/usr/bin 아래에 있는 실행 파일이다.

확인 방법: type , which

type ls
which ls

type ls 는 ls 가 외부 프로그램인지, 쉘 내장(builtin)인지 알려준다.
which ls 는 ls 실행 파일이 어디 있는지 보여준다.

보통은 이런 결과가 나온다.

ls is aliased to ... (alias가 걸려있을 수도 있고)
ls is /usr/bin/ls

즉 ls 는 실제 실행 파일이 존재하고, 실행하면 프로세스로 실행된다.

4. 그런데 cd 는 왜 다르다고 할까?

cd 는 정말 중요하다. 많은 초보자가 여기서 한 번 헷갈린다.

1) cd 는 보통 "쉘 builtin"이다

cd는 디렉터리를 바꾸는 기능인데,

이 기능은 현재 쉘 프로세스의 작업 디렉터리를 바꿔야 의미가 있다.

만약 cd 가 /usr/bin/cd 같은 외부 프로그램이라면 어떤 문제가 생길까?

쉘이 cd 를 실행하기 위해 새 프로세스를 만든다.
새 프로세스에서 디렉터리를 바꾼다.
프로세스가 종료된다.
원래 쉘은 그대로다.

즉, "디렉터리를 바꿨는데도 터미널의 위치가 안 바뀌는" 이상한 상황이 된다.

그래서 cd 는 현재 쉘 안에서 직접 실행되는 내장 명령(builtin) 이어야 한다.

2) 확인해보기

type cd

대부분 이런 결과가 나온다.

cd is a shell builtin

정리하면:

cd 는 명령어이긴 하지만, 보통 외부 실행 파일이 아니라 쉘 내부 기능
실행 시 새 프로세스를 만들지 않고 현재 쉘 프로세스가 직접 처리

5. echo 는 프로그램일까? builtin일까?

echo 는 재미있는 케이스다. 환경에 따라 다를 수 있다.

많은 쉘에서 echo 는 builtin이다.
동시에 /usr/bin/echo 같은 외부 프로그램도 존재할 수 있다.

확인

type echo
which echo

type echo 에서 builtin이라고 나오면, 보통 별도 프로세스 없이 쉘이 처리한다.
\echo 처럼 백슬래시를 붙이면 alias/builtin을 우회하는 경우도 있다.
/usr/bin/echo 를 직접 호출하면 외부 프로그램 프로세스가 실행된다.

즉 echo 는 "항상 프로그램/항상 프로세스"라고 단정하기 어렵고,

어떤 echo를 쓰느냐가 중요하다.

6. 프로세스가 생기는 순간: 쉘은 무엇을 할까?

외부 프로그램( ls , cat , rm 등)을 실행할 때,

쉘은 보통 이런 흐름으로 동작한다.

사용자가 명령어 입력
쉘이 파싱(parsing)
리다이렉션 설정(필요하면 파일 디스크립터 변경)
새 프로세스 생성( fork )
새 프로세스가 프로그램 실행( exec )
프로그램 종료 후 쉘로 복귀

여기서 중요한 건:

리다이렉션( > , < , 2> , 2>&1 등)은 보통 프로그램 실행 전에 쉘이 설정
그래서 프로그램 입장에서는 "그냥 stdout/stderr에 출력했을 뿐"인데, 실제로는 파일로 들어간다.

7. 한 장 표로 정리: cd, ls, cat, echo, rm

명령어보통 정체실행 파일 존재?실행 시 프로세스 생성?

명령어	보통 정체	실행 파일 존재?	실행 시 프로세스 생성?
cd	쉘 builtin	보통 없음	보통 X (현재 쉘이 처리)
ls	외부 프로그램	/usr/bin/ls	O
cat	외부 프로그램	/usr/bin/cat	O
rm	외부 프로그램	/usr/bin/rm	O
echo	builtin 또는 외부	/usr/bin/echo 있을 수 있음	상황에 따라 O/X

8. 마무리: "명령어"를 보면 무엇을 떠올리면 좋을까?

리눅스에서 어떤 명령어를 봤을 때 이렇게 생각하면 헷갈림이 확 줄어든다.

내가 입력한 건 "명령어 문자열"이다.
이 명령어가 가리키는 대상은:
- 외부 프로그램일 수도 있고 ( /usr/bin/... )
- 쉘 builtin일 수도 있다.
외부 프로그램이면:
- 실행 순간 운영체제가 프로세스를 만든다.
builtin이면:
- 현재 쉘 프로세스가 내부적으로 처리한다.

이 관점으로 보면 cd 가 왜 특별한지,

리다이렉션이 왜 쉘의 기능인지,

echo 가 왜 환경마다 다르게 느껴지는지까지 한 번에 연결된다.

[Ncloud 1기] 6주차 회고 및 전체를 돌아보며

hwangsoojin — Sat, 29 Nov 2025 20:51:26 +0900

작성일: 2025.11.29

학습 주제: NCA 자격시험 대비 모의고사
작성자: 황수진(컴퓨터과학부)

6주차는 네이버클라우드 아카데미 과정의 마지막 주차였다.
6주차 회고이면서 전체 과정에 대한 회고이기 때문에 이전에 따랐던 형식을 따르지 않고 작성해보려고 한다.

1. 6주차 - NCA 자격 시험 대비 모의고사 응시 & 문제 풀이

6주차 수업에서는 NCA 자격시험을 대비한 모의고사를 실제 시험처럼 풀어보았다.
시험을 코앞에 두고 있어서 나름대로 열심히 준비하고 싶었지만,

상황은 생각보다 녹록지 않았다.

학교에서는 전공 팀프로젝트 발표가 다가오고 있었고,

여러 과제들이 동시에 몰리면서 공부 시간을 확보하는 게 쉽지 않았다.

그래도 "떨어지면 안된다"는 마음 하나로

모을 수 있는 자투리 시간을 모조리 모아 공부했다.
학교 수업 쉬는 시간에 네이버클라우드 아카데미에서 배포해주신 강의자료를

읽으면서 암기해야 할 사항들을 워드 파일로 정리해나갔다.

통학길 지하철에서는 그 정리한 자료를 반복해서 읽었다.

3시간 정도의 왕복 통학 길이니 그 시간들을 모으면 꽤 많은 시간이 모인다.

모의고사 점수를 확인했을 때는 안도의 한숨을 쉬었다.

부족한 시간이었지만 준비를 잘 했구나라는 생각이 들었다.

모의고사가 끝난 뒤 강사님의 문제풀이까지 더해지니

실제 시험날에는 NCA를 분명히 취득할 수 있겠다는 생각이 들었다.

2. 네이버 클라우드 아카데미 - 진로를 바꾸게 된 프로그램

아카데미에 처음 지원할 당시에 나는 백엔드 개발 공부를 하고 있었고

진로도 백엔드 개발자쪽으로 생각하고 있었다.
하지만 늘 "클라우드 기반 지식이 부족하다"는 생각이 머릿속에 자리 잡고 있었고,
혼자 자료를 찾아 공부하는 것은 항상 중간에 흐름이 끊기곤 했다.
그래서 학과 카톡방에서 네이버클라우드 아카데미 모집 공지를 봤을 때,
이 기회는 놓치면 안 된다는 생각이 들었다.

6주 동안 매주 5시간씩 들은 수업은 생각보다 훨씬 더 몰입감 있는 경험이었다.
이영태 강사님의 설명은 실무 이야기가 자연스럽게 녹아 있어서 이해가 잘 되었고,
수업이 끝난 후 복습과 개인 실습을 하다 보면 어느새 시간이 훌쩍 지나 있었다.

복습과 개인 실습을 진행하면서

'네트워크 공부가 이렇게 재밌었나?'싶을 정도로 푹 빠져서 했던 것 같다.

학교에서 들었던 네트워크 과목들은 이렇게까지 재미있는 공부는 아니었던 것 같은데....

학교다니면서 들었던 어떠한 전공과목보다도 분명 유익했던 것 같다.

클라우드 공부를 하면서

'내가 지금까지 백엔드 개발 공부를 이렇게 재밌게 해본 적이 있었나?'라는 생각이 들면서

매주차를 거듭할수록 백엔드 개발자가 아니라

클라우드 엔지니어가 되고 싶다는 생각이 굳어지고 있었다.

학교에서 들었던 네트워크 수업들과는 분명히 느낌이 달랐다.
이번 교육은 "운영환경에서 실제로 어떤 일이 일어나는지"를 눈으로 직접 보면서

배우는 과정이었기 때문에 훨씬 생생했고 재미있었다.

진로에 대한 생각이 바뀐

가장 결정적인 순간은 5주차의 3-Tier 아키텍처 구현 미니 프로젝트였다.
나는 팀에서 백엔드와 인프라 구성을 모두 맡았고,
개발을 할 때는 생기없던 내가

클라우드 인프라를 구현하는 과정에서는 눈에 생기가 도는 나를 발견했다.

내가 이 일을 즐기고 있다는 걸 깨달은 순간,

"클라우드 엔지니어가 되어야겠다."는 마음을 먹었다.

3. 프로그램 전반에서 좋았던 점

① Slack으로 운영진과의 원활한 소통
슬랙이라는 프로그램으로 강사님과 운영진분들과 소통하였다.

공부하다가 궁금한 점은 강사님께 질문하였고 친절히 답변주셨다.

운영진분들께서 주목할만한 클라우드 관련 기사도

실시간으로 공유해주시고 채용 공고도 공유해주셨다.

프로그램 내에서 지속적으로 관리받고 있다는 기분이 들어서

강사님과 운영진분들께 감사했다.

② 비용 걱정 없는 실습 환경
클라우드에서 실습하려면 과금이 늘 부담된다.
하지만 교육 계정 덕분에 마음껏 서버를 만들고 삭제하고 Auto Scaling도 설정해보고
SSL VPN까지 직접 연결해보는 등 실제 운영 환경에 가까운 경험을 할 수 있었다.

분명히 책으로는 배울 수 없는 살아있는 경험이었다.

③ 저혈당 방지
매주 5시간이라는 꽤 긴 시간의 수업이기 때문에

체력적으로 분명히 지치고 피곤한 순간들이 있었는데

당 떨어지는 일은 절대 없었다.

항상 풍족한 과자를 구비해주셨고 다 떨어지면

그만큼의 양을 또 새로 구비해주셨다.

저혈당을 막았다. 정말 감사합니다.

④ 교육 이후 예정된 네이버 1784 투어
지금도 기대되는 부분 중 하나다.
실제 현장에 가보는 것은 처음이라 기대된다.

4. 아쉬웠던 점

"좋았던 점" 항목이 있으면 밸런스를 맞추기 위해

아쉬웠던 점도 항목 넣어야 할 것 같아서 넣긴 했는데

사실 아쉬웠던 점에 대해서는 크게 생각나는 게 없다.

전체적으로는 만족도가 매우 높은 교육이었다.

5. 마무리하며

6주 동안 아낌없이 가르쳐주신

이영태 강사님, 김지용 강사님께 진심으로 감사드립니다.

또한 질문에 항상 친절히 답변해주시고,

실습 환경까지 세심하게 지원해주신 운영진 분들께도 감사드립니다.

[NCloud 1기] NCP Auto Scaling이 실제로 발동한 날

hwangsoojin — Tue, 25 Nov 2025 17:57:52 +0900

교육 계정의 자동 정지 정책 때문에 예상치 않게 서버가 두 배로 늘어난 사례

네이버클라우드 아카데미 교육 계정을 사용하다가
어느 날 콘솔에서 예상치 못한 장면을 마주했다.
원래 WEB 2대, WAS 2대 총 4대만 있던 서버가
갑자기 8대로 늘어나 있는 것을 발견한 것이다.

1. 아침에 콘솔을 열어보니, 서버가 8대?

어느날 NCP 콘솔의 Server 탭을 눌러보니
서버 목록이 갑자기 길게 늘어나 있었고, 순간 멈칫했다.
"원래 4대였는데… 왜 8대지?"

유심히 보니 다음과 같은 상태였다.

기존 서버 4대 → 정지 상태
정체불명의 4대 → 운영 중

그리고 운영 중인 서버들의 이름을 보는 순간
이유를 바로 떠올릴 수 있었다.

운영 중인 서버 이름이
webauto-xxxx , wasauto-xxxx 형태였기 때문이다.
이 접두사(prefix)는 Auto Scaling Group을 만들 때
내가 직접 설정했던 값이었다.

✔ prefix란?

서버를 자동 생성할 때
*자동 생성 인스턴스 이름 앞에 붙는 고정 문자열(접두사)이다.
NCP에서 Auto Scaling으로 생성되는 서버는
prefix-랜덤문자 형식으로 이름이 붙는다.
그래서 한눈에 "아, 이건 Auto Scaling이 만든 서버구나"를 알 수 있다.

2. 왜 Auto Scaling이 발동했을까?

내 계정은 교육용 계정이라 매일 특정 시간대가 되면
계정이 생성한 서버가 자동으로 정지된다.
자원 낭비를 막기 위한 정책이다.

그 결과,
내가 수동으로 생성해 두었던 WEB 2대, WAS 2대가
밤새 전부 자동 정지되었다.

그런데 문제는 …

Auto Scaling Group은 “최소 용량 2대 유지”로 설정해 두었다는 점이다.

즉, Auto Scaling 입장에서는 이렇게 판단한다.

“헬스 체크 실패”
“현재 서버 수: 0대”
“최소 용량: 2대 → 빨리 채워야 한다”

그래서 WEB 2대, WAS 2대가
Auto Scaling에 의해 새로 생성된 것이었다.

3. 실제 Auto Scaling Group의 최소 용량 설정

Auto Scaling Group 목록을 확인해 보니
두 그룹 모두 최소 용량이 2로 설정돼 있었다.

이 설정 때문에
기존 서버가 자동 정지되자마자 Auto Scaling이
"2대를 채워야 한다"며 신규 서버를 만들었던 것이다.

4. Auto Scaling Group을 만들 때 설정했던 내용

Auto Scaling Group을 생성할 때,
나는 다음과 같이 설정했었다.

서버 이름 Prefix = webauto
최소 용량 = 2
기대 용량 = 2
최대 용량 = 3

이때 설정한 Prefix(webauto) 가
새로 생성된 서버 이름에 그대로 붙어 있었기 때문에
"아, Auto Scaling이 발동했구나" 하고 바로 파악할 수 있었다.

5. Auto Scaling에 일정(Schedule)도 걸어두었었다

서버를 구축할 당시에 다음과 같은 요구사항을 충족하기 위해
Auto Scaling 일정도 설정해 두었었다.

"매달 1일부터 3일까지 자격증 신청 기간입니다.
해당 기간에는 WEB, WAS 서버를 3대까지 늘려주세요."

그래서 일정 정책을 이렇게 구성했다.

매달 1일 00:00 → 기대 용량 3대로 증가
매달 4일 00:00 → 다시 기대 용량 2대로 감소

즉, 원래는 특정 기간에만 서버를 늘렸다가 다시 원래대로 돌아오는
스케일링 목적으로 설정해 둔 정책이었다.

6. 그런데 실제로는 "서버 다운 복구"에도 작동했다

나는 Auto Scaling이
주로 트래픽 증가 또는 주기적 스케일링을 기준으로 동작할 것이라고만 생각했다.

하지만 이번 사례처럼
서버가 모두 정지돼 헬스 체크에 실패한 상황에서도
최소 서버 수를 맞추기 위해 자동으로 복구된다는 것을 직접 확인했다.

굉장히 신기했다.

마무리

이 경험을 통해 Auto Scaling이 단순히
"서버를 필요할 때 늘렸다 줄이는 기능"을 넘어서

헬스 체크 실패
서버 다운
강제 정지
장애 상황

이런 환경에서도 최소한의 서버 수를 유지하도록 자동 복구해 준다는 점을 명확히 이해할 수 있었다.

교육 계정의 자동 정지 기능 때문에 발생한 일이었지만
결과적으로 Auto Scaling의 핵심 기능을
가장 명확하게 확인할 수 있었던 사례였다.

자동 정지 감사합니다 ...

[NCloud 1기] 5주차 회고

hwangsoojin — Tue, 25 Nov 2025 17:47:28 +0900

5주차 회고

작성일: 2025.11.25

학습 주제: 3-Tier 아키텍처 설계 및 구현 미니 프로젝트

실습 환경: NCP Console + PuTTY + WinSCP

작성자: 황수진_컴퓨터과학부

이번 주차에서는 3-Tier 아키텍처를 직접 구성해보는 팀 프로젝트를 진행했다.
3명으로 팀을 구성했고, 역할은 아키텍처 설계 / 백엔드 / 프론트엔드로 나눴다.
나는 백엔드를 맡아서 API 설계, 구현, 배포까지 담당했다.

1. KEEP (유지할 점)

1-1. 피드백을 바로 반영한 아키텍처 구조도 개선

프로젝트 결과를 발표했을 때,

강사님께서 전체적인 완성도는 좋다고 칭찬을 해주셨다.
다만 보완할 점으로,

우리 팀의 아키텍처 구조도가 눈으로 보기에 너무 복잡하다는 지적을 받았다.

선이 지나치게 많이 교차하고 있고
각 계층이 한 번에 눈에 들어오지 않으며
처음 보는 사람이 보면 흐름을 파악하기 어려운 그림이었다.

다른 팀들의 아키텍처 다이어그램이 생각보다 훨씬 깔끔해서,

발표를 들으면서 많이 반성했다.
아키텍처 구조 자체만 맞으면 된다고 생각했는데,

실제로는 이 구조도를 보는 사람(고객사, 다른 팀원, 운영자)이 한눈에 이해할 수 있게

그려져 있는지가 더 중요할 수 있다는 점을 깨달았다.

그래서 발표가 끝났다고 그냥 넘기지 않고,

수업이 끝난 뒤에 구조도를 스스로 다시 그려보았다.

불필요하게 교차하는 선 정리
WEB / WAS / DB / Edge / Security / Monitoring 등 역할별 영역 재배치
관리자 경로(SSL VPN, IDS, Cloud Insight)의 흐름도 따로 눈에 띄게 정리

이렇게 다시 그려보는 과정에서, 나 스스로도 아키텍처를 더 잘 이해하게 되었다.
이미 우리 팀 아키텍처 구조를 잘 이해하고 있다고 생각했지만,

보기 좋은 그림으로 재구성하다 보니 세부 흐름이 더 선명하게 정리되는 경험을 했다.
앞으로도 아키텍처를 설계할 때는

"맞게 만드는 것"과 동시에

"보기 좋게 설명할 수 있는 것"까지 항상 함께 고민해야겠다고 느꼈다.

1-2. 배운 내용을 꾸준히 기록으로 남긴 습관

5주차는 단순히 기능만 구현하는 것으로 끝내지 않았다.
로드밸런서, Auto Scaling, SSL VPN, Object Storage, Image Optimizer 등

과금 걱정없이 다양한 NCP 서비스를 동시에 다루는 경험이 너무 소중하다 보니

이 경험, 배운 내용, 문제점을 모두 기록하고 싶었다.

그래서 프로젝트를 진행하면서 다음과 같은 습관을 유지했다.

각 단계에서 콘솔 화면을 캡처
문제가 생긴 에러 메시지를 그대로 저장
해결 과정을 티스토리 글로 정리

사람은 금방 잊어버리는 존재라,

"지금은 당연히 기억하겠지"라고 생각한 내용도 며칠 지나면 흐릿해진다.
나중에 비슷한 인프라를 다시 구성하거나,

3-Tier 구조를 발전시킬 일이 생겼을 때

이 기록들이 큰 도움이 될 것 같아서 꾸준히 남겨 두었다.

아래 글들은 이번 3-Tier 프로젝트를 진행하면서 남긴 기록들 중 그 일부를 공유한다.

전체 아키텍처를 어떻게 설계하고,

어떤 순서로 구성했는지 정리하였습니다.

[NCloud 1기] Naver Cloud Platform으로 3-Tier 아키텍처 구성하기

SSH 세션에 종속된 프로세스,

nohup 실행 방식 등을 정리하였습니다.

[NCloud 1기] PuTTY를 끄고 나니 NCP 서버의 Spring Boot가 죽어버린 문제

재부팅 후 프로세스 자동 실행, 서버 이미지에 대한 오해,

systemd 도입까지 정리하였습니다.

[NCloud 1기] 서버를 껐다 켰더니 백엔드가 사라졌다

이 습관은 앞으로

"단순히 공부를 하면서", "다른 프로젝트를 하면서"도 유지하고 싶은 부분이다.

2. PROBLEM (어려웠던 점)

2-1. 예상보다 훨씬 많은 시간과 에너지를 쏟아야 했던 미니 프로젝트

처음 이영태 강사님의 안내를 들었을 때는

"부담 갖지 않고 경험 위주로 진행해도 된다"라는 말이 있어서,

비교적 가벼운 미니 프로젝트라고 생각했다.
하지만 실제로는 월요일에 아키텍처 초안이 확정된 이후,

화요일부터 금요일 오전까지 거의 내내 개발과 배포에 시간을 쏟아야 했다.

실제 개발 과정에서도 에러도 많이 났었고

로컬에서 되던 것이 클라우드 서버에서는 안 되기도 하였다.

꽤 헤맸던 것 같다.

그런데 실제로 에러를 만나고,

로그를 뒤지고,

설정을 하나씩 바꿔가며 트러블슈팅하는 동안

클라우드에 대한 이해도가 이전과 비교도 안 될 정도로 올라갔다.

스트레스도 컸지만, 프로젝트가 끝난 뒤에는

"이걸 안 해봤으면 어쩔 뻔했나" 싶을 정도로 성장한 느낌이었다.

2-2. Image Optimizer 연동 과정에서의 쿼리스트링 실수 지옥

이번 프로젝트에서는 NCP Image Optimizer를 이용해

업로드된 이미지를 300x300 사이즈로 리사이즈하는 기능을 구현했다.

문제는, 이 Optimizer API를 처음 연동할 때였다.

문서를 자세히 읽었다고 생가하였고 그것을 바탕으로 구현했더니,

계속 이런 식의 에러가 떨어졌다.

HTTP 400 Bad Request
파라미터 누락 오류 메시지

원인은 요구하는 "쿼리스트링"을 제대로 만족시키지 못한 코드를 짰기 때문이었다.

문서를 제대로 읽었다고 생각했는데...

내가 미처 읽지 못한 부분에서

쿼리스트링 형식에 대한 디테일이 살아있었다.

이 디테일을 찾지 못해서 헤메다가 낭비한 시간이

4-5시간은 됐던 것 같다...

"API 연동은 문서를 꼼꼼히 읽는 것으로 개발을 시작해야 한다"는

아주 기본적인 사실을 몸소 체험했다.

3. TRY (개선할 점 / 앞으로 시도할 것)

3-1. 에러는 당연하되, 스트레스 관리도 함께 가져가기

개발이라는 것은 결국 에러와 로그, 트러블슈팅의 연속이다.
이번에도 여러 문제를 해결하면서 얻은 게 많았지만,

"기한 안에 배포를 못 끝내면 어떡하지?"라는 불안감 때문에

과하게 스트레스를 받기도 했다.

앞으로는 에러는 당연한 것으로 인정하고

조금 더 행복하고 여유 있게 프로젝트를 진행하는 연습이 필요하다고 느꼈다.

3-2. 초반 설계 단계에서 다이어그램과 API 문서를 더 철저하게

이번 프로젝트를 돌아보면, 초반 설계와 문서 읽기 단계를 좀 더 탄탄하게 가져갔으면 좋았을 것 같다는 아쉬움이 있다.

아키텍처 다이어그램은 기능 구현이 어느 정도 끝난 뒤에야
본격적으로 다듬기 시작했고
Image Optimizer 연동도 문서를 충분히 읽기 전에 코드를 먼저 짜기 시작했다.

다음에는 이렇게 해보고 싶다.

아키텍처 초안을 그릴 때부터 "보기 좋은 구조도"를 목표로 잡고,
팀원들과 더 많이 리뷰하기
설계/문서 단계와 구현 단계를 조금 더 명확하게 분리하기

이렇게 하면 불필요하게 헤매는 시간을 줄이고,

더 중요한 부분에 에너지를 쓸 수 있을 것 같다.

4. 느낀 점 (Reflection)

네이버클라우드 아카데미를 수강하기 전과 후를 비교하면,

이론 교육만으로도 이미 클라우드에 대한 이해도는 많이 올라와 있었다.
하지만 5주차 미니 프로젝트는 그 위에 실제 경험을 한 층 더 쌓아 올려 준 시간이었다.

WEB / WAS / DB로 나뉜 3-Tier 구조를 직접 구성하고
로드밸런서, Auto Scaling, SSL VPN,
Cloud DB, Object Storage, Image Optimizer까지 연결해서
실제 외부 사용자에게 노출할 수 있는 형태의 서비스를 만들어 본 경험은,
학교 수업만으로는 얻기 어려운 경험이었다.

과금 걱정 없이 서버를 만들었다가 지워 보고,
설정을 바꿔 보고, 잘못 구성해서 망가뜨려 보기도 했다.
이 과정이 나를 "설명만 들은 사람"에서 "직접 운용해 본 사람"으로 바꿔 준 것 같다.

5주차가 끝난 지금,

클라우드 인프라를 바라보는 시야가 분명히 한 단계 넓어졌다.
이번 경험을 발판 삼아,
앞으로는 더 큰 규모의 아키텍처와 더 복잡한 시스템에도 도전해 보고 싶다.

SQLD 59회 응시 후기 – 대학생, 일정 지옥 속에서도 도전하다

hwangsoojin — Mon, 24 Nov 2025 23:26:11 +0900

이번 학기, 정말 정신이 없었다.
전공 과목만 해도 벅찬데,

소프트웨어공학 팀플,

우테코 프리코스 오픈 미션,

네이버클라우드 아카데미 실습 프로젝트까지…
게다가 중간중간 학교 과제, 발표, 포트폴리오 준비까지 이어지니 하루가 어떻게 지나가는지도 모르겠더라.

그럼에도 데이터베이스 전공과목을 수강하고 있는 지금..!
“지금이 아니면 SQLD를 이렇게 수월하게 준비할 시기가 또 올까?”

라는 생각이 갑자기 들었다.

그리고 그냥 해버렸다.
SQLD 59회 시험(2024.11.16) 응시.

솔직히 미쳤다 싶었다.
하지만 이상하게 후회는 안 된다.

1. 시험 접수 & 준비 - 나의 SQLD 도전 동기

나는 이번 학기에 데이터베이스 전공 과목을 듣고 있었다.
수업 내용이 SQLD 범위와 많이 겹치길래, ‘이왕 공부하는 거 자격증 하나 따두자’는 생각이 들었다.

자격증 하나라고 해서 부담 없는 건 아니었다.
하지만 개발자로 진지하게 준비하는 지금, 나를 한 단계 더 밀어붙일 타이밍이라고 느꼈다.

시험 당일엔 나도 이런 말을 중얼거렸다.

“그래도… 여기까지 온 것도 대단한 거 아니냐?”

2. 공부 방법 - 지하철, 새벽, 강의실 사이에서 틈틈이

본격적인 공부는 한 달 정도.
하지만 ‘몰아서 공부한 한 달’이 아니라
지옥 일정 속에서 가능한 시간들을 다 긁어서 만든 한 달이었다.

지하철 통학 시간 = 기출 한 세트
팀플 끝나고 카페 = 조인·집계 정리
오픈 미션 JSON 분석 코드 짜다 머리아플 때 = SQL 문법 복습
NCP 서버 생성 기다리는 동안 = 정규화 외우기
새벽 3시 = "아… IN이냐 EXISTS냐…"

정말 ‘틈틈이’의 극한 버전이었다.

3. 사용 교재 - 전공 수업 ppt + 노랭이 책 + 기출

딱 두 가지만 했다.

1. 전공 ppt 정독하고 개념 잡기
SQLD는 개념만 잘 잡아도 절반 이상은 간다.
특히 전공 ppt에는 조인이나 정규화와 같은 빈출 개념이 정리가 잘 되어 있었다!

2. 노랭이 책 (SQLD 수험서)
핵심 정리 + 기출 유형 감 익히는 데 최고였다.

4. 내가 만든 공부 자료들 - “이해를 위해 직접 정리한 SQL 노트”

사실 책만 봤다면 이렇게 오래 기억에 남진 않았을 것 같다.
그래서 내 방식대로 다시 정리했다.
필기하면서 손이 기억하게 만드는 스타일.

아래 사진들은 내가 실제로 정리한 SQL 노트들이다.
이걸 기반으로 SQL 개념을 완전히 ‘내 것’으로 만들었다.

4-1. 조인과 서브쿼리 – 직접 손으로 그려가며 이해한 방식

이 필기는

JOIN과 서브쿼리의 차이
IN / EXISTS / ALL / ANY
조인 조건의 의미
를 정리하면서 만든 것이다.

특히

FROM a INNER JOIN b ON 조건

이 공식은 그냥 외우는 것보다
왜 저 구조가 되는지를 그림으로 이해하면 훨씬 오래 남는다.

4-2. FROM → WHERE → GROUP BY → HAVING → SELECT 실행 순서

이건 SQL이 어떤 순서로 실행되는지를
직접 단계별로 풀어쓴 노트다.

SQL은 작성 순서가 아니라 “실행 순서”가 훨씬 중요하다.

FROM
WHERE
GROUP BY
HAVING
SELECT
ORDER BY
LIMIT

이 흐름만 이해해도 기출의 절반은 설명 가능하다.

4-3. DDL / DML 핵심 정리

시험 직전까지 보고 들어간 건 아마 이것.
특히 외래키 제약 조건 옵션

5. 시험 당일 – 피곤과 긴장의 콜라보

시험장에 가는 길, 솔직히 너무 졸렸다.
전날까지 우테코 오픈 미션 리팩터링하고

NCP 프로젝트 문서 만들고
팀플 발표 준비까지 하느라 거의 못 잤다.

그런데도 이상하게 마음은 차분했다.
“그래도 내가 할 건 다 했다”는 느낌이 있었기 때문이다.

시험장 내 자리에 앉아서 최종 복습..ㅋㅋ

문제 난이도는

개념 파트: 무난
SQL 파트: 좀 꼬아낸 문제 존재
전체 난이도: 예상보다 살짝 어려움

그래도 시간은 넉넉하게 풀었다.

6. 결과는? (아직 발표 전)

SQLD 59회는 아직 발표가 나지 않았다.
그래서 긴장되는 마음으로 기다리는 중이다.

합격하면 좋겠지만,
이 시험을 준비하면서 느낀 건 딱 하나였다.

“배운 만큼 성장한다는 걸 오랜만에 깊게 체감했다.”

이 바쁜 일정 속에서도 책 붙잡고 문제 풀며
모르는 개념 이해하려고 씨름했던 시간들 자체가
이미 나에게 큰 자산이 되었다.

7. 마무리 – 다음 목표는?

SQLD 준비하면서
“아, 내가 점점 나아지고 있구나”라는 감각이 들었다.
그게 너무 좋았다.

다음 목표는 SQLP?
아직은 생각 없다.

지금은 우테코 프리코스 완주부터…

그리고 NCP 아키텍처 프로젝트 발표까지 해야 하니까.

그래도,
한 달 동안 SQL과 정말 친해졌다!!

읽기 두려운 SQL문은 이제 거의 별로 없는...

읽어줘서 고맙습니다 :)

시험 결과 나오면 바로 후기 업데이트할게요~

JSON DTO Converter (4) - Exception 분석

hwangsoojin — Mon, 24 Nov 2025 18:25:52 +0900

UserException · InternalException · main() 예외 처리 흐름까지

이 글은 JSON DTO Converter 프로젝트의 예외 처리 계층(exception 패키지)를 정리한 글이다.

앞선 글들에서

CLI 계층: 잘못된 옵션/경로를 어떻게 막는지
JSON 분석 계층: JSON 구조를 어떻게 스키마로 바꾸는지
Generator 계층: 설계도를 실제 .java 파일로 만드는지

를 다뤘다면,

이 글은 "그 과정에서 발생하는 오류를 어떻게 분류하고, 사용자에게 어떻게 보여줄 것인가"에 초점을 둔다.

0. 왜 예외 설계가 중요한가?

CLI 도구 특성상, 예외 설계는 곧 사용자 경험(UX) 이다.

잘못된 인자, 없는 파일, 깨진 JSON 같은 "사용자가 고칠 수 있는 오류"
버그, 구현 누락, 설계 상 발생하면 안 되는 상태 같은 "개발자가 고쳐야 하는 오류"

를 같은 방식으로 출력하면:

사용자는 "내가 뭘 잘못한 건지" 알 수 없고
내부 버그가 발생했을 때도 조용히 묻힐 수 있다.

그래서 이 프로젝트에서는 예외를 두 축으로 나눴다.

1. 사용자가 고칠 수 있는 오류 → UserException
2. 코드/설계 버그 → InternalException

이 둘을 분리해두면, main() 에서 처리 전략도 명확해진다.

1. exception 패키지 구조

org.example.exception 패키지는 단 두 개의 클래스로 이루어진다.

org.example.exception
 ├─ UserException.java
 └─ InternalException.java

심플하지만, 이 두 클래스가 예외 설계 방향을 완전히 갈라 놓는다.

2. UserException — "사용자가 수정할 수 있는 오류"

2-1. 개념

UserException은 말 그대로

"사용자가 입력을 바꾸면 해결할 수 있는 오류"

를 나타낸다.

예를 들면:

--input 에 존재하지 않는 파일 경로를 넣었다
JSON 문법이 잘못된 파일을 입력했다
--inner-classes maybe 처럼 허용되지 않는 값을 넣었다
--out 디렉터리가 쓰기 권한이 없다

이런 것은 사용자가 명령을 고쳐서 다시 실행하면 해결되는 문제다.

따라서:

내부 스택 트레이스를 장황하게 보여줄 필요가 없고
짧고 맥락 있는 오류 메시지만 써도 충분하다.

예시 메시지:

[ERROR] 입력 JSON 파일을 찾을 수 없습니다: input/not-exists.json
[ERROR] --inner-classes 옵션은 true/false만 허용합니다: maybe
[ERROR] JSON 파싱에 실패했습니다. 파일 형식을 다시 확인해주세요: broken.json

2-2. 구현 형태

UserException은 보통 이렇게 구현한다(실제 구현과 개념적으로 동일):

package org.example.exception;

public class UserException extends RuntimeException {

    public UserException(String message) {
        super(message);
    }

    public UserException(String message, Throwable cause) {
        super(message, cause);
    }
}

특징:

RuntimeException 을 상속 → 체크 예외처럼 매번 throws 선언 강제하지 않음
message는 사용자에게 그대로 보여줄 전용 메시지로 사용
필요하면 cause를 함께 넘겨 내부 디버깅에 활용할 수 있음

2-3. 어디서 UserException을 던지는가?

프로젝트 전반에서 "사용자가 잘못 입력하면 발생할 만한 곳"은 전부 UserException의 후보이다.

대표적으로:

ArgumentParser
- 필수 옵션 누락
- 옵션 이름 오타
- --inner-classes 값이 true/false가 아닌 경우
JsonValidator
- 입력 파일이 없음
- 디렉터리를 파일로 건넴
- JSON 파싱 실패
- 루트가 객체/배열이 아닌 경우
FileWriter
- 출력 디렉터리 권한 없음
- 파일 쓰기 실패

예를 들어 FileWriter에서는 이런 식으로 예외를 래핑할 수 있다.

public void write(Path outDir, String className, String content) {
    Path file = outDir.resolve(className + ".java");
    try {
        Files.writeString(file, content, StandardCharsets.UTF_8);
    } catch (IOException e) {
        throw new UserException(
            "[ERROR] Java 파일을 저장하는 중 오류가 발생했습니다: " + file, e
        );
    }
}

여기서 IOException은 사용자가 경로/권한을 바꾸면 해결될 수도 있는 문제이므로
UserException으로 감싸는 쪽에 가깝다.

3. InternalException — "이건 버그다, 사용자가 아니라 개발자의 책임"

3-1. 개념

InternalException은 설계 상 "여기까지 오면 안 된다" 수준의 문제에 사용한다.

예를 들면:

SchemaPrimitive 에 정의되지 않은 PKind가 들어왔다
SchemaUnion 에서 처리해야 할 케이스를 빼먹었다
TypeInferencer가 지원하지 않는 SchemaNode 타입을 만났다
ModelGraph에서 null이 되어선 안 되는 값이 null이 됐다

이건 사용자가 뭘 잘못한 게 아니라,
내가(개발자)가 코드를 잘못 짠 것이다.

따라서:

사용자에게는 "내부 오류입니다"라고 알려야 하고
동시에 스택 트레이스도 출력해서 개발자가 디버깅할 수 있어야 한다.

3-2. 구현 형태

InternalException도 UserException과 비슷하게 구현하되, 의미만 다르다.

package org.example.exception;

public class InternalException extends RuntimeException {

    public InternalException(String message) {
        super(message);
    }

    public InternalException(String message, Throwable cause) {
        super(message, cause);
    }
}

핵심은 의미적 차이다:

UserException: 사용자 입력 잘못
InternalException: 프로그램 내부 상태/설계 오류

3-3. 어디서 InternalException을 던지는가?

예를 들어 TypeInferencer가 SchemaNode를 처리할 때:

TypeRef infer(SchemaNode node) {
    if (node instanceof SchemaPrimitive primitive) {
        // ...
    } else if (node instanceof SchemaObject object) {
        // ...
    } else if (node instanceof SchemaArray array) {
        // ...
    } else if (node instanceof SchemaUnion union) {
        // ...
    } else {
        // 여기 오면 안 된다 = 새로운 서브타입이 추가됐는데 처리 안 한 것
        throw new InternalException(
            "[INTERNAL] 지원하지 않는 SchemaNode 타입입니다: " + node.getClass()
        );
    }
}

이런 예외는 사용자에게 책임을 돌릴 수 없다.
"새로운 타입이 추가됐는데, 내가 처리 코드를 안 쓴 것"일 뿐이다.

이렇게 InternalException을 활용하면:

개발 중에 놓친 케이스를 빨리 발견할 수 있고
예외 메시지를 보고 "어디 부분이 설계 미스인지" 바로 알 수 있다.

4. main()에서의 예외 처리 전략

모든 예외 설계의 끝은 main() 에서 어떻게 처리하느냐로 귀결된다.

이 프로젝트에서는 대략 이런 구조를 가진다(의사코드):

public class Main {

    public static void main(String[] args) {
        try {
            // 1. CLI 인자 파싱
            ArgumentParser parser = new ArgumentParser();
            ParsedArguments parsed = parser.parse(args);

            // 2. JSON 파일 로드 및 검증
            JsonValidator.Result result =
                JsonValidator.validateAndLoad(parsed.getInputPath());

            // 3. JSON 구조 분석 → SchemaNode
            JsonAnalyzer analyzer = new JsonAnalyzer();
            SchemaNode rootSchema = analyzer.analyze(result.root());

            // 4. 타입 추론
            TypeInferencer inferencer = new TypeInferencer();
            // 타입 추론 + ModelGraph 구성
            ModelGraph graph = ModelGraph.from(rootSchema, parsed, inferencer);

            // 5. ClassSpec 리스트를 얻고, 각 클래스 생성
            ClassGenerator classGenerator = new ClassGenerator();
            CodeFormatter formatter = new CodeFormatter();
            FileWriter fileWriter = new FileWriter();

            for (ClassSpec spec : graph.getAllClasses()) {
                String raw = classGenerator.generate(spec);
                String formatted = formatter.format(raw);
                fileWriter.write(parsed.getOutDirPath(), spec.className(), formatted);
            }

        } catch (UserException e) {
            System.err.println(e.getMessage());
            System.exit(1);
        } catch (InternalException e) {
            System.err.println("[INTERNAL ERROR] 예기치 못한 오류가 발생했습니다.");
            e.printStackTrace();
            System.exit(2);
        }
    }
}

여기서 중요한 포인트 3가지:

4-1. UserException → 메시지만 출력, exit code 1

사용자 잘못이므로 message만 보여주면 충분
exit code 1은 "정상은 아니지만, 사용자가 입력을 고쳐서 다시 시도할 수 있음" 정도의 의미

예를 들어,

[ERROR] 입력 JSON 파일을 찾을 수 없습니다: input/not-exists.json

이 출력만 보고도 사용자는 "아, 경로가 잘못됐구나"를 알 수 있다.

4-2. InternalException → 안내 문구 + 스택 트레이스, exit code 2

사용자에게는 "내부 오류입니다" 정도만 안내
하지만 e.printStackTrace() 를 통해 개발자 입장에서는 디버깅 정보를 확인 가능
exit code 2는 “내부 버그”라는 의미로 구분

콘솔 출력 예:

[INTERNAL ERROR] 예기치 못한 오류가 발생했습니다.
org.example.exception.InternalException: [INTERNAL] 지원하지 않는 SchemaNode 타입입니다: class org.example.json.SchemaSomethingNew
    at org.example.json.TypeInferencer.infer(TypeInferencer.java:85)
    ...

이렇게 하면:

사용자는 "내가 뭘 잘못한 건 아니구나"를 알 수 있고
나는 스택 트레이스를 보고 어디를 고쳐야 할지 파악할 수 있다.

4-3. 왜 Exception을 전부 main()까지 올렸는가?

중간 계층에서 예외를 잡고 silent fail을 하면:

어디서 터졌는지
무슨 종류의 문제인지
사용자에게 뭐라고 알려야 하는지

를 놓치기 쉽다.

그래서 설계 방향을 이렇게 잡았다:

각 계층에서 "뜻이 있는 예외 타입(User/Internal)"을 던진다
최종적으로 main()에서 종류에 따라 딱 두 갈래로 처리한다

이 덕분에:

예외 흐름이 단순하고 예측 가능
exit code에 의미를 부여할 수 있음
나중에 스크립트/CI에서 exit code를 기준으로 실패 종류를 구분하기도 쉬움

5. 예외 설계와 9가지 예외 테스트 시나리오의 연결

별도의 글(《실행 가이드 & 9가지 예외 테스트 시나리오》)에서 정리한

--input 생략
존재하지 않는 파일
디렉터리/읽을 수 없는 파일
깨진 JSON ( broken.json )
루트가 숫자인 JSON ( root_number.json )
루트가 배열인 JSON ( root_array.json )
--root-class 빠짐
--package 빠짐
--inner-classes 값이 true/false가 아닌 경우

이 케이스들은 모두 UserException 계열이다.

즉, 이 9가지 케이스를 명시적으로 테스트해봄으로써:

"사용자가 실수할 수 있는 부분"을 대부분 커버했는지
모든 경우에 친절한 에러 메시지 + exit code 1로 떨어지는지

를 검증한 셈이다.

6. 이 예외 설계가 주는 장점 정리

책임 분리
- 로직에서 예외를 던질 뿐, "프린트/종료 방식"은 main에서만 결정
- 각 계층은 자기 도메인에만 집중 가능
사용자 경험
- 사용자가 잘못한 경우와,
- 도구 내부의 버그를 명확히 구분
  → "내가 뭘 잘못했지?"라는 불필요한 혼란 감소
디버깅 용이성
- InternalException일 때만 스택 트레이스를 출력
- 로그/콘솔에서 버그 지점을 빠르게 찾을 수 있음
테스트하기 좋은 구조
- 특정 입력 → UserException 발생 예상
- 잘못된 SchemaNode 타입 주입 → InternalException 발생 예상
  같은 테스트 케이스를 만들기 쉬움

7. 마무리 — 작은 도구에도 "예외 설계"는 중요하다

JSON DTO Converter는 규모가 큰 애플리케이션은 아니지만,
이 프로젝트를 통해 다음과 같은 것들을 직접 설계해볼 수 있었다.

사용자 오류와 내부 버그를 예외 계층에서 분리하는 전략
main()에서 예외를 한 번에 처리하는 정책
exit code에 의미를 부여하여 CLI 도구답게 동작시키는 방식
9가지 예외 시나리오를 직접 정의하고 테스트해보는 경험

단순히 "예외가 나면 터진다"가 아니라,

"예외가 나더라도, 사용자는 정확히 이유를 알고,
나는 내부 버그를 빠르게 추적할 수 있도록 설계하는 것"

이 이 프로젝트에서 예외를 설계할 때 가장 신경 썼던 부분이다.

JSON DTO Converter (3) - Generator & 출력 분석

hwangsoojin — Mon, 24 Nov 2025 18:00:44 +0900

Template · ClassGenerator · CodeFormatter · FileWriter로 이어지는 "코드 생성 파이프라인'

이 글에서는 JSON DTO Converter의 마지막 단계인 generator 계층을 집중적으로 다룬다.

앞선 글(Overview / CLI / JSON 분석)에서 우리는

CLI로부터 설정을 받아
JSON을 검사하고(JsonValidator)
JsonNode → SchemaNode → 타입 추론(TypeInferencer) → ModelGraph까지

왔다.

이제 남은 일은 단 하나다!

"설계도(ModelGraph)를 실제 Java 코드(.java 파일)로 바꾸는 것"

이 역할을 담당하는 것이 바로 generator 패키지다.

0. generator 패키지의 구성

org.example.generator 에는 다음 네 개의 핵심 클래스가 있다.

Template : 문자열 템플릿 엔진 ( ${name} 치환 )
ClassGenerator : ClassSpec → Java 소스코드 문자열 생성
CodeFormatter : 줄바꿈/공백/빈 줄 정리
FileWriter : 최종 문자열을 .java 파일로 저장

이 네 클래스는 서로 결합되어 다음과 같은 파이프라인을 만든다.

[ClassSpec]
   ↓ ClassGenerator
[raw Java source String]
   ↓ CodeFormatter
[formatted Java source String]
   ↓ FileWriter
[MyDto.java 파일]

1. Template — 최소한의 템플릿 엔진

1-1. 왜 직접 Template을 만들었나?

외부 템플릿 엔진(예: Freemarker, Velocity 등)을 쓰는 것도 방법이지만,

프리코스에서는 외부 라이브러리 의존도를 낮추는 것이 좋다고 판단했고,
"템플릿 엔진이 내부에서 어떻게 동작하는지" 이해하고 싶었고,
필요한 기능은 ${var} 치환 정도로 충분했다.

그래서 아주 작은 범위의 템플릿 기능만 직접 구현했다.

1-2. Template의 기본 구조

Template은 내부에 pattern 문자열을 하나 들고 있는 불변 객체다.

public class Template {

    private static final char DOLLAR = '$';
    private static final char OPEN_BRACE = '{';
    private static final char CLOSE_BRACE = '}';

    private final String pattern;

    public Template(String pattern) {
        this.pattern = Objects.requireNonNull(pattern, "pattern must not be null");
    }

    public String render(Map<String, String> variables) {
        StringBuilder result = new StringBuilder();
        // pattern을 순회하며 ${name}을 찾아 variables.get("name")으로 치환
        return result.toString();
    }
}

여기서 플레이스홀더는 다음 형태만 지원한다.

${className}
${package}
${fields}
${methods}
...

이 정도면 코드 생성용으로는 충분하다.

1-3. 템플릿 사용 예시

예를 들어 클래스 전체 구조 템플릿은 이런 식으로 설계할 수 있다.

String pattern = """
package ${package};

${imports}

public class ${className} {

${fields}

${methods}
}
""";

Template t = new Template(pattern);
String source = t.render(Map.of(
    "package", "com.example",
    "imports", "import java.util.List;",
    "className", "User",
    "fields", "    private String name;\n    private int age;",
    "methods", "    public String getName() { return name; }\n    // ..."
));

이렇게 하면 Template은 내부적으로 문자열을 순회하며 ${...} 패턴을 찾고
variables 에서 값을 꺼내 치환한 결과를 돌려준다.

핵심 포인트:
Template은 "문자열 조립" 이라는 책임만 가진다.
이 템플릿에 어떤 데이터를 넣을지는 ClassGenerator의 책임이다.

2. ClassGenerator — DTO 한 개의 소스 코드를 만드는 역할

2-1. ClassSpec / FieldSpec - "코드 생성 계획" 객체

generator 계층은 ModelGraph로부터 이미 클래스 설계도를 전달받는다.
이 설계도는 코드 생성에 최적화된 DTO인 ClassSpec 형태다.

개념적으로:

public final class ClassSpec {

    public static final class FieldSpec {
        private final String type;      // "String", "int", "List<Location>" ...
        private final String name;      // "name", "age" ...
        private final boolean optional; // 필요 시 nullable 표현 등에 활용 가능
    }

    private final String packageName;   // com.example.dto
    private final String className;     // WeatherApiResponse
    private final List<FieldSpec> fields;
    private final List<String> importTypes; // java.util.List 등
    private final boolean innerClass;   // 루트 내부에 중첩 클래스인지 여부
    // ...
}

이 시점의 ClassSpec은 이미:

필드 타입 추론(TypeInferencer까지 끝난 상태)
이름(NameConverter까지 반영된 상태)
optional 여부 판단 완료
inner-classes 옵션 반영 여부 결정

즉, ClassGenerator는 비즈니스 로직을 고민할 필요 없이,
"기계적으로 '코드 텍스트'를 찍어내기만 하면 되는 상태"가 된다.

2-2. ClassGenerator의 책임

ClassGenerator는 다음 책임을 갖는다.

ClassSpec으로부터 import 목록 생성
fields 리스트를 바탕으로 필드 선언부 문자열 생성
생성자, getter 같은 부가 메서드를 필요에 맞게 생성
Template에 채워 넣을 문자열을 준비
Template.render를 호출해 최종 소스 코드 문자열 생성

의사코드로 표현하면:

String generate(ClassSpec spec) {
    String packageLine = "package " + spec.packageName() + ";";
    String imports = buildImports(spec.importTypes());
    String fields = buildFieldLines(spec.fields());
    String methods = buildMethods(spec.fields());

    Template t = new Template(CLASS_TEMPLATE);
    return t.render(Map.of(
        "package", packageLine,
        "imports", imports,
        "className", spec.className(),
        "fields", fields,
        "methods", methods
    ));
}

➕ 왜 Template과 ClassGenerator를 분리했나?

Template은 "문자열 틀"에 집중
ClassGenerator는 "틀에 넣을 데이터 계산"에 집중

만약 템플릿이나 출력 스타일을 바꾸고 싶다면 Template 쪽만 손대면 되고,
DTO의 스펙 자체가 바뀌면 ClassGenerator 쪽만 손대면 된다.

즉, 관심사의 분리(Separation of Concerns)를 지키기 위함이다.

2-3. 예시 — WeatherApiResponse를 어떻게 생성하나?

JSON 분석 계층에서 아래 설계도(ClassSpec)가 넘어왔다고 해보자.

ClassSpec: WeatherApiResponse
- package: com.team606.mrdinner.entity
- fields:
    - Location location
    - Current current
- innerClasses: true
- nested ClassSpec:
    - Location (fields: String name, String country)
    - Current (fields: double tempC, int humidity, boolean isDay)

ClassGenerator의 출력은 대략 다음과 같이 된다:

package com.team606.mrdinner.entity;

public class WeatherApiResponse {

    private Location location;
    private Current current;

    public Location getLocation() {
        return location;
    }

    public Current getCurrent() {
        return current;
    }

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

        public String getName() { return name; }
        public String getCountry() { return country; }
    }

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

        public double getTempC() { return tempC; }
        public int getHumidity() { return humidity; }
        public boolean isDay() { return isDay; }
    }
}

여기까지가 "raw Java 코드 문자열"이다.
이제 이 문자열을 조금 더 정리해서 보기 좋게 만들 차례다.

3. CodeFormatter - 줄바꿈(LF), 공백, 빈 줄 정리

ClassGenerator까지 지나면 기능적으로는 문제가 없는 Java 코드가 나온다.
하지만 코드 스타일 측면에서는 다음과 같은 문제가 있을 수 있다.

Windows/Unix 환경이 섞여 CRLF / LF가 뒤섞임
일부 줄 끝에 불필요한 공백 존재
템플릿/조립 과정에서 빈 줄이 두 세 줄씩 생김

이 문제를 해결하기 위해 별도의 CodeFormatter 클래스를 만들었다.

3-1. CodeFormatter가 수행하는 규칙

1) 개행 문자 통일 — 전부 \n (LF)로

테스트 코드 예시:

@Test
void 개행_문자를_전부_LF로_통일한다() {
    String src = "line1\r\nline2\rline3\n";
    String result = formatter.format(src);

    assertThat(result).contains("line1\nline2\nline3\n");
    assertThat(result).doesNotContain("\r");
}

어떤 환경에서 생성하든 결과물은 항상 LF 기반 코드만 남도록.

2) 줄 끝 공백 제거

테스트 예시:

@Test
void 줄_끝_공백을_제거한다() {
    String src = "int x = 1;   \nint y = 2;\t\n";
    String result = formatter.format(src);

    assertThat(result).isEqualTo("int x = 1;\nint y = 2;\n");
}

코드 리뷰 시 "줄 끝에 공백"이 잡히는 것만큼 거슬리는 것도 없으므로
아예 생성 단계에서 제거해버린다.

3) 연속된 빈 줄 하나로 축소

@Test
void 연속된_빈줄을_하나로_축소한다() {
    String src = "class A {\n\n\n    int x;\n}\n";
    // ...
}

format 호출 후 결과:

class A {

    int x;
}

처럼 중간에 불필요하게 2줄 이상 비어 있는 구간을 하나로 줄인다.

3-2. 왜 CodeFormatter를 별도 클래스로 뺐을까?

SRP 관점

ClassGenerator는 "논리적 코드 내용"만 고민해야 한다.
- 어떤 필드를 가질지
- 어떤 메서드를 생성할지
- 어떤 import가 필요한지 등
CodeFormatter는 "코드의 외형/스타일"만 고민해야 한다.
- 줄바꿈 / 공백 / 빈 줄

두 가지를 섞어버리면:

ClassGenerator가 지나치게 비대해지고
포맷팅 룰을 바꿀 때마다 코드 생성 로직까지 건드려야 한다.

따라서 유지보수성과 변경 용이성을 위해 완전히 분리했다.

4. FileWriter — 최종 결과를 디스크에 내리는 단계

마지막으로, FileWriter 가 String 으로 된 소스를 .java 파일로 저장한다.

4-1. FileWriter의 책임

public class FileWriter {

    public void write(Path outDir, String className, String content) {
        Path file = outDir.resolve(className + ".java");
        try {
            Files.writeString(file, content, StandardCharsets.UTF_8);
        } catch (IOException e) {
            throw new UserException(
                "[ERROR] Java 파일을 저장하는 중 오류가 발생했습니다: " + file, e);
        }
    }
}

책임은 딱 두 가지다.

"className.java" 파일 경로 조합
UTF-8로 파일 쓰기 + 예외를 UserException으로 래핑

4-2. 왜 UserException으로 래핑했나?

파일 저장 실패는 대부분 사용자가 조정할 수 있는 문제다.

잘못된 out 경로 지정
권한 없는 디렉터리
디스크 가득 참

이런 문제에 대해 스택 트레이스를 그대로 보여주면,
사용자는 혼란만 느낄 수 있다.

그래서:

내부적으로는 IOException을 받되
사용자에게는 깔끔한 메시지로 전달
( [ERROR] Java 파일을 저장하는 중 오류가 발생했습니다: ... )

하는 구조를 택했다.

5. 전체 Generator 파이프라인 다시 한 번 정리

Generator 계층은 한 마디로 말하면:

"ModelGraph가 만든 ClassSpec(설계도)를
Java 소스코드 문자열로 만들고,
스타일을 정리한 뒤, 실제 파일로 저장하는 역할"

을 수행한다.

흐름을 코드로 표현하면 대략 이런 느낌이다.

for (ClassSpec spec : modelGraph.getAllClasses()) {
    String rawSource = classGenerator.generate(spec);
    String formatted = codeFormatter.format(rawSource);
    fileWriter.write(outDir, spec.className(), formatted);
}

ClassGenerator → 논리적으로 올바른 Java 코드 생성
CodeFormatter → 보기 좋은 형태로 정리
FileWriter → 실제 .java 파일로 저장

이 세 부분이 역할을 나누어 맡는다.

6. Generator 계층 설계가 의미하는 것

이 구조는 단순히 DTO를 찍어내기 위한 것이 아니다.
조금 관점을 바꿔 보면:

Template : 출력 형식에 대한 추상
ClassGenerator : 도메인 모델(ClassSpec)을 코드로 매핑하는 컴파일러 프런트엔드
CodeFormatter : pretty printer
FileWriter : 백엔드(코드 → 파일)

즉, 아주 작은 스케일이지만 "코드 생성기(Code generator)"를 설계해 본 셈이다.

7. 마무리 — Generator가 만들어낸 최종 산출물

최종적으로 사용자는:

CLI 옵션만 적절히 넘겨주면
JSON 구조를 이해하지 않고도
Java 소스코드(DTO)를 바로 받아서 프로젝트에 포함시킬 수 있다.

Generator 계층 덕분에
이 도구는 “콘솔 로그만 찍고 끝나는 프로그램”이 아니라,

실제 프로젝트에서 바로 가져다 쓸 수 있는 .java 파일을 생산하는
작은 빌드 도구

의 역할까지 수행할 수 있게 되었다.

마지막으로, 분석된 스키마를 실제 Java 클래스로 변환하는

ClassGenerator·Template·CodeFormatter 구현 과정을 소개한다

JSON DTO Converter (4) - Exception 분석

JSON DTO Converter (2) - JSON 분석

hwangsoojin — Mon, 24 Nov 2025 17:16:24 +0900

JsonValidator → JsonNode → SchemaNode → TypeInferencer → ModelGraph

"JSON이 어떻게 DTO 설계도로 변환되는가?"를 깊이 있게 분석한다

이 글은 JSON DTO Converter의 핵심 로직이 담긴 "JSON 분석 계층"을 집중적으로 다룬다.

이 계층은 도구 전체의 심장이다.

JSON 파일을 로드하고
구조를 분석하여
Java 타입을 추론하고
DTO 클래스 구조(ModelGraph)를 만드는

모든 과정이 여기에 포함된다.

0. JSON 분석 계층이 왜 중요한가?

CLI 계층이 "입력 검증"을 담당했다면,
JSON 분석 계층은 실제로 JSON을 분석하여 DTO 설계도를 만들어내는 엔진이다.

즉, JSON 분석 계층은 다음 역할을 한다:

JSON 파일           → JsonValidator
JsonNode 트리       → JsonAnalyzer
SchemaNode 스키마   → TypeInferencer
Java 타입           → ModelGraph
DTO ClassSpec       → Generator 계층 전달

여기서 잘못되면 올바른 DTO를 만들 수 없다.
그래서 이 계층이 가장 중요하며, 가장 정교하게 설계되어야 한다.

1. JsonValidator - JSON 파일을 안전하게 로드하기 위한 필터

JsonValidator는 프로그램 전체에서 가장 먼저 JSON 파일을 직접 다루는 계층이다.

✔ JsonValidator가 수행하는 검증 리스트

1) 파일 존재 여부 확인

경로가 존재해야 한다
존재하지만 디렉터리라면 금지

2) 파일 크기 제한 (5MB)

왜 제한을 둘까?

JSON이 지나치게 크면 메모리 사용량이 폭증한다
CLI 도구는 즉각적인 응답성이 중요하다
파일 크기가 비정상적으로 크다면 사용자의 입력 실수 가능성 ↑

따라서 5MB 제한은 "안전 장치"이다.

3) BOM(Byte Order Mark) 검사 및 제거

BOM이란?

일부 Windows 에디터는 UTF-8 파일을 저장할 때
맨 앞에 다음 3바이트를 붙인다:

EF BB BF

이게 BOM이다.

문제는 JSON의 시작은 {여야 하는데
BOM이 있으면…

ï»¿{

처럼 보이지 않는 쓰레기 바이트가 앞에 붙는다.
파서에 따라 오류가 날 수 있으므로 반드시 제거해야 한다.

JsonValidator의 처리 방식:

파일을 raw byte로 읽는다
첫 3바이트가 BOM인지 검사
맞으면 제거
제거 여부를 boolean hadBom 에 기록

이것이 JsonValidator.Result 내부에 포함된다.

4) JSON 문법 파싱

Jackson ObjectMapper.readTree() 사용.

5) 루트 타입 검사

루트는 반드시 ObjectNode여야 한다.
배열 루트는 지원하지 않는다.

✔ JsonValidator.Result

JsonValidator는 다음 데이터를 함께 반환한다:

필드	설명
JsonNode root	JSON 루트 트리
boolean hadBom	BOM 제거 여부
sizeBytes	파일 크기

이 값들은 이후 JSON 분석 단계에서 활용된다.

2. JsonNode Tree Model — JSON을 메모리 트리로 표현하는 방식

JsonNode는 Jackson이 제공하는 트리 기반 JSON 모델이다.

예를 들어 아래 JSON을 보자:

{
  "user": {
    "name": "Alice",
    "age": 20
  }
}

JsonNode 트리 구조는 텍스트가 아니라 실제로 이렇게 생겼다:

ObjectNode
 └─ "user" → ObjectNode
         ├─ "name" → TextNode("Alice")
         └─ "age"  → IntNode(20)

JsonNode를 사용하는 이유

1) 구조적 탐색에 최적화

필드 키, 값, 노드 타입 등에 대해 자유롭게 탐색 가능.

2) JSON 스키마 분석을 정확하게 수행 가능

값이 객체인지, 배열인지, 숫자인지 쉽게 판단할 수 있음.

3) "스트리밍(JSON parser)"보다 더 안정적

스트리밍 파서는 순차 처리라 구조 분석이 어렵다
DTO 구조 생성에는 트리 기반 파싱(Tree Model)이 필수

즉, JsonNode는 "스키마 분석용 내부 AST(Abstract Syntax Tree)"라고 볼 수 있다.

3. SchemaNode — 도구 내부 JSON 스키마 표현 모델

JsonAnalyzer는 JsonNode를 기반으로 JSON 구조를
언어 독립적인 계층 구조로 추출한다.

이것이 SchemaNode다.

✔ SchemaNode 구조 요약

SchemaNode
 ├─ SchemaPrimitive   : 문자열/숫자/boolean/null
 ├─ SchemaObject      : 필드 이름 → FieldInfo
 ├─ SchemaArray       : 요소 타입의 Set
 └─ SchemaUnion       : 혼합된 여러 타입 (예: [1, "text"])

각 타입은 서로 조합될 수 있다.

3-1. SchemaPrimitive

JSON 원시값에 해당한다.

JSON 값	SchemaPrimitive 타입
"str"	STRING
123	INTEGER
12.3	NUMBER
true	BOOLEAN
null	NULL

3-2. SchemaObject

예:

{
  "name": "Alice",
  "age": 20
}

SchemaObject:

SchemaObject
 ├─ name → FieldInfo(STRING)
 └─ age  → FieldInfo(INTEGER)

여기서 FieldInfo는 옵셔널 여부까지 계산한다.

▷ presenceCount

JSON 여러 개를 분석할 때(배열 등),
각 필드가 얼마나 등장했는지를 센다.

▷ optional 판단

예를 들어,

[{ "name": "A" }, { "name": "B", "age": 20 }]

출현 횟수:

필드	count	total	optional
name	2	2	false
age	1	2	true

3-3. SchemaArray

배열의 요소 타입을 모두 모아 Set으로 저장한다.

예:

["A", "B", "C"]

→ SchemaArray{ STRING }

예:

[ true, 42 ]

→ SchemaArray{ BOOLEAN, INTEGER }
→ 이 경우 SchemaUnion으로 변환됨

3-4. SchemaUnion — 값이 여러 타입일 때

예:

{ "value": [1, "A", true] }

분석:

value → SchemaUnion{
            INTEGER,
            STRING,
            BOOLEAN
        }

이는 TypeInferencer 단계에서
공통 상위 타입(Object) 또는 Wrapper 타입으로 축소된다.

4. TypeInferencer — SchemaNode → Java 타입 매핑

이제 스키마 구조를 바탕으로 Java 실제 타입을 추론한다.

주요 매핑 규칙

1) Primitive 매핑

SchemaPrimitive	Java 타입
STRING	String
INTEGER	int
NUMBER	double
BOOLEAN	boolean
NULL	Object (또는 nullable wrapper)

2) Optional 필드 → Wrapper 승격

예:

int → Integer
boolean → Boolean

이는 Java에서는 primitive 타입이 null을 허용하지 않기 때문이다.

3) SchemaArray → List<T>

예:

{ "tags": ["dev", "cs"] }

→ List<String>

4) SchemaObject → 별도 DTO 클래스

이는 ModelGraph에서 클래스로 승격된다.

5) SchemaUnion → 공통 타입으로 수렴

예:

[1, 2, 3] → int
[1, 1.5] → double
[1, "a"] → Object

5. ModelGraph — 최종 DTO 클래스 설계도(IR)

ModelGraph는 TypeInferencer의 결과를 받아서
실제로 생성될 클래스들의 관계도를 만든다.

클래스 생성 전략

1) SchemaObject마다 하나의 ClassSpec 생성

예:

Root
├─ User
└─ Address

2) inner-classes 옵션 반영

true → Root 클래스 내부에 static class로 생성
false → 모두 독립된 .java 파일로 생성

ModelGraph가 해결하는 문제들

✔ 클래스 이름 충돌

동일한 이름이 나오면 suffix를 붙인다:

Location, Location2

✔ import 목록 관리

필드 타입이 다른 클래스라면 import
동일 패키지는 생략

✔ 클래스 계층 유지

중첩 구조 유지

6. JSON 분석 전체 흐름을 하나의 예시로 정리

아래 JSON을 예로 들어 과정 전체를 시각화해보자:

{
  "user": {
    "name": "Alice",
    "age": 20
  }
}

6-1. JsonNode 트리

ObjectNode
 └─ user : ObjectNode
        ├─ name : "Alice"
        └─ age  : 20

6-2. SchemaNode 트리

SchemaObject
 └─ user : SchemaObject
        ├─ name : STRING
        └─ age  : INTEGER

6-3. TypeInferencer 결과

user → User 클래스
name → String
age → int

6-4. ModelGraph 결과

RootDto
 └─ User user

User
 ├─ String name
 └─ int age

7. 이 설계의 장점 — 유지보수성과 확장성

✔ 1) JSON 형식만 바뀌어도 DTO 생성 자동 대응

DTO 작성 자동화

✔ 2) 다양한 JSON 구조에 미래 대응

가변 필드
optional 필드
union 타입
중첩 구조

✔ 3) 구조 변경에 강하다

스키마 → 타입 → 클래스 구조
각 단계가 독립되어 있어 유지보수가 쉽다.

8. JSON 분석 파트 요약

단계	설명
JsonValidator	파일 검증, BOM 제거, JSON 파싱
JsonNode	실제 JSON 트리 모델
SchemaNode	언어 독립적 스키마 구조
TypeInferencer	SchemaNode → Java 타입 추론
ModelGraph	DTO 클래스 구조 결정

이 다섯 단계가 JSON DTO Converter의 핵심 엔진이다.

다음 편에서는 JSON을 구조적으로 해석하는

JsonAnalyzer와 TypeInferencer의 내부 흐름을 살펴본다

JSON DTO Converter (3) - Generator & 출력 분석

JSON DTO Converter (1) - CLI 분석

hwangsoojin — Mon, 24 Nov 2025 16:49:55 +0900

"ArgumentParser, CommandLineOption, FileValidator, ParsedArguments"를 깊이 있게 파헤치기

이 글은 JSON DTO Converter 프로젝트의 CLI 계층 전체를 상세하게 분석하는 글이다.

프로그램이 실행되기 위해서는
CLI입력 → 인자 파싱 → 값 검증 → 환경 DTO(ParsedArguments) 생성
까지의 과정이 정확히 수행되어야 한다.

실제로 이 단계는 “도구 전체의 입구(Entry Point)”이기 때문에
여기서 제대로 설계하지 않으면 전체 동작이 망가질 수 있다.

1. CLI 계층의 역할

CLI 계층은 다음 4가지 책임만 가진다.

✔ 1) 명령줄 옵션을 정의하고

✔ 2) 사용자가 입력한 인자를 파싱하고

✔ 3) 검증(필수 옵션 체크 / 타입 체크 / 경로 체크)하고

✔ 4) 결과를 불변 DTO로 제공한다(ParsedArguments)

즉,

"사용자가 CLI로 전달한 값을,
프로그램이 이해할 수 있는 형태의 설정(config)으로 변환하는 계층"

이라 할 수 있다.

이 역할 단 하나만 수행하도록 구조화한 것이 핵심이다.

2. CLI 입력 옵션 전체 정리

프로그램이 받아들일 수 있는 옵션은 단 5개이다:

옵션	필수	설명
--input	✔	JSON 파일 경로
--root-class	✔	루트 DTO 클래스 이름
--package	✔	생성 DTO의 패키지 이름
--out	✔	.java 파일 저장 디렉터리
--inner-classes	✖	true/false (기본값 false)

❗ 중요한 설계 원칙:

옵션과 값 사이에는 반드시 공백이 있어야 한다.

--input sample.json       ← ✔
--input=sample.json       ← ✖ 금지

이 규칙은 ArgumentParser가 정확하고 단순하게 동작하도록 설계된 중요한 제약이다.

3. CommandLineOption - CLI 옵션을 Enum으로 정의한 이유

많은 CLI 도구가 문자열 비교로 옵션을 처리하지만
이 프로젝트에서는 Enum으로 옵션을 정의했다.

예:

public enum CommandLineOption {
    INPUT("--input", true),
    ROOT_CLASS("--root-class", true),
    PACKAGE("--package", true),
    OUT("--out", true),
    INNER_CLASSES("--inner-classes", false);
}

왜 Enum인가?

(1) 오타 방지

문자열 기반 파싱은 "--input" 과 "--inptu" 을 구분하지 못해
에러가 발생하면 파악이 어렵다.
Enum을 사용하면 IDE의 자동완성 + 컴파일러 체크까지 받는다.

(2) 필수 옵션(required) 여부 명시

각 옵션이 필수인지 아닌지를 Enum 안에 저장한다.
따라서 ArgumentParser는 다음과 같이 깔끔하게 필수 옵션을 체크할 수 있다.

for (CommandLineOption opt : CommandLineOption.values()) {
    if (opt.required() && !parsed.containsKey(opt)) {
        throw new UserException("[ERROR] " + opt.name() + "은 필수입니다.");
    }
}

(3) 구조적 확장 가능

옵션을 더 늘리고 싶어도 Enum에 한 줄 추가하면 끝!

4. ArgumentParser - CLI 인자 파싱 핵심 로직

ArgumentParser는 다음 5단계를 수행한다:

4-1. 옵션 이름(--something) 인식

CLI 입력의 예:

--input sample.json --root-class ApiRes --package com.test --out src --inner-classes true

ArgumentParser는 편의를 위해 다음 패턴을 강제한다:

--옵션명  값

즉
--옵션=값 과 같이 '=' 이 들어간 형태는 허용하지 않는다.

4-2. 옵션-값 쌍 수집

파서가 수행하는 기본 동작:

토큰을 순서대로 읽는다
"--" 로 시작하면 옵션
다음 토큰을 “값”으로 간주
Map<CommandLineOption, String> 형태로 저장
옵션인지 모르면 UserException 발생

이 구조는 단순하지만 명확하여 오류를 줄인다.

4-3. 필수 옵션 누락 오류 검사

ArgumentParser는 Enum에 저장된 required 플래그를 보고
필수 옵션이 제공되지 않았다면 UserException을 즉시 발생시킨다.

예:

root-class 누락
package 누락
input 누락
out 누락

전부 “사용자가 수정할 수 있는 오류”이므로 UserException이 맞다.

4-4. boolean 옵션( --inner-classes )의 처리

--inner-classes 는 true/false만 허용한다.

--inner-classes true  ← OK
--inner-classes false ← OK
--inner-classes maybe ← ERROR

boolean 해석은 ArgumentParser에서 책임지도록 설계했다.
파일 저장과는 관련 없는 로직이므로, generator 계층에 영향을 주지 않게 하기 위함이다.

5. FileValidator — 출력 디렉터리 검증 & 생성

FileValidator는 다음만 책임진다:

주어진 경로가 디렉터리인지
존재하지 않으면 생성
쓰기 권한이 있는지 검증

❗ 왜 이 로직이 CLI 계층에 있어야 하는가?

출력 디렉터리가 유효하지 않으면
나머지 파이프라인 전체가 작동할 수 없기 때문
(경로 없이 파일 생성 불가능)
JSON 파싱 계층(json package)이나 코드 생성(generator package)은
"파일 시스템"이라는 개념을 몰라야 한다.
SRP를 지키기 위해 IO 검증은 CLI 계층에서 종결한다.

6. ParsedArguments — 불변(immutable) 환경 설정 객체

ArgumentParser가 최종적으로 반환하는 객체는 ParsedArguments 다.

예:

public final class ParsedArguments {
    private final String inputPath;
    private final String rootClass;
    private final String packageName;
    private final String outDir;
    private final boolean innerClasses;
}

왜 Immutable인가?

설정값은 프로그램 실행 동안 바뀌어서는 안 된다
thread-safe
이후 계층에서 실수로 값을 수정할 여지가 없다
"환경의 스냅샷" 역할 수행 가능

즉, CLI 분석이 끝난 시점에서
"사용자가 원하는 설정이 무엇이었는가?"를 고정시키는 객체다.

7. BOM(Byte Order Mark) — 개념 설명

CLI 글에서 BOM 설명을 요청한 만큼, 개념을 쉽게 정리해보자.

7-1. BOM이란?

UTF-8 BOM(Byte Order Mark)은
텍스트 파일의 맨 앞에 붙는 3바이트 시퀀스다.

EF BB BF

일부 Windows 기반 에디터(Notepad 등)는
UTF-8 파일을 저장할 때 BOM을 붙이는 경우가 있다.

7-2. BOM이 있으면 어떤 문제가 생기나?

JSON은 다음과 같이 시작해야 한다:

{ "key": "value" }

하지만 BOM이 있으면 실제 파일의 맨 앞은 다음과 같다:

ï»¿{ "key": "value" }

사람 눈에는 보이지 않지만,
파서 입장에서는 쓰레기 바이트가 들어온 것이다.

Jackson은 BOM 처리를 자동으로 지원하기도 하지만,
이 프로젝트에서는 명시적으로

BOM 여부 확인
필요 시 제거

를 구현했다.

7-3. 왜 CLI 분석 글에서 BOM 설명을 하나?

이유는 간단하다:

BOM은 사용자 입력의 파일 형식 문제이기 때문
JsonValidator는 CLI 입력( --input )을 처리하는 과정의 연속선상에서 동작
따라서 CLI와 밀접한 상위 개념

그래서 Overview나 JSON 분석 글보다
CLI 글에서 다루는 것이 가장 자연스럽다고 판단하였다.

8. CLI 단계에서의 오류 처리 전략

ArgumentParser / FileValidator는 사용자가 잘못 입력한 경우
전부 UserException 을 발생시킨다.

예:

필수 옵션 누락
존재하지 않는 파일
경로가 파일이 아니라 디렉터리
boolean 옵션 잘못된 값
출력 디렉터리 권한 없음

이 예외들은 모두 "사용자가 수정할 수 있는 문제"이므로
friendly error message가 핵심 철학이다.

예시 출력:

[ERROR] --input은 필수입니다.

[ERROR] --inner-classes 옵션은 true 또는 false만 허용합니다: maybe

9. 최고로 중요한 포인트 - CLI 계층은 전체 파이프라인의 안전장치다

정리하면 CLI 계층의 목적은 다음이다:

✔ 1) 입력이 “제대로 된 JSON 파일인지”

(파일 존재 / 디렉터리 금지 / 크기 제한 / 확장자 / BOM 등)

✔ 2) 옵션이 “정확한 형태인지”

( --option value 형식 고정)

✔ 3) 필수 입력이 모두 들어왔는지

✔ 4) Boolean 옵션을 올바르게 파싱했는지

✔ 5) 출력 디렉터리가 “파일 생성 가능한 상태인지”

(없으면 생성, 권한 체크)

이 단계가 제대로 처리되고 나면,
다음 단계(JSON 분석 계층)부터는 오직 "JSON 구조 분석과 타입 추론"에만 집중하면 된다.

즉, CLI 계층은 전체 프로그램의 안정성과 예측 가능성을 보장하는 초석이다.

이어지는 글에서는 입력 JSON을 검증하고 정제하는

JsonValidator와 JSON 파싱 로직을 다룬다

JSON DTO Converter (2) - JSON 분석