moyang

대시보드 대용량 데이터 처리(feat.웹 압축 기술)

moyanglee — Sat, 6 Dec 2025 09:53:49 +0900

회사에서 서비스 현황을 한눈에 볼 수 있는 대시보드를 만들게 되었다.

이번 대시보드를 개발하면서,

DB 쿼리 레벨의 집계와 설계
YouTube 대시보드 요청 쿼리 구조
백엔드–프론트엔드 간 효율적인 네트워크 통신
실제 사용자 관점에서의 UX 개선

까지 한 번에 고민해볼 수 있었던 점이 매우 재밌었고, 유익한 경험이었기에 이를 기억하고자 또 공유하고 기록을 남긴다.

대시보드 요구 사항

처음 요구사항은 비교적 단순해 보였다.

달력을 통한 자유로운 기간 선택
집계 단위 선택 (Hour / Day / Week / Month / Year)
멀티 리전/여러 고객사(프로젝트) 지원
각 집계 단위마다 표출할 수 있는 데이터 최대 수량을 지정 할 수 있어야 한다.(e.g. 시간 단위 선택시 최근 24시간 표출)

그런데 꼭 기간 마다 표출할 수 있는 데이터의 최대 수량을 지정하는게 필요할까 라는 생각과, 만약 그렇게 표출하는 데이터의 최대 수량을 지정하게 되면 1번 요구사항과 상충된다고 생각이 들었다.

예를 들어, 내가 기간은 3년 + 집계 단위를 시간으로 설정하면, 실제로 보여주는 건 최근 24시간만 보여준다. 이상하다.

더군다나 대시보드 상단에 선택한 기간에 대한 Total Count가 표시되는 부분이 있는데, 차트는 최근 24시간, 상단 카드에는 선택한 기간 그대로 표시해야 하나? 라는 생각이 들었다. 이상하다.

그럼 그냥 데이터 전부를 보여주면 어떨까? 3년 선택하고 Day로 집계를 하게 되면 아래처럼 X축 라벨이 엉망으로 나오게 될 텐데...?

YouTube 대시보드 분석 - UX

우선 가장 먼저 떠오르는 고도화된 대시보드인 YouTube의 대시보드를 보기로 했다.

YouTube 컨텐츠 조회 고급 분석 대시보드 화면

우선 먼저 문제 하나는 해결됐다.

"데이터를 다 보여주되, X축에는 가시성이 좋을 정도로만 Label을 표시하자"

따라서 요구사항 4번 부분을 빼기로 하고 총 3개의 요구사항을 만족시키는 대시보드를 구현해보기로 했다.

문득, 이 생각이 들었다.

"10년치의 데이터를 일별 집계로 들고 오면 어마어마한 데이터일텐데 이걸 YouTube는 어떻게 처리할까?"

YouTube 대시보드 분석 - Request/Response 구조

개발자 모드에서 Request와 Response를 까봤다.

아래 사진은 유튜브가 대시보드 화면을 구성하기 위해 보낸 요청의 Payload 구조이다.

내가 생각한 것과 너무 달랐다.

우선, 왜 nodes 배열로 관리를 할까? 왜 Object 형태가 가독성, 접근성 모두 좋을텐데? 라는 생각이 들었다.

그러나 아래 connectors를 보는 순간 그래프인가!? 라는 생각이 들었다.

YouTube Request Payload 전체구조

connectors 부분만 잠깐 설명을 하자면,

extractorParams는 어떤 쿼리 노드의 결과에서 뭘 뽑아올지 정의하는 부분이고,

fillerParams은 뽑아온 값으로 어떤 노드의 쿼리/ID를 채울지 정의하는 부분 이다.

예를 들어, extractorParams의 2__TOP_ENTITIES_TABLE_QUERY_KEY 라는 쿼리 노드는 영상의 조회수, 조회 시간 등 각종 데이터를 테이블 형태로 나오는 쿼리이다. 그래서 이 테이블 결과에서 VIDEO 디멘션 값들(VIDEO ID) 추출해라. 라는 뜻이고,

fillerParams는 뽑아낸 VIDEO ID들을 2__TOP_ENTITIES_CHARTS_QUERY_KEY 조회할 때 채워라.
거기에도 { "dimension": { "type": "VIDEO" } }라고 되어 있으니까, 이 video ID들을 filller로 넣어라. 라는 뜻이다.

그랬다. YouTube는 한번의 요청으로 대시보드 화면을 구성하기 위해, 위와 같이 그래프 형태의 페이로드 구조로 요청을 보내고 있었다.

재밌다.

이제 응답 구조를 한번 보자.

앞서 요청 페이로드에 있었던 nodes 배열과 흡사하게 results 값 역시 배열로 구성되어 있다.

YouTube Response 전체구조

우리가 집중할 부분은 Chart 부분이니 차트 관련 쿼리만 자세히 보도록 한다.

YouTube Response - Chart 쿼리 응답 구조

해당 쿼리의 응답 구조는 크게 3부분으로 나누어져 있다.

dimensionColumns의 dateIds, dimensionColumns의 strings.values, metricColumns의 counts.values

dimensionColumns는 내가 조회한 기간을 의미한다.
dimensionColumns의 strings.values는 영상의 고유한 아이디 이다.
metricColumns의 counts.values는 실제 조회수 이다.

즉, 각각의 0번째 Index 값들을 조회하면 20251128년도 Er... 영상의 조회수는 0이었다. 라는 것을 알 수 있다.

저 데이터 구조를 보니 차트에 바로 넣기 최적화된 구조라는 것을 알 수 있었다.
아! 프론트엔드 부하를 줄이기 위해 서버쪽에서 차트에 넣기 최적화된 구조로 파싱해서 내려주고 있구나. 라고 생각을 했다.

YouTube의 대용량 데이터 처리 방법

근데 문제점은 중복된 데이터들 이었다.

지금 나는 조회기간을 매우 짧게 영상도 1개에 대해 조회한 것이지만 만약 영상 100개, 3년간의 일자별 데이터를 조회하면?
그럼 데이터 칼럼 부분은 100개 * 3년 * 365 개의 어마어마한 중복된 데이터를 보내게 된다.

그럼 이런 네트워크 부하를 어떻게 줄이고 있을까?

결론적으로 YouTube는 Brotli라는 압축 기술을 쓰고 있다.

아래 사진에서 Content-Encoding: br 이라는 부분이 해당 응답은 Brotli로 압축해서 내려온 데이터다 라는 것을 보여주는 항목이다.
특히, Brotli는 더 큰 윈도우 사이즈를 활용해 중복된 데이터를 매우 효율적으로 압축할 수 있다는 점에서 강점을 가진 압축 알고리즘이다.

YouTube 요청/응답 헤더

사실 부끄럽지만, Brotli는 처음 들어봤다.
하지만 당연히 gzip은 들어봤기에 두개의 압축기술을 비교하며 정리해봤다.

Brotli vs Gzip

참고로 Brotli가 Gzip보다 압축효율이 15~20%정도 좋다.

특히나 중복된 데이터를 검사하는 윈도우 사이즈가 gzip보다 훨씬 크기 때문에 훨씬 효율적으로 압축을 진행할 수 있다.
사실 거의 모든 면에서 Brotli가 좋아보이지만, IE를 지원하지 않는다는 단점이 존재했다.

레거시한 환경에서 접속을 많이 하는 우리 제품 특성상 gzip을 사용하기로 했다.
KeyLink에서 2~3년간의 일자별 데이터를 조회 했을 때, 데이터의 크기가 일반적으로 gzip의 윈도우 사이즈(32kb)보다 작은 것을 확인했고, 크게 문제되지 않을 것이라 판단했다.

YouTube 분석 결과 및 적용 포인트

그래서 결론적으로 YouTube 대시보드를 분석/KeyLink에 적용한한 결과는 아래와 같았다.

프론트 엔드 부하 최소화
프론트에서는 최소한의 작업으로 차트 렌더링 할 수 있도록 서버가 가공된 데이터를 전달 해주고 있었다.
그래프 구조의 쿼리가 멋있어 보였지만, 현재 우리 제품의 레벨에서는 오버엔지니어링이란 판단을 내렸고,
우선, 프론트에서 바로 차트에 데이터를 넣어 렌더링 할수 있도록 아래처럼 구조를 설계하였다.
Brotli 와 같은 웹 압축기술 사용
앞서 언급한 것처럼 제품이 납품되는 사이트 특성상 gzip을 적용하기로 결정했다.
UI/UX 포인트
선택된 기간의 데이터를 전부 보여주되, 사용자가 보기 좋게 X축 라벨을 일부 생략하여 보여주기로 결정했다.

YouTube 분석 결과 및 응답 구조 재설계

gzip 적용 및 성능 테스트

이제 gzip을 Spring서버에 application.yml에서 아래처럼 간단히 세팅했다.

mime-types: 압축할 대상 타입을 지정
min-request-size: 압축할 응답 최소 사이즈 지정

모든 응답에 대해 압축을 진행하게 되면 오버헤드가 더 커질 것이므로, min-request-size를 통해 1kb이상의 응답에 대해서만 압축을 진행하도록 세팅하였다.

이제 성능 테스트를 진행해봤다.

gzip 성능 테스트

네트워크 전송 용량은 96%가 획기적으로 감소했다. 하지만 응답속도의 변화는 미미했다.
용량이 저렇게 획기적으로 줄었다는 것도 충분히 획기적인 성능 개선이지만, UX를 개선하고 싶었던 내 입장에선 조금 아쉬웠고 이유를 파고 들었다.

원인은 테스트 환경에 있었다. 테스트 진행시 로컬에 띄운 서버에서 테스트를 진행했고, 로컬에서 진행하다 보니 전체 소요시간에서 네트워크 전송시간이 차지하는 비율이 매우 작았다. 따라서 줄어든 네트워크 전송시간이 압축/해제 시간에 의해 상쇄됐던 것이다.

gzip 적용 후, 전송시간 변화 원인 분석

하지만, 일반적인 네트워크환경이나 조금만 안좋은 네트워크 환경에서는 그 시간이 획기적으로 줄어들 것으로 생각되며, 사실 네트워크 전송 데이터량을 96%나 줄이는 것만으로도 웹 압축기술은 반드시 도입해야할 기술이라고 생각이 된다.

집계 테이블 리팩토링 및 쿼리 최적화

이제 다음으로 집계 테이블에서 어떻게 데이터를 들고 오는지, 쿼리 레벨에서 분석했다.

기존 집계 테이블 구조엔 yy, mm, dd, hh, week와 같이 집계 시점을 저장하는 필드들이 있었다.

처음 설계하던 당시엔 Index만 제대로 걸어 놓는다면 어떤 시점의 데이터를 들고오기 좋은 구조라고 생각했다.

DB 스키마 변경(전)

하지만, 기간 검색을 하다보니 문제가 생겼다.

저렇게 각 필드로 저장된 값을 조합해서 기간으로 검색하려고 하니 각 필드를 CONCAT해서 String을 비교 연산자를 통해 비교하게 되었다.

참고로 이런 경우 당연히 인덱스도 안탄다.

집계 기준시간을 event_time 이라는 필드에 저장하기로 했다.

DB 스키마 변경(후)

참고로 해당 필드를 String으로 저장할지 datetime으로 저장할지 고민하다가

DATETIME 타입이 저장용량도 적을 뿐더러 비교할 때에도 String은 한글자씩 비교하지만, DATETIME은 숫자로 저장되기에 비교 속도마저 빠르기 때문에, 훨씬 적합한 필드 타입이라 생각이 되어 DATETIME 타입으로 결정했다.

UX 개선(feat. chart.js 커스텀 함수)

이제 마지막으로 UX 개선을 하기로 했다.

앞서 말한 것 처럼 아래 사진같은 현상을 막기 위해 기간에 맞춰 데이터는 다 보여주되, 가독성 좋게 몇개의 라벨만 보여주기로 했다.

수많은 라벨이 X축에 쌓여있는 차트

Canvas에 기반한 Chart.js 라이브러리를 사용하고 있었는데,
다행히 해당 라이브러리에서 AutoSkip이라는 옵션을 제공해주고 있었다.

하지만, 항상 그렇듯 문제가 있었다. 마지막 라벨이 출력이 안된다.

chart.js - 마지막 라벨 출력 문제

찾아보니 라벨을 auto skip할 때 앞에서 하나씩 채워 나가기 때문에, 이런 문제가 생기며 chart.js의 고질적인 문제였다.
다행히 label을 렌더링 하는 callback 함수를 세팅하는 옵션을 제공해 주었기에 직접 구현하기로 했다.

우선 아래처럼 구현했다.

X축에서 최대 8개 정도의 라벨이 출력되도록 세팅하였고, 마지막 라벨과 그 직전 라벨이 겹치는 경우가 생겨 생략하는 로직까지 추가했다.

chart.js ticks callback 구현

최종 회고

이번 대시보드를 구현하는 과정은 정말 즐거운 경험이었다.

특히 YouTube가 대용량 데이터를 어떻게 처리하는지, 왜 그런 복잡한 쿼리 구조와 응답 포맷을 선택했는지 하나씩 뜯어보는 과정이 무척 흥미로웠다. 이 프로젝트를 통해

DB 쿼리 레벨의 집계와 설계,
백엔드–프론트엔드 간 네트워크 통신 구조,
실제 사용자 관점에서의 UX 개선
까지 한 번에 고민해볼 수 있었던 점이 개인적으로 큰 배움이었다.

무엇보다도 이 경험을 나만의 경험으로 끝내지 않고, 사내 동료들과 세미나 형식으로 공유한 것이 뜻깊었다. 발표를 통해 내가 설계한 방향이 타당한지 검증받을 수 있었고, 동시에 동료들이 제안해준 다른 관점과 아이디어를 접하면서 내가 미처 보지 못했던 부분도 새롭게 생각해볼 수 있었다.

