React Query 项目中如何组织查询和命名 query key？

项目里不要把 useQuery 散落在组件里。更稳的做法是按业务域组织：API 函数只负责请求，自定义 Hook 负责暴露查询，query key 工厂负责命名和失效。query key 用数组，从宽到窄写，比如 ['users', 'detail', id]；凡是 queryFn 依赖的参数都必须进 key，否则缓存可能串数据。

追问

为什么不建议直接写字符串 key？

字符串很难表达层级，也不方便批量失效。数组 key 可以让你失效整个用户域、某个详情页，或某个筛选列表。

API 函数和 Hook 为什么要分开？

API 函数可独立测试，也能被预取、SSR、mutation 复用。Hook 里再放 staleTime、enabled、select 等 React Query 配置。

项目结构按 api、hooks 分，还是按 feature 分？

小项目都可以；中大型项目更推荐 feature 分组，例如 features/user/api.ts、queries.ts、keys.ts，修改用户模块时不用跨目录找文件。

命名上最容易踩什么坑？

列表和详情共用一个 key、筛选条件没放进 key、mutation 成功后失效范围太大。这些都会造成脏数据或无意义重请求。

写段代码

ts
export const userKeys = {
  all: ['users'] as const,
  detail: (id: string) => [...userKeys.all, 'detail', id] as const,
};

export function useUser(id: string) {
  return useQuery({
    queryKey: userKeys.detail(id),
    queryFn: () => getUser(id),
    staleTime: 60_000,
  });
}