Mayorov BLOG

outputFiles: {
  './userApi.generated.ts': {
    filterEndpoints: [/user/i],
  },
  './orderApi.generated.ts': {
    filterEndpoints: [/order/i],
  },
  './petApi.generated.ts': {
    filterEndpoints: [/pet/i],
  },
},

Шаг 5. Генерируем хуки из OpenAPI

Аналогом npx в pnpm является команда pnmp dlx - используем ее и плагин @rtk-query/codegen-openapi для генерации кода:

pnpm dlx @rtk-query/codegen-openapi ./src/services/petStoreApi/openapi-codegen-config.cjs

(Опционально) Можете добавить эту команду как скрипт в package.json, чтобы быстрее ее вызывать и использовать в CI/CD пайплайне

Таким образом мы получим файл api.generated.ts с хуками, которые мы сможем использовать в наших компонентах. ВАЖНО: Ни в коем случае не пытайтесь вручную изменять сгенерированный файл! Ведь если api еще в разработке, при каждой повторной кодогенерации, все изменения будут удаляться.

Шаг 6. Используем хуки в наших компонентах

Создадим компонент, который будет получать информацию о питомце по id. Импортируем нужный нам сгенерированный хук, благодаря React Query он способен самостоятельно следить за статусом запроса, кэширует данные и обновляет компонент при их изменении:

📄 src/components/petInfo/petInfo.tsx

import { useGetPetByIdQuery } from "../../services/petStoreApi/api.generated";
const PetInfo = () => {
    const { data, error, isLoading, isFetching } = useGetPetByIdQuery({ petId: 10 });

    if (isLoading || isFetching) { return <div>Loading...</div>;}
    if (error) { return <div>{ 'status' in error ? error.status : error.message}</div>}

    return (
        <div>
            {data && (
            <div>
                <p>Name: {data.name}</p>
                <p>Category: {data.category ? data.category.name : "Не известна"}</p>
                <p>Status: {data.status ? data.status : "Не известно"}</p>
            </div>
            )}
        </div>
    );
};

export default PetInfo;

Попробуйте дополнить этот компонент самостоятельно, например, добавьте в него поле input для ввода id питомца, и проследите за отправкой запросов через вкладку Network в devTools - вы увидите как RTK Query их кэширует.

Кастомизация и сложные кейсы

Важно помнить, что RTK Query спроектирован так, чтобы обеспечить нам максимальную декларативность при использовании в связке с React. Не нужно пытаться использовать createAsyncThunk или напрямую обращаться к API, ведь RTK Query самостоятельно следит за статусом запроса, кэширует данные и обновляет компонент при их изменении. Если вы хотите имплементировать что-то сложное, чтобы обеспечить общую консистентность, лучшим решением будет создать новый хук, который будет использовать внутри себя сгенерированные хуки.

Кейс 1: хочу отправить POST запрос и автоматически обновить связанные данные

Предположим, что мы хотим создать нового питомца и после этого обновить информацию получаемую по id. У нас уже есть компонент counter, который мы для примера используем как генератор id питомца. Обновим в соответствии с этим компонент PetInfo:

📄 src/components/petInfo/petInfo.tsx

import { useGetPetByIdQuery } from "../../services/petStoreApi/api.generated";
import { useAppSelector } from "../../store/hooks";

const PetInfo = () => {
    // Используем уже готовый сounter вместо id
    const id = useAppSelector((state) => state.counter.value);
    const { data, error, isLoading, isFetching } = useGetPetByIdQuery({ petId: id });

    if (isLoading || isFetching) { return <div>Loading...</div>;}
    if (error) { return <div>{ 'status' in error ? error.status : error.message}</div>}

    return (
        <div>
            {data && (
            <div>
                <p>Name: {data.name}</p>
                <p>Category: {data.category ? data.category.name : "Не известна"}</p>
                <p>Status: {data.status ? data.status : "Не известно"}</p>
            </div>
            )}
        </div>
    );
};