이 대시보드 프로젝트는 단순한 기능 개발을 넘어, “좋은 구조란 무엇인가”를 함께 고민하고 성장할 수 있었던 소중한 경험으로 남았다.

[R2DBC] MariaDB Bulk Insert 성능 23배 개선: Driver의 한계를 넘자

moyanglee — Wed, 26 Nov 2025 10:49:45 +0900

1. 서론

Spring WebFlux + R2DBC + MariaDB 조합으로 서비스를 개발하다 보면, 대량 INSERT가 필요한 구간에서 성능 이슈를 마주하게 된다. 특히 “키 생성”, “로그 적재”, “배치성 데이터 적재”처럼 한 번에 수천~수만 건을 넣어야 하는 상황에서

Reactive니까 알아서 빠르겠지 라는 기대와 달리,
실제로는 몇 분 단위로 시간이 걸리는 경우를 겪게 된다.

이 글은

Spring WebFlux + R2DBC + MariaDB 환경에서
대량 INSERT 성능이 잘 나오지 않았던 원인을 분석하고,
다중 VALUES 기반 Bulk Insert 유틸리티로 성능을 개선한 사례와,
그 과정에서 고려해야 할 보안·유지보수 관점의 트레이드오프

까지 정리한 기록이다.

2. 문제 상황

개발하고 있는 차량 키 관리 솔루션에서 대칭 키를 대량으로 유도/생성/암호화하여 DB에 저장하는 기능이 있었고,

이에 대한 요구사항은 명확했다.

“10,000개 키 생성·저장을
**현실적인 시간 내(1분 이내)**에 끝낼 수 있게 만들 것.”

R2DBC에서 제공하는 API(repository.saveAll(Flux<...>))를 사용하였으나 10분이상 소요되는 문제가 발생하였고,
심지어 10,000건이 넘어가는 경우 DB Connection이 초과되는 에러가 발생했다.

3. R2DBC + MariaDB 조합에서의 제약

3-1. 숫자부터 확인: 어디가 느린가?

처음에는 “Reactive + 비동기니까 어느 정도는 빨라야 하지 않을까?”라는 막연한 기대가 있었다.
그래서 먼저, 다음 정도만 빠르게 계측했다.

키 생성 자체에 걸리는 시간
DB INSERT 구간에 걸리는 시간
전체 배치 처리 시간

결과적으로:

키 생성 로직은 상대적으로 빠른 편이었고,
INSERT 쿼리가 나가는 구간에서 지연이 집중되어 있었다.

즉, 이 문제는 알고리즘이나 비즈니스 로직이 아니라, DB 쓰기 패턴과 관련이 있었다.

3-2. “내 코드 탓인가?” – saveAll, 설정, 인덱스까지 의심

다음으로 의심한 건 순수하게 “내 코드/설정 문제”였다.

Spring Data R2DBC의 saveAll/리액티브 리포지토리 패턴을 제대로 쓰고 있는지,
커넥션 풀 크기, 타임아웃 등 R2DBC 관련 설정이 적절한지,
인덱스 설계/실행 계획에서 쓸데없는 풀스캔이 있는지

간단히 했던 일들:

EXPLAIN으로 INSERT 대상 테이블 인덱스 확인
불필요한 인덱스/트리거 여부 점검
R2DBC 설정 조정 후 성능 재측정
saveAll / DatabaseClient 여러 조합으로 실험

하지만 이런 조정을 통해서는 근본적인 성능 향상은 나오지 않았다.
체감상 조금 나아지는 정도에 그쳤고, “10분 → 1분” 수준의 개선과는 거리가 멀었다.

3-3. “그럼 R2DBC 쪽 한계일 수도?” – 레퍼런스 탐색

여기부터는 가설을 바꿨다.

“혹시 내가 API를 잘못 쓰고 있는 게 아니라,
아예 이 조합(R2DBC + MariaDB)이 Batch Insert를 제대로 지원하지 않는 건 아닐까?”

그래서 다시 열심히 구글링을 시작했다.

그 과정에서 아래 GitHub 이슈를 포함한 몇 가지 레퍼런스를 확인하게 되었다.

spring-projects/spring-data-r2dbc의 Add support for batch insert (#259) GitHub

이 이슈에서는,

DatabaseClient를 이용해 Batch Insert를 하고 싶다는 요청이 있었고,
작성자가 “워크어라운드로 Statement를 직접 써보긴 했지만, Connection을 직접 관리해야 해서 불편하다”고 적고 있다. GitHub
라벨이 status: pending-design-work로 달려 있으며,
“아직 정식으로 설계·지원되지 않은 기능”이라는 상태로 유지되고 있었다. GitHub

이걸 보고 정리한 결론은 단순했다.

“내가 API를 ‘틀리게’ 쓰고 있어서가 아니라,
Spring Data R2DBC 자체가 아직 원하는 형태의 Batch Insert를 공식 지원하지 않는 상황에 가깝다.”

즉, 프레임워크에 “알아서 Batch 처리해달라”고 맡기는 전략은 이 조합에서는 한계가 있다는 걸 받아들이게 되었다.

3-4. 방향 전환: 프레임워크에 맡기지 말고, 쿼리 패턴을 내가 설계하자

여기서부터 접근이 바뀌었다.

“고수준 API를 더 파보자” → “실제 DB로 나가는 쿼리 패턴 자체를 바꾸자”
드라이버·프레임워크에 기대지 않고,
내가 원하는 형태의 INSERT 쿼리를 만들어서 한 번에 보내는 쪽으로 방향을 틀었다.

이때 떠올린 전통적인 RDB 패턴이 바로 다음과 같은 아주 기본적인 다중 VALUES Bulk Insert였다.

INSERT INTO key_table (col1, col2, col3) VALUES 
('a1', 1, '2025-11-26'), 
('a2', 2, '2025-11-27'),
... ,
('aN', N, '2025-12-01');

4. 해결 방향: 다중 VALUES 기반 Bulk Insert 유틸리티

위 패턴을 활용하면,

쿼리 호출 횟수 감소 → 네트워크 왕복 감소
쿼리 파싱/실행 계획 수립 횟수 감소
한 번의 트랜잭션 안에서 더 많은 row 처리

라는 장점이 있다.

그래서 R2DBC 환경에서도 이 형태를 쓰기 위해, 그리고 동료도 편히 쓸 수 있도록
다중 VALUES 기반 Bulk Insert SQL을 만들어주는 유틸리티를 직접 설계했다.

5. Bulk Insert 유틸리티 설계

코드를 블로그에 그대로 공개하는 것은 문제가 있어, 아주 단순화한 유틸리티를 활용한 예시는 다음과 같다.

5-1. BatchQuery 생성 예제

StringBuilder sqlSb = queryGenerator.getInitSql(ProjectUsers.class, true);
sqlSb.append(queryGenerator.generateBatchQuery(users, createId, ProjectUsers.class));

return databaseClient.sql(sqlSb.toString())
        .fetch()
        .all()
        .map(row -> {
            log.info("row is {}", row);
            return ProjectUsers.builder().build();
        });

⚠️ Security Note: SQL Injection 방어 이 방식은 Raw SQL을 생성하므로 SQL Injection에 취약할 수 있다. 따라서 이 유틸리티를 범용적으로 공개하지 않고, 엄격한 Type Check가 선행된 내부 로직에만 제한적으로 사용하도록 통제했다. 외부 사용자 입력을 직접 바인딩해야 한다면 ESAPI나 엄격한 정규식 검증을 거치도록 설계해야 하므로 주의가 필요하다.

6. 실제 적용 결과: 10,000건 기준 13분 → 34초

이 Bulk Insert 유틸리티는 실제로 차량 키 관리 솔루션의 대칭 키 생성 배치 작업에 적용했다.

최초 구현에서는 대칭 키 10,000개를 생성·저장하는 데 약 13분(780초)이 걸렸지만,
Bulk Insert 유틸리티 적용 후에는 10,000개 기준으로 환산하면 약 32초가 소요됐으며,
대략 23배 수준의 성능을 확보할 수 있었다.

10,000개 키 유도/암호화/저장

7. 개발 편의성과 성능관점에서의 트레이드오프

내가 구현한 Bulk Insert 유틸리티는 Java Reflection을 사용하여 쿼리를 동적으로 생성했다.
이는 매번 개발자가 직접 Query를 작성하지 않고, 유지보수성을 높이기 위함이었다.

물론, 일반적으로 Reflection은 정적 코드보다 호출 비용이 높다고 알려져 있다.

하지만 이 기능의 핵심 병목(Bottleneck)은 CPU 연산이 아니라, DB와의 네트워크 통신(I/O)에 있었다.
실제로 10만 건의 데이터를 처리할 때 DB I/O가 수 초(Sec) 단위로 발생하는 반면, Reflection을 통한 문자열 생성은 밀리초(ms) 단위에 불과했다.

따라서 코드의 복잡도를 높이는 캐싱 로직 추가보다는, 유지보수성과 범용성을 챙기는 방향으로 구현했다.

WebFlux 환경에서 레거시 Logging 시스템을 AOP 기반으로 리팩토링한 기록

moyanglee — Sun, 13 Apr 2025 16:06:45 +0900

컨트롤러에 로직이 묻히고, 로그 한 줄 남기기 위해 수십 줄의 코드가 반복되던 레거시 로깅 시스템.

결국 주말을 반납하고 고군분투 끝에 AOP 기반으로 리팩토링했다.

이번 포스트에서는 이 리팩토링 과정을 정리 해보려고 한다.

✨ 리팩토링 배경

1. 기존 Logging 기능

기존 레거시 로그코드는 아래와 같은 기능과 모습을 가지고 있었다.

6하원칙 기반 로그 메시지: 누가, 언제, 어디서, 무엇을 했는지를 기반으로 성공/실패 여부와 메시지를 남긴다.
다국어 지원: 한국어 및 영어 메시지를 국제화 키로 관리
WebFlux 대응: 비동기 환경에서도 동작 가능

2. 문제점

문제 항목	상세 설명
⚠️ 관심사 혼재	컨트롤러에 비즈니스 로직과 로깅 로직이 섞여 있어 가독성 저하(가장 문제가 되는 부분이었다.)
⚠️ 반복 코드	API마다 유사한 로깅 코드가 반복됨
⚠️ 메시지 분산	다국어 메시지 키가 코드 곳곳에 분산되어 유지보수 어려움
⚠️ WebFlux 특성	RequestBody는 Flux로 구성돼 있어 한번 소비하면 재사용 불가

기존 레거시코드는 아래와 같은 구조를 가지고 있었으며 위와 같은 문제점을 가지고 있었다.

@Operation(summary = "Insert Secure Data", description = "Legacy Insert API with Logging")
@PostMapping("/insert")
public Mono<SecureDTO.Response> insert(
        @Parameter(description = "SecureDTO.Request") @RequestBody SecureDTO.Request reqDto,
        ServerHttpRequest request) {

    return getCurrentUserId(request).switchIfEmpty(Mono.just("")).flatMap(userId -> {
        String userIp = extractClientIp(request);
        String uri = request.getPath().toString();

        // Set common service metadata
        // ...

        AtomicReference<List<Map<String, Object>>> logs = new AtomicReference<>();

        Mono<SecureEntity> insertFlow = secureService.insertData(reqDto)
        .doOnSuccess(result -> {
            // Success log 세팅
            // ...
        })
        .onErrorResume(e -> {
            // Error log 세팅
            // ...
        });

        return logUtil.logWithData(insertFlow, logs);
    });
}

리팩토링 목표 및 성과

내가 지향하는 이번 리팩토링의 목표는 아래와 같았다.

6하원칙에 의거한 자세한 로깅 Content 제공
기존에 비해 심플한 로깅 메시지를 남기되, RequestBody를 함께 저장함으로써 추적성을 올렸다.
성공/실패에 대한 로그 및 에러코드 제공
기존과 동일하게 해당 요청의 성공/실패 여부를 남기고, 실패 했다면 실패 원인과 에러코들르 함께 남긴다.
multipart/form-data Content-Type 지원
제품 특성상 자주 쓰이는 multipart/form-data Content-Type을 지원해야 했다. 단, 이때 용량이 크고 보안상 문제가 될 수 있는 fileData는 filename만 로그에 남기는 식으로 처리하였다.
다국어 기능 제공
기존과 동일하게 2개국어 지원이 되도록 한다.
보안 데이터 마스킹
비밀번호와 같은 보안데이터는 로그데이터에 남기지 않도록 마스킹처리 하였다.
로그 메시지 유지보수성 제고
기존에 분산화 되어 있던 로그메시지를 하나의 파일에서 직접 관리할 수 있도록 개선하였다.
WebFlux환경에서 Reactive하게 동작

이번에 리팩토링한 결과 아래처럼 간단히 @LoggingAPI만 붙여주면 로그가 모두 남게 되었다.
아래 실제 구현 코드를 보면서 어떻게 위 조건들을 충족시킬 수 있었는지 정리해보도록하자.

@LoggingAPI
@PostMapping("/insert")
public Mono<SecureDTO.Response> insert(@RequestBody SecureDTO.Request reqDto, ServerHttpRequest request) {
    return getCurrentUserId(request).flatMap(userId -> {
        //... data settings...
        String userIp = extractClientIp(request);
        return secureService.insertData(reqDto);
    });
}

구현 구조

이번 리팩토링에서는 세 가지 핵심 컴포넌트를 새롭게 설계하여 전체 로깅 시스템의 구조를 개선했다.

각 컴포넌트는 기존의 문제를 해결하기 위한 목적을 가지고 있으며, 어떻게 역할을 나누었는지 아래에 자세히 설명한다.

1. LogMessages - 로그 메시지 집중 관리

기존에는 로그 메시지에 사용되는 다국어 키들이 코드 전반에 흩어져 있었기 때문에, 하나의 메시지를 변경하려 해도 어디서 사용하는지 찾는 데 시간이 걸렸다. 이를 해결하기 위해 메시지 키를 Enum 클래스로 집중 관리하도록 설계했다.

@Getter
@RequiredArgsConstructor
public enum LogMessages {
    LOGIN("/login", "System", "log.audit.login.success", "log.audit.login.fail"),
    ...
    UNKNOWN("", "Unknown", "log.audit.etc.success", "log.audit.etc.fail");

    public static LogMessages fromPath(String path) {
        return Arrays.stream(values())
            .filter(e -> path.equalsIgnoreCase(e.path))
            .findFirst().orElse(UNKNOWN);
    }
    
    public String getSuccessMessage(List<String> params) {
        return MessageUtil.getMessageService().getMessage(successMsgKey, params);
    }

    public String getFailMessage(List<String> params) {
        return MessageUtil.getMessageService().getMessage(failMsgKey, params);
    }
}

이 Enum을 사용하면 경로 기반으로 자동으로 메시지를 매핑할 수 있어서 가독성과 유지보수성을 크게 개선할 수 있었다.

2. CachingRBFilter - RequestBody 캐싱

WebFlux의 비동기 환경에서는 RequestBody가 스트리밍 방식으로 전달되기 때문에, 한번 읽고 나면 더 이상 데이터를 꺼내 쓸 수 없다. 이 문제를 해결하기 위해 RequestBody를 메모리에 저장해두고, 여러 번 재사용할 수 있도록 필터(WebFilter)를 도입했다.

@Component
//...
@Slf4j
public class CachingRequestBodyFilter implements WebFilter {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        if (!isCachingRequired(request)) {
            log.debug("no need to cache request body");
            return chain.filter(exchange);
        }

        return DataBufferUtils.join(request.getBody())
                .defaultIfEmpty(exchange.getResponse().bufferFactory().wrap(new byte[0]))
                .flatMap(dataBuffer -> {
                    byte[] bytes = new byte[dataBuffer.readableByteCount()];
                    dataBuffer.read(bytes);
                    DataBufferUtils.release(dataBuffer);

                    String cachedBody = new String(bytes, StandardCharsets.UTF_8);

                    // 저장
                    exchange.getAttributes().put("cachedRequestBody", cachedBody);

                    // 복제해서 body 제공
                    ServerHttpRequestDecorator decoratedRequest = new ServerHttpRequestDecorator(request) {
                        @Override
                        public HttpHeaders getHeaders() {
                            return super.getHeaders();
                        }

                        @Override
                        public Flux<DataBuffer> getBody() {
                            return Flux.defer(() -> {
                                DataBufferFactory factory = exchange.getResponse().bufferFactory();
                                return Flux.just(factory.wrap(bytes));
                            });
                        }
                    };

                    return chain.filter(exchange.mutate().request(decoratedRequest).build());
                });
    }
}

