🧩 회원가입 폼 리팩터링 & Zod 검증 트러블슈팅 (공통 Input의 한계와 우회 전략)

💬 배경

다른 팀에서 만든 회원가입 폼을 리팩터링해달라는 요청을 받았다.

코드를 분석해보니 다음과 같은 이슈가 있었다:

• 비밀번호 검증이 .regex()로 중첩되어 유지보수 어려움
• 여러 조건을 위반해도 첫 번째 에러만 표시(스무고개 UX)
• 여러 에러 메시지가 줄바꿈 없이 한 줄로 출력
• 프로젝트 Zod 버전 호환 문제 (최신 옵션 사용 불가)
• 공통 Input 컴포넌트가 error: string만 지원 → 배열을 직접 넣을 수 없음

---

🔍 기존 코드 (Before)

Zod 스키마

import { z } from 'zod'

const passwordSchema = z
  .string({
    error: (issue) =>
      issue.input === undefined
        ? '비밀번호를 입력해주세요'
        : '올바른 비밀번호 형식으로 입력해주세요',
  })
  .min(8, { error: '비밀번호는 최소 8자 이상이어야 합니다.' })
  .max(50, { error: '비밀번호는 50자 이하로 입력해주세요.' })

export const registerSchema = z
  .object({
    email: z.string().trim(),
    password: passwordSchema
      .regex(/[a-z]/, { error: '비밀번호는 최소 하나의 소문자를 포함해야 합니다.' })
      .regex(/[A-Z]/, { error: '비밀번호는 최소 하나의 대문자를 포함해야 합니다.' })
      .regex(/\d/,    { error: '비밀번호는 최소 하나의 숫자를 포함해야 합니다.' })
      .regex(/[!@#$%^&*(),.?":{}|<>]/, { error: '비밀번호는 최소 하나의 특수문자를 포함해야 합니다.' }),
    passwordConfirm: z.string({
      error: (issue) =>
        issue.input === undefined ? '비밀번호 확인 값을 입려해주세요.' : '문자열이어야 합니다',
    }),
    nickname: z.union([z.literal(''), z.string().trim().min(2).max(12)]).optional(),
  })
  .refine((data) => data.password === data.passwordConfirm, {
    message: '비밀번호 값이 일치하지 않습니다',
    path: ['passwordConfirm'],
  })

Form 컴포넌트

// RegisterForm.tsx (Before)
<Input
  label="비밀번호"
  type="password"
  name="password"
  value={formData.password || ''}
  onChange={handleChange}
  placeholder="최소 8자 이상 (영문, 숫자, 특수문자 포함)"
  error={error.includes('비밀번호') && !error.includes('확인') ? error : undefined}
  required
/>

• 에러 상태가 단일 문자열(error: string)이라 여러 조건을 동시에 보여줄 수 없음

---

🎯 리팩터링 목표

1. 여러 조건 위반을 동시에 보여주기
2. .regex() 나열 대신 superRefine로 위반된 항목만 누적
3. 공통 Input은 가급적 큰 변경 없이 확장/우회
4. 가독성 있는 에러 리스트로 UX 개선

---

🚀 리팩터링 (After)

1) Zod: superRefine로 위반만 누적

import { z } from 'zod'

export const registerSchema = z
  .object({
    email: z.string().min(1, { message: '이메일을 입력해주세요.' }).email(),
    password: z.string().min(8).max(50),
    passwordConfirm: z.string().min(1, { message: '비밀번호 확인 값을 입력해주세요.' }),
    nickname: z.union([z.literal(''), z.string().trim().min(2).max(12)]).optional(),
  })
  .superRefine((data, ctx) => {
    const pwd = data.password ?? ''

    if (pwd.length < 8)
      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['password'], message: '비밀번호는 최소 8자 이상이어야 합니다.' })
    if (!/[A-Z]/.test(pwd))
      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['password'], message: '비밀번호는 최소 하나의 대문자를 포함해야 합니다.' })
    if (!/\d/.test(pwd))
      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['password'], message: '비밀번호는 최소 하나의 숫자를 포함해야 합니다.' })
    if (!/[!@#$%^&*(),.?":{}|<>]/.test(pwd))
      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['password'], message: '비밀번호는 최소 하나의 특수문자를 포함해야 합니다.' })

    if (data.password !== data.passwordConfirm)
      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['passwordConfirm'], message: '비밀번호 값이 일치하지 않습니다' })
  })

