낙관적 업데이트와 onMutate

_sw_·2025년 2월 20일

프로젝트를 진행하면서 팔로우/좋아요 버튼에 낙관적 업데이트를 처음 적용해보았고, 그 과정에서 관련 자료들을 찾아보고, 낙관적 업데이트에 대한 생각들이나 초기 코드를 리팩토링하는 과정을 적어보았다.

이전에는요…

const useToggleFollow = ({
  initFollowState,
}: {
  initFollowState: boolean | null;
}) => {
  ...

  const mutation = useMutation<
    void,
    Error,
    { userId: number; following: boolean }
  >({
    mutationFn: async ({ userId, following }) => {
      following ? await deleteFollow(userId) : await postFollow(userId);
    },

    onSuccess: (_, { following }) => {
      const currentUserId = TokenHandler.getUserIdFromToken();

      if (currentUserId) {
        [
          ARTWORK.followedArtists,
          USER.followerList(currentUserId),
          USER.followingList(currentUserId),
        ].forEach((queryKey) => {
          queryClient.invalidateQueries({ queryKey: [queryKey] });
        });
      }

      setIsFollowing(!following); // 성공 시 데이터 변경
    },

    onError: (error) => {
      console.error('팔로우 상태 변경 에러: ', error.message);
    },
  });

	...

  return { isFollowing, toggleFollow };
};

export default useToggleFollow;

기존 로직의 개선점

useMutation의 동작에 따라 onSuccess는 mutateFn이 정상적으로 마쳐야 동작. 따라서 follow 상태를 변경하는 로직은 api 로직이 모두 끝난 다음에야 동작.

→ UI 갱신이 follow/unfollow의 로직 처리 시간에 영향을 받음.
에러가 발생했을 때, 함수 자체가 미실행 된 것인지, 버튼 이벤트가 실패한 것인지에 대한 피드백이 없음 (다른 UI 장치가 없다고 가정.)

낙관적 업데이트

사용자 경험(UX)를 증진시키기 위해 적용하는 개념으로, 상태, 데이터 업데이트와 관련해서 우선 데이터 변경이 정상적으로 이루어진 다는 것을 가정하여 요청이 마무리 되기전에 상태를 변경하고, 추후 실패 상태에 대해서는 다시 원래 상태로 복구 시켜 에러 이벤트에 대한 피드백을 전달하는 방식

기존 업데이트 플로우	낙관적 업데이트 플로우
1. 사용자 동작 수행 2. 서버에 변경 사항 전달 3. 전달 성/패에 따라 UI 업데이트	1. 사용자 동작 수행 2. 성공 케이스로 UI 업데이트 3. 서버에 변경 사항 전달 4. 실패 시 기존 상태로 롤백

낙관적 업데이트는 언제 활용해야할까.

낙관적 업데이트를 적용하는 기준에 대해서 프로젝트 데모 발표 때에도 받았었다. 개인적으로, 이번에 적용한 팔로우, 좋아요 버튼과 같이 사용자가 api 요청에 대한 결과를 사용하지 않아 사용자 액션에 영향을 주지 않는 UI의 UX를 개선하기 위해 사용하려고 했다.

반면에 갱신된 서버 데이터로 인해서 이후 다른 인터렉션에 영향이 미치는 경우나 중요한 비즈니스 로직의 경우 빠른 반응보다 정확한 처리가 더 중요하기 때문에 이런 경우에는 지양하는 것이 좋겠다라는 생각을 했다.

낙관적 업데이트 적용하기

1. setState로 적용하기

단순히 ‘상태를 미리 갱신한다.’는 점에서 setState를 통해서 구현이 가능하다.

mutateFn 내에서 api 요청을 실행하기 전에 state를 수정하고, 성공 시에 상태는 그대로 두고, 에러 발생 시 mutateFn의 인자로 전달받은 값을 통해 이전 값으로 갱신한다.

```jsx
const useToggleFollow = ({
  initFollowState,
}: {
  initFollowState: boolean | null;
}) => {
	...

  const mutation = useMutation<
    void,
    Error,
    TogglePropsType,
    MutationContextType
  >({
    mutationFn: async ({ userId, following }) => {
	    // 상태 먼저 갱신
      setState(!following);
      following ? await deleteFollow(userId) : await postFollow(userId);
    },
    
    onSuccess: () => {
      const currentUserId = TokenHandler.getUserIdFromToken();

      if (currentUserId) {
        [
          ARTWORK.followedArtists,
          USER.followerList(currentUserId),
          USER.followingList(currentUserId),
        ].forEach((queryKey) => {
          queryClient.invalidateQueries({ queryKey: [queryKey] });
        });
      }
      
      // 성공시 변경된 상태 그대로 유지
    },

    onError: (error, { following }) => {
	    // 에러 발생시 상태 롤백
	    setState(following);
      console.error('팔로우 상태 변경 에러: ', error.message);
    },
  });
	
	...
};
```

이것도 충분히 잘 작동한다.

2. useMutate로 적용하기

tanstack query에서는 낙관적 업데이트를 위한 useMutation의 onMutate 옵션을 제공하고 있다. 공식 문서에서는 다음과 같이 onMutate에 대해서 설명하고 있다.

이함수는 mutation 함수가 실행되기 이전에 실행된다. 그리고 mutation 함수가 받아 하는 변수와 동일한 변수를 전달 받는다.
mutation이 성공했을 때에 대한 낙관적 업데이트에 활용할 수 있다.
mutation이 실패한 경우, 이 함수로 부터 return된 값은 onError와 onSettled로 전달 된다. 그리고 낙관적업데이트를 롤백하는 데 유용하다.

onMutate를 활용하여 다음과 같이 적용해볼 수 있다.

const useToggleFollow = ({
    initFollowState,
  }: {
      initFollowState: boolean | null;
  }) => {
    ...

    const mutation = useMutation<
      void,
      Error,
        TogglePropsType,
        MutationContextType
    >({
        mutationFn: async ({ userId, following }) => {
          following ? await deleteFollow(userId) : await postFollow(userId);
        },

        onMutate: async ({ following }) => {
          await queryClient.cancelQueries();

          // 에러 케이스를 대비하여 기존 상태 값 저장
          const prevFollowStatus = isFollowing;

          // 일단 상태 변경
          setIsFollowing(!following);

          return { prevFollowStatus };
        },

        onSuccess: () => {
          const currentUserId = TokenHandler.getUserIdFromToken();

          if (currentUserId) {
            [
              ARTWORK.followedArtists,
              USER.followerList(currentUserId),
              USER.followingList(currentUserId),
            ].forEach((queryKey) => {
              queryClient.invalidateQueries({ queryKey: [queryKey] });
            });
          }

          // 성공시 변경된 상태 그대로 유지
        },

        onError: (error, _, context) => {
          console.error('팔로우 상태 변경 에러: ', error.message);

          // 에러가 발생한 경우 원래 상태로 롤백
          if (context?.prevFollowStatus !== undefined) {
              setIsFollowing(context.prevFollowStatus);
        }
      },
    });
  
  ...
  
};