특히 multipart/form-data 형식은 애초에 재사용이 가능할 뿐아니라 대용량 파일이 들어올 수 있기 때문에,
이런 요청은 필터에서 캐싱 대상에서 제외(isCachingRequired)해 성능에 주는 영향을 최소화 하였다.

3. LoggingAspect - 핵심 로깅 로직

로깅 처리는 LoggingAspect라는 클래스에서 수행되며, 핵심 흐름은 다음과 같다.

@LoggingAPI 어노테이션이 붙은 API를 감지하여 AOP가 동작한다.
사용자 ID, IP, 요청 URI, Body 등을 추출한다.
요청 결과가 성공인지 실패인지에 따라 적절한 메시지를 설정한다.
이를 바탕으로 로그를 생성하고 DB에 저장한다.

아래는 그 예시코드이다.

@Aspect
@Component
@Slf4j
@Order(3)
@RequiredArgsConstructor
public class LoggingAspect {

    private final ConfigProperties configProperties;
    private final LoginService loginService;
    private final ApiKeyService apiKeyService;
    private final AuditLogRepository auditLogRepository;
    private final int UNEXPECTED_ERROR_CODE = 9999;

    @Around("@annotation([package-path].LoggingAPI)")
    public Object logRequestResponse(ProceedingJoinPoint joinPoint) {
        Object[] args = joinPoint.getArgs();
        ServerHttpRequest request = (ServerHttpRequest) args[args.length - 1];

        return getUserId(request)
                .flatMap(userId -> processLoging(joinPoint, request, args, userId))
                .cast(Object.class);
    }

    /**
     * 사용자 ID를 조회하는 메서드
     * 1. 쿠키에 토큰이 있는 경우에는 해당 토큰으로 사용자 ID를 조회
     * 2. 쿠키에 토큰이 없는 경우에는 API Key로 사용자 ID를 조회
     * 3. fallback 처리
     *
     * @param request
     * @return
     */
    private Mono<String> getUserId(ServerHttpRequest request) {
        //...
    }

    private Mono<?> processLoging(ProceedingJoinPoint joinPoint, ServerHttpRequest request, Object[] args, String userId) {
        LocalDateTime requestTime = DateUtil.getUTCLocalDateTime();
        String userIp = NetworkUtil.getClientIP(request);
        String requestPath = request.getPath().toString();
        String requestMethod = request.getMethod().toString();

        String requestBody = extractRequestBody(request, args);

        LogMessages lm = LogMessages.fromPath(requestPath);
        String successMessage = lm.getSuccessMessage(null);
        String failMessage = lm.getFailMessage(null);

        AuditLogBuilder alb = AuditLog.builder()
                //... 생략
                .userId(userId)
                .userIp(userIp)
                .requestPath(requestPath)
                .requestMethod(requestMethod)
                .requestBody(requestBody)
                .requestTime(requestTime);
        try {
            Object result = joinPoint.proceed();
            return handleResult(result, alb, successMessage, failMessage)
                    .onErrorResume(e -> {
                        // some error 처리
                        return Mono.error(e);
                    });
        } catch (Throwable e) {
            return handleException(e, alb, failMessage);
        }
    }

    /**
     * Request Body를 추출하는 메서드
     * content-type이 multipart/form-data인 경우에는
     * FilePart를 포함한 Map<String, Object> 형태로 변환하여 데이터를 정리하여 json.stringify해서 리턴
     * 그 이외의 경우에는 String 형태로 변환하여 리턴
     *
     * @param request
     * @param args
     * @return
     */
    private String extractRequestBody(ServerHttpRequest request, Object[] args) {
        // ... 생략
        // 그 이외의 경우
        Object cachedBody = request.getAttributes().get("cachedRequestBody");
        return (cachedBody instanceof String) ? (String) cachedBody : ObjectUtil.convertObjectToJsonString(cachedBody);
    }

    /**
     * multipart/form-data인 경우에 Request Body를 Map<String, Object> 형태로 변환하는 메서드
     * FilePart인 경우에는 filename을 key로 하여 Map에 저장
     * FilePart[]인 경우에는 filename을 ArrayList에 저장하여 Map에 저장
     * jsonString인 경우에는 data를 키로 하여 그대로 Map에 저장
     *
     * @param args
     * @return
     */
    private Map<String, Object> getMultipartDataMap(Object[] args) {
        Map<String, Object> result = new HashMap<>();
        for (Object arg : args) {
            if (arg instanceof FilePart) {
                FilePart file = (FilePart) arg;
                result.put("file", file.filename());
            } else if (arg instanceof FilePart[]) {
                FilePart[] files = (FilePart[]) arg;
                ArrayList<String> filenames = new ArrayList<>();
                for (FilePart file : files) {
                    filenames.add(file.filename());
                }
                result.put("files", filenames);
            } else if (arg instanceof String) {
                result.put("datas", arg);
            }
        }

        return result;
    }

    /**
     * 응답을 처리하는 메서드
     */
    private Mono<?> handleResult(Object result, AuditLogBuilder alb, String successMessage, String failMessage) {
        if (result instanceof Mono) {
            return ((Mono<?>) result).flatMap(response -> {
                AuditLog auditLog = alb.logMessage(successMessage)
                        .errorCode(0)
                        .build();

                return saveAuditLog(auditLog).thenReturn(response);
            })
                    .onErrorResume(e -> {
                        String errorDesc = e.getMessage();
                        int errorCode = UNEXPECTED_ERROR_CODE;

                        if (e instanceof CustomException) {
                            errorDesc = ((CustomException) e).getErrorMsg();
                            errorCode = ((CustomException) e).getErrorCode().getCode();
                        }
                        AuditLog auditLog = alb.logMessage(failMessage)
                                .errorCode(errorCode)
                                .errorDesc(errorDesc)
                                .build();

                        return saveAuditLog(auditLog).then(Mono.error(e));
                    });
        } else {
            // Mono가 아닌 응답 처리
            // ...
        }
    }
}

삽질 & 극복기

처음 이 리팩토링을 시작했을 때에는 그렇게 어려운 작업이 아닐거라고 생각했지만,
여느 다른 일들과 마찬가지로 막상 시작하고나니 여러가지 문제들이 나를 기다리고 있었다.

1. WebFlux와 RequestBody

WebFlux에서는 RequestBody가 Flux<DataBuffer> 형태로 들어오는데, 이게 한 번 읽고 나면 다시는 사용할 수 없다는 제한이 있다. 처음엔 단순히 로그를 남기려다 전체 API 동작이 꼬이는 문제가 생겼다. 그래서 이 문제를 해결하기 위해 CachingRBFilter를 만들었고, Request를 복제해서 다시 사용할 수 있도록 ServerHttpRequestDecorator를 적용해 해결할 수 있었다.

2. 성능 고려

RequestBody를 캐싱하면 메모리를 추가로 사용하게 되는데, 우리 시스템처럼 대용량 파일도 다뤄야 하는 상황에서는 큰 부담이 될 수 있었다. 그래서 multipart/form-data 요청은 캐싱 대상에서 제외했고, 나머지 요청에 대해서만 필요한 경우에 한해 캐싱이 동작하도록 설계했다. 이후 JMeter로 현재 제품 사용량을 고려한 실제 부하 테스트를 돌려본 결과, 성능상 문제가 없는 것을 확인했다.

3. 레거시 코드 제거

AOP 기반 로깅 시스템을 도입하면서 기존의 모든 API에서 레거시 로깅 코드를 걷어내야 했다. 단순히 삭제만 하면 되는 줄 알았지만, 실제로는 과거 코드 안에 숨어 있던 버그 3개를 발견하게 되었고, 이 기회에 함께 수정할 수 있었다. 이 작업이 정말 시간이 오래 걸렸다.

4. 동료 설득

가장 고민스러웠던 부분 중 하나는 기존 로그 시스템이 동료 선임분이 꽤 공들여 만들어 놓은 구조였다는 점이다. 자칫하면 기존 코드를 부정하는 모양새가 될 수 있었기에, 변경 전후 비교 예시와 개선 효과를 실제 코드와 함께 최대한 정리해서 설명드렸다. 실제 동작하는 모습까지 보여드리며 리뷰를 요청했고, 다행히 긍정적으로 검토해 주시고 피드백도 많이 주셔서 성공적으로 마칠 수 있었다.

마무리하며

단순히 코드를 리팩토링한 것이 아니라, 시스템의 유지보수성과 확장성을 높이는 경험이었다. 반복되는 코드, 분산된 메시지, WebFlux의 제약을 극복하면서 더욱 견고하고 재사용 가능한 로깅 시스템을 만들 수 있었다.

앞으로도 기술적 부채를 외면하지 않고, 직접 개선하는 개발자가 되고 싶다.

[Java] Java에서 JSON 다루기(mapper, converter)

moyanglee — Thu, 4 Apr 2024 09:00:18 +0900

이번 포스트에서는 Java에서 JSON을 다루는 방법에 대해 정리해보고자 합니다.

간단하게 유틸화시켜 사용해보니 꽤나 편리합니다.

Object to JsonString

POJO를 JsonString으로 변환하는 방법입니다.

다양한 방법이 있지만 만약 아래처럼 field명과 jsonProperty가 달라야 한다면 ObjectMapper를 사용하는 것이 편리합니다.

따라서 저는 ObjectMapper를 사용하는 방법을 중심으로 설명하도록 하겠습니다.

public class SampleClass{
    @JsonProperty("Test Custom Field")
    private String testCustomField;
}

import com.fasterxml.jackson.databind.ObjectMapper;


public static String convertObjectToJsonString(Object o) {
    ObjectMapper om = new ObjectMapper();
    //Object에 비어있지 않은 값만 JSONString에 포함
    om.setSerializationInclusion(JsonInclude.Include.NON_EMPTY);

    String result = null;
    try {
        result = om.writeValueAsString(o);
    } catch (JsonProcessingException e) {
        System.out.println("Error");
    }
    return result;
}

JsonString to Object (특정 클래스로 변환)

앞서 변환한 JSONString을 특정 클래스로 되돌리는 함수입니다.
강제 캐스팅 없이 범용적으로 사용하기 위해 Generic으로 만들었습니다.

public static <T> T convertJsonStringToObject(String jsonString, Class<T> c) {
    ObjectMapper om = new ObjectMapper();
    T result = null;
    try {
        result = om.readValue(jsonStr, c);
    } catch (JsonProcessingException e) {
        System.out.println("Error");
    }
    return result;
}

Object to JSONObject

POJO를 JSONObject로 변환하는 방법입니다.

이때 JSONOBject의 import 경로에 주의해주세요.(simple json이 아닙니다.)

convertObjectToJsonString 함수는 앞서 구현한 Object To JsonString을 참고해주세요.

import org.json.JSONObject;

public static JSONObject convertObjectToJSONObject(Object obj) {
    String stringifiedJSON = convertObjectToJsonString(obj);
    JSONObject jsonObject = new JSONObject(stringifiedJSON);

    return jsonObject;
}

