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.

Le contrat d'API s'arrête aux mappers : les écrans ne voient que le modèle du front Écrans et composants importent un composable, typent avec Order et WithRequired le modèle du front frontière : pas de SDK au-dessus endpoint/orders/get-order/ useGetOrder.ts clé de cache, options, invalidation, Mercure mapToModel.ts (et mapToRequest.ts pour une écriture) champ par champ, jamais de spread les types du SDK SDK généré (hey-api) getOrder(), GetOrderResponse, ShipOrderData HTTP, JSON-LD API du service order (API Platform) À éviter : un écran qui appelle le SDK, refusé par no-restricted-imports SDK régénéré : un champ renommé casse les mappers à la compilation, pas les écrans

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, avec state pour 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-tsc en 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.