TanStack Query v5 基础：从 Server State 到 Query、Mutation 与缓存

npm install @tanstack/react-query@^5

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import {
  QueryClient,
  QueryClientProvider,
} from "@tanstack/react-query";
import { App } from "./App";

const queryClient = new QueryClient();

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </StrictMode>,
);

// src/todos.ts
export type Todo = {
  id: string;
  title: string;
  completed: boolean;
};

export type TodoFilter = "all" | "open" | "done";

const todoRoot = ["todos"] as const;

export const todoKeys = {
  all: todoRoot,
  list: (filter: TodoFilter) =>
    [...todoRoot, "list", { filter }] as const,
  detail: (id: string) => [...todoRoot, "detail", id] as const,
};

export async function fetchTodos(
  filter: TodoFilter,
  signal?: AbortSignal,
): Promise<Todo[]> {
  const response = await fetch(`/api/todos?filter=${filter}`, { signal });

  // fetch 在收到 HTTP 4xx / 5xx 时不会自动 reject。
  if (!response.ok) {
    throw new Error(`读取 Todo 失败：${response.status}`);
  }

  return response.json() as Promise<Todo[]>;
}

export async function createTodo(input: {
  title: string;
}): Promise<Todo> {
  const response = await fetch("/api/todos", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(input),
  });

  if (!response.ok) {
    throw new Error(`创建 Todo 失败：${response.status}`);
  }

  return response.json() as Promise<Todo>;
}

// src/TodoList.tsx
import { useQuery } from "@tanstack/react-query";
import {
  fetchTodos,
  todoKeys,
  type TodoFilter,
} from "./todos";

export function TodoList({ filter }: { filter: TodoFilter }) {
  const todosQuery = useQuery({
    queryKey: todoKeys.list(filter),
    queryFn: ({ signal }) => fetchTodos(filter, signal),
    staleTime: 30_000,
  });

  if (todosQuery.status === "pending") {
    return <p>正在加载 Todo…</p>;
  }

  if (todosQuery.status === "error") {
    return <p role="alert">加载失败：{todosQuery.error.message}</p>;
  }

  return (
    <>
      {todosQuery.isFetching ? (
        <small>正在同步最新内容…</small>
      ) : null}

      <ul>
        {todosQuery.data.map((todo) => (
          <li key={todo.id}>
            {todo.completed ? "✅" : "⬜️"} {todo.title}
          </li>
        ))}
      </ul>
    </>
  );
}

// src/AddTodoForm.tsx
import { useState, type FormEvent } from "react";
import {
  useMutation,
  useQueryClient,
} from "@tanstack/react-query";
import { createTodo, todoKeys } from "./todos";

export function AddTodoForm() {
  const [title, setTitle] = useState("");
  const queryClient = useQueryClient();

  const createTodoMutation = useMutation({
    mutationFn: createTodo,
    onSuccess: async () => {
      setTitle("");

      await queryClient.invalidateQueries({
        queryKey: todoKeys.all,
      });
    },
  });

  function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();

    const trimmedTitle = title.trim();
    if (!trimmedTitle) return;

    createTodoMutation.mutate({ title: trimmedTitle });
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={title}
        onChange={(event) => setTitle(event.target.value)}
        placeholder="新增一个 Todo"
      />

      <button
        type="submit"
        disabled={createTodoMutation.isPending || !title.trim()}
      >
        {createTodoMutation.isPending ? "创建中…" : "创建"}
      </button>

      {createTodoMutation.isError ? (
        <p role="alert">
          创建失败：{createTodoMutation.error.message}
        </p>
      ) : null}
    </form>
  );
}

await queryClient.invalidateQueries({
  queryKey: todoKeys.all,
});

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30_000,
    },
  },
});

import { useQuery } from "@tanstack/react-query";

type Project = { id: string; name: string };

async function fetchProjects(
  userId: string,
  signal?: AbortSignal,
): Promise<Project[]> {
  const response = await fetch(`/api/users/${userId}/projects`, { signal });

  if (!response.ok) {
    throw new Error(`读取项目失败：${response.status}`);
  }

  return response.json() as Promise<Project[]>;
}

export function ProjectList({ userId }: { userId?: string }) {
  const projectsQuery = useQuery({
    queryKey: ["users", userId, "projects"],
    queryFn: ({ signal }) => {
      if (!userId) {
        throw new Error("userId 尚未准备好");
      }

      return fetchProjects(userId, signal);
    },
    enabled: Boolean(userId),
  });

  if (!userId) {
    return <p>请先选择用户。</p>;
  }

  if (projectsQuery.status === "pending") {
    return <p>正在读取项目…</p>;
  }

  if (projectsQuery.status === "error") {
    return <p role="alert">读取失败：{projectsQuery.error.message}</p>;
  }

  return (
    <ul>
      {projectsQuery.data.map((project) => (
        <li key={project.id}>{project.name}</li>
      ))}
    </ul>
  );
}