2. Gson 사용

google에서 나온 Gson을 이용해서도 아래처럼 간단히 구현할 수 있지만, 앞서 설명한 것 처럼 커스턴 프로퍼티네이밍을 처리하기가 불편합니다.

//build.gradle.kts
implementation("com.google.code.gson:gson:2.10.1")


//Some.java
public static JSONObject convertObjectToJSONObject(Object obj) {
    String gsonStringJson = new Gson().toJson(obj);
    JSONObject jsonObject = new JSONObject(gsonStringJson);

    return jsonObject;
}

JSONObject to Object(특정 클래스로 변환)

JSONObject를 원래 Object로 변환하는 방법입니다.

역시 강제 캐스팅 없이 범용적으로 사용하기 위해 Generic으로 만들었습니다.

참고로 JSONObject.toString 메소드를 이용하면 간단히 JSONString으로 변환할 수 있습니다.

public static <T> T convertJSONObjectToObject(JSONObject jsonObj, Class<T> c) {
    return convertJsonStringToObject(jsonObj.toString(), c);
}

[OpenSSL]self-signed 인증서 체인 만들기(2depth, intermediateCA)

moyanglee — Wed, 20 Mar 2024 11:01:49 +0900

이번 포스트에서는 openssl을 이용하여 인증서 체인을 만드는 방법에 대해 정리해보고자 합니다.

최종 모습은 RootCA - IntermediateCA - Leaf 구조(2depth)가 될 것입니다.

그리고 이렇게 발급된 인증서가 정상적으로 발급된 것인지 openssl을 활용한 검증 방법까지 정리해보도록 하겠습니다.

당연히 아래 작업을 진행하기 위해서는 openssl이 설치되어 있어야 합니다.

인증서 발급 순서

openssl을 이용하여 인증서를 발급받는 일반적인 순서는 아래와 같을 것입니다.
하지만 RootCA, IntermediateCA, Leaf 마다 발급 시 옵션이 조금씩 상이하니 아래 글을 따라 진행해주시면 되겠습니다.
(** CA = Certificate Authority)

privateKey 생성
CSR 생성
Certificate생성

RootCA 인증서 발급

RootCA인증서 발급방법에 대해 바로 들어가기 전에 먼저 CSR이 무엇인지 간단히 집고 넘어가도록 하겠습니다.

만약, 이미 RootCA는 CSR을 생성할 필요가 없는 이유에 대해 알고 계시다면 아래 CSR부분은 넘겨도 무방합니다.

1. CSR(Certificate Signing Request)?

CSR은 인증서 발급기관(Certificate Authority)에게 제출하는 일종의 인증서 발급 요청서라고 할 수 있습니다.

CSR이 일반적으로 어떤 내용을 포함하고 있는지 openssl을 이용해 확인해 보겠습니다.

openssl req -in serverCA.csr -text -noout

# CSR 내용
Certificate Request:
    Data:
        Version: 1 (0x0)
        Subject: C=KR, ST=Seoul, L=Yeouido, O=ServerCA, OU=ServerCA, CN=localhost
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    00:fc:80:2b:1c:af:...
                Exponent: 65537 (0x10001)
        Attributes:
            (none)
            Requested Extensions:
    Signature Algorithm: sha256WithRSAEncryption
    Signature Value:
        7e:bc:c7:79:09:...

Subject는 인증서에 포함될 Entity에 대한 정보를 가지고 있으며 보통 아래 내용이 포함됩니다.

C(country): 국가
ST(State or Province Name): 주, 또는 지방
L(Locality Name): 도시 또는 지역
O(Organization Name): 주체의 조직 또는 회사명
OU(Organization Unit Name): 주체의 부서나 단위
CN(Common Name): 주로 서버의 도메인 이름이나 개체의 이름입니다. 인증서가 특정 도메인이나 개체와 연결되어야 할 때 사용됩니다.

Subject Public Key Info는 인증서에 포함된 PublicKey에 대한 정보를 보여주며, 보통 아래 내용을 포함합니다.

Public Key Algorithm: 공개키 생성 알고리즘
Public-Key: 공개키 크기(e.g. 2048 bit)
Modulus, Exponent: RSA알고리즘 디테일정보
Signature Value: CSR에 포함된 publicKey와 쌍이 되는 privateKey를 이용해 CSR에 사인한 값. (CA가 검증하기 위해 사용)

이렇게 CSR은 CA에게 이런이런 내용의 인증서를 발급해달라는 요청서이기 때문에, 상위 CA가 없는 RootCA는 CSR을 생성할 필요가 없기 때문입니다. (RootCA는 Self-Signed한 인증서를 가지게 됩니다.)

따라서 저는 아래에서 진행할 RootCA 인증서 발급에서 CSR을 생성하지 않고 바로 Self-Signed 인증서를 만들 것입니다.

2. RootCA 인증서 발급

#serverRootCA 개인키 생성
openssl genrsa -aes256 -out rootCA.key 2048
#serverRootCA 인증서 발급(self-sign)
openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1825 -out rootCA.pem

위 command가 가지는 의미는 아래와 같습니다.

genrsa: rsa알고리즘을 이용하여 개인키 생성
-aes256: 개인키 생성시 AES 256 비트 암호화 사용
-out: 출력 파일의 이름 지정
2048: 개인키 길이
req -x509 -new: x.509형식의 새로운 인증서를 생성
-key: 인증서에 서명할 키를 지정(이때 RootCA의 개인키를 그대로 사용 -> selfSigned)
-sha256: 인증서 서명을 sha256알고리즘 이용해 암호화
-days: 인증서 유효기간
-out: 출력파일 이름지정

3. 발급 시 입력 값 예시 및 결과

위 커맨드를 그대로 붙여넣게 되면 몇가지 입력할 사항들이 생기는데, 이 부분은 아래처럼 입력해주면 됩니다.

아래 내용은 블로그 포스트용으로 임시로 생성한 것으로, 적합하게 바꿔 입력하면 됩니다.

RootCA 인증서 발급

그 결과로 아래처럼 rootCA.key와 rootCA.pem이 생성된 것을 볼 수 있습니다.

RootCA 인증서 발급 결과

IntermediateCA 인증서 발급

이제 위에서 만든 RootCA인증서로 사인한 IntermediateCA용 인증서를 발급 받아보도록 하겠습니다.

1. IntermediateCA 인증서 발급

RootCA인증서 발급과 달라 주의할 부분은 아래와 같습니다.

발급절차에 CSR 생성 추가
인증서 발급시 CA관련 정보 입력 및 basicConstraints 추가

# intermediateCA 개인키 생성
openssl genrsa -aes256 -out intermediateCA.key 2048
# intermediateCA CSR 생성
openssl req -new -sha256 -key intermediateCA.key -out intermediateCA.csr
# intermediateCA 인증서 발급
openssl x509 \
  -req \
  -in intermediateCA.csr \
  -CA rootCA.pem \
  -CAkey rootCA.key \
  -CAcreateserial \
  -out intermediateCA.pem \
  -days 365 \
  -sha256 \
  -extfile <(echo "basicConstraints=critical,CA:TRUE")

위 커맨드에서 새롭게 추가되어 주의할 부분은 아래와 같습니다.

-CAcreateserial: 자동으로 시리얼(serial) 파일을 생성하여 서명된 인증서에 일련 번호(serial number)를 할당. 이 옵션이 있으면, 따로 시리얼 넘버를 지정할 필요가 없어서 편리.
-extfile: 사용자 지정 확장(extension) 구성 파일을 지정하는 데 사용. 주로 인증서의 확장 필드를 설정하는 데 활용.
여기에서는 Leaf인증서가 아닌, CA인증서로 발급하기 위해 사용(자세한 내용은 하단 TroubleShooting 참고)

2. 발급 시 입력 값 예시 및 결과

EmailAddress와 optional한 입력값들은 그냥 enter키를 입력하여 넘겼습니다.

Intermeidate 인증서 발급절차

이제 intermediateCA.key, intermediateCA.csr, intermediateCA.pem이 생성된 것을 볼 수 있을 것입니다.

아래 명령어를 통해 인증서가 제대로 생성됐는지 살펴보고 가겠습니다.

# intermediateCA 인증서 출력
openssl x509 -in intermediateCA.pem -text -noout

결과는 아래와 같습니다.

IntermediateCA 인증서 상세내역

여기에서 주의해서 볼 점은 Issuer부분과 X509v3 extensions 부분입니다.

Issuer 부분에서 RootCA 인증서를 발급할 때 입력한 값들이 제대로 들어 있는지 확인합니다.

X509v3 extensions 부분에서 X509v3 Basic Constraints가 critical, CA:TRUE로 세팅되어 있는지 확인합니다.
이 값이 존재해야 Leaf인증서가 아닌, CA인증서로 제대로 발급된 것입니다.

3. 검증

intermediateCA 인증서가 제대로 발급되었는지, 간단히 검증해보도록 하겠습니다.

아래 명령어로 검증 해볼 수 있습니다.

# openssl 인증서 검증
openssl verify -CAfile rootCA.pem intermediateCA.pem

아래처럼 OK가 나오면 rootCA로 제대로 사인되었고, 검증이 가능하다는 뜻입니다.

IntermediateCA 인증서 검증 결과

Leaf 인증서 발급

이제 intermediate인증서를 이용하여 Leaf 인증서를 발급해보도록 하겠습니다.

Leaf 인증서는 해당 인증서로 다른 인증서를 발급하지 못하는 인증서를 말합니다. 즉, CA 인증서가 아니라는 뜻입니다.

1. Leaf 인증서 발급

intermediateCA 인증서를 발급했던 것과 거의 흡사합니다. 단, CA인증서 확장필드값을 설정해주는 부분이 사라졌습니다.

openssl genrsa -aes256 -out leaf.key 2048
openssl req -new -sha256 -key leaf.key -out leaf.csr
openssl x509 \
	-req \
	-in leaf.csr \
	-CA intermediateCA.pem \
	-CAkey intermediateCA.key \
	-CAcreateserial \
	-out leaf.pem \
	-days 365 \
	-sha256

2. 발급 시 입력 값 예시 및 결과

intermediateCA 인증서를 발급과 같은 절차입니다.

Leaf 인증서 발급

이제 leaf.key, leaf.csr, leaf.pem 파일이 생성된 것을 볼 수 있을 것입니다.

아래처럼 정상적으로 발급된 것을 확인 할 수 있습니다.

extensions에 CA관련 부분이 없다는 것을 확인 할 수 있습니다.

openssl x509 -in leaf.pem -noout -text
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            15:01:be:40:d1:b4:5f:72:6d:b1:d2:df:2b:18:1f:d7:14:d6:a5:2e
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=KR, ST=Seoul, L=Yeouido, O=IntermediateCA, OU=IntermediateCA, CN=localhost
        Validity
            Not Before: Mar 20 01:32:41 2024 GMT
            Not After : Mar 20 01:32:41 2025 GMT
        Subject: C=KR, ST=Seoul, L=Yeouido, O=Leaf, OU=Leaf, CN=localhost
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    00:c6:26:c9:b3:...
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Key Identifier:
                47:9C:51:5B:9E:12:C8:C8:1C:A6:BB:FE:28:63:18:0A:C3:89:9C:D7
            X509v3 Authority Key Identifier:
                85:29:C1:4C:3D:2A:87:CC:A4:88:DA:FD:89:8B:BE:71:BE:BD:9D:83
    Signature Algorithm: sha256WithRSAEncryption
    Signature Value:
        58:7c:1e:57:c1:3d:...

3. 검증

이제 RootCA, IntermediateCA 인증서를 이용해 Leaf 인증서가 제대로 발급되었는지 확인해보겠습니다.

먼저 RootCA 인증서와 IntermediateCA 인증서를 이어붙여 trustChain을 만들겠습니다.

cat rootCA.pem intermediateCA.pem > trustChain.pem

openssl은 검증할 때, 인증서 체인을 따라 올라가며 끝까지 검증을 합니다.

따라서 위처럼 trustChain을 만들어 해주는 것이 편리합니다.

이 trustChain으로 RootCA부터 Leaf 인증서까지 모두 정상적으로 검증되는 것을 아래 사진을 통해 볼 수 있습니다.

TrustChain 인증서 검증

만약, 위처럼 trustChain을 만들지 않고 아래처럼 바로 IntermediateCA 인증서로 Leaf 인증서를 검증하려고 한다면,
아래와 같은 에러를 맞이할 것입니다.

Leaf 인증서 - 검증실패

이는 IntermediateCA 인증서의 Issuer가 있다고 하는데, -CAfile에서 해당 인증서(RootCA 인증서)를 찾지 못했기 때문에 발생하는 에러입니다.

TroubleShootings

1. TrustChain 구성하지 않음

처음에는 openssl이 검증할 때 최상단 RootCA 인증서까지 검증한다는 사실을 모르고, IntermediateCA 인증서로 Leaf인증서를 검증하려고 하여 아래와 같은 에러를 계속 맞이하였습니다.

openssl verify -CAfile wrongCA.pem leaf2.pem
C=KR, ST=Seoul, L=Yeouido, O=WrongCA, OU=WrongCA, CN=localhost
error 2 at 1 depth lookup: unable to get issuer certificate
error leaf2.pem: verification failed
80052A0301000000:error:80000002:system library:file_open:No such file or directory:providers/implementations/storemgmt/file_store.c:263:calling stat(/opt/homebrew/etc/openssl@3/certs)

이 부분은 앞서 설명한 것처럼 RootCA 인증서까지 포함한 trustChain을 만듦으로써 해결할 수 있었습니다.

2. CA 인증서 발급, not Leaf 인증서

trustChain을 구성했음에도 검증에 실패하며 아래와 같은 에러가 발생하였습니다.

