[React] 파편화된 Form 유효성 검사 로직, Zod로 우아하게 격리하기

1. 들어가며: 거대해진 Form의 습격

프런트엔드 개발을 하다 보면 수십 개의 입력 필드를 가진 거대한 설정 Form을 다뤄야 할 때가 있습니다.초기에는 단순했던 유효성 검사 로직도 서비스가 성장하면서 점점 복잡해집니다.

• 정규식 기반 포맷 검증
• 파일 크기 및 확장자 체크
• 특정 조건이 만족될 때만 이어지는 순차 검증

이런 로직들이 하나둘 추가되다 보면, 어느 순간 UI 컴포넌트 안에 수백 줄의 검증 코드가 뒤엉켜 있는 상태를 마주하게 됩니다.

해당 프로젝트는 초기에 약 3주만에 클라우드 서비스를 올려야 했으며, MVP가 기존의 온프레미스의 기본 기능을 모두 혼자 구현해야 한다는 핑계로 UI로직과 비지니스 로직이 뒤섞인 상태였습니다. 최근에 해당 프로젝트의 유효성 검증 로직이 추가 요구사항으로 들어오게 되어 덮어두었던 인라인으로 작성된 유효성 검사 로직을 Zod 스키마 기반으로 리팩토링하게 되었습니다. 이 경험으로 UI와 비즈니스 로직을 분리하는 것이 얼마나 중요한지 다시 한번 체감했습니다. 이 글에서는 그 과정에서의 고민과, 현실적인 제약 속에서 내린 엔지니어링 선택을 공유하고자 합니다.

 

2. 문제 인식: UI 속에 숨어버린 비즈니스 로직

기존 구현에서는 각 입력 컴포넌트의 rules 프로퍼티 안에 모든 검증 로직이 들어 있었습니다.

아래 코드는 기존 코드와 유사한 예제입니다.

// AS-IS: UI와 로직이 뒤섞인 모습
<TextField
  rules={[
    (value) => {
      if (!/https?:\/\/.+/.test(value)) {
        return Promise.reject("URL 형식이 틀립니다.");
      }
      return Promise.resolve();
    },
  ]}
/>

처음에는 간단해 보이지만, 이 방식에는 명확한 한계가 있었습니다.

문제점

• 가독성 저하
  JSX 구조와 검증 로직이 뒤섞이면서 UI의 의도가 한눈에 들어오지 않습니다.
• 로직 재사용 불가
  동일한 URL 검증이 필요한 곳마다 정규식을 복사해 사용해야 했습니다.
• 복잡한 검증의 확장성 부족
  “파일이 존재할 때만 크기를 체크하고, 통과하면 확장자를 검사한다” 같은
  순차적 조건이 들어가는 순간 코드가 급격히 지저분해집니다.

결국 유효성 검사가 UI의 책임처럼 보이지만, 실제로는 명백한 비즈니스 로직이라는 점이 가장 큰 문제였습니다.

 

 

3. 현실적인 제약: “왜 React-Hook-Form을 쓰지 않았나?”

유효성 검사 리팩토링을 고민하면 가장 먼저 떠오르는 선택지는 React-Hook-Form + Zod 조합일 것입니다. 하지만 실무에서는 항상 이상적인 선택만 할 수는 없습니다.

프로젝트의 제약 사항

• 전사 공통 UI 라이브러리를 깊게 사용 중
• 해당 라이브러리는 ref 기반의 명령형 검증과 자체 rules 시스템에 의존
• RHF로 전환하려면 기존 입력 컴포넌트를 전면 재작성해야 하는 상황

이는 단순한 리팩토링이 아니라 대규모 구조 변경에 해당했고, 리스크와 비용 대비 현실적인 선택은 아니었습니다.

그래서 내린 결론은 하나였습니다.

“프레임워크를 바꿀 수 없다면, 검증 엔진만이라도 분리하자.”

UI 시스템은 유지하되, 그 안에 숨겨진 판단 로직을 독립적인 검증 레이어로 격리하는 전략을 선택했습니다.

 

 

 

4. 왜 Zod였는가? (Yup / Joi와 비교)

검증 라이브러리를 도입하기 전, 다음 후보들을 검토했습니다.

• Yup
• Joi
• Zod

그리고 최종적으로 구조적으로 가장 잘 맞는 Zod를 선택했습니다.

항목	Zod	Yup	Joi
TypeScript 친화성	매우 우수 (z.infer로 타입 자동 추론)	제한적 (타입 보조 필요)	불편함 (타입 정의가 번거로움)
스키마 가독성	선언적이고 직관적	비교적 명확	문법이 다소 무거움
런타임 검증	safeParse 기반, 예외 없이 안전	가능	가능
복합 검증	superRefine으로 유연하게 표현 가능	가능하지만 가독성 떨어짐	가능하지만 코드 복잡
프레임워크 종속성	없음 (독립 사용 가능)	없음	없음
RHF 외 단독 사용	매우 적합	가능하나 불편	가능하나 과함
러닝 커브	낮음	낮음	상대적으로 높음
실무 체감	타입 + 검증을 하나로 관리 가능	타입 분리 관리 필요	서버 검증용 느낌이 강함

 

