Le problème
Prenons le back-office d'une boutique en ligne : un
front Vue, fronts/admin, qui consomme les API
des services order, stock et
shipping. Un SDK TypeScript est généré depuis
la spec OpenAPI de chaque API, et les écrans l'appellent
avec un useQuery écrit sur place.
Chaque écran dépend du contrat de l'API.
Les templates lisent status, les dates arrivent
en chaînes, null et undefined se
mélangent. Un champ renommé, et le SDK régénéré casse des
écrans dispersés.
Les clés de cache s'écrivent à la main. Un
écran lit ['order', id], un autre
['orders', id]. Après une expédition,
l'invalidation en oublie la moitié, et une liste affiche un
état périmé.
Chaque écran fait à sa façon. L'un s'abonne au hub Mercure dans la vue, l'autre relit l'API à intervalle régulier. Un agent de code qui ajoute un écran imite le plus proche, et la dispersion grandit.
Les options
Appeler le SDK généré depuis les composants
- Ce qu'elle règle : aucune couche à écrire, et le typage du SDK suit l'API.
-
Ce qu'elle coûte : les symptômes
ci-dessus. La représentation de l'API (JSON-LD, noms,
null) entre dans le cache et les templates.
Un store Pinia par ressource
- Ce qu'elle règle : un point d'accès unique par ressource, partagé par les écrans.
- Ce qu'elle coûte : Pinia gère l'état du client, pas celui du serveur. Cache, déduplication, relecture et chargement sont à réécrire dans chaque store, quand TanStack Query les fournit.
Un composable générique par ressource
-
Ce qu'elle règle : peu de fichiers.
Un
useResource('orders')expose lecture, liste, création et modification. - Ce qu'elle coûte : les transitions de workflow et les actions métier n'entrent pas dans ce CRUD. Le typage devient générique, et le mapping aussi : un spread de la réponse, ou rien.
Un composable par endpoint, avec ses mappers explicites
- Ce qu'elle règle : chaque endpoint (lecture, page de liste, écriture, transition) a son dossier, toujours le même. Les écrans ne voient que le modèle du front.
- Ce qu'elle coûte : plus de fichiers, et du code répétitif d'un dossier à l'autre.
Notre recommandation
Un dossier par endpoint, toujours le même : un composable TanStack Query et ses mappers explicites. Les écrans n'importent que ces composables et le modèle métier du front.
Le composable possède l'URL et les mappers ; son appelant règle le reste (clé, options, callbacks). Le modèle métier appartient au front : il ne suit aucune représentation d'API.
Un modèle aux champs optionnels
Aucun endpoint ne donne tous les champs d'une commande : la liste en donne moins que le détail. Chaque champ du modèle est donc optionnel, et un utilitaire dit ce que chacun garantit ou exige :
// libs/typescript/front-model/WithRequired.ts
/** Un concept dont ces champs sont garantis. */
export type WithRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
Là où une page passe les données d'un endpoint à un
composant, vue-tsc vérifie que l'un couvre
l'autre. Un composant qui exige
customerId accepte les données de
get-order, pas celles de
list-orders.
Ce que cette forme apporte à un agent de code
Ajouter cancel-order revient à copier
ship-order, puis à renommer. Le typage vérifie
la copie aux deux bouts : mapToModel lit
la réponse typée du SDK, mapToRequest produit
sa requête typée. Un champ requis oublié, ou mal nommé,
échoue à la compilation, pas en production.
Un agent de code, comme un nouveau développeur, cherche un exemple à imiter. Quand tous les dossiers se ressemblent, l'exemple le plus proche est le bon, et sa copie se vérifie. La règle tient en une phrase, et le lint la fait respecter.
Les compromis assumés
Plus de fichiers. Deux à quatre par endpoint, même pour une suppression. Chaque fichier a un seul rôle, et son nom dit lequel.
Du code répétitif, assumé. Les
mapToModel de get-order et de
ship-order listent presque les mêmes champs.
Nous ne les factorisons pas : chaque endpoint a son
type de réponse, et un mapper partagé masquerait le jour où
ils divergent.
Pas de générateur ni de tests au départ. Nous stabilisons d'abord la structure sur quelques ressources. Un générateur figerait une forme encore mouvante ; les tests des mappers viendront ensuite.
Un GET par élément quand l'API ne filtre pas par
identifiant.
Pour un écran « commandes suivies »,
useGetEachOrder(ids) lance un
useQueries sous les clés
detail(id). Il partage le cache de
useGetOrder, au prix d'une requête par
commande.
Le signal qui doit faire réexaminer ce choix : des dossiers qui divergent, ou des copies qui oublient l'entretien du cache. C'est le moment d'écrire le générateur et les tests. Si les GET par élément se multiplient, l'API mérite un filtre par identifiant.
Mise en œuvre
Les exemples utilisent Vue 3.5, TanStack Query 5
(@tanstack/vue-query) et un SDK généré par
hey-api. Le service order expose ses
ressources DTO
avec API Platform.
1. L'arborescence
libs/
typescript/
front-model/ # le modèle métier du front, sans framework
WithRequired.ts
order/Order.ts
api-mapping/ # optional, required, toDate, oneOf, toCollection
order-api-sdk/ # généré, jamais modifié à la main
vue/
api-query/ # createResourceQueryKeys, ApiQueryOptions, useMercure
order-api/
client/orderApiClient.ts
endpoint/orders/
queryKeys.ts
get-order/
useGetOrder.ts
mapToModel.ts
index.ts
list-orders/
useListOrders.ts
mapToModel.ts
index.ts
ship-order/
useShipOrder.ts
mapToModel.ts
mapToRequest.ts
index.ts
Une lib Vue par API, un seul modèle métier pour toutes.
L'index.ts d'un dossier n'exporte que le
composable et ses types. Le client porte l'URL du service et
le jeton de l'utilisateur.
Le nom suit l'opération à chaque couche. Côté API, nous
fixons l'operationId (openapi: new Model\Operation(operationId:
'shipOrder')). Le SDK expose alors shipOrder(),
ShipOrderData et
ShipOrderResponse, et le dossier s'appelle
ship-order.
2. Le modèle du front
// libs/typescript/front-model/order/Order.ts
/** Où en est une commande dans son workflow. */
export const ORDER_STATE = {
Draft: 'draft',
Placed: 'placed',
Paid: 'paid',
Shipped: 'shipped',
Cancelled: 'cancelled',
} as const;
export type OrderState = (typeof ORDER_STATE)[keyof typeof ORDER_STATE];
/** Une commande vue du front : chaque champ est optionnel. */
export interface Order {
id?: string;
reference?: string;
/** Undefined pour un état que ce front ne connaît pas encore. */
state?: OrderState;
customerId?: string;
carrier?: string;
trackingNumber?: string;
placedAt?: Date;
}
/** Ce que donne le formulaire d'expédition. */
export interface OrderShipInput {
carrier: NonNullable<Order['carrier']>;
trackingNumber: NonNullable<Order['trackingNumber']>;
}
Un concept s'identifie par id, quel que soit le
nom que lui donne l'API. Sa position dans un workflow
s'appelle state pour toutes les API, qu'elles
disent status ou place. Une saisie
type ses champs depuis le concept.
3. Le mapper, champ par champ
// libs/vue/order-api/endpoint/orders/get-order/mapToModel.ts
import type { GetOrderResponse } from '@app/order-api-sdk';
import { oneOf, optional, required, toDate } from '@app/api-mapping';
import { ORDER_STATE, type Order } from '@app/front-model/order/Order';
import type { WithRequired } from '@app/front-model/WithRequired';
/** Les champs que cet endpoint donne toujours. */
export type Model = WithRequired<Order, 'id' | 'reference' | 'customerId'>;
/** La commande que renvoie cet endpoint, et que pousse le hub, dans le modèle du front. */
export function mapToModel(data: GetOrderResponse): Model {
return {
id: required(data.id, 'order id'),
reference: required(data.reference, 'order reference'),
// L'API nomme status la position du workflow : le front ne connaît que state.
state: oneOf(ORDER_STATE, data.status),
customerId: required(data.customerId, 'order customerId'),
carrier: optional(data.carrier),
trackingNumber: optional(data.trackingNumber),
placedAt: toDate(data.placedAt),
};
}
Jamais de spread : ...data ferait entrer
dans le modèle les champs JSON-LD (@id,
@type) et chaque champ que l'API ajoute. Champ
par champ, un renommage dans la spec casse ce mapper à la
compilation, pas les écrans.
Les aides de api-mapping restent petites :
optional (null devient
undefined), required (une absence
lève une erreur), toDate.
oneOf rend undefined pour un état
inconnu. toCollection mappe une page Hydra
(member, totalItems,
view) pour list-orders, dont le
type Member est plus étroit.
4. Les clés de requête
// libs/vue/order-api/endpoint/orders/queryKeys.ts
import type { ListOrdersData } from '@app/order-api-sdk';
import { createResourceQueryKeys } from '@app/vue-api-query';
export const orderKeys = createResourceQueryKeys<ListOrdersData['query']>('order', 'orders');
La fabrique rend des clés de la plus large à la plus
étroite : all, lists(),
list(filters), details(),
detail(id). TanStack Query invalide par
préfixe : orderKeys.lists() couvre toutes
les pages, quels que soient leurs filtres. Le nom de l'API
vient en tête, pour que deux API ne se télescopent pas dans
le cache.
Les filtres d'une liste gardent le type du SDK
(ListOrdersData['query']). L'écran passe un
objet littéral que TypeScript vérifie, sans rien importer du
SDK.
5. Le composable de lecture
// libs/vue/order-api/endpoint/orders/get-order/useGetOrder.ts
import { getOrder, type GetOrderResponse } from '@app/order-api-sdk';
import { useMercure, type ApiQueryOptions } from '@app/vue-api-query';
import { useQuery, useQueryClient } from '@tanstack/vue-query';
import { computed, toValue, type MaybeRefOrGetter } from 'vue';
import { orderApiClient } from '../../../client/orderApiClient';
import { orderKeys } from '../queryKeys';
import { mapToModel, type Model } from './mapToModel';
/** Une commande, GET /orders/{id}. live : tenue à jour par le hub Mercure. */
export function useGetOrder(
id: MaybeRefOrGetter<string | undefined>,
options: ApiQueryOptions<Model> & { live?: boolean } = {},
) {
const { enabled = true, live = false, ...queryOptions } = options;
const query = useQuery({
queryKey: computed(() => orderKeys.detail(toValue(id) ?? '')),
...queryOptions,
// L'enabled de l'appelant s'ajoute à ce que le composable attend : un id.
enabled: () => Boolean(toValue(id)) && toValue(enabled),
async queryFn() {
const { data } = await getOrder({
client: orderApiClient,
path: { id: toValue(id) ?? '' },
throwOnError: true,
});
return mapToModel(data);
},
});
if (live) {
const queryClient = useQueryClient();
useMercure(
() => (toValue(id) ? [`https://example.com/orders/${toValue(id)}`] : []),
(payload: GetOrderResponse) => {
// Même représentation que le GET : même mapper, sans aller-retour.
const order = mapToModel(payload);
queryClient.setQueryData(orderKeys.detail(order.id), order);
},
);
}
return query;
}
ApiQueryOptions<Model> reprend toutes les
options de useQuery, sauf queryFn.
Avec throwOnError: true, le SDK rejette sa
promesse sur une erreur HTTP. Pour un préchargement, le
dossier peut aussi exporter un
queryOptions() que le composable réutilise.
useMercure ouvre un
EventSource sur le hub Mercure. Si le service
publie une autre représentation que celle du GET, le
composable invalide plutôt la clé.
useListOrders, lui, invalide
orderKeys.lists() à chaque mise à jour.
6. Une transition, et l'invalidation
// libs/vue/order-api/endpoint/orders/ship-order/mapToRequest.ts
import type { ShipOrderData } from '@app/order-api-sdk';
import type { OrderShipInput } from '@app/front-model/order/Order';
export interface ShipOrderVariables {
id: string;
input: OrderShipInput;
}
/** La requête de la transition, depuis la saisie du formulaire. */
export function mapToRequest({ id, input }: ShipOrderVariables): Omit<ShipOrderData, 'url'> {
return {
path: { id },
body: {
carrier: input.carrier,
trackingNumber: input.trackingNumber,
},
};
}
// libs/vue/order-api/endpoint/orders/ship-order/useShipOrder.ts
import { shipOrder } from '@app/order-api-sdk';
import type { ApiMutationOptions } from '@app/vue-api-query';
import { useMutation, useQueryClient } from '@tanstack/vue-query';
import { orderApiClient } from '../../../client/orderApiClient';
import { orderKeys } from '../queryKeys';
import { mapToModel, type Model } from './mapToModel';
import { mapToRequest, type ShipOrderVariables } from './mapToRequest';
/** La transition ship, PATCH /orders/{id}/ship. Relit ensuite la commande et les listes. */
export function useShipOrder(options: ApiMutationOptions<Model, ShipOrderVariables> = {}) {
const queryClient = useQueryClient();
return useMutation({
onSuccess: (_order, { id }) =>
Promise.all([
queryClient.invalidateQueries({ queryKey: orderKeys.detail(id) }),
queryClient.invalidateQueries({ queryKey: orderKeys.lists() }),
]),
...options,
async mutationFn(variables: ShipOrderVariables) {
const { data } = await shipOrder({
client: orderApiClient,
...mapToRequest(variables),
throwOnError: true,
});
return mapToModel(data);
},
});
}
L'entretien du cache est le onSuccess par
défaut. Il renvoie sa promesse : la mutation reste en
cours jusqu'à la fin des relectures. Une transition qui
touche d'autres ressources ajoute leurs clés ici.
Un écran qui veut réagir au succès passe son callback à
mutate(variables, { onSuccess }). TanStack
Query l'appelle après celui du composable, qui garde
l'entretien du cache. Un onSuccess passé dans
les options, lui, remplacerait cet entretien.
7. L'écran ne connaît que le modèle
<!-- fronts/admin/src/pages/order/PageOrder.vue -->
<template>
<OrderCustomerCard
v-if="order"
:order="order"
/>
<ShipOrderForm @submit="(input) => ship({ id: orderId, input })" />
</template>
<script setup lang="ts">
import { useGetOrder } from '@app/vue-order-api/endpoint/orders/get-order';
import { useShipOrder } from '@app/vue-order-api/endpoint/orders/ship-order';
import OrderCustomerCard from '@/components/OrderCustomerCard.vue';
import ShipOrderForm from '@/components/ShipOrderForm.vue';
const props = defineProps<{ orderId: string }>();
const { data: order } = useGetOrder(() => props.orderId, { live: true });
const { mutate: ship } = useShipOrder();
</script>
OrderCustomerCard déclare
order: WithRequired<Order, 'reference' |
'customerId'>. vue-tsc vérifie ce type contre le
Model de get-order, et l'écran
n'importe rien du SDK.
8. La frontière, vérifiée par le lint
// eslint.config.js (extrait)
export default [
{
files: ['fronts/*/src/**/*.{ts,vue}'],
rules: {
'no-restricted-imports': [
'error',
{
patterns: [
{
regex: '^@app/[a-z-]+-api-sdk(/|$)',
message: 'Screens use an endpoint composable of libs/vue/<api>-api, never the SDK.',
},
{
regex: '^@app/vue-[a-z-]+-api/client(/|$)',
message: 'The API client is reserved for its endpoint composables.',
},
],
},
],
},
},
];
La règle refuse aussi les import type (allowTypeImports
vaut false par défaut) : un écran ne type
rien avec le SDK. Avec eslint-plugin-vue, elle couvre le
<script> des composants monofichiers. Un
grep en CI sur
@app/[a-z-]+-api-sdk double la règle à peu de
frais.
Checklist
- Un dossier par endpoint, nommé d'après son opération, avec son composable et ses mappers.
- Des mappers qui listent chaque champ, sans spread.
-
Un modèle métier du front aux champs optionnels, identifié
par
id, avecstatepour un workflow. -
Des endpoints et des composants qui déclarent leurs champs
avec
WithRequired. - Des clés de requête issues d'une seule fabrique, le nom de l'API en tête.
-
Une mutation qui relit par défaut ce qu'elle rend périmé ;
les callbacks d'un écran passés à
mutate(). -
Aucun import du SDK ni du client hors des libs d'API,
vérifié par
no-restricted-imports. -
vue-tscen CI, pour vérifier les props des templates.
Sources
Versions relevées le 15 novembre 2026 :
@tanstack/vue-query 5.107.1, Vue 3.5.45,
@hey-api/openapi-ts 0.99.0, ESLint 10.15.0, API
Platform 5.0.7.
- TanStack Query (Vue), Query Keys, Reactivity et Query Invalidation : clés, getters réactifs, invalidation par préfixe.
-
TanStack Query (Vue),
Mutations
et
Invalidations from Mutations : callbacks de
mutate(), promesse deonSuccess. -
TanStack Query (Vue),
Query Options,
Parallel Queries
et
client state :
queryOptions,useQueries, état serveur. -
Vue,
Using Vue with TypeScript :
vue-tsc. -
hey-api,
SDK,
TypeScript
et
Migrating : fonctions par opération, option
client, typesDataetResponse,throwOnError. -
ESLint,
no-restricted-imports :
patterns,regex,allowTypeImports. -
API Platform,
OpenAPI
et
classe Model\Operation :
operationIdd'une opération. - Lychen, pull requests 260, 262, 263 et 267 : une mise en œuvre open source de ce que décrit cet article, sur trois API, dans un monorepo moon.
- Lychen, pull request 256 : des écrans branchés sur ces composables, sans import du SDK.