export default PetInfo;

Теперь создадим новый компонент, который будет отправлять запрос на создание питомца и обновлять информацию о нем:

📄 src/components/petInfo/addPet.tsx

import { useAddPetMutation } from '../../services/petStoreApi/api.generated';
import { useAppSelector } from '../../store/hooks';

const AddPet = () => {
    // Используем уже готовый Counter вместо поля ввода id
    const id = useAppSelector((state) => state.counter.value);
    // Используем готовый хук useAddPetMutation для добавления питомца
    const [triggerAddPet] = useAddPetMutation();

    function handleAddPet() {
        triggerAddPet({ pet: {
            id,
            name: 'New Pet with id ' + String(id),
            photoUrls: [],
            category: { id: 1, name: 'Dogs' },
            status: 'available'
        }});
    }

    return (
        <div><button onClick={handleAddPet}>Add Pet with id: {id}</button></div>
    );
};

export default AddPet;
                                

Но мы увидим, что при добавлении питомца, информация о нем по id не обновляется автоматически, а только после обновления страницы. Для того чтобы исправить это поведение, как мы обсуждали ранее, нужно добавить к эндпоинтам определения providesTags и invalidatesTags. Это можно сделать двумя способами.

Способ 1: Если в OpenAPI схеме прописаны тэги, то можно просто добавить свойство tags: true в openapi-codegen-config.cjs и повторно сгенерировать файл api.

Способ 2: вручную добавить определения providesTags и invalidatesTags с помощью enhanceEndpoints. Для этого создадим новый файл apiEnhanced:

📄 src/services/petStoreApi/apiEnhanced.ts

import { petStoreApiGenerated } from "./api.generated";
export const petStoreApiEnhanced = petStoreApiGenerated.enhanceEndpoints({
    addTagTypes: ['Pet'],
    endpoints: {
        getPetById: {
            providesTags: ['Pet'],
        },
        addPet: {
            invalidatesTags: ['Pet'],
        },
    },
});

export const {
    useAddPetMutation,
    useGetPetByIdQuery,
  } = petStoreApiEnhanced;

Теперь вместо импортирования из сгенерированного api, импортируем хуки из apiEnhanced в наших компонентах:

import { useGetPetByIdQuery } from "../../services/petStoreApi/apiEnhanced"; 

import { useAddPetMutation } from '../../services/petStoreApi/apiEnhanced'; 

В результате сразу после создания нового питомца с помощью useAddPetMutation кэш с тэгом Pet будет инвалидироваться, что приведет к повторному вызову запроса из useGetPetByIdQuery и автоматическому обновлению нужных нам данных.

Кейс 2: хочу отправить запрос с предустановленными аргументами

Если у вас есть сгенерированный эндпоинт, который принимает несколько аргументов, вы можете создать кастомный хук, где часть данных будет уже предустановлена.

Создадим кастомный хук useFindAvailablePetsQuery, который будет возвращать список питомцев со статусом "available". За основу возьмем хук useFindPetsByStatusQuery, в котором нужно явно указать статус, чтобы сделать запрос.

📄 src/services/petStoreApi/apiEnhanced.ts

import { useFindPetsByStatusQuery } from "./api.generated";

export const useFindAvailablePetsQuery = (args: { page: number; limit: number }) => {
    return useFindPetsByStatusQuery({ ...args, status: 'available' });
};

Теперь вместо импортирования из сгенерированного api, импортируем хук из apiEnhanced в наших компонентах:

📄 src/components/petInfo/availablePets.tsx

import { useFindAvailablePetsQuery } from '../../services/petStoreApi/apiEnhanced';
const AvailablePets = () => {
    const { data, error, isLoading, isFetching } = useFindAvailablePetsQuery({page: 1, limit: 20});
    if (isLoading || isFetching) { return <div>Loading...</div>;}
    if (error) { return <div>{ 'status' in error ? error.status : error.message}</div>}

    return (
        <div>
            {data && (
            <div>
                <h2>Available pets:</h2>
                <ul>
                    {data.map((pet) => (
                        <li key={pet.id}>{pet.name}</li>
                    ))}
                </ul>
            </div>
            )}
        </div>
    );
};

