📝 06. [실무] 폼(Form) 연동 및 오프라인-First 앱 설계

📋 목차

• ☕️ 영철이의 고민: "입력창 데이터랑 캐시 메모리가 자꾸 싸워요!"
• 🤔 왜 알아야 하는가: 극한의 UX 방어선
• 1. 폼(Form) 연동의 황금률: "초깃값은 부모가 넘기고 손절하라"
• 2. 오프라인 퍼스트(Offline-First) 설계: "인터넷이 끊겨도 앱은 살아야 한다"
  • 오프라인 큐(Offline Mutation Queue) 해제법
• 📝 배운 내용 점검하기 (Quiz)

"영철 님, 유저가 산속에서 터널 지날 때 글 작성 버튼 눌렀더니 에러 나고 방금 쓴 글 한 바닥 다 날아갔다는데요?"

☕️ 영철이의 고민: "입력창 데이터랑 캐시 메모리가 자꾸 싸워요!"

(목요일 오후, 폼(Form) 화면의 버그 리포트를 읽고 머리를 쥐어뜯는 영철)

🐣 영철: 리드 님, React Hook Form 도입해서 회원정보 수정 창 만들었거든요?
근데 첫 화면 띄울 때 useQuery로 받아온 유저 정보를 폼 초기값으로 넣어주고, 유저가 막 타이핑하다가 1분이 지나니까... React Query 백그라운드 리패칭이 돌면서 useQuery 데이터가 새로 들어오고 제 폼 작성 내용이 싹 다 리셋돼버려요! 유저들 항의가 빗발칩니다 ..

그리고 하나 더요! 와이파이 살짝 끊겼을 때 "저장" 버튼 누르신 분들은 Network Error 뜨면서 작성 내용이 허공으로 증발해버렸대요. 난감합니다.

🦁 영호: 영철 님, 프론트엔드 개발의 실무에서 가장 까다로운 두 영역, 에디터(Form) 와 결손 네트워크(Offline) 를 동시에 맞으셨군요.
첫 번째 문제는 Server State와 Client State를 한 공간에 섞어놔서 벌어진 참사고(TkDodo #14),
두 번째 문제는 React Query v5에 내장된 오프라인 대응 뮤테이션(Offline Mutation) 옵션을 안 켜둬서 그렇습니다 (TkDodo #13).
실전의 벽, 폼과 오프라인을 우아하게 정복해 봅시다.

🤔 왜 알아야 하는가: 극한의 UX 방어선

웹 앱이 가장 자주 흔들리는 곳은 유저가 텍스트를 입력하는 폼(Form) 화면입니다.
서버에서 데이터를 읽어와서(Read), 사용자가 그걸 고치고(Update), 다시 서버에 저장해야 합니다(Mutation).

여기서 React Query(서버의 진실)와 React Hook Form(유저의 입력값)의 타이밍을 엄격히 통제하지 못하면 영철이처럼 사용자 입력이 서버 리패칭 결과로 덮어써지는 문제가 발생합니다.

또한 모바일 브라우저 환경은 언제 터널이나 지하철에 들어가 인터넷이 10초간 끊길지 모릅니다. 이때 "인터넷이 끊겼습니다" 하고 입력을 잃는 앱과, "일단 저장해 둘게요" 하고 연결이 회복되면 자동 재시도하는 앱의 사용자 경험은 크게 다릅니다.

1. 폼(Form) 연동의 황금률: "초깃값은 부모가 넘기고 손절하라"

영철이의 폼 초기화 에러 원인은 Basic 08강에서 살짝 다루었습니다.
useQuery에서 데이터를 받아와서 폼의 defaultValues에 넣었는데, 1분 뒤 백그라운드에서 캐시가 갱신되자 그 데이터가 다시 폼 입력값을 덮어쓴 거죠.

이를 막으려면 뷰(View)를 분리해야 합니다!
데이터를 퍼오기만 하는 부모(Data Fetcher) 와 폼만 가지고 노는 자식(Form Editor) 으로 말이죠.

// 📝 부모 컴포넌트: 오직 데이터를 가져오고 넘겨주기만 한다.
function UserProfilePage() {
  const { data: user } = useQuery({ queryKey: ['user'], queryFn: fetchUser });
 
  if (!user) return <Spinner />;
 
  // 🚀 황금률 1: 데이터가 완전히 준비된 상태에서만 자식 폼을 그린다.
  return <UserProfileForm initialData={user} />
}

// 📝 자식 컴포넌트: React Hook Form (오직 클라이언트 상태)
import { useForm } from 'react-hook-form';
 
type FormValues = { name: string; age: number };
 
function UserProfileForm({ initialData }: { initialData: User }) {
  const { register, handleSubmit } = useForm<FormValues>({
    // 🚀 황금률 2: 부모가 준 데이터를 "최초의 초깃값"으로만 쓰고 뒤도 돌아보지 않는다.
    defaultValues: { name: initialData.name, age: initialData.age },
  });
 
  const mutation = useMutation({
    mutationFn: updateUser,
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['user'] }),
  });
 
  const onSubmit = (values: FormValues) => {
    mutation.mutate(values);
  };
 
  return <form onSubmit={handleSubmit(onSubmit)}>...</form>
}

