1
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
2

3
// 定义 API 钩子
4
function useUsers() {
5
  return useQuery({
6
    queryKey: ['users'],
7
    queryFn: () => fetch('/api/users').then(r => r.json()),
8
    // 2026 年的新特性：自动背景刷新
9
    refetchInterval: 30_000,
10
    // 乐观更新
11
    staleTime: 10_000,
12
    // 错误重试
13
    retry: 3,
14
    retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 10000),
15
  });
16
}
17

18
function useUpdateUser() {
19
  const queryClient = useQueryClient();
20

21
  return useMutation({
22
    mutationFn: (user: { id: string; name: string }) =>
23
      fetch(`/api/users/${user.id}`, {
24
        method: 'PUT',
25
        body: JSON.stringify(user),
26
      }),
27
    // 乐观更新
28
    onMutate: async (newUser) => {
29
      await queryClient.cancelQueries({ queryKey: ['users'] });
30
      const previous = queryClient.getQueryData(['users']);
31
      queryClient.setQueryData(['users'], (old: any[]) =>
32
        old.map(u => u.id === newUser.id ? { ...u, ...newUser } : u)
33
      );
34
      return { previous };
35
    },
36
    onError: (err, newUser, context) => {
37
      // 回滚
38
      queryClient.setQueryData(['users'], context?.previous);
39
    },
40
    onSettled: () => {
41
      queryClient.invalidateQueries({ queryKey: ['users'] });
42
    },
43
  });
44
}

1
import { createRouter, Route, Link, useNavigate } from '@tanstack/react-router';
2

3
// 定义路由树
4
const rootRoute = new Route({ getParentRoute: () => undefined, component: App });
5

6
const indexRoute = new Route({
7
  getParentRoute: () => rootRoute,
8
  path: '/',
9
  component: HomePage,
10
});
11

12
const userRoute = new Route({
13
  getParentRoute: () => rootRoute,
14
  path: '/users/$userId',
15
  // 路由级别的数据加载
16
  loader: async ({ params: { userId } }) => {
17
    const user = await fetch(`/api/users/${userId}`).then(r => r.json());
18
    return { user };
19
  },
20
  component: ({ useLoaderData }) => {
21
    const { user } = useLoaderData();
22
    return <div>用户：{user.name}</div>;
23
  },
24
});
25

26
const router = createRouter({
27
  routeTree: rootRoute.addChildren([indexRoute, userRoute]),
28
});
29

30
// 类型安全的导航
31
function UserCard({ userId }: { userId: string }) {
32
  const navigate = useNavigate();
33

34
  return (
35
    <button onClick={() => navigate({
36
      to: '/users/$userId',
37
      params: { userId },  // 类型必须是 string
38
      search: { tab: 'profile' as const },  // 类型安全的 search params
39
    })}>
40
      查看详情
41
    </button>
42
  );
43
}

1
import { useForm } from '@tanstack/react-form';
2
import { z } from 'zod';
3

4
const registrationSchema = z.object({
5
  email: z.string().email('请输入有效邮箱'),
6
  password: z.string()
7
    .min(8, '密码至少 8 个字符')
8
    .regex(/[A-Z]/, '需要至少一个大写字母')
9
    .regex(/[0-9]/, '需要至少一个数字'),
10
  confirmPassword: z.string(),
11
}).refine(d => d.password === d.confirmPassword, {
12
  message: '两次密码不一致',
13
  path: ['confirmPassword'],
14
});
15

16
function RegistrationForm() {
17
  const form = useForm({
18
    defaultValues: {
19
      email: '',
20
      password: '',
21
      confirmPassword: '',
22
    },
23
    validators: {
24
      // 字段级验证（实时）
25
      onChange: registrationSchema,
26
      // 提交时验证
27
      onSubmit: registrationSchema,
28
    },
29
    onSubmit: async (values) => {
30
      await fetch('/api/register', {
31
        method: 'POST',
32
        body: JSON.stringify(values),
33
      });
34
    },
35
  });
36

37
  return (
38
    <form.Subscribe selector={(state) => state.errors}>
39
      {(errors) => (
40
        <form onSubmit={form.handleSubmit} className="space-y-4">
41
          <form.Field name="email">
42
            {(field) => (
43
              <div>
44
                <label>邮箱</label>
45
                <input
46
                  value={field.state.value}
47
                  onChange={e => field.handleChange(e.target.value)}
48
                />
49
                {field.state.meta.errors && (
50
                  <p className="text-red-500">{field.state.meta.errors[0]}</p>
51
                )}
52
              </div>
53
            )}
54
          </form.Field>
55
          {/* ...其他字段... */}
56
          <button type="submit">
57
            {form.state.isSubmitting ? '提交中...' : '注册'}
58
          </button>
59
        </form>
60
      )}
61
    </form.Subscribe>
62
  );
63
}

1
import { createAIProvider } from '@tanstack/ai';
2

3
// 配置 AI 提供商
4
const ai = createAIProvider({
5
  provider: 'openai',   // 也支持 claude, gemini, 或自部署模型
6
  model: 'gpt-5.5',
7
  apiKey: process.env.AI_API_KEY,
8
});
9

10
// 流式生成 AI 内容
11
async function generateInsights(userData: UserData) {
12
  const stream = await ai.stream({
13
    messages: [
14
      {
15
        role: 'system',
16
        content: '你是一个数据分析助手，基于用户数据生成洞察报告。',
17
      },
18
      {
19
        role: 'user',
20
        content: `分析以下用户数据，给出 3 个关键洞察：${JSON.stringify(userData)}`,
21
      },
22
    ],
23
    temperature: 0.3,
24
    maxTokens: 1000,
25
  });
26

27
  for await (const chunk of stream) {
28
    // 逐 token 流式更新 UI
29
    updateUI(chunk.content);
30
  }
31
}

1
// v5 的写法（旧 API）
2
import { useQuery } from '@tanstack/react-query';
3

4
function usePosts() {
5
  return useQuery('posts', fetchPosts, {
6
    staleTime: 5000,
7
    refetchOnWindowFocus: true,
8
  });
9
}
10

11
// v6 的写法（新 API——更类型安全）
12
import { queryOptions } from '@tanstack/react-query';
13

14
const postsOptions = queryOptions({
15
  queryKey: ['posts'],
16
  queryFn: fetchPosts,
17
  staleTime: 5000,
18
  refetchOnWindowFocus: true,
19
});
20

21
function usePosts() {
22
  return useQuery(postsOptions);
23
}
24

25
// 在路由中预加载数据（配合 TanStack Router）
26
const postsRoute = new Route({
27
  getParentRoute: () => rootRoute,
28
  path: '/posts',
29
  loader: async () => {
30
    const queryClient = getQueryClient();
31
    return queryClient.ensureQueryData(postsOptions);
32
  },
33
});

1
// React 项目中使用
2
import { useQuery } from '@tanstack/react-query';
3
import { userListOptions } from '@shared/api';
4

5
export function UserList() {
6
  const { data } = useQuery(userListOptions());
7
  return <UserTable data={data} />;
8
}

1
<!-- Vue 项目中使用 -->
2
<script setup lang="ts">
3
import { useQuery } from '@tanstack/vue-query';
4
import { userListOptions } from '@shared/api';
5

6
const { data } = useQuery(userListOptions());
7
</script>
8

9
<template>
10
  <UserTable :data="data" />
11
</template>