최근 npm trends 비교 - 출처 : https://npmtrends.com/joi-vs-yup-vs-zod

 

Zod란?
- Zod는 TypeScript-first 스키마 선언 및 데이터 검증 라이브러리입니다. 데이터의 구조와 제약 조건을 코드로 선언하고, 런타임에서 안전하게 검증할 수 있도록 도와줍니다.

설치 방법
- npm npm install zod
- yarn yarn add zod
- pnpm pnpm add zod

Zod를 선택한 결정적 이유

1. 타입과 검증을 하나의 소스로 관리 가능

const schema = z.object({ url: z.string(), }); 
type Schema = z.infer<typeof schema>;

스키마 정의 자체가 곧 타입이 되기 때문에,
검증 규칙과 타입 정의가 자연스럽게 단일 소스(Single Source of Truth)가 됩니다.

Yup이나 Joi에서는 이 일관성이 상대적으로 약했습니다.

---

2. superRefine을 통한 실무형 검증 표현력

실무에서 필요한 검증은 단순 required/min/max가 아니라,
비즈니스 규칙에 가까운 로직입니다.

.superRefine((value, ctx) => {
  if (!value) return;

  if (value.size > LIMIT) {
    ctx.addIssue({ message: "용량 초과" });
    return;
  }

  if (!isValidExt(value)) {
    ctx.addIssue({ message: "확장자 오류" });
  }
});

이 방식은 단순히 “검증 도구”라기보다,
검증 규칙을 선언적으로 모델링하는 도구라는 인상을 주었습니다.

---

3. 특정 Form 라이브러리에 종속되지 않음

Zod는 RHF와 함께 자주 사용되지만,
sageParse라는 명확한 인터페이스 덕분에 완전히 독립적인 검증 엔진처럼 활용 가능했습니다.

이 점 덕분에 기존 UI 시스템 위에 어댑터 패턴을 적용할 수 있었습니다.

 

 

 

5. 해결책: Zod + 어댑터 패턴(Adapter Pattern)

1) 중앙 집중식 스키마 정의

먼저 모든 유효성 검사 규칙을 Zod 스키마로 한 곳에 모았습니다.
특히 복잡한 순차 검증은 superRefine을 활용해 선언적으로 표현했습니다.

// webSettingSchema.ts 예제
export const webSettingSchema = z.object({
  url: z.string().regex(URL_REGEX, "올바른 URL이 아닙니다."),
  loginRecords: z.any().superRefine((val, ctx) => {
    if (!val?.[0]) return;

    if (val[0].size > LIMIT) {
      ctx.addIssue({
        code: "custom",
        message: "파일 크기가 제한을 초과했습니다.",
      });
      return; // 에러 발생 시 후속 검증 중단
    }

    if (ext !== "ecl") {
      ctx.addIssue({
        code: "custom",
        message: "허용되지 않은 확장자입니다.",
      });
    }
  }),
});

 

2) validateWith: 작은 어댑터의 힘

문제는 기존 UI 라이브러리가 (value) => Promise 형태의 rules를 요구한다는 점이었습니다.

이를 해결하기 위해 Zod 스키마를 기존 인터페이스에 맞춰주는 작은 어댑터를 만들었습니다.

// validation.ts
export const validateWith = (schema) => (value) => {
  const result = schema.safeParse(value);

  return result.success
    ? Promise.resolve()
    : Promise.reject(result.error.issues[0].message);
};

이 어댑터 덕분에:

• 기존 UI 컴포넌트는 단 한 줄도 수정하지 않고
• 내부 검증 로직만 Zod 기반으로 교체할 수 있었습니다.

 

5. 리팩토링 결과: UI는 더 가볍게, 로직은 더 견고하게

리팩토링 후 UI 컴포넌트는 훨씬 단순해졌습니다.

// AS-IS: UI와 로직이 뒤섞인 모습
<TextField
  rules={[
    (value) => {
      if (!/https?:\/\/.+/.test(value)) {
        return Promise.reject("URL 형식이 틀립니다.");
      }
      return Promise.resolve();
    },
  ]}
/>

// TO-BE: 선언적인 연결
<TextField
  name="url"
  rules={[validateWith(schema.shape.url)]}
/>

리팩토링을 통해 다음과 같은 이점을 확보했습니다.

1. 관심사의 분리 (Separation of Concerns)
   • 검증 규칙은 스키마에, UI는 화면 구성에만 집중
2. 유지보수성 향상
   • 규칙 변경 시 UI 파일을 열 필요가 없음
   • 스키마 한 곳만 수정하면 전체 반영
3. UI 일관성 유지
   • 기존 UX와 컴포넌트 구조를 그대로 유지
4. 낮은 인지 부하
   • JSX 사이에 숨어 있던 정규식과 if/else 제거
   • 코드 가독성 대폭 개선

 

6. 마치며

이번 리팩토링은 “도구를 바꿨다”기보다는, 책임의 경계를 다시 정의한 경험에 가까웠습니다. 혹시 여러분의 프로젝트에서도 유효성 검사 로직이 JSX 사이에 숨어 있지는 않나요? 프레임워크를 갈아엎지 않아도, 어댑터 패턴과 스키마 기반 검증만으로 충분히 우아한 구조를 만들 수 있습니다.