• 충족한 조건은 에러에 포함되지 않음
• 위반된 조건만 배열로 수집되어 UI에서 모두 표시 가능

---

2) 상위 상태: 필드별 배열로 에러 관리

type FormDataState = z.infer<typeof registerSchema>
type FieldErrors = Partial<Record<keyof FormDataState, string[]>>

const [errors, setErrors] = useState<FieldErrors>({})

const parsed = registerSchema.safeParse(formData)
if (!parsed.success) {
  const { fieldErrors } = parsed.error.flatten()
  setErrors(fieldErrors as FieldErrors) // ✅ 각 필드의 에러가 string[] 형태
  return
}

• fieldErrors.password는 string[]
• 여러 위반 메시지를 동시에 들고 있을 수 있음

---

3) 왜 공통 Input에는 배열을 직접 넣지 않았나?

공통 Input 현재 타입

interface InputProps extends ComponentPropsWithRef<'input'> {
  label?: string
  error?: string          // ❌ string만 허용
  helperText?: string
}

• error가 string으로 고정되어 있어 string[]을 그대로 넣으면 타입 에러
• 또한 내부 렌더링도 <p>{error}</p> 구조라 리스트 출력 불가
• 공용 컴포넌트를 광범위하게 수정하면 다른 팀 화면들에 영향이 갈 수 있음

그래서 택한 전략: 외부에서 FieldErrors로 렌더링

function FieldErrors({ messages }: { messages?: string[] }) {
  if (!messages?.length) return null
  return (
    <ul className="mt-1 space-y-1 text-sm text-destructive" role="alert">
      {messages.map((m, i) => <li key={i}>• {m}</li>)}
    </ul>
  )
}

<Input
  label="비밀번호"
  type="password"
  name="password"
  value={formData.password || ''}
  onChange={handleChange}
  placeholder="최소 8자 이상 (영문, 숫자, 특수문자 포함)"
  // error prop은 생략하거나 첫 에러만 넣을 수도 있음
  required
/>
<FieldErrors messages={errors.password} />

• 공통 Input은 그대로 두고, 필드 아래에서 리스트로 표시
• 협업/안정성 측면에서 가장 안전한 우회 전략

참고: 장기적으로는 공통 Input의 error 타입을 string | string[]로 확장하고, 내부에서 <ul>을 렌더링하도록 개선하면 폼 쪽 코드가 더 깔끔해진다. 단, 이는 컴포넌트 사용하는 전체에 미치는 영향 체크하고 진행해야 한다.

---

📊 Before / After 비교

항목	Before	After
검증 방식	.regex() 중첩	superRefine로 통합
에러 구조	error: string (단일)	errors[field]: string[] (다중)
에러 표시	한 줄	<ul><li> 리스트
Input 사용	error에 문자열	FieldErrors로 배열 직접 렌더
공통 컴포넌트 영향	없음	없음 (외부 확장 방식)
UX	스무고개형	위반 항목 동시 노출

---

🧠 배운 점

1. 타인의 코드를 리팩터링할 땐 분석이 먼저.

   수정할 부분과 감싸서 해결할 부분을 구분해야 한다.

2. 검증은 로직이 아니라 UX.

   왜 틀렸는지 한눈에 보이게 해야 한다.

3. 공통 컴포넌트는 변경 영향도를 고려.

   우선은 외부에서 확장해 안전하게 개선하고,

   필요할 때 팀 합의로 공통 컴포넌트를 발전시키자.

4. Zod superRefine은 강력한 도구.

   복잡한 조건을 한 번에 제어하고, “위반만” 모아서 보여줄 수 있다.

---

✍️ 마무리

이번 리팩터링은 단순히 에러 문구를 고치는 작업이 아니라,

다른 팀이 만든 공통 컴포넌트의 제약을 이해하고,

그 안에서 UX를 최대한 끌어올리는 구조적 개선이었다.

필요하다면 공통 Input을 error: string | string[]로 확장하는 다음 단계도 가능하지만,

이번에는 안전하고 영향이 적은 우회 전략(FieldErrors) 으로 목표를 달성했다.