Next 14（App Router）+ tRPC数据更新后UI不刷新问题咨询

问题1：UI无法更新的原因 #

• revalidatePath 仅支持服务器环境：你在客户端组件中调用 revalidatePath 不会生效，该函数只能在服务器组件、Server Action 或 Route Handler 中使用，客户端调用无法触发数据重验证。
• router.refresh 不影响 tRPC 查询缓存：router.refresh 主要用于触发服务器组件的重新渲染，但你的数据通过 tRPC useQuery 获取，tRPC 有独立的客户端缓存机制，router.refresh 不会主动更新这个缓存，因此页面仍显示旧数据。
• 未主动更新 tRPC 查询缓存：后端数据变更后，前端的 useQuery 缓存没有被触发更新，自然不会同步新数据到UI。

问题2：最优数据获取/增改模式 #

1. 后端代码优化：减少冗余查询 #

当前后端先查询旧数据、再更新、最后又查询新数据的流程可以简化，直接利用SQL逻辑操作切换状态，避免两次额外查询：

toggleLock: publicProcedure
  .input(z.object({ docId: z.number() }))
  .mutation(async ({ ctx, input }) => {
    // 直接用 NOT 操作切换 isLocked 状态，无需先查询旧值
    await ctx.db.update(docs)
      .set({ isLocked: sql`NOT ${docs.isLocked}` })
      .where(eq(docs.id, input.docId));

    // 查询并返回更新后的数据
    const docAfter = await ctx.db.query.docs.findFirst({
      where: eq(docs.id, input.docId),
    });

    return docAfter;
  }),

2. 前端缓存更新方案 #

方案一：主动调用 refetch

这是最直接的方式，在 mutation 成功后刷新当前查询的缓存：

export default function Page({ params }: { params: { doc: string } }) {
  const docId = parseInt(params.doc);
  const { data, refetch } = api.docs.getDoc.useQuery({ docId });

  const toggleLock = api.docs.toggleLock.useMutation({
    onSuccess: () => {
      refetch(); // 强制重新获取数据，更新UI
    },
  });

  // ... 组件其余代码
}

方案二：清除指定查询缓存

如果多个组件依赖该文档数据，可以用 invalidateQueries 清除对应缓存，让所有相关组件自动重新获取：

import { useQueryClient } from '@tanstack/react-query';

export default function Page({ params }: { params: { doc: string } }) {
  const queryClient = useQueryClient();
  const docId = parseInt(params.doc);

  const { data } = api.docs.getDoc.useQuery({ docId });

  const toggleLock = api.docs.toggleLock.useMutation({
    onSuccess: () => {
      // 清除指定查询的缓存，触发重新获取
      queryClient.invalidateQueries({ queryKey: ['docs.getDoc', { docId }] });
    },
  });

  // ... 组件其余代码
}

方案三：乐观更新（提升用户体验）

对于状态切换这类场景，可以在发起请求时先更新UI，无需等待后端响应，请求失败再回滚：

import { useQueryClient } from '@tanstack/react-query';

export default function Page({ params }: { params: { doc: string } }) {
  const queryClient = useQueryClient();
  const docId = parseInt(params.doc);

  const { data } = api.docs.getDoc.useQuery({ docId });

  const toggleLock = api.docs.toggleLock.useMutation({
    // 发起请求前更新缓存（乐观更新）
    onMutate: async ({ docId }) => {
      // 暂停当前查询，避免旧数据覆盖
      await queryClient.cancelQueries({ queryKey: ['docs.getDoc', { docId }] });
      
      // 获取当前缓存数据
      const oldDoc = queryClient.getQueryData(['docs.getDoc', { docId }]);
      
      // 预更新缓存状态
      if (oldDoc) {
        queryClient.setQueryData(['docs.getDoc', { docId }], {
          ...oldDoc,
          isLocked: !oldDoc.isLocked,
        });
      }

      return { oldDoc };
    },
    // 请求失败时回滚缓存
    onError: (err, variables, context) => {
      if (context?.oldDoc) {
        queryClient.setQueryData(['docs.getDoc', { variables.docId }], context.oldDoc);
      }
    },
    // 请求完成后确保缓存与后端一致
    onSettled: ({ docId }) => {
      queryClient.invalidateQueries({ queryKey: ['docs.getDoc', { docId }] });
    },
  });

  // ... 组件其余代码
}

3. 组件模式建议 #

如果页面可以拆分，可将数据获取部分放在服务器组件中，用 Server Action 处理变更，此时 revalidatePath 就能正常生效。但如果你依赖 tRPC 客户端hooks的灵活性，优先选择上述缓存更新方案即可。

内容的提问来源于stack exchange，提问作者qq1o9u81