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

📋 목차

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

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

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

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

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

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

🦁 영호: 영철 님, 프론트엔드 개발의 진정한 지옥 2가지, 에디터(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) 상태로 숨죽이고 기다립니다 (TkDodo 피셜, 최고의 미덕).

그런데 여기서 함정 카드!
데이터를 서버로 보내는(수정하는) 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 아키텍처입니다.

🐣 영철이의 퇴근 일기

와, 오프라인 모드에서 에러 안 나고 백그라운드 큐(Queue)에 쌓아 놨다가 나중에 쏴주는 거 진짜 컬처쇼크다. 이거 내가 수동으로 짰으면 로컬스토리지에 데이터 캐싱하고, window.addEventListener('online', ...) 달고 백날 생쑈를 했을 텐데, 옵션 두 개(networkMode, retry)로 끝난다고...?

💡 오늘의 교훈: "Form 데이터와 Query 캐시는 철저히 부모/자식 관계로 쪼개서 초기화 간섭을 끊어라! 그리고 결제처럼 민감한 게 아닌 모든 Mutation(좋아요, 리스트 수정 등)은 과감하게 오프라인 Retry 큐를 열어둬서 결손 네트워크 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)는 생명 주기(Lifecycle)가 완전히 다릅니다! Input 창은 별도의 스마트 컴포넌트로 빼서(자식으로 분리) 입력값만 debounce 태워서 위로 쏴주던가, 아니면 리스트 컴포넌트 자체를 자식으로 분리해서 렌더링 충돌을 쪼개야 프레임 저하를 막을 수 있어요."
• 📌 핵심 기억법: 입력창(Form/Input)과 조회창(Query List)은 컴포넌트를 찢어라! 렌더링 간섭 금지!