Next.js 13中用Tanstack Query调用GitHub API报错求助

错误本质 #

「No overload matches this call」错误是TypeScript类型不匹配导致的——TanStack Query对queryKey的类型、查询函数的参数/返回值类型有严格校验，当queryKey类型与查询函数参数类型不匹配，或未明确指定泛型让TS正确推断时，就会触发该错误。

分步解决 #

1. 定义仓库数据类型 #

先明确GitHub API返回的仓库结构，定义对应TypeScript接口：

interface GitHubRepo {
  id: number;
  name: string;
  description: string | null;
  html_url: string;
  stargazers_count: number;
  updated_at: string;
}

2. 编写类型对齐的查询函数 #

确保查询函数的参数与queryKey类型一致，通过queryKey解构获取用户名：

const fetchRepos = async ({ queryKey }: { queryKey: [string, string] }) => {
  const [_, username] = queryKey;
  // 调用GitHub API，按更新时间排序、返回6条数据
  const res = await fetch(`https://api.github.com/users/${username}/repos?sort=updated&per_page=6`);
  if (!res.ok) throw new Error('获取仓库列表失败');
  // 断言返回数据类型为定义好的数组
  return res.json() as Promise<GitHubRepo[]>;
};

3. 正确使用useQuery并指定泛型 #

给useQuery明确指定泛型参数，让TS正确推断queryKey和返回值类型，同时处理用户名可能为空的情况：

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

// 假设data.githubUserName是从配置或其他渠道获取的用户名
const { data: repos, isLoading, error } = useQuery<GitHubRepo[], Error, GitHubRepo[], [string, string]>({
  queryKey: ['repos', data.githubUserName],
  queryFn: fetchRepos,
  // 仅当用户名存在时触发查询
  enabled: !!data.githubUserName,
});

4. 渲染仓库列表 #

根据查询状态渲染对应UI：

if (isLoading) return <div>加载中...</div>;
if (error) return <div>加载失败：{error.message}</div>;
if (!repos) return null;

return (
  <div className="repo-grid">
    {repos.map((repo) => (
      <a 
        key={repo.id} 
        href={repo.html_url} 
        target="_blank" 
        rel="noopener noreferrer"
        className="repo-card"
      >
        <h3>{repo.name}</h3>
        {repo.description && <p className="repo-desc">{repo.description}</p>}
        <div className="repo-meta">
          <span>⭐ {repo.stargazers_count}</span>
          <span>更新于：{new Date(repo.updated_at).toLocaleDateString()}</span>
        </div>
      </a>
    ))}
  </div>
);

常见坑点排查 #

• 若data.githubUserName可能为undefined/null，必须添加enabled: !!data.githubUserName，否则queryKey会包含非字符串类型，触发类型错误
• 泛型参数顺序不可错：useQuery<返回数据类型, 错误类型, 最终数据类型(可选), queryKey类型>
• 必须给查询函数返回值添加类型断言，否则TS无法识别返回数据的结构

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