React Query usage

React Query предоставляет удобный способ написания запросов в API через react hooks.

Директории. Наименования.В директории src/api/ создаются папки, название которых должно соответствовать названию домена API. Обычно домен прописывается вначале метода, например, метод GET /catalog/banners:search соответствует домену catalog (строго говоря, домен называется PIM, но для удобства единообразия неймингов на фронте и бэке, примем более часто повторяющееся название домена). Наименование файла должно семантически отражать описываемые в нем методы. Например, файл banners.ts содержит методы для CRUD баннера/ов

Структура

api → apiDomainName → method.ts

В директории apiDomainName также есть папка с типами. Типы описываются согласно предоставляемой бекендерами документации в Stoplight’е.

Все методы реэкспортируются в файлике index.ts. Для удобства импортов в места использования. Аналогично и с типами. Например в types/index.ts будет примерно такой код

export * from './banners.ts';
export * from './brands.ts'

Написание хуков

Здесь не должно быть проблем, все дается просто по аналогии с другими примерами.

Не забывать прописывать все типы: для ответа, для ошибки, для параметров (если есть)

👍

import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
import { CommonResponse } from '@api/common/types';
import { client } from '../index';
import { BrandsParams, Brand, BrandBase, BrandBaseWithId, BrandsImageMutateParams } from './types';

const BRANDS_BASE_URL = 'catalog/brands';

export const useBrands = (data: BrandsParams = {}) =>
    useQuery<CommonResponse<Brand[]>, Error>({
        queryKey: ['brands', data],
        queryFn: () => client(`${BRANDS_BASE_URL}:search`, { data }),
    });

Для хуков, использующих useQuery, не забывать прокидывать параметры в ключ queryKey Иначе, мы не получим прелести автоматического рефетча при изменении параметров.

Также, считаю хорошей практикой, прописав параметр BrandsParams, не разворачивать его так, как это сделано в примере ниже. А делать это по месту использования хука. Потому что разные наборы параметров могут быть необходимы в разных условиях (и судя по stoplight'у здесь представлены не все)

💩

export const useProducts = ({
    id,
    name,
    code,
    category,
    brand,
    createdAtFrom,
    createdAtTo,
    priceFrom,
    priceTo,
    page,
}: Partial<ProductFilter>, isEnabled = true) =>
    useQuery<ProductProp, Error>({
        enabled: isEnabled,
        queryKey: [
            'products',
            id,
            name,
            code,
            category,
            brand,
            createdAtFrom,
            createdAtTo,
            priceFrom,
            priceTo,
            page
        ],
        queryFn: () => client('catalog/products:search', {
            data: {
                filter: {
                    external_id: [code],
                    name,
                    code: id,
                    category_id: category,
                    brand_id: brand,
                    created_at_from: createdAtFrom,
                    created_at_to: createdAtTo,
                    price_from: priceFrom,
                    price_to: priceTo,
                },
                pagination: {
                    limit: ITEMS_PER_PRODUCTS_PAGE,
                    offset: page ? (page - 1)*ITEMS_PER_PRODUCTS_PAGE : 0,
                    type: 'offset',
                },
            },
        }),
    });

Пример использования хука мутации

Определим сам хук

const BASE_URL = 'cms/banners';

export const useCreateProductGroupBanner = () =>
    useMutation<BannerCreateResponse, Error, BannerCreateParams>(
        data => client(`${BASE_URL}`, { data }));

Добавим хук на страницу.

const createProductGroupBanner = useCreateProductGroupBanner();

И используем метод mutateAsync

const res = await createProductGroupBanner.mutateAsync(data));
// какой-то код с res
setBanner(res.data);

Обратите внимание, константа createProductGroupBanner – это объект. Но здесь мы не будем использовать деструктуризацию, для того, чтобы не заниматься бесконечным переименованием в случае использования других хуков мутации на одной странице. Например

💩

const {
    data: apiRegions,
    isFetching: isLoadingRegions,
    error: regionsError,
} = useRegions();

const {
    data: apiPrices,
    isFetching: isPricesLoading,
    error: pricesError,
} = useDeliveryPrices();

Инвалидация кеша.

После использования хука мутации, а именно удаления/обновления/добавления какой-нибудь сущности, то нужно инвалидировать кеш и переполучить данные либо для конкретной сущности, либо для всего списка сущностей. Можно сделать оптимистичное обновление интерфейса и в случае неудачи откатиться назад, но это немного сложно, и на мой взгляд, для этого проекта избыточно.

Сейчас на проекте встречается 2 способа инвалидации кэша:

Первый. После успешной мутации мы скидываем кеш для конкретных ключей. В примере ниже, кэш станет невалидным для всех ключей, начинающихся с 'brands'. Это действие произойдет автоматически.

export const useCreateBrand = () => {
    const queryClient = useQueryClient();

    return useMutation<CommonResponse<Brand>, Error, BrandBase>(data => client(BRANDS_BASE_URL, { data }), {
        onSuccess: () => queryClient.invalidateQueries(['brands']),
    });
};

Второй. Мы вручную переполучим данные. Для этого нам нужно получить метод refetch из хука, который использует под капотом useQuery. А потом этот refetch используем в нужном месте, например, при успехе обновления данных об одном конкретном пользователе

const { data, refetch } = useCustomer(id);
const customer = data?.data;
const updateCustomer = useUpdateCustomer();

const onCustomerUpdate = async (values: FormikValues) => {
    if (customer) {
        await updateCustomer.mutateAsync(
            {
                ...customer,
                birthday: values?.birthday?.toString(),
                gender: +values?.gender,
                city: values?.city,
                comment_internal: values?.comment,
            },
        );
        refetch();
    }
}

Какой из двух способов использовать, решать вам. Но помните, что в первом случае инвалидация кеша и приведет к переполучению всех данных, чей ключ прокинут в invalidateQuery(key). И это будет происходить всякий раз при мутации.