openssl verify -CAfile wrongTrustChain.pem leaf2.pem
C=KR, ST=Seoul, L=Yeouido, O=WrongCA, OU=WrongCA, CN=localhost
error 79 at 1 depth lookup: invalid CA certificate
error leaf2.pem: verification failed

스택오버플로우에서 openssl에서 확장필드값을 설정하지 않고 인증서를 발급하게 되면, default로 CA인증서가 아니라 Leaf인증서를 발급한다는 사실을 알게 되었습니다. (참고링크)

이에 앞서 IntermediateCA 인증서를 발급하는 부분에서 언급한 것처럼 CA 인증서로 지정하는 extension 부분을 설정해줌으로써 정상적으로 검증할 수 있었습니다.

[Springboot] Reactive Redis 총 정리(config, generic, test)

moyanglee — Tue, 6 Feb 2024 14:31:58 +0900

사내에서 Springboot를 사용하면서 Reactive Redis를 쓰고 있습니다.
이번 포스트에서는 config는 어떻게 설정하는지, 테스트 코드 작성방법, Generic하게 클래스에 맵핑해서 꺼낼 수 있는방법에 대해 정리해보고자 합니다.

Dependency

springboot 3.2.2, java17을 사용하고 있으며, dependency는 아래와 같습니다.

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-data-redis-reactive'
	implementation 'org.springframework.boot:spring-boot-starter-webflux'
	compileOnly 'org.projectlombok:lombok:1.18.24'
	annotationProcessor 'org.projectlombok:lombok'
	testImplementation 'org.springframework.boot:spring-boot-starter-test'
	testImplementation 'io.projectreactor:reactor-test'
	testImplementation "org.junit.jupiter:junit-jupiter:5.8.1"

	//test-container
	testImplementation 'org.testcontainers:junit-jupiter'
	testImplementation 'org.testcontainers:testcontainers:1.19.4'
}

Configuration

Redis에 연결하고 관련 서비스를 만들기 위해서, redis.core의 ReativeRedisOperation이 필요합니다.

아래 Config는 해당 Bean을 등록해주는 과정이라고 생각해주시면 됩니다.

@Configuration
@EnableAutoConfiguration(exclude={RedisAutoConfiguration.class, RedisReactiveAutoConfiguration.class})
public class RedisConfig {
    @Value("${spring.data.redis.host}")
    private String host;

    @Value("${spring.data.redis.port}")
    private int port;

    @Bean
    public ReactiveRedisConnectionFactory redisConnectionFactory() {
        return new LettuceConnectionFactory(host, port);
    }

    @Bean
    public ReactiveRedisOperations<String, Object> redisTemplate() {
        ReactiveRedisConnectionFactory rrcf = redisConnectionFactory();

        Jackson2JsonRedisSerializer<Object> serializer = new Jackson2JsonRedisSerializer<>(Object.class);

        RedisSerializationContext.RedisSerializationContextBuilder<String, Object> builder = RedisSerializationContext
                .newSerializationContext(new StringRedisSerializer());

        RedisSerializationContext<String, Object> context = builder.value(serializer).hashValue(serializer)
                .hashKey(serializer).build();

        return new ReactiveRedisTemplate<>(rrcf, context);
    }
}

@EnableAutoConfiguration(exclude={...})
내가 지정한 host, port, serializer를 등록하기 위한 부분입니다. 이 부분이 없으면 아래와 같은 에러를 보게 될 것입니다.

The bean 'redisConnectionFactory', defined in class path resource [org/springframework/boot/autoconfigure/data/redis/LettuceConnectionConfiguration.class], could not be registered. A bean with that name has already been defined in class path resource [com/example/demo/RedisConfig.class] and overriding is disabled.

Jackson2JsonRedisSerializer<Object> serializer
JSON 형식의 데이터를 Redis에 저장하기 위한 직렬화 및 역직렬화를 담당하는 Jackson2JsonRedisSerializer를 생성합니다. 이 때, Object.class를 전달하여 어떠한 객체 타입이라도 처리할 수 있도록 합니다. 이후 데이터를 가져올 때, 알맞은 Dto와 맵핑하는 부분은 아래 RedisService에서 구현하겠습니다.

그리고 application.yml에 아래처럼 세팅해주었습니다.

spring:
  data:
    redis:
      host: localhost
      password:
      port: 6379

redis test - TestContainer

1. 테스트 컨테이너 생성

레디스를 테스트하는 것에는 embeded redis 혹은 testContainer를 이용하는 2가지 방법이 있습니다.

저는 아래와 같은 이유로 testContainer를 이용하기로 결정하였습니다. 아래코드는 테스트컨테이너 홈페이지를 참조했습니다.

git clone만 받으면 따로 local에 redis설치 없이도 테스트를 돌릴 수 있다.
테스트의 독립성을 보장할 수 있다.
포트 충돌을 고려할 필요 없다.(참고링크)

우선, 아래와 같이 Redis Test Container를 생성해줍니다. 아래 클래스는 BeforeAllCallback의 구현 클래스입니다.

테스트 코드 내에서 @BeforeAll안에서 사용하지 않고 이렇게 빼는 이유는 아래에서 설명하겠습니다.

package com.example.demo;

import org.junit.jupiter.api.extension.BeforeAllCallback;
import org.junit.jupiter.api.extension.ExtensionContext;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.utility.DockerImageName;

public class RedisContainer implements BeforeAllCallback{

    private static final String REDIS_DOCKER_IMAGE = "redis:5.0.3-alpine";

    @Override
    public void beforeAll(ExtensionContext context) throws Exception {
        GenericContainer<?> REDIS_CONTAINER = new GenericContainer<>(DockerImageName.parse(REDIS_DOCKER_IMAGE))
            .withExposedPorts(6379).withReuse(true);

        REDIS_CONTAINER.start();

        System.setProperty("spring.data.redis.host", REDIS_CONTAINER.getHost());
        System.setProperty("spring.data.redis.port", REDIS_CONTAINER.getMappedPort(6379).toString());
    }
}

위 코드가 의미하는 부분은 간단합니다.
가장 먼저 "redis:5.0.3-alpine" 라는 이미지를 사용하여 REDIS_CONTAINER 내부에서 redis default port인 6379를 expose하도록 세팅합니다.

그리고 실제로 해당 컨테이너를 띄운 후, 해당 컨테이너의 호스트와 컨테이너 내부 포트 6379와 매핑되는 외부포트를 받아와 SystemProperty에 세팅해줍니다.

2. 테스트코드 작성

테스트 코드를 작성해보겠습니다.

여기에서 주의하여 볼 점은 @BeforeAll 메소드를 사용하는 것이 아니라, RedisContainer를 따로 뺀 뒤, ExtendWith를 통해 CoffeeTest클래스 생성전에 레디스 컨테이너연결을 하도록 했다는 점입니다.

package com.example.demo;

import static org.assertj.core.api.Assertions.*;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.annotation.Import;
import org.testcontainers.junit.jupiter.Testcontainers;
import reactor.core.publisher.Mono;
import reactor.test.StepVerifier;


@ExtendWith(RedisContainer.class)
@Testcontainers
@Import(RedisService.class)
@SpringBootTest
public class CoffeeTest {

    @Autowired
    private RedisService redisService;

    @Test
    void testCoffee() {
        String TESTKEY = "TEST_KEY";
        String TESTVALUE = "TEST_VALUE";

        redisService.setValue(TESTKEY, TESTVALUE).subscribe();
        Mono<String> storedValue = redisService.getCacheValueGeneric(TESTKEY, String.class);

        StepVerifier.create(storedValue)
                .assertNext(value -> assertThat(value).isEqualTo(TESTVALUE))
                .verifyComplete();
    }
}

위 테스트를 실행시키면, 아래처럼 testContainer가 실제로 뜨는 것을 확인 할 수 있습니다.

redis 서비스 - Generic redis service

이번에는 redis service를 만들어 보겠습니다. 처음 말씀드린 것처럼 Object로 직렬화 시켜 저장시킨 데이터를 다시 역직렬화 시키면서 원하는 DTO에 매핑하는 부분을 ObjectMapper와 Generic 함수를 이용해 getCacheValueGeneric를 구현해 보겠습니다.

package com.example.demo;

import org.springframework.data.redis.core.ReactiveRedisOperations;
import org.springframework.stereotype.Component;

import com.fasterxml.jackson.databind.ObjectMapper;

import reactor.core.publisher.Mono;
import lombok.RequiredArgsConstructor;

@Component
@RequiredArgsConstructor
public class RedisService {
  private final ReactiveRedisOperations<String, Object> redisOps;
  private final ObjectMapper objectMapper;

  public Mono<String> getValue(String key) {
    return redisOps.opsForValue().get(key).map(String::valueOf);
  }

  public Mono<Boolean> setValue(String key, Object value) {
    return redisOps.opsForValue().set(key, value);
  }

  public <T> Mono<T> getCacheValueGeneric(String key, Class<T> clazz) {
      try {
          return redisOps.opsForValue().get(key)
              .switchIfEmpty(Mono.error(new RuntimeException("No Datas for key: " + key)))
              .flatMap(value -> Mono.just(objectMapper.convertValue(value, clazz)));
      } catch (Exception e) {
          e.getStackTrace();
          return Mono.error(new RuntimeException("error occured!" + e.getMessage()));
      }
  }
}

실제코드와 연동

만약, 위 서비스 코드를 test-container가 아닌, 실제 redis와 연결해 이용하고 싶다면 redis를 설치 후 redis-server를띄운 뒤, 해당 서비스와 매핑되는 controller 코드를 구현하여 실행시키면 될 것입니다.

1. redis 설치

brew install redis

2. redis-server 실행

redis-server

3. Controller 구현

간단하게 만든 controller코드는 아래와 같습니다.

package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import lombok.RequiredArgsConstructor;
import reactor.core.publisher.Mono;

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;


@RestController
@RequiredArgsConstructor
public class CoffeeController {
  private final RedisService redisService;

  @GetMapping("/coffees")
  public Mono<Coffee> getCoffee(@RequestParam("id") String coffeeId) {
    return redisService.getCacheValueGeneric(coffeeId, Coffee.class);
  }

  @PostMapping("/coffee")
  public Mono<Boolean> postMethodName(@RequestBody Coffee coffee) {

      return redisService.setValue(coffee.getId(), coffee);
  }
  
}

Preview 있는 File Input 만들기(Next.js, TS)

moyanglee — Mon, 29 Jan 2024 13:25:00 +0900

현재 만들고 있는 기술블로그(링크)에서 포스팅의 편리성을 위해 이미지 업로드를 할 수 있는 기능이 필요했습니다. 이를 위해 사진 이미지를 미리 보여주는 file input 컴포넌트를 만들었고, 이번 포스트에서는 어떻게 구현했는지 정리해 보고자 합니다. CSS에 대한 포스트가 아님으로 CSS 부분은 최소화하고, 구현 로직에 대해 코드로 설명하겠습니다.

컴포넌트 설계

File Input with Preview 작동모습

무엇을 만들기 전에, 내가 만들고자 하는 것의 핵심 기능은 무엇인지, 어떻게 사용할 것인지 정리하는 부분은 정말 중요한 것 같습니다.

핵심기능

제가 구현 하고자 하는 File Input의 핵심기능은 아래와 같습니다.

복수의 이미지 파일들을 버튼을 통해 업로드 할 수 있다.
복수의 이미지 파일들을 preview 쪽에 Drag&Drop으로 업로드 할 수 있다.
현재 업로드한 파일의 preview를 보여준다.
preview 우측상단의 삭제 버튼을 통해 업로드한 파일을 삭제 할 수 있다.

사용방법

저는 해당 컴포넌트를 아래와 같은 방식으로 사용하고 싶습니다.
File 리스트 타입을 가진 useState를 선언하고, files와 setFiles 함수만 간단히 전달하면 나머지 preview, 삭제 버튼 등의 기능은 내부적으로 처리가 되었으면 좋겠습니다.

이후, 선택된 파일들을 서버에 보낼 때에는 files를 사용하면 될 것 입니다.

//...
const [files, setFiles] = useState<File[]>([]);
//...
<FileInput files={files} setFiles={setFiles} />
//...

기능 구현

Input태그를 사용하는 방법자체는 매우 간단합니다. 아래처럼 type을 file로, 그리고 multiple 속성을 주면 됩니다.

//accept는 Input이 허용할 파일 유형을 나타냅니다.
<input type="file" multiple accept="image/*" />

이 태그를 그대로 사용해도 되지만, CSS를 커스텀해주기 위해서는 아래의 추가 작업이 필요합니다.

input에 display:none; 속성을 줘서 보이지 않게 한다.
useRef를 활용하여, 커스텀 버튼이 클릭되면 Input태그가 클릭되게 한다.
팝업된 파일선택창에서 파일은 선택하면, trigger되는 이벤트인 change에 이벤트 리스너를 단다.

JSX 구조 잡기

기본적인 JSX구조를 먼저 잡아 보겠습니다.

크게 타이틀, Preview, CustomButton 으로 구성되어 있습니다.
Input태그에는 display:none; 속성을 부여했고, 버튼을 클릭할 경우, useRef를 활용하여 Input태그를 클릭하게 했습니다.
Preview지역에 Drop이벤트가 일어나거나, File을 선택하는 이벤트가 발생하면, selectFile가 실행됩니다.

<Top05>사진첨부</Top05>
<FileThumbnails
    files={files}
    deleteFileHandler={deleteFile}
    addFileHandler={() => inputRef.current?.click()}
    onDrop={selectFile}
/>
<Spacing size={15} />
<Button
    onClick={() => inputRef.current?.click()}
    style="outline"
    fontSize="0.75rem"
    btnType="button"
>
    사진을 추가해주세요
</Button>
<input
    id="file"
    ref={inputRef}
    type="file"
    multiple
    accept="image/*"
    style={{ display: 'none' }}
    onChange={selectFile}