이렇게 트리를 쪼개면 부모 쪽 React Query가 1분마다 백그라운드 통신을 하든 말든, 자식 쪽의 useForm은 처음 넘겨받은 초깃값만 쥐고 자기 갈 길을 가기 때문에 유저가 타이핑하던 글자가 리셋되는 일이 0%가 됩니다.

2. 오프라인 퍼스트(Offline-First) 설계: "인터넷이 끊겨도 앱은 살아야 한다"

자, 두 번째 문제! 유저가 폼을 다 작성하고 "저장" 버튼을 눌렀는데 하필 지하철 와이파이가 끊겼습니다. 바닐라 fetch 였다면 즉시 Uncaught Network Error가 떠서 빨간 알림창을 뿜었겠죠.

하지만 React Query에는 무시무시한 기본값이 숨어있습니다.
데이터를 가져오는 useQuery 는 통신이 실패하면 자동으로 3번까지 재시도(Retry) 하고, 오프라인 상태일 때는 인터넷이 연결될 때까지 일시 정지(Pause) 상태로 대기 상태로 머뭅니다.

그런데 여기서 함정 카드!
데이터를 서버로 보내는(수정하는) useMutation 은 기본적으로 Retry가 0번(꺼져있음)입니다. 왜냐하면 결제 버튼을 3번 연달아 누르는 사고가 터질까 봐 보수적으로 세팅된 거니까요.

오프라인 큐(Offline Mutation Queue) 해제법

댓글 작성, 좋아요, 일반적인 글 수정 같은 안전한(Idempotent한 느낌의) Mutation에 한하여, 우리는 이들을 일시 정지(Pause)시켜뒀다가 인터넷이 복구되는 순간 일제히 투하 할 수 있습니다!

// 📝 커스텀 Mutation 훅
export const useSavePost = () => {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: savePostApi,
    // 🚀 기법 1: "오프라인일 땐 에러로 튕겨내지 말고, 일시 정지(Pause)시켜서 큐에 담아라!"
    networkMode: 'offlineFirst',
 
    // 🚀 기법 2: "네트워크 끊겨서 실패했어? 그럼 인터넷 복구될 때까지 3번은 다시 시도해봐!"
    retry: 3,
 
    onMutate: async (newPostInfo) => {
      // 🚀 낙관적 업데이트 발동!
      // 인터넷이 끊겨서 서버가 "응답"을 안 줬음에도 불구하고
      // 화면에는 반드시 새로 쓴 글을 당장 그려서 유저 마음을 편안하게 만듭니다.
      await queryClient.cancelQueries({ queryKey: ['posts'] });
 
      /* ... 앞의 06강처럼 setQueryData 로 캐시 조작 ... */
    },
  });
};

이렇게 세팅하고 유저가 비행기 모드에서 폼을 전송 쳐보세요.

1. 낙관적 업데이트 덕분에 화면에는 내 글이 멋지게 등록된 것처럼 보입니다.
2. 뒷단에서 Mutation은 실패하지만 실패하지 않고 대기열(Queue) 에 들어가 숙면을 취합니다. (isPaused === true)
3. 30분 뒤 유저가 와이파이 존에 들어와 핸드폰 데이터가 다시 연결(online 이벤트 발동)됩니다!
4. React Query 큐에 잠들어있던 Mutation이 즉각적으로 서버로 발사(Retry)되며 DB에 정말로 저장됩니다!

이 흐름이야말로 넷플릭스, 인스타그램에서나 볼 법한 초일류 오프라인 퍼스트(Offline-First) UX 아키텍처입니다.

📝 배운 내용 점검하기 (Quiz)

Q. 영철이는 다음과 같이 useQuery에서 받아온 데이터와 컴포넌트 내부의 로컬 useState (필터용 입력 상태)를 하나의 파일 안에 모두 넣어두었습니다. 다음 중, 이 컴포넌트가 성능상 문제를 일으키고 (또는 버그의 온상이 되고) 있는 이유를 Form/컴포넌트 분리 원칙에 입각하여 가장 정확하게 짚은 것은 무엇입니까?

function BadSearchPage() {
  const { data } = useQuery({ queryKey: ['orders'], queryFn: fetchOrders });
  const [filterText, setFilterText] = useState("");
 
  const filteredData = data?.filter(item => item.name.includes(filterText));
 
  return (
    <div>
      <input value={filterText} onChange={e => setFilterText(e.target.value)} />
      <ul>{filteredData?.map(...)}</ul>
    </div>
  )
}

