클라이언트 측 비밀번호 확인 로직 도입 (Zod refine 활용)

[sgoldenbird]

🎯 개선 목표 (What needs improvement?)

기존에 서버에서 담당하도록 설계되었던 회원가입 시 비밀번호 일치 여부 검증 로직을 클라이언트 측(프론트엔드)에서 처리하도록 변경하여 사용자 경험을 개선하고 서버 부하를 줄이는 것을 목표로 합니다. 이를 위해 Zod 라이브러리의 refine 메서드를 활용하여 스키마 기반 유효성 검사를 적용합니다.

---

🧭 사용자 시나리오 (User scenario)

기존 시나리오:

1. 사용자가 회원가입 폼에 비밀번호와 비밀번호 확인을 입력합니다.
2. 비밀번호와 비밀번호 확인이 일치하지 않는 상태로 폼을 제출합니다.
3. 클라이언트는 요청을 서버로 보냅니다.
4. 서버는 비밀번호 불일치를 확인하고 에러 응답을 반환합니다.
5. 클라이언트는 서버로부터 받은 에러 메시지를 사용자에게 표시합니다.
   • 문제점: 비밀번호 불일치와 같은 단순 유효성 검사에도 불필요한 네트워크 왕복이 발생하고, 사용자는 에러 메시지를 받기까지 대기해야 합니다.

개선된 시나리오:

1. 사용자가 회원가입 폼에 비밀번호를 입력합니다.
2. 비밀번호 확인 필드에 입력하는 즉시, 또는 필드를 벗어나는 순간 (onBlur), 비밀번호와 비밀번호 확인 필드의 값이 일치하는지 클라이언트에서 즉시 검사합니다.
3. 두 필드의 값이 일치하지 않으면, 사용자는 폼 제출 전에 즉각적으로 "비밀번호가 일치하지 않습니다."와 같은 에러 메시지를 확인합니다.
4. 비밀번호가 일치하는 경우에만 폼 제출이 가능하며, 서버에는 유효한 요청만 전달됩니다.
   • 개선점: 사용자는 즉각적인 피드백을 통해 오류를 수정할 수 있으며, 서버는 유효하지 않은 요청을 처리할 필요가 없어 부하가 감소합니다.

---

🔍 문제의 원인

기존 설계에서 비밀번호 일치 검사를 서버에 의존함으로써 다음과 같은 문제가 발생했습니다:

• 느린 사용자 피드백: 사용자가 비밀번호를 잘못 입력했더라도 서버 응답을 기다려야만 오류를 알 수 있었습니다. 이는 사용자 경험을 저해하는 요인이 됩니다.
• 불필요한 서버 리소스 소모: 단순한 입력 값 불일치에도 불구하고 매번 서버에 요청이 전달되어, 서버는 유효하지 않은 요청을 처리하고 응답하는 데 리소스를 소모했습니다.
• 네트워크 지연 영향: 사용자의 네트워크 환경에 따라 서버 응답 시간이 지연될 수 있으며, 이는 유효성 검사 과정의 체감 성능을 더욱 저하시켰습니다.

---

💡 개선 제안 (Suggested solution)

Zod의 refine 메서드를 활용하여 회원가입 스키마에 비밀번호와 비밀번호 확인 필드의 일치 여부를 검사하는 로직을 추가했습니다.
이 로직은 폼 제출 전 클라이언트 측에서 실행되어, 즉각적인 유효성 검사 피드백을 제공하고 서버 통신을 최적화합니다.

---

🛠 구현 구조 요약 (How it was implemented)

사용자가 입력한 비밀번호(password)와 비밀번호 확인(passwordConfirm)이 일치하는지 프론트엔드에서 유효성 검사하고 서버로 데이터를 전송할 때는 passwordConfirm 필드를 제외하고 전송

1. Zod 스키마 정의 (src/domain/Auth/schemas/request.ts):

• 기본 스키마 (baseSignupRequestSchema)

  • email, nickname, password, passwordConfirm 필드 정의
  • 각 필드는 최소 길이, 포맷 등 클라이언트 측 유효성 검사 규칙 포함

• refine 추가 (signupRequestSchema)

  • refine() 메서드를 사용하여 password와 passwordConfirm 값의 일치 여부를 검사
  • 일치하지 않으면 passwordConfirm 필드에 커스텀 에러 메시지 표시

export const signupRequestSchema = baseSignupRequestSchema.refine(
  (data) => data.password === data.passwordConfirm,
  {
    path: ['passwordConfirm'],
    message: '비밀번호가 일치하지 않습니다.',
  },
);

• 서버 전송용 스키마 (signupDataRequestSchema)
  • passwordConfirm 필드를 제거하여 서버에는 전송되지 않도록 분리
  • 이 스키마는 실제 API 요청에 사용됨

export const signupDataRequestSchema = baseSignupRequestSchema.omit({
  passwordConfirm: true,
});

2. 타입 추론 및 구분:

• SignupFormValues | 클라이언트 폼 전체 입력값 타입 (passwordConfirm 포함)
• SignupRequest | 서버 전송용 타입 (passwordConfirm 제외)

3. 폼 컴포넌트 통합 (/src/domain/Auth/components/SignUpForm.tsx):

• react-hook-form과 zodResolver(signupRequestSchema)를 연결
• 각 InputRoot에 register() 적용
• 에러메시지는 formState.errors에서 추출하여 해당 InputRoot 컴포넌트의 error prop으로 전달하여 InputHelper에 렌더링을 위임
• 제출 시:
  • signupRequestSchema에 따라 전체 SignupFormValues에 대한 클라이언트 측 유효성 검사를 수행
  • 검증 통과 후, 서버 전송용 타입인 SignupRequest로 데이터를 가공하여 passwordConfirm 필드를 제거한 후 API를 호출

전체 관련 스키마 코드

// src/domain/Auth/schemas/request.ts
import z from 'zod';

//
// ───────────────────── 🔐 회원가입 (Sign Up) ─────────────────────
//

/**
 * @schema baseSignupRequestSchema
 * @description
 * 회원가입 폼 입력값에 대한 기본 스키마입니다.
 * passwordConfirm은 서버 전송에는 포함되지 않으며, 클라이언트에서만 사용됩니다.
 */
const baseSignupRequestSchema = z.object({
  email: z.string().email({ message: '유효한 이메일 형식이 아닙니다.' }),
  nickname: z
    .string()
    .min(1, { message: '닉네임을 입력해주세요' })
    .max(10, { message: '닉네임은 10자 이하로 입력해주세요.' }),
  password: z
    .string()
    .min(8, { message: '비밀번호는 최소 8자 이상이어야 합니다.' })
    .regex(/^(?=.*[A-Za-z])(?=.*\d)(?=.*[^A-Za-z\d])[A-Za-z\d\W_]+$/, {
      message: '비밀번호는 영문, 숫자, 특수문자를 모두 포함해야 합니다.',
    }),
  passwordConfirm: z
    .string()
    .min(8, { message: '비밀번호는 최소 8자 이상이어야 합니다.' }),
});

/**
 * @schema signupRequestSchema
 * @description 비밀번호와 비밀번호 확인 필드가 일치하는지 검사하는 refine이 적용된 스키마입니다.
 */
export const signupRequestSchema = baseSignupRequestSchema.refine(
  (data) => data.password === data.passwordConfirm,
  {
    path: ['passwordConfirm'],
    message: '비밀번호가 일치하지 않습니다.',
  },
);

/**
 * @typedef {Object} SignupFormValues
 * @description
 * `react-hook-form`의 `useForm` 훅에 사용되는 회원가입 폼의 데이터 타입입니다.
 * 클라이언트 측 유효성 검사 스키마인 `signupRequestSchema`로부터 타입을 추론(infer)하며,
 * `passwordConfirm` 필드를 포함하여 폼의 전체 상태를 나타냅니다.
 * 이 타입은 주로 `useForm`의 제네릭(`useForm<SignupFormValues>`)과 `onSubmit` 핸들러의 `data` 인수에 사용됩니다.
 */
export type SignupFormValues = z.infer<typeof signupRequestSchema>;

/**
 * @schema signupDataRequestSchema
 * @description 서버에 실제로 전송할 회원가입 데이터에서 passwordConfirm을 제거한 스키마입니다.
 */
export const signupDataRequestSchema = baseSignupRequestSchema.omit({
  passwordConfirm: true,
});

/**
 * @type SignupRequest
 * @description 회원가입 요청에 사용되는 타입입니다. 서버에는 passwordConfirm이 포함되지 않습니다.
 */
export type SignupRequest = z.infer<typeof signupDataRequestSchema>;

---

✅ 개선 결과 및 성과 (Results)

즉각적인 사용자 피드백 제공:
사용자가 비밀번호를 입력하는 도중 또는 입력 완료 후 즉시 일치 여부를 확인할 수 있어 사용자 경험(UX)이 크게 향상되었습니다.
서버 부하 감소:
비밀번호 불일치와 같은 기본적인 유효성 검사 실패 요청이 서버에 도달하지 않으므로, 서버의 불필요한 처리 부담이 줄어들었습니다.
클라이언트 성능 향상:
불필요한 네트워크 왕복이 줄어들어 전반적인 폼 제출 및 유효성 검사 과정의 속도가 빨라졌습니다.
개발 효율성 증대:
Zod의 강력한 타입 추론 기능을 활용하여 스키마 정의와 폼 연동이 더욱 견고하고 효율적으로 이루어졌습니다.

---

🔗 참고자료 / 관련 이슈, PR

• Zod 공식 문서: refine 메서드 활용법
• src/domain/Auth/schemas/request.ts
• src/domain/Auth/components/SignUpForm.tsx
• src/domain/Auth/hooks/useSignupMutation.ts (해당 스키마를 사용하는 뮤테이션 훅)