/>

selectFile 구현하기

파일을 선택할 때 실행되는 selectFile 함수를 구현해보도록 하겠습니다.
drop이벤트와,파일 추가 버튼을 클릭하는 경우로 나누어 분기처리 해주어야 합니다.

기존에 추가된 파일이 있는 경우, 덮어 쓰는 것이 아니기 때문에, spread문법을 이용해 파일을 추가해주었습니다.

export default function FileInput({ files, setFiles }: FileInputProps) {
    //...
    function selectFile(
        e: React.DragEvent | React.ChangeEvent<HTMLInputElement>
    ) {
        e.preventDefault();
        let selectedFiles = [] as File[];
        if (e.type === 'drop') {
            const event = e as React.DragEvent;
            //Drop인 경우, dataTransfer 속성안에서 files를 찾을 수 있다.
            selectedFiles = Array.from(event.dataTransfer.files);
        } else if (e.type === 'change') {
            const inputEl = e.target as HTMLInputElement;
            //Change인 경우, event.target.files에서 files를 찾을 수 있다.
            selectedFiles = inputEl.files ? Array.from(inputEl.files) : [];
        }

        setFiles((prev) => [...prev, ...selectedFiles]);
    }
    //...
}

Preview - URL.createObjectURL

selectFile을 통해 추가된 파일들을 미리 보여 주는 기능을 URL.createObjectURL()을 이용하여 구현했습니다.

URL.createObjectURL는 File, Blob, MediaSource객체를 인자로 받고, 전달받은 객체를 가리키는 URL을 DOMString으로 변환하여 돌려줍니다.(API 세부 내역링크)

앞서 저는 선택한 파일들의 리스트(File[])를 FileThumbnails에 files props로 내려줬습니다. FileThumbnails에서 아래처럼 map을 이용해 순회하면서 렌더 해주었습니다.
Image는 next/image를 사용했고, src 부분에 집중해 주시면 되겠습니다.

//FileThumbnails.tsx
type FileThumbnailsProps = {
    files: File[];
    deleteFileHandler?: Function;
    addFileHandler?: MouseEventHandler<HTMLDivElement>;
    onDrop?: Function;
};

export default function FileThumbnails({
    files,
    deleteFileHandler,
    addFileHandler,
    onDrop
}: FileThumbnailsProps) {
//...
    {files.map((file) => (
        <div className={classes.image} key={file.name}>
            <Image
                src={URL.createObjectURL(file)}
                width={80}
                height={80}
                sizes="80px"
                alt={file.name}
                placeholder="blur"
                blurDataURL={URL.createObjectURL(file)}
            />
            <div
                className={classes.delete__btn}
                onClick={() => clickDeleteBtn(file.name)}
            >
                <CloseIcon size="0.8rem" />
            </div>
        </div>
    ))}
}
//...

이제 추가한 파일들의 preview를 볼 수 있습니다.
참고로, 여기에서 preview 우측 상단에 delete 버튼을 추가하고, 클릭 시 clickDeleteBtn 함수를 호출하게 합니다.

Drop이벤트 구현하기

위에서 FileThumbnails에 onDrop Props로 selectFile을 넘겨줬습니다. 이 부분을 어떻게 마무리해줘야 하는지 간단히 정리해 보겠습니다.

Thumbnails 컴포넌트 최상단 요소에 아래와 같이 이벤트 리스너를 설정해 주어야 합니다.

이는 우리가 파일을 드래그 & 드롭하게 되면 생기는 이벤트들 중 drop 이벤트가 일어났을 때에만 원하는 함수를 실행시키기 위함입니다.
(드래그 & 드랍시 발생하는 이벤트 리스트 참고)

<div className={classes.image__wrapper}
    onDragOver={(e) => {
        e.preventDefault();
        e.stopPropagation();
    }}
    onDragEnter={(e) => {
        e.preventDefault();
        e.stopPropagation();
    }}
    onDrop={(e) => {
        e.preventDefault();
        e.stopPropagation();
        onDrop && onDrop(e)
    }
    }
>
    //...
</div>

이렇게 하면 우리가 파일을 드래그 & 드롭 했을 때 정상적으로 selectFile이 실행되는 것을 확인할 수 있습니다.

추가 파일 제거 기능

추가된 파일을 목록에서 제거 하는 방법은 아래 처럼 fileName을 이용해 줬습니다.

//FileInput.tsx
//...
function deleteFile(fileName: string) {
    setFiles((prev) => prev.filter((file) => file.name !== fileName));
}

자! 이제 Preview를 보여주는 커스텀 File Input 컴포넌트가 모두 완성되었습니다.
확실히 각 기능을 담당하는 컴포넌트들을 미리 만들어 놓은 상태에서 위에서 기술한 JSX 구조 잡기에서처럼 코드를 작성하다 보니, 가독성도 좋고 개발 시간도 줄일 수 있었습니다.

내가 필요한 기능이 있으면 바로바로 기능들을 하나씩 추가할 수 있다는 부분이 참 재미있고, 자신만의 기술 블로그를 가지는 매력인 듯합니다.

혹시 부족한 부분이 있거나 궁금한점이 있으면 언제든지 댓글로 문의 부탁드립니다!

[ToC] 목차 컴포넌트 (feat. React) 구현

moyanglee — Sat, 20 Jan 2024 21:00:53 +0900

요즘 너무 바쁘지만, 주말을 맞아 NextJS로 만들고 있던 Blog에 ToC 컴포넌트 만들어 봤습니다.

이번 포스트에서는 어떤 부분에 포커스를 두고 개발을 했고, 구현하며 있었던 문제점과 해결방법에 대해 정리해보고자 합니다.

구현한 최종 모습은 아래와 같을 것입니다. (영상을 찍으면서 box-shadow효과가 뭉개져서 나오는데 이 부분은 무시해주세요..ㅎ)

주요 기능사항

포스트의 HTag를 기반으로 목차를 만든다(범위 : h1 ~ h3)
목차를 열고 닫을 수 있어야 한다.
1. ToC 컴포넌트가 메인컴포넌트가 겹치지 않는다면 열려 있는 것이 default이어야 한다.
2. 겹친다면, 닫혀 있는 것이 default이어야 한다.
현재 읽고 있는 부분이 ToC 컴포넌트에 색상으로 표시되어야 한다.
ToC컴포넌트에서 클릭 시, 해당 컨텐츠로 이동해야 한다.

구현 로직

제가 생각했던 기본 로직은 아래와 같습니다.