• A) useState가 입력될 때마다 (키보드 칠 때마다) useQuery 또한 매번 리렌더링되어 서버에 백그라운드 중복 Fetch를 쏘게 되기 때문이다.
• B) filterText 타이핑으로 인해 컴포넌트가 다시 렌더링될 때마다, 굳이 안 바뀌어도 되는 껍데기 로직들이 재실행되고, 반대로 서버 data가 도착하거나 백그라운드 리패칭 될 때마다 타이핑 중이던 UI가 렌더 버벅임을 일으키는 "상태 범위 침범" 이 발생하기 때문이다.
• C) useState 대신 반드시 전역 상태(Zustand)를 써야만 필터가 적용되기 때문이다.

✅ 정답: B

💡 상세 해설:

• 원리 설명: React Query는 기본적으로 A번처럼 컴포넌트가 리렌더된다고 해서 네트워크 요청을 무조건 다시 쏘지 않습니다 (캐시가 제어함). 진짜 심각한 문제는 B번입니다! 사용자가 키보드를 'A', 'p', 'p', 'l', 'e' 칠 때마다 setFilterText가 발생하며 저 거대한 컴포넌트를 5번 재렌더합니다. 만약 화면 하단에 무거운 로직이 있다면 키보드 타이핑마다 앱 전체가 끊깁니다.
• 오답 피드백: "영철 님, 클라이언트 입력 상태(input)와 서버 렌더 상태(data list)는 생명 주기가 다릅니다. 입력창은 별도 컴포넌트로 분리하고, 필요한 경우 debounce된 값만 부모나 query key로 전달해야 프레임 저하를 막을 수 있어요."
• 📌 핵심 기억법: 입력창(Form/Input)과 조회창(Query List)은 컴포넌트를 분리하라! 렌더링 간섭 금지!

📝 마무리 퀴즈

Q1. React Query 데이터와 React Hook Form 입력값을 같은 생명주기로 묶으면 어떤 문제가 생기나요?

✅ 정답: 백그라운드 리패칭으로 서버 데이터가 바뀌는 순간 사용자가 입력 중인 폼 값이 덮이거나 리셋될 수 있습니다.

💡 상세 해설:
서버 데이터는 Query Cache가 계속 최신성을 확인합니다. 반면 폼 입력은 사용자가 지금 편집 중인 클라이언트 상태입니다. 부모가 데이터를 가져온 뒤 자식 폼에 초기값으로만 넘기고, 이후에는 폼 상태를 독립시키는 이유가 여기에 있습니다.

Q2. 오프라인 환경에서 networkMode: 'offlineFirst'와 retry를 함께 고려하는 이유는 무엇인가요?

✅ 정답: 네트워크가 끊겼을 때 뮤테이션을 곧바로 실패로 끝내지 않고 대기시킨 뒤, 연결이 회복되면 다시 시도해 사용자 입력 유실을 줄이기 위해서입니다.

💡 상세 해설:
모든 요청을 오프라인 큐에 넣어도 되는 것은 아닙니다. 좋아요, 댓글 저장처럼 재시도 가능한 작업과 결제처럼 중복 실행이 위험한 작업을 나눠야 합니다. 영호가 보는 기준은 UX뿐 아니라 작업의 멱등성과 비즈니스 위험입니다.

Q3. 영철이의 테스트 타임: 회원정보 폼에서 사용자가 이름을 고치는 중인데 1분마다 서버 리패칭이 일어납니다. 어떤 구조가 가장 안전한가요?

✅ 정답: 부모 컴포넌트는 useQuery로 초기 데이터를 준비하고, 자식 폼은 initialData를 defaultValues로 한 번만 사용해 편집 상태를 독립적으로 관리합니다.

💡 상세 해설:
폼은 사용자의 임시 작업 공간입니다. 서버 캐시가 갱신될 때마다 폼을 다시 초기화하면 사용자가 작성한 내용이 사라집니다. 영철이 이제 서버 상태의 신선도와 사용자의 편집 중 상태를 분리해 봐야 합니다.

🐣 영철이의 퇴근 일기

오프라인 모드에서 실패한 요청을 바로 사용자 입력 손실로 이어지게 만들지 않고, 재시도 가능한 작업으로 분류해 나중에 처리할 수 있다는 점이 인상적이었다. 예전 같으면 localStorage와 online 이벤트를 직접 엮었을 텐데, 이제는 작업의 멱등성과 재시도 가능성을 먼저 따져야 한다.

💡 오늘의 교훈: "Form 데이터와 Query 캐시는 부모/자식 관계로 분리해 초기화 간섭을 끊자. 오프라인 재시도는 작업의 멱등성과 비즈니스 위험을 확인한 뒤 켜자."

이 구조를 앱에 반영하고 영숙 디자이너 님에게 시연했더니, 터널 구간에서도 댓글 입력이 보존되는지 QA 시나리오로 다시 확인해보자고 했다. 내일은 오프라인 큐에 넣어도 되는 작업과 넣으면 안 되는 작업을 표로 정리해야겠다.