Daten aus einer API mit Composables
Bau in Vue 3 einen kleinen Fetch-Client und ein generisches Composable für REST-Entitäten: Listen mit Seiten, Suche und Sortierung, einzelne Einträge, Speichern und Löschen, mit Ladezuständen, Fehlern und ohne Race Conditions.
Auf dieser Seite
Quest-Ziele
- fetch in einen kleinen Client mit echten Fehlermeldungen packen
- Ein Composable schreiben, das jede Entität einer REST-API abdeckt
- Eine Liste blättern, durchsuchen und sortieren und bei jeder Änderung neu laden
- Nur die neueste Anfrage zählen lassen, indem ältere abgebrochen werden
- Die Unterschiede zwischen APIs an einer Stelle halten
Fast jede App spricht mit einer API, und fast jede Liste darin braucht dasselbe: einen Ladezustand, Fehlermeldungen, Seiten, eine Suche, Sortierung und Buttons, die speichern oder löschen. In jede Komponente geschrieben ist das viel gleicher Code. Dieses Tutorial packt ihn in ein Composable, das für jede Art von Entität funktioniert, und ein zweites, winziges pro Entität.
Die Beispiel-API ist DummyJSON, eine kostenlose Test-API mit 208 Benutzern. Sie blättert, sucht und sortiert und antwortet auf Anlegen, Ändern und Löschen wie eine echte API, ohne wirklich etwas zu speichern. Der Code baut auf dem Projekt aus Vue mit Vite, Tailwind CSS und PrimeVue auf, aber jedes Vue-3-Projekt mit TypeScript tut es auch.
Ein Client für die API
Zuerst eine dünne Schicht über fetch, die jede Anfrage zu JSON rein, JSON raus macht und jeden Fehlschlag zu einem Fehler mit Meldung:
// An error from the API, with the HTTP status and the API's own message
export class ApiError extends Error {
readonly status: number;
constructor(status: number, message: string) {
super(message);
this.name = 'ApiError';
this.status = status;
}
}
export type Api = ReturnType<typeof createApi>;
// A small wrapper around fetch for one JSON API
export function createApi(baseUrl: string) {
async function request<T>(
method: string,
path: string,
body?: unknown,
signal?: AbortSignal,
): Promise<T> {
const headers: Record<string, string> = { Accept: 'application/json' };
// Only with a body: on a GET, a Content-Type would make the browser
// ask the server for permission first (a CORS preflight)
if (body !== undefined) {
headers['Content-Type'] = 'application/json';
}
// This is the place for an Authorization header, if your API needs one
const response = await fetch(baseUrl + path, {
method,
headers,
body: body === undefined ? undefined : JSON.stringify(body),
signal,
});
if (!response.ok) {
throw new ApiError(response.status, await errorMessage(response));
}
// No Content, for example after a DELETE
if (response.status === 204) {
return undefined as T;
}
return (await response.json()) as T;
}
return {
get: <T>(path: string, signal?: AbortSignal) => request<T>('GET', path, undefined, signal),
post: <T>(path: string, body: unknown) => request<T>('POST', path, body),
put: <T>(path: string, body: unknown) => request<T>('PUT', path, body),
del: <T = void>(path: string) => request<T>('DELETE', path),
};
}
// The API's own message if it sends one, otherwise the HTTP status text
async function errorMessage(response: Response): Promise<string> {
try {
const body = await response.json();
if (typeof body?.message === 'string') {
return body.message;
}
} catch {
// Not JSON
}
return response.statusText || `HTTP ${response.status}`;
}
export const api = createApi('https://dummyjson.com/');fetchschlägt bei HTTP-Fehlern nicht fehl, nur wenn gar keine Antwort kommt. Der Client prüftresponse.okund wirft einenApiErrormit dem Status und der Meldung der API, etwa „User with id '9999' not found“, damit die Seite etwas Besseres zeigen kann als „Fehler“.Der Header Content-Type wird nur mit einem Body gesendet. Bei einem
GETwürde der Browser sonst zuerst eine Preflight-Anfrage schicken, einen Umweg für nichts.Ein 204 No Content hat keinen Body, und
response.json()würde daran scheitern.getnimmt einAbortSignalan, damit sich eine Anfrage abbrechen lässt. Das Composable wird das brauchen.
createApi ist kein Composable: Es hält keinen reaktiven Zustand, also kann ein Client die ganze App bedienen. Darum beginnt sein Name nicht mit use.
Der direkte Weg
Für eine erste Liste reicht der Client allein:
<script setup lang="ts">
import { onMounted, ref } from 'vue';
import { api } from '../api';
type User = { id: number; firstName: string; lastName: string; email: string };
const users = ref<User[]>([]);
onMounted(async () => {
const response = await api.get<{ users: User[] }>('users?limit=10');
users.value = response.users;
});
</script>
<template>
<ul>
<li v-for="user in users" :key="user.id">
{{ user.firstName }} {{ user.lastName }}, {{ user.email }}
</li>
</ul>
</template>Das funktioniert, aber es fehlt viel: Nichts zeigt, dass geladen wird, eine fehlgeschlagene Anfrage endet als unbehandelter Fehler in der Konsole, es gibt nur eine Seite, und die nächste Liste wiederholt alles. Darum kümmert sich ein Composable.
Ein Composable für jede Entität
useEntity hält alles, was eine Art von Entität braucht: eine Seite der Liste, einen einzelnen Eintrag, das Speichern und die Zustände dazu. Was sich von API zu API unterscheidet, etwa die Adressen und die Form der Liste, kommt als config herein:
import { computed, ref, shallowReactive, shallowRef, type Ref } from 'vue';
import type { Api } from '../api';
// Which part of the list to load
export type ListQuery<T> = {
page: number;
limit: number;
search: string;
sortBy: keyof T | null;
order: 'asc' | 'desc';
};
// One page of the list, and how many items there are in total
export type ListPage<T> = { items: T[]; total: number };
// Where an entity lives in the API. APIs differ most in these.
export type EntityConfig<T, TList> = {
listUrl: (query: ListQuery<T>) => string;
itemUrl: (id: number) => string;
createUrl: string;
toPage: (response: TList) => ListPage<T>;
};
export function useEntity<T extends { id: number }, TList>(
api: Api,
config: EntityConfig<T, TList>,
) {
const query = shallowReactive<ListQuery<T>>({
page: 1,
limit: 10,
search: '',
sortBy: null,
order: 'asc',
});
const items = shallowRef<T[]>([]);
const total = ref(0);
const pageCount = computed(() => Math.max(1, Math.ceil(total.value / query.limit)));
const loadingList = ref(false);
const item = shallowRef<T | null>(null);
const loadingItem = ref(false);
const saves = ref(0);
const saving = computed(() => saves.value > 0);
const error = shallowRef<Error | null>(null);
// Runs loads so that only the newest one counts: a new load aborts the one
// before, and only the newest one ends the loading state.
function latestOnly(loading: Ref<boolean>) {
let current: AbortController | null = null;
return async (load: (signal: AbortSignal) => Promise<void>) => {
current?.abort();
const controller = (current = new AbortController());
loading.value = true;
error.value = null;
try {
await load(controller.signal);
} catch (caught) {
if (!controller.signal.aborted) {
error.value = toError(caught);
}
} finally {
if (current === controller) {
loading.value = false;
}
}
};
}
const loadList = latestOnly(loadingList);
const loadItem = latestOnly(loadingItem);
function fetchList() {
return loadList(async (signal) => {
const response = await api.get<TList>(config.listUrl(query), signal);
signal.throwIfAborted();
const page = config.toPage(response);
items.value = page.items;
total.value = page.total;
});
}
function fetchItem(id: number) {
return loadItem(async (signal) => {
const response = await api.get<T>(config.itemUrl(id), signal);
signal.throwIfAborted();
item.value = response;
});
}
// Runs a create, update or delete. Returns its result, or null if it failed.
async function save<R>(task: () => Promise<R>): Promise<R | null> {
saves.value += 1;
error.value = null;
try {
return await task();
} catch (caught) {
error.value = toError(caught);
return null;
} finally {
saves.value -= 1;
}
}
function create(data: Omit<T, 'id'>) {
return save(async () => {
item.value = await api.post<T>(config.createUrl, data);
return item.value;
});
}
function update(id: number, data: Partial<T>) {
return save(async () => {
const updated = await api.put<T>(config.itemUrl(id), data);
item.value = updated;
items.value = items.value.map((entry) => (entry.id === id ? updated : entry));
return updated;
});
}
function remove(id: number) {
return save(async () => {
await api.del(config.itemUrl(id));
if (item.value?.id === id) {
item.value = null;
}
items.value = items.value.filter((entry) => entry.id !== id);
total.value -= 1;
return true;
});
}
return {
query,
items,
total,
pageCount,
loadingList,
fetchList,
item,
loadingItem,
fetchItem,
saving,
create,
update,
remove,
error,
};
}
function toError(caught: unknown): Error {
return caught instanceof Error ? caught : new Error(String(caught));
}Stück für Stück:
querybeschreibt, welcher Teil der Liste geladen wird: Seite, Seitengröße, Suche und Sortierung. Es ist einshallowReactive-Objekt, damit eine Komponentequery.pagedirekt ändern und das Ganze beobachten kann. Flach reicht, weil die Werte einfache Strings und Zahlen sind, und so bleibtsortByals Feld vonTtypisiert.itemsunditemsindshallowRefs. Die Daten der API werden immer als Ganzes ersetzt, nie im Inneren geändert, also muss Vue nicht jeden Benutzer tief reaktiv machen.latestOnlybehebt das klassische Wettrennen: Jemand klickt dreimal auf Next, drei Anfragen laufen, und die langsamste gewinnt, egal für welche Seite sie war. Hier bricht ein neuer Ladevorgang den vorherigen ab. Eine abgebrochene Anfrage ist kein Fehler, und nur der neueste Ladevorgang beendet den Ladezustand.signal.throwIfAborted()fängt den seltenen Fall einer Antwort ab, die genau dann ankommt, wenn eine neuere Anfrage startet.saveumschließt Anlegen, Ändern und Löschen: Es setztsavingunderrorund gibt das Ergebnis zurück, odernull, wenn es fehlschlug, damit der Aufrufer keintrybraucht.savingzählt laufende Speichervorgänge, statt ein einfacher Boolean zu sein, damit zwei gleichzeitige es nicht zu früh beenden.Nach einem Ändern oder Löschen zeigt die Liste die Änderung sofort, ohne neu zu laden.
Ein Composable pro Entität
Für Benutzer bleibt nur noch zu sagen, wo sie liegen und wie DummyJSONs Listen aussehen:
import { api } from '../api';
import { useEntity } from './useEntity';
export type User = {
id: number;
firstName: string;
lastName: string;
email: string;
};
// What DummyJSON sends for a list of users
type UserList = { users: User[]; total: number };
export function useUsers() {
return useEntity<User, UserList>(api, {
listUrl: ({ page, limit, search, sortBy, order }) => {
const params = new URLSearchParams({
limit: String(limit),
skip: String((page - 1) * limit),
select: 'firstName,lastName,email',
});
if (sortBy) {
params.set('sortBy', sortBy);
params.set('order', order);
}
// DummyJSON searches at an address of its own
if (search) {
params.set('q', search);
return `users/search?${params}`;
}
return `users?${params}`;
},
itemUrl: (id) => `users/${id}`,
createUrl: 'users/add',
toPage: (response) => ({ items: response.users, total: response.total }),
});
}Aus den Seiten werden DummyJSONs limit und skip, select fragt nur die Felder ab, die die Liste zeigt, und die Suche hat eine eigene Adresse. Eine andere API bräuchte nur ein anderes listUrl und toPage; useEntity bleibt gleich. Ein useProducts oder usePosts ist genauso kurz.
Die Liste
Die Komponente beschreibt jetzt nur noch die Seite:
<script setup lang="ts">
import { onWatcherCleanup, ref, watch } from 'vue';
import { useUsers, type User } from '../composables/useUsers';
const { query, items: users, total, pageCount, loadingList, fetchList, saving, remove, error } =
useUsers();
// Loads the list now, and again whenever the page, search or sorting changes
watch(query, fetchList, { immediate: true });
// Searches once typing pauses for 300 ms, starting on the first page
const search = ref('');
watch(search, (value) => {
const timer = setTimeout(() => {
query.search = value.trim();
query.page = 1;
}, 300);
onWatcherCleanup(() => clearTimeout(timer));
});
// A second click on the same column turns the order around
function sortBy(field: keyof User) {
query.order = query.sortBy === field && query.order === 'asc' ? 'desc' : 'asc';
query.sortBy = field;
}
</script>
<template>
<section>
<input v-model="search" type="search" placeholder="Search users" />
<p v-if="error" role="alert">{{ error.message }}</p>
<table :aria-busy="loadingList">
<thead>
<tr>
<th><button @click="sortBy('firstName')">First name</button></th>
<th><button @click="sortBy('lastName')">Last name</button></th>
<th><button @click="sortBy('email')">Email</button></th>
<th></th>
</tr>
</thead>
<tbody>
<tr v-for="user in users" :key="user.id">
<td>{{ user.firstName }}</td>
<td>{{ user.lastName }}</td>
<td>{{ user.email }}</td>
<td><button :disabled="saving" @click="remove(user.id)">Delete</button></td>
</tr>
</tbody>
</table>
<p v-if="loadingList">Loading...</p>
<p v-else-if="users.length === 0">No users found.</p>
<nav>
<button :disabled="query.page <= 1" @click="query.page--">Previous</button>
Page {{ query.page }} of {{ pageCount }}, {{ total }} users
<button :disabled="query.page >= pageCount" @click="query.page++">Next</button>
</nav>
</section>
</template>watch(query, fetchList, { immediate: true })lädt die erste Seite sofort und lädt neu, sobald sich Seite, Suche oder Sortierung ändern. Die Buttons ändern nurquery.Das Suchfeld schreibt nicht bei jeder Taste in
query. Es wartet, bis die Eingabe pausiert: Jede Änderung startet einen Timer, undonWatcherCleanupbricht den vorherigen ab. Eine Suche beginnt wieder auf Seite 1.Destrukturieren mit neuen Namen, wie bei
items: users, gibt den Teilen die Namen, die zur Komponente passen. Die Refs bleiben reaktiv.
Klick ein paarmal schnell auf Next: Die Liste landet auf der richtigen Seite, und kein Fehler erscheint. Such nach „john“, sortiere zweimal nach Vornamen und lösche eine Zeile: DummyJSON bestätigt das Löschen, und die Zeile verschwindet, auch wenn der Benutzer nach dem Neuladen der Seite wieder da ist.
Anlegen und das Ergebnis des Speicherns
create, update und remove geben das Ergebnis zurück, oder null, wenn es fehlschlug:
const { create, error } = useUsers();
const user = await create({ firstName: 'Ada', lastName: 'Lovelace', email: 'ada@example.com' });
if (user) {
console.log('Created with id', user.id);
} else {
console.log('Failed:', error.value?.message);
}Die Dateien dieses Tutorials:
src/
├── api.ts
├── components/
│ └── UserList.vue
└── composables/
├── useEntity.ts
└── useUsers.tsUm den Client je nach Umgebung auf einen anderen Server zu richten, nimm eine Vite-Umgebungsvariable: createApi(import.meta.env.VITE_API_URL), mit VITE_API_URL=https://api.example.com/ in .env. Die Basisadresse endet mit einem Schrägstrich, und Pfade beginnen ohne.
Kommentare
Die Kommentare sind GitHub Discussions: Zum Schreiben mit GitHub anmelden.
Die Kommentare kommen über giscus von GitHub. Beim Laden gehen deine IP-Adresse an giscus.app und GitHub.