用途:规范 Sentry 前端在 static/ 目录下新增或修改调用 API 的 React 代码时的数据获取写法,统一使用 TanStack Query 的 useQuery 配合 apiOptions。
主要能力与约定:显式禁用已废弃的 useApiQuery、getApiQueryData、setApiQueryData。基础用法是 useQuery(apiOptions.as<ResponseType>()('/organizations/$organizationIdOrSlug/endpoint/', {path: {organizationIdOrSlug: organization.slug}, staleTime: 30_000}))。条件获取通过将 path 传为 skipToken 来禁用查询。staleTime 必填,可选 0、毫秒数、Infinity 或 'static'。抽象应建立在 apiOptions 之上而非 useQuery 之上,返回 options 对象以便传给 useQuery、useQueries、prefetchQuery 等。缓存存储的是 {json, headers} 而非仅响应体;apiOptions 默认用 select 提取 .json,但 getQueryData、setQueryData、retry、predicate 收到的是原始 ApiResponse<T>。不要用 api.requestPromise 做 Query,必要时手写 queryFn 应使用 apiFetch。
类型推断:禁止在调用处向 useQuery、useMutation、mutationOptions、queryOptions 等传泛型,应让 TypeScript 从 queryFn/mutationFn 与回调推断。为 mutationFn 参数而非 hook 泛型标注类型;用 fetchMutation<T> 标注返回值;不要将错误泛型写成 RequestError,默认是 Error,需要时用 error instanceof RequestError 做运行时收窄;context 由 onMutate 返回推断,无需单独声明类型。
响应头读取:默认仅选 JSON 体。若需响应头(如分页 Link、X-Hits、X-Max-Hits 计数),用 select: selectJsonWithHeaders 覆盖,此时 data 为 ApiResponse<T>,通过 data?.json 取数据、data?.headers.Link 取分页、data?.headers['X-Hits'] 与 ['X-Max-Hits'] 取计数,且后两者已解析为 number | undefined,无需 parseInt。
适用场景:Sentry 前端中任何调用 API 的 React 查询或变更代码。限制:资料未提供收费、价格、平台与使用步骤等更多信息。