post 본문을 감싸는 태그에 유니크한 아이디를 부여한다.(e.g. #content__entry__point)
(물론, 본문을 string으로 넘겨 처리하는 방법도 존재하지만, tistory와 같은 곳에서도 사용할 수 있도록 이러한 방법을 선택했습니다.)
본문에 있는 h1~h3 태그들을 모두 찾는다.
찾은 hTag들을 기반으로 목차에 넣을 li 요소를 만들어준다.
(이때 만들면서 클릭하면, 해당요소의 위치로 이동하는 eventListner도 같이 설정 해 줍니다.)
현재 focused Element를 찾아 표시한다.
스크롤 이벤트가 일어날 때 마다 focused Element를 찾아 표시해준다.

가장 하단에 전체 구현코드를 첨부하도록 하고, 바로 TroubleShooting으로 넘어가도록 하겠습니다.

TroubleShootings

[메인 컨텐츠 위치 찾기 - Problem] 잘못된 방법(IntersectionObserver)

사실 로직을 구현하는 부분 자체는 크게 어렵지 않았습니다. 다만, 현재 읽고 있는 부분을 어떻게 정의하고 이를 찾는 방법을 구현하는 것에 가장 많은 시간이 소모되었습니다.

가장 처음 생각 했던 방법은 IntersectionObeserver 였습니다.

현재 화면에 보이고 있는 hTag를 찾고, 상단 20%정도안에 위치한 hTag중 가장 처음에 있는 태그를 메인 컨텐츠로 설정하면 어떨까 했습니다. 하지만, 이 방법은 아래 사진에서 볼 수 있듯이 컨텐츠양이 커질 경우 문제가 있었습니다.

ToC가 메인컨텐츠를 보여주지 못하고 있는 예시

위 사진을 보면 현재 메인 컨텐츠는 올드타운하우스 부분이지만, ToC에서는 그 하단에 있는 도르트문트 U-타워를 보여주고 있습니다.

이 문제는 메인 컨텐츠가 길어져서 해당 제목(HTag)이 화면에 더 이상 보이지 않는 경우 발생합니다.

[메인 컨텐츠 위치 찾기 - Solve] 직접 메인 컨텐츠 판단하는 함수 개발

제가 원하는 방식으로 메인컨텐츠를 찾아내기 위해 아래처럼 직접 함수를 만들기로 했습니다.
최대한 자세히 주석을 달도록 하였지만, 궁금하시거나 잘못된 부분이 있다면 댓글로 알려주세요.

/**
 * 진짜 내가 보고 있는 컨텐츠의 헤드를 찾아주는 함수
 * 단순히 ObserverIntersection을 이용하면, 컨텐츠가 길어지는 경우, HTag가 보이지 않으면
 * 내가 보고 있는 컨텐츠가 아니라, 하단에 아직 읽지 않고 있는 hTag에 포커스가 가는 것을 방지하기 위함
 * @param mainContentHeight
 * @returns
 */
function getMainElementAtMainContentHeight(mainContentHeight: number) {
    // 메인 컨텐츠의 높이(mainContentHeight)
    // 이전 태그의 TOP값(PT)
    // 이후 태그의 TOP값(NT)
    // MainTag(MT)
    // 조건: 항상 PT < NT
    // 경우의 수
    // 1. PT <= mainContentHeight < NT ==> MT = PT
    // 2. mainContentHeight < PT ==> MT = PT
    // 3. PT < mainContentHeight && NT <= mainContentHeight ==>  MT = NT
    let MT = hTags[0];
    for (let i = 1; i < hTags.length; i++) {
        const PT = hTags[i];
        if (
            mainContentHeight < MT.offsetTop &&
            mainContentHeight < PT.offsetTop
        ) {
            return MT;
        } else if (
            MT.offsetTop < mainContentHeight &&
            mainContentHeight <= PT.offsetTop
        ) {
            return MT;
        } else {
            MT = PT;
        }
    }
    return MT;
}

이 함수를 이용하여 아래처럼 컨텐츠가 길어져서 현재 보이는 HTag는 This is the Second H1 Tag 밖에 없더라도
메인 컨텐츠는 상단의 andSomeLongPart 태그라고 판단 할 수 있었습니다.

ToC 메인 컨텐츠 판단 함수 활용 예시

[현재 보고 있는 위치 찾기 - Problem] 잘못된 방법: window.innerHeight

사실 위에서 설명한 함수를 통해 메인 컨텐츠를 찾을 수는 있지만, 메인 컨텐츠의 높이를 구하는 것 자체에서 막혔습니다.

window.innerHeight로 판단하면 될 것 같았는데, 이 방식으로는 스크롤에 따라 변하는 내가 현재 보고 있는 위치를 알 수 없었습니다.

[현재 보고 있는 위치 찾기 - Solve] innerHeight + scrollY + Offset

사실 실시간으로 내가 보고 있는 위치를 찾는 방법은 어렵지 않았습니다. innerHeight와 scrollY를 통해 현재 위치를 찾을 수 있었고, 따로 offset을 추가 하면서 정확히 화면상단 n%의 높이를 찾을 수 있었습니다.

하단 코드에서 각각의 변수들이 의미하는 바는 아래와 같습니다.

window.innerHeight / 2 : 화면의 전체 뷰포트 높이를 픽셀로 나타낸 수의 절반
window.scrollY : 원점으로부터 문서를 수직방향으로 스크롤한 픽셀 수
mainContentOffset : 기준점을 화면 상단으로부터 30%인 지점으로 잡기 위한 offset
(e.g. 화면 상단으로부터 20%를 기준점으로 잡으려면 mainContentOffset을 0.3으로 조정)

function setFocusedElement() {
    const mainContentOffset = 0.2;
    const mainContentHeight =
        window.innerHeight * (0.5 - mainContentOffset) + window.scrollY;

    const mainTag =
        getMainElementAtMainContentHeight(mainContentHeight);
    const focusedTocTag = hTagToTocElMapper.get(mainTag?.innerHTML);

    focusedTag.current?.classList.remove(classes.focused);
    focusedTocTag?.classList.add(classes.focused);
    focusedTag.current = focusedTocTag ?? null;
}

[ToC요소 클래스명 부여 - Problem] 잘못된 방법: focuse변할 때마다 리렌더링(feat. useState)

위에서 개발한 함수를 통해 메인 컨텐츠를 찾는 부분은 해결했지만, 여기에서 찾은 HTag는 본문의 태그이기에 ToC컴포넌트의 Element에 제가 원하는 클래스(".focused")를 부여해주는 작업이 필요했습니다. 처음에는 그냥 ToC순회 하면서 li Element안의 innerHTML이 내가 찾은 HTag의 innerHTML과 같은 경우에 ".focused"클래스를 부여해주려고 하였습니다.

하지만, 이 경우에 focused가 바뀌었을 때, 제거 하는 작업을 하기위해 또 순회해야 하는 문제가 생겼습니다.

그래서 focusedTag를 state로 관리를 하려고 하였지만, 이렇게 되면 focusedTag가 변할 때 마다 ToC컴포넌트가 리렌더링되는 문제가 발생하였습니다.

[ToC요소 클래스명 부여 - Solve] Map으로 관리(feat. useRef)

이러한 해결하기 위해 ToC의 li Element를 Map으로 관리하고, focused Element는 useRef로 관리하기로 했습니다.

hTag를 순회하며 ToC의 li Element를 생성해주는 과정에서 실제 컨텐츠의 hTag의 innerHTML을 key로, TocElement를 value로 가지는 Map을 생성해주었습니다.

//...
const hTagToTocElMapper = new Map<String, HTMLElement>();
//...
//HTag를 돌면서, Toc에 넣을 Element를 생성해서 넣어준다.
hTags?.forEach((hTag) => {
    const liEl = document.createElement('li');
    const linkEl = document.createElement('a');

    //...
    //liElement를 생성하면서 바로 Map에 넣어준다. 
    //실제 컨텐츠의 hTag의 innerHTML을 key로, TocElement를 value로 가진다.
    hTagToTocElMapper.set(hTag.innerHTML, liEl);
    listContainer?.appendChild(liEl);
});

그리고 하단처럼 focusedElement를 세팅해주는 함수에서 아래처럼 기존에 있는 focusedTag의 클래스를 삭제하고, 현재 focusedTag에 클래스를 부여하고 useRef에 세팅해주는 방식으로 해결하였습니다. 이를 통해 리렌더 되지 않고도 focusedTag를 적절히 관리 할 수 있었습니다.

//...
const focusedTag = useRef<HTMLElement | null>(null);
//...
function setFocusedElement() {
	//...
    const focusedTocTag = hTagToTocElMapper.get(mainTag?.innerHTML);

    focusedTag.current?.classList.remove(classes.focused);
    focusedTocTag?.classList.add(classes.focused);
    focusedTag.current = focusedTocTag ?? null;
}

이를 통해 앞서 보여드린 결과물 처럼 메인 컨텐츠에 따라 focused 된 부분을 표현 할 수 있었습니다.

사용방법

사용방법은 아래와 같습니다.
여기에서 주의할 점은 본문이 있는 CustomMarkdown 태그를 content__entry__point id를 가진 div로 감싸줬다는 점입니다.
그리고, 하단에 ToC컴포넌트를 호출해주면 됩니다.

<div className={classes.content__wrapper}>
    <FadeIn from="left">
            <div id="content__entry__point">
                <CustomMarkdown components={post} />
            </div>
        </article>
    </FadeIn>
    <Toc title={post.title}></Toc>
</div>

구현코드

전체 구현코드는 아래와 같습니다. (Next.js를 사용하고 있기에 use clinet로 client 컴포넌트임을 명시했습니다.)
내부 구현 로직에 대해서는 최대한 자세히 주석을 달았습니다.
잘못된 점이 있거나 궁금한 점이 있다면 댓글로 남겨주시면 감사하겠습니다!

'use client';

import classes from './toc.module.scss';
import ListIcon from './icons/list-icon';
import CloseIcon from './icons/close-icon';
import { useEffect, useRef, useState } from 'react';

type TocProps = {
	title?: string;
};
const levelMap: { [key: string]: string } = {
	H1: 'lv1',
	H2: 'lv2',
	H3: 'lv3',
};

export default function Toc({ title }: TocProps) {
	const [tocOpened, setTocOpened] = useState(false);
	const [hTags, setHTags] = useState<[] | NodeListOf<HTMLElement>>([]);
	const focusedTag = useRef<HTMLElement | null>(null);

	console.log('hmm');
	//처음 렌더 후, hTag 모두 찾기.
	useEffect(() => {
		const entryPoint = document.querySelector('#content__entry__point');
		const hTagEls = entryPoint?.querySelectorAll(
			'h1, h2, h3'
		) as NodeListOf<HTMLElement>;
		setHTags(hTagEls);

		//현재 창 넓이가 1350 이하면 ToC와 메인 컴포넌트가 겹친다.
		//그 이상이라면, ToC를 처음에 열어준다.
		const width = window.innerWidth;
		if (width >= 1350) {
			setTocOpened(true);
		}
	}, []);

	//hTag를 다 찾으면, 아래 로직 실행
	useEffect(() => {
		//실제 HTag에 해당하는 TocElement를 맵핑해주는 Map
		//실제 컨텐츠의 hTag의 innerHTML을 key로, TocElement를 value로 가진다.
		const hTagToTocElMapper = new Map<String, HTMLElement>();
		const listContainer = document?.querySelector('#toc__list');

		//HTag를 돌면서, Toc에 넣을 Element를 생성해서 넣어준다.
		hTags?.forEach((hTag) => {
			const liEl = document.createElement('li');
			const linkEl = document.createElement('a');

			linkEl.innerHTML = hTag.innerHTML;
			//linkEl를 클릭하면, 해당 Tag를 가진 곳으로 스크롤 해 준다.
			linkEl.addEventListener('click', () => {
				window.scrollTo({
					top: hTag.offsetTop - 20,
					behavior: 'smooth',
				});
			});
			liEl.appendChild(linkEl);
			const levelClass = levelMap[hTag.tagName];
			liEl.classList.add(classes[levelClass]);

			hTagToTocElMapper.set(hTag.innerHTML, liEl);

			listContainer?.appendChild(liEl);
		});

		//현재 focused Element를 찾아 세팅해준다.
		setFocusedElement();

		//scroll Event가 발생할 때마다 focused Element를 찾아 세팅해준다.
		const findCurTagEvent = (window.onscroll = () => setFocusedElement());

		function setFocusedElement() {
			// window.innerHeight / 2 : 화면의 전체 뷰포트 높이를 픽셀로 나타낸 수의 절반
			// window.scrollY : 원점으로부터 문서를 수직방향으로 스크롤한 픽셀 수
			// mainContentOffset : 기준점을 화면 상단으로부터 30%인 지점으로 잡기 위한 offset
			// e.g. 화면 상단으로부터 20%를 기준점으로 잡으려면 mainContentOffset을 0.3으로 조정
			const mainContentOffset = 0.2;
			const mainContentHeight =
				window.innerHeight * (0.5 - mainContentOffset) + window.scrollY;

			const mainTag =
				getMainElementAtMainContentHeight(mainContentHeight);
			const focusedTocTag = hTagToTocElMapper.get(mainTag?.innerHTML);

			focusedTag.current?.classList.remove(classes.focused);
			focusedTocTag?.classList.add(classes.focused);
			focusedTag.current = focusedTocTag ?? null;
		}

		/**
		 * 진짜 내가 보고 있는 컨텐츠의 헤드를 찾아주는 함수
		 * 단순히 ObserverIntersection을 이용하면, 컨텐츠가 길어지는 경우, HTag가 보이지 않으면
		 * 내가 보고 있는 컨텐츠가 아니라, 하단에 아직 읽지 않고 있는 hTag에 포커스가 가는 것을 방지하기 위함
		 * @param mainContentHeight
		 * @returns
		 */
		function getMainElementAtMainContentHeight(mainContentHeight: number) {
			// 메인 컨텐츠의 높이(mainContentHeight)
			// 이전 태그의 TOP값(PT)
			// 이후 태그의 TOP값(NT)
			// MainTag(MT)
			// 조건: 항상 PT < NT
			// 경우의 수
			// 1. PT <= mainContentHeight < NT ==> MT = PT
			// 2. mainContentHeight < PT ==> MT = PT
			// 3. PT < mainContentHeight && NT <= mainContentHeight ==>  MT = NT
			let MT = hTags[0];
			for (let i = 1; i < hTags.length; i++) {
				const PT = hTags[i];
				if (
					mainContentHeight < MT.offsetTop &&
					mainContentHeight < PT.offsetTop
				) {
					return MT;
				} else if (
					MT.offsetTop < mainContentHeight &&
					mainContentHeight <= PT.offsetTop
				) {
					return MT;
				} else {
					MT = PT;
				}
			}
			return MT;
		}

		//걸어줬던 스크롤 이벤트를 clean-up 해준다.
		return findCurTagEvent;
	}, [hTags]);

	return (
		<>
			<div
				className={`${classes.icon} ${tocOpened && classes.opened}`}
				onClick={() => setTocOpened((prev) => !prev)}
			>
				<ListIcon size="25px" />
			</div>
			{hTags.length > 0 && (
				<div
					className={`${classes.toc} ${tocOpened && classes.opened}`}
				>
					<nav>
						<header className={`${classes.title}`}>
							<div
								className={classes.close__icon}
								onClick={() => setTocOpened(false)}
							>
								<CloseIcon size="12.5px" />
							</div>
							<p>{title ? title : 'Table Of Contents'}</p>
						</header>
						<div className={`${classes.toc__body}`}>
							<ul
								className={classes.toc__list}
								id="toc__list"
							></ul>
						</div>
					</nav>
				</div>
			)}
		</>
	);
}

Content-Type vs Accept vs responseType(feat. XHR, ajax)

moyanglee — Tue, 9 Jan 2024 10:00:15 +0900

HTTP 통신에서 사용하는 headers 중 Content-Type과 Accept, 그리고 XHR 프로퍼티중 하나인 responseType에 대해 비교하고 정리해보고자 합니다.

Content-Type

Content-Type은 Client가 서버로 보내는 HTTP요청의 Message Body가 가지고 있는 리소스 타입에 대해 알려주는 역할을 합니다. 예를 들어, 아래처럼 간단한 HTTP POST요청을 한다고 하였을 때, body에 들어가 있는 타입을 알려주는 역할을 한다는 것입니다. 여기에서는 json 형식이니, "application/json"을 넣어 주었습니다.

fetch('some/url', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({ key: 'value' })
})

만약, formData를 보낸다고 한다면 "Content-Type": "multipart/form-data" 처럼 지정할 수 있을 것입니다.

만약에 POST요청을 "Content-Type"을 설정하지 않고 보낸다면, default는 "application/x-www-form-urlencoded

"이게 되고,
FormData를 보내는 경우에는 "multipart/form-data"가 default로 설정되게 됩니다.

Accept

클라이언트 자신이 원하는 미디어 타입 및 우선순위를 알려주기 위해 사용됩니다.

즉, 서버한테 나한테 이런 종류의 데이터를 응답으로 보내줘 라고 알려주는 역할이라고 생각하면 이해하기 쉽습니다.

responseType

responseType은 서버의 응답 데이터를 XHR Object가 어떤 포맷으로 Parse할 지 결정하는 속성입니다. 서버가 보내는 응답 데이터의 타입에 대해 정의한다는 점은 Accept와 같지만, 사용되는 level에서 차이가 있습니다.

앞서 설명 한 것처럼, Accept header는 Client가 서버에 요청할 때 자신이 받고 싶은 데이터의 타입을 설정하는 부분입니다. 이 header를 확인한 서버는 Accept에 맞도록 응답을 보내려고 할 것입니다.

반면 XHR 객체의 responseType은 서버가 이미 보낸 응답을 브라우저가 js를 이용해서 어떤 포맷으로 parse할 지 결정할 때 사용되는 속성입니다.

responseType에 사용될 수 있는 속성은 아래와 같습니다.(참고링크)

"": default 값으로 "text"와 똑같이 처리 됩니다.
"arraybuffer"
"blob"
"docuemnt"
"json"
"text"

파일 다운로드시 헤더 example

그럼 마지막으로 예시를 통해 정리해보도록 하겠습니다.

클라이언트가 파일 다운로드를 하기 위해 POST요청으로 body에 fileId를 실어 보내고, 서버는 클라이언트에게 byte[]로 응답을 해준다고 가정해봅시다. 이때, 파일다운로드 요청을 보낼 때 어떻게 보내면 좋을까요?

fetch('some/url', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/octet-stream',
    },
    responseType: 'blob' //혹은 'arraybuffer'도 좋습니다.
    body: JSON.stringify({ fId: 'someId' })
})

Content-Type: 'application/json' - POST요청의 body에 심은 fileId가 json형식이라는 뜻
Accept: 'application/octet-stream' - 파일 데이터를 바이너리데이터 형식으로 받고 싶다 라는 뜻
responseType: 'blob' - 응답 데이터를 브라우저에서 blob 포맷으로 파싱하겠다는 뜻

혹시나 잘못된 점이 있거나 질문이 있다면, 댓글로 알려주시기 바랍니다. 감사합니다.

[React] Custom useForm 직접 만들기 (feat. zod)

moyanglee — Mon, 8 Jan 2024 11:00:23 +0900

최근에 Next.js를 이용해서 내 블로그를 직접 만들고 있습니다. 작업하는 와중에 form 유효성 검사를 좀 간단히 할 수 있는 hook을 만들고 싶어져 zod를 활용하여 한번 만들어 보게 되었습니다. useForm이라는 라이브러리가 있는 것도 알고 있지만, 간단한 것은 직접 만드는게 좋아 직접 만들어 보게 되었고, 공유하고자 글을 정리해봅니다. 어떻게 구현했는지는 코드를 보면 알 수 있으니, 구현하면서 겪었던 문제점과 해당 문제점을 어떻게 해결했는지 위주로 정리했습니다.

useForm

Features

우선, 완성된 form은 아래처럼 작동 하게 될 것입니다.

useForm 작동 영상

useForm이라는 커스텀 훅에서 제가 원하는 기능은 아래와 같습니다.

각 input을 유효성 체크하는 함수와 에러 메시지를 z.object(using zod)를 이용해 인자로 전달 할 수 있다.
submit 버튼을 클릭하기 전에는 유효성 검사를 진행하지 않는다.
submit 버튼을 클릭하면 유효성 검사를 진행하고, 실패한 인풋들은 빨간색 테두리를 부여한다.
submit 버튼 클릭 이후에는 input에 입력할 때마다, 유효성 체크를 진행한다.
유효성 검사 실패 시, z.object에 설정한 에러 메시지가 아래에 표시된다.
모든 인풋이 유효성 검사에 통과 했는지 여부를 알 수 있는 상태 값을 리턴 받는다.
form태그의 onSubmit에 전달된 함수의 로직은 유효성검사가 끝난 이후에 실행된다.

사용 방법

useForm hook은 아래처럼 사용 할 수 있다.