export default AvailablePets;

Кейс 3: хочу модифицировать результат запроса прямо в хуке

Если вам нужно модифицировать результат запроса, например, добавить новое поле или отфильтровать данные, вы можете сделать это прямо в хуке. Для примера создадим хук useFindAvailableSlavicPetsQuery, который будет возвращать список питомцев с именами на кириллице и добавит новое поле в получаемые объекты.

📄 src/services/petStoreApi/apiEnhanced.ts

import { Pet } from "./api.generated";
import { useFindPetsByStatusQuery } from "./api.generated";

type ModifiedPet = Pet & {
    isNameCyrillic: boolean; // Добавляем новое поле
};

export const useFindAvailableSlavicPetsQuery = () => {
    const { data, error, isLoading, isFetching } = useFindPetsByStatusQuery({ status: 'available' });

    // Модифицируем results - оставляем только питомцев с именами, содержащими кириллицу, и добавляем новое поле
    const modifiedData: ModifiedPet[] | undefined = data?.map((pet) => ({
        ...pet, // Сохраняем остальные данные
        isNameCyrillic: /[а-яА-ЯЁё]/.test(pet.name), // Проверяем имя на кириллицу и добавляем новое поле
    })).filter((pet) => pet.isNameCyrillic) // Оставляем только питомцев с именами на кириллице

    return {
        data: modifiedData,
        error,
        isLoading,
        isFetching,
    };
};

Кейс 4: хочу отправить несколько запросов параллельно и, если хоть один будет отклонен, отобразить ошибку для всех

Если вам нужно отправить несколько запросов параллельно и обработать их примерно также как это делает Promise.All(), то достаточно просто обработать ошибки прямо в компоненте.

📄 src/components/petInfo/parallelRequests.tsx

import { useFindAvailableSlavicPetsQuery, useGetPetByIdQuery } from '../../services/petStoreApi/apiEnhanced';

const ParallelRequests = () => {
    const { data: slavicPetsList, error: slavicPetsListError, isLoading: slavicPetsListLoading } = useFindAvailableSlavicPetsQuery();
    const { data: firstPet, error: firstPetError, isLoading: firstPetLoading } = useGetPetByIdQuery({petId: 0});

    // Обрабатываем статусы загрузки
    if (slavicPetsListLoading || firstPetLoading) return <div>Loading...</div>;
    if (slavicPetsListError || firstPetError) return <div>Error occurred</div>;

    // Если оба запроса завершились успешно
    return (
        <div>
            {slavicPetsList && firstPet && (
                <div>
                    <h1>Slavic Pets:</h1>
                    <ul>
                        {slavicPetsList.map((pet) => (
                            <li key={pet.id}>{pet.name}</li>
                        ))}
                    </ul>
                    <h1>First Pet</h1>
                    <ul>
                        {firstPet.name}
                    </ul>
                </div>
            )}
        </div>
    );
};

export default ParallelRequests;

Попробуйте поперезагружать страницу, пока один из запросов не провалится, вы увидите, что ни один из результатов не отобразился.

Кейс 5: хочу чтобы запрос отправлялся заново каждые 3 секунды

Ну и напоследок самый легкий кейс - чтобы отправлять запрос циклично, просто добавьте свойство pollingInterval в используемый хук, указав интервал в миллисекундах:

📄 src/components/petInfo/petInfo.tsx

const { data, error, isLoading, isFetching } = useGetPetByIdQuery({ petId: id }, {
  pollingInterval: 3000
});

Заключение

Таким образом, мы рассмотрели базовые кейсы использования RTK Query с OpenAPI и сгенерированными хуками. Надеюсь, что этот гайд поможет вам быстрее начать работу с RTK Query и упростит взаимодействие с API в ваших проектах.