NEXT.js 의 useMutation은 ReactQuery의 'useMutation' 훅을 활용하여 데이터 변경작업(mutate)을 수행하는 데 사용된다. 이 훅은 주로 API 요청을 보내고 그에 대한 응답을 처리하는데 활용된다.
POST, PUT, DELETE 작업을 할 때 주로 사용.
- useMutation 을 사용하여 API 요청을 보낼 때에는 'mutationFn' 옵션에 요청을 수행하는 함수를 제공해야 한다. 이 함수는 API 요청을 수행하고 그에대한 응답을 반환한다
- 데이터 변이(mutate) 관리 : 'useMutation' 훅 혹은 API 요청이 성공하거나 실패했을 때에 대한 상태를 관리한다. 성공할 경우 성공 상태를 업데이트하고 ,실패할 경우 오류 상태를 업데이트한다.
- 옵션 설정 : useMutation 은 다양한 옵션을 설정할 수 있다. 요청을 보낼 때에 사용할 데이터를 지정할 수 있고 성공 또는 실패한 후에 콜백 함수를 지정할 수 있다
- 자동 재요청 : 요청이 성공했을 때 데이터를 자동으로 다시 가져오는 옵션도 제공한다. 실시간 업데이트에 유용하다.
EX)
import { useMutation } from 'react-query';
const YourComponent = () => {
// useMutation 훅을 사용하여 API 요청을 보냅니다.
const mutation = useMutation({
mutationFn: async (data) => {
// API 요청을 보내고 응답을 반환하는 비동기 함수입니다.
const response = await axios.post('/api/your-endpoint', data);
return response.data;
},
// 성공 및 실패 시 실행될 콜백 함수를 지정할 수 있습니다.
onSuccess: (data) => {
console.log('요청이 성공했습니다:', data);
},
onError: (error) => {
console.error('요청이 실패했습니다:', error);
},
});
// 데이터 변경(mutate)을 위한 이벤트 핸들러 함수 등에서 mutation 함수를 호출하여 API 요청을 보냅니다.
const handleMutate = () => {
mutation.mutate({ /* 요청에 필요한 데이터 */ });
};
return (
<button onClick={handleMutate}>API 요청 보내기</button>
);
};
사용
import { useRouter } from 'next/router'
import axios from 'axios'
import { useMutation } from 'react-query'
import { useEffect } from 'react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
const Temp = () => {
const { query } = useRouter()
console.log(query)
const certificateMutation = useMutation({
mutationFn: () => {
return axios.post('http://localhost:3000/api/만들어야댐', query)
},
})
useEffect(() => {
if (Object.keys(query).length > 0) {
console.log('🚀 ~ useEffect ~ query:', query)
console.log('🚀 ~ useEffect ~ Object:', Object)
// query 객체가 비어 있지 않은 경우에만 실행
certificateMutation.mutate()
}
}, [query])
return (
<>
<p>인증중입니다</p>
<div></div>
</>
)
}
export default Temp
다음은 공식문서에서 알려주는 사용법이다.
OPTIONS
mutationFn: 비동기 작업을 수행하는 함수로, 이 함수는 Promise를 반환합니다. 이 함수는 variables라는 객체를 받아 실행되며, 이 객체는 mutate가 호출될 때 넘겨진다.
cacheTime: 사용되지 않거나 비활성화된 캐시 데이터가 메모리에 유지되는 시간입니다. 기본적으로 캐시 데이터는 해당 기간 이후에 가비지 컬렉션됩니다. 더 긴 캐시 시간이 지정되면 그것이 사용됩니다.
mutationKey: 변이 키는 queryClient.setMutationDefaults로 설정된 기본값을 상속할 수 있습니다.
networkMode: 네트워크 모드는 'online', 'always', 'offlineFirst' 중 하나입니다. 기본값은 'online'입니다.
onMutate: 변이 함수가 호출되기 전에 실행되는 함수로, 변이 함수가 받는 변수와 동일한 변수가 전달됩니다. 변이가 성공적으로 실행되면 이 함수가 반환하는 값이 onError 및 onSettled 함수에 전달됩니다.
onSuccess: 변이가 성공적으로 실행될 때 호출되는 함수입니다. 변이의 결과가 전달됩니다.
onError: 변이가 오류를 만날 때 호출되는 함수입니다. 오류가 전달됩니다.
onSettled: 변이가 성공적으로 가져오거나 오류를 만났을 때 호출되는 함수입니다. 결과 데이터 또는 오류가 전달됩니다.
retry: 실패한 변이를 재시도하는 데 사용되는 옵션입니다. 기본값은 0이며, 실패한 변이가 재시도되지 않음을 의미합니다.
retryDelay: 재시도 간격을 결정하는 함수입니다.
useErrorBoundary: 변이 오류를 렌더링 단계에서 던지고 가장 가까운 오류 경계로 전파할지 여부를 결정하는 옵션입니다.
meta: 변이 캐시 항목에 추가 정보를 저장하는 데 사용되는 선택적 객체입니다.
context: 사용자 정의 React Query 컨텍스트를 사용하는 데 사용됩니다.
RETURNS
mutate: 변이 함수는 변수를 전달하여 변이를 실행하고, 선택적으로 추가 콜백 옵션을 사용할 수 있습니다. 이것은 실제로 데이터를 변경하는 작업을 수행합니다.
mutateAsync: mutate와 비슷하지만 Promise를 반환합니다. 이는 변이가 비동기 작업을 수행하고 완료되면 값을 반환할 수 있음을 의미합니다.
status: 변이의 현재 상태를 나타냅니다. "idle"은 변이 함수가 아직 실행되지 않은 초기 상태를 나타냅니다. "loading"은 변이가 현재 실행 중인 상태를 의미합니다. "error"는 변이가 실패했음을 나타내며, "success"는 변이가 성공적으로 완료되었음을 나타냅니다.
isIdle, isLoading, isSuccess, isError: 각각 변이의 상태를 부울 값으로 나타냅니다. 이것들은 변이의 상태를 확인하는 데 사용됩니다.
isPaused: 변이가 현재 일시 중지된 상태인지 여부를 나타냅니다. 일시 중지되면 true이고, 그렇지 않으면 false입니다.
data: 마지막으로 성공적으로 해결된 쿼리의 데이터를 나타냅니다. 변이가 성공하면 해당 데이터가 여기에 포함됩니다.
error: 변이 작업 중에 발생한 오류를 나타냅니다. 오류가 없는 경우 null입니다.
reset: 변이의 내부 상태를 초기화하는 함수입니다. 이 함수를 호출하면 변이 상태가 초기 상태로 돌아갑니다.
failureCount: 변이가 실패한 횟수를 나타냅니다. 변이가 실패할 때마다 이 카운트가 증가하며, 성공하면 다시 0으로 재설정됩니다.
failureReason: 변이 재시도의 실패 이유를 나타냅니다. 변이가 성공하면 null입니다.참고 문서 : https://tanstack.com/query/latest/docs/framework/react/overview,
https://tanstack.com/query/v4/docs/framework/react/reference/useMutation,
https://tanstack.com/query/latest/docs/framework/react/guides/mutations