form 태그 안에 label과 input을 생성하고, label의 htmlFor과 input의 name과 id를 같은 값으로 입력해준다.
form태그에 ref를 걸어준다.
각 인풋들을 유효성 체크로직을 zod의 z.object를 활용하여 입력해준다.(이때, 에러 메시지는 { message } 형태로 넣어준다.)
useForm의 인자로, formRef와 z.object(schema)를 넣어 준다.
useForm은 form 전체가 유효성 검사에 통과했는지 여부를 리턴한다.
useForm의 리턴값으로, submitHandler에서 이후 로직을 진행할지 여부를 결정한다.

//JS
const schema = z.object({
    email: z.string().email({ message: 'email 형식에 맞지 않습니다.' }),
    name: z.string().min(1, { message: '필수 입력 값 입니다.' }),
});
const formRef = useRef<HTMLFormElement>(null);
const formValid = useFrom(formRef, schema);

function submitHandler(e: FormEvent) {
    e.preventDefault();

    if (!formValid) return;
    console.log('submitted!', formValid);
}

//JSX
<form
    onSubmit={submitHandler}
    ref={formRef}
    noValidate
>
    <div className={classes.control}>
        <label htmlFor="email" className="required">
            Your Email
        </label>
        <input
            type="email"
            id="email"
            name="email"
            autoComplete="off"
            required
        />
    </div>
    <div className={classes.control}>
        <label htmlFor="name" className="required">
            Your Name
        </label>
        <input
            type="text"
            id="name"
            name="name"
            autoComplete="off"
        />
    </div>
    <div className={classes.actions}>
	    <button type="submit">Send Message</button>
    </div>
</form>

이렇게 해주면, 위 영상에서처럼 작동하게 됩니다.

구현 코드

전체 구현 코드는 아래와 같습니다.

import { z } from 'zod';
import { RefObject, useEffect, useState } from 'react';

export default function useFrom(
	formRef: RefObject<HTMLFormElement | null>,
	schema: z.ZodObject<any>
) {
	const ERROR_MSG_ID_PREFIX = 'error__msg__';
	const [formStatus, setFormStatus] = useState<{ [key: string]: boolean }>(
		{}
	);
	const [isFirst, setIsFirst] = useState(true);
	const [formValid, setFormValid] = useState(false);
	const [formData, setFormData] = useState<{ [key: string]: any }>({});

	useEffect(() => {
		const formElement = formRef.current;
		let removeSubmitEventListener: null | Function = null;

		function checkFormValidHandler() {
			const values = Object.values(formStatus);
			return (
				values.length > 0 &&
				Object.values(formStatus).every((valid) => valid === true)
			);
		}

		function addSubmitEventListenerHandler(formElement: HTMLFormElement) {
			// submit 버튼 클릭 할 때, 실행 되는 함수.
			function handleSubmit(event: SubmitEvent) {
				const target = event.target as HTMLFormElement;
				if (target) {
					setIsFirst(false);
					if (isFirst) {
						addValidateELHandler(target, schema);
					}

					if (checkFormValidHandler()) {
						setFormValid(true);
					} else {
						setFormValid(false);
					}
				}
			}

			formElement.addEventListener('submit', handleSubmit);

			return () => {
				formElement.removeEventListener('submit', handleSubmit);
			};
		}

		function addValidateELHandler(
			formElement: HTMLFormElement,
			schema: z.ZodObject<any>
		) {
			const inputs = formElement.querySelectorAll('input');
			const textareas = formElement.querySelectorAll('textarea');

			for (const input of inputs) {
				//처음 submit 버튼 클릭했을 때, validate.
				validateInputHandler(input, schema);
				setEventHandler(input, schema);
			}

			for (const textarea of textareas) {
				validateInputHandler(textarea, schema);
				//이후 input 이벤트 마다 validate 하도록 eventListenr 추가.
				setEventHandler(textarea, schema);
			}
		}

		function setEventHandler(
			inputEl: HTMLInputElement | HTMLTextAreaElement,
			schema: z.ZodObject<any>
		) {
			//validate eventHandler
			inputEl.addEventListener('input', () =>
				validateAndSetFormDataHandler(inputEl, schema)
			);
		}

		function validateAndSetFormDataHandler(
			input: HTMLInputElement | HTMLTextAreaElement,
			schema: z.ZodObject<any>
		) {
			setFormDataHandler(input);
			validateInputHandler(input, schema);
		}

		function setFormDataHandler(
			input: HTMLInputElement | HTMLTextAreaElement
		) {
			const targetId = input.id;
			setFormData((prev) => {
				return {
					...prev,
					[targetId]: input.value,
				};
			});
		}

		function validateInputHandler(
			input: HTMLInputElement | HTMLTextAreaElement,
			schema: z.ZodObject<any>
		) {
			const targetId = input.id;

			const response = schema
				.pick({ [targetId]: true })
				.safeParse({ [targetId]: input.value });

			if (!response.success) {
				setFormStatus((prev) => {
					return {
						...prev,
						[targetId]: false,
					};
				});
				const { errors } = response.error;
				input.classList.add('invalid');
				addErrorMsgElement(input, targetId, errors);
			} else {
				setFormStatus((prev) => {
					return {
						...prev,
						[targetId]: true,
					};
				});
				input.classList.remove('invalid');
				input.parentElement
					?.querySelector(`#${ERROR_MSG_ID_PREFIX}${targetId}`)
					?.remove();
			}
		}

		if (formElement) {
			removeSubmitEventListener =
				addSubmitEventListenerHandler(formElement);
			//required 별표 표시는 label에 global css를 적용
			//제출 버튼을 눌렀을 때 부터 input 요소들에게 맞는 validation 해야 한다.
		}

		return () => {
			if (removeSubmitEventListener) {
				removeSubmitEventListener();
			}
		};
	}, [formRef, schema, isFirst, formStatus]);

	function addErrorMsgElement(
		inputEl: HTMLInputElement | HTMLTextAreaElement,
		targetId: String,
		errors: z.ZodIssue[]
	) {
		const errorMsgEl = inputEl.parentElement?.querySelector(
			`#${ERROR_MSG_ID_PREFIX}${targetId}`
		);

		if (errorMsgEl) {
			errorMsgEl.innerHTML = errors[0].message;
		} else {
			const errorMsg = document.createElement('span');
			errorMsg.id = `${ERROR_MSG_ID_PREFIX}${targetId}`;
			errorMsg.className = 'error__msg';
			errorMsg.innerHTML = errors[0].message;
			inputEl.parentElement?.insertAdjacentElement('beforeend', errorMsg);
		}
	}

	return { valid: formValid, formData: formData };
}

아, 참고로 아래처럼 global css를 적용해줘야 위 영상처럼 작동 할 수 있습니다.

input:focus {
    outline: none;
}

label.required {
    &::after {
        content: ' *';
        color: rgb(249, 77, 77);
        font-size: 1rem;
    }
}

.invalid {
    border: 1px solid red !important;
}
.error__msg {
    color: red;
    font-size: 1rem;
}

주의점

사실, 위 코드를 보시면 아시겠지만, 일반적인 input과 textarea들에 대해서만 validation 체크가 진행되고, 나머지 케이스에는 작동하지 않습니다. 이 부분은 추후 개발할 예정입니다.

TroubleShootings

1. useRef 값 customHook에 넘기기(feat. lifecycle, useEffect)

useForm에 인자로 formElement(formRef.current)를 넘겨줬는데, 처음에 null로 나왔습니다.
이때 제일 처음 든 생각은 아래처럼 useEffect의 dependency에 formElement를 등록해주면 되겠네? 였습니다.

export default function useForm(formElement: HTMLFormElement | null, schema: z.ZodObject<any>){
//...
    useEffect(() => {
    if(!formElement) return;
    //formElement가 정상적으로 등록 된 경우 아래 로직 진행

    }, [formElement])
}

function TestComponent(){
	//...
	const formRef = useRef(null);
	useForm(formRef.current, shema);
    
    return(
    	<form ref={formRef}>
        //...
    )
}

하지만, 리액트 공식문서에도 나와 있다싶이, 리액트는 useRef.current의 변경은 알지 못합니다.
애초에 값의 변화가 있을 때, 리렌더가 일어나지 않기위해 만든 hook이니까요. 대신, 그 값의 변화는 useRef.current에 저장되어 있으니, 변화된 값을 언제든지 사용할 수 있습니다!

따라서 우리는 formRef.current 처럼 값 자체가 아닌, formRef 객체 자체를 넘겨줘야 나중에 변화된 값을 사용할 수 있습니다.

그럼 실행 시점이 중요 해 보입니다. 사실 useForm을 호출하는 시점 자체는 TestComponent가 mount하기 이전 시점이니까요.
공식문서에 따르면, useEffect 훅은 ComponentDidMount()가 일어난 이후에 실행되게 됩니다.
(물론, dependency를 빈 배열로 줬을때 입니다!, 위 코드처럼 인자를 넘긴다면, ComponentDidUpdate()이후에도 실행되게 됩니다.)

그럼 이제 모든 문제는 해결됐습니다! 컴포넌트가 어떻게 실행될지 아래를 참고해봅시다.

formRef를 useRef를 이용해 생성한다.(formRef.current는 여전히 null인 상태)
useForm을 호출한다.
이때, useForm(formRef, shema)처럼 객체를 통으로 넘겨줘야 합니다. 이 시점에도 여전히 formRef.current는 null 입니다.
return 문을 통해 해당 컴포넌트가 렌더된다.(ComponentDidMount() → formRef.current에 DOM요소가 들어가게 됩니다.)
useForm안에 등록되어 있던 useEffect가 호출된다. (formRef.current를 통해 DOM 요소에 접근 가능하다.)

그래서 최종적으로 코드는 아래처럼 구현하였습니다.

export default function useForm(formRef: RefObject<HTMLFormElement | null>, schema: z.ZodObject<any>){
//...
    useEffect(() => {
    const formElement = formRef.current
    if(!formElement) return;
    //formElement가 정상적으로 등록 된 경우 아래 로직 진행

    }, [formRef])
}

function TestComponent(){
	//...
	const formRef = useRef(null);
	useForm(formRef, shema);
    
    return(
    	<form ref={formRef}>
        //...
    )
}

근데, 이 로직대로라면, useEffect안에 formRef 의존성을 추가 안해줘도 되는 거 아닌가? 라는 생각이 드실 수 있습니다.
하지만, 그렇게 하면, lint에서 경고를 주기 때문에, 일단 추가를 해주었습니다. 이렇게 해도 사실상 formRef가 변경되는 일은 없기 때문에, 사이드이펙트는 없다고 판단하였습니다.

2. submit시점 처리 (다수의 이벤트 핸들러 순서 처리)

저는 처음 생각했을 때, 아래처럼 form태그의 onSubmit 을 통해서 사이드이펙트를 처리하고자 했습니다.

그리고, 처음부터 validation을 체크하는 것이 아니라 버튼이 클릭된 이후부터 유효성검사를 실시하고자 했죠.

const formValid = useFrom(formRef, schema);

<form
    className={classes.form}
    onSubmit={submitHandler}
    ref={formRef}
    noValidate
>

이때의 문제점은, validation과 submitHandler 둘 다 submit이벤트를 통해 실행되지만,
submitHandler가 validation이 모두 마친 뒤에 실행되어야 한다는 점이었습니다. 그래야, validation의 결과인 formValid를 통해서 form을 제출할 지 여부를 결정할 수 있으니까요.

우선, 제가 알고있기로 eventListner는 등록된 순서대(FIFO)로 호출되고 있었습니다. 하지만 React는 브라우저 기본 이벤트가 아닌, ReactEventObject(synthetic event)를 사용하기에 조금 찾아봐야 했습니다.

아래는 브라우저에서 이벤트 리스너를 확인해본 모습입니다. (dev모드라, 2번씩 등록되어 있습니다.)
button에 등록된 2개의 이벤트(33, 36 line)는 제가 addEventListner로 등록한 이벤트핸들러이고, document에 등록된 이벤트는 onClick으로 React 이벤트를 등록한 이벤트 핸들러입니다.

이처럼 React는 브라우저 기본 이벤트처럼 각 Dom요소에 이벤트리스너를 추가하는 것이 아니라, root(docuemnt)요소에 모두 등록을 합니다. 이렇게 되면 간단해 졌습니다. 먼저 자기에게 걸린 이벤트 핸들러를 먼저 실행시키고, 부모에 걸려있는 이벤트핸들러를 실행시키기 때문입니다.

그럼 아래처럼 이벤트를 등록했을 때, 이벤트 동작순서는 어떻게 될까요?

function clickHandler() {
    console.log('react Event handler!');
}

useEffect(() => {
    console.log('useEffect');
    const testbtn = document.querySelector('#test');
    console.log('testbtn is', testbtn);
    testbtn?.addEventListener('click', () => {
        console.log('native first function');
    });
    testbtn?.addEventListener('click', () => {
        console.log('native last function');
    });
}, []);
    
//jsx
<button id="test" onClick={clickHandler}>
    click
</button>

결과는 아래와 같습니다.(역시나 dev모드라 두번씩 실행되었습니다.)

버튼이 클릭되게 되면, 자신에게 가장 먼저 걸려있는 이벤트 리스너부터 실행 시키고, 그 다음에 자신에게 add된 이벤트 리스너, 그 다음에 리액트 이벤트핸들러로 등록된 이벤트가 실행되게 됩니다.

결국 저는 아래처럼 코드를 구현하였습니다.

form에 onSubmit 이벤트 등록(validation이 모두 끝난 이후에 실행된다.)
useForm 내부에서 form요소를 찾아 addEventListener("submit", validateForm) 해준다.(1번보다 먼저 실행)

Next.js를 시작한지 지금 몇 일 되지 않아, 부족하거나 잘못된 점이 있을 수 있습니다.
잘못된 점이나 궁금한점에 대해서 댓글로 알려주신다면 감사합니다!