@qiaopeng/tanstack-query-plus 0.5.7 → 0.5.8

package/README.md

@@ -291,18 +291,30 @@ function App() {
   queries: {
     staleTime: 30000,
     gcTime: 600000,
-    retry: defaultQueryRetryStrategy,
+    retry: defaultQueryRetryStrategy,  // 智能重试：4XX不重试，5XX最多1次
     retryDelay: exponentialBackoff,
     refetchOnWindowFocus: true,
     refetchOnReconnect: true,
   },
   mutations: {
-    retry: 0,
+    retry: 0,  // Mutation 默认不重试
     gcTime: 600000,
   }
 }
 ```
 
+**重试策略说明：**
+
+- **Query 重试**（`defaultQueryRetryStrategy`）：
+  - 4XX 客户端错误：不重试（客户端问题，重试无意义）
+  - 5XX 服务端错误：最多重试 1 次（避免过度重试）
+  - 网络错误：最多重试 2 次
+  
+- **Mutation 重试**（`defaultMutationRetryStrategy`）：
+  - 4XX 客户端错误：不重试
+  - 5XX 服务端错误：不重试（避免重复操作）
+  - 网络错误：最多重试 1 次
+
 这些值是经过实践验证的最佳实践，适合大多数应用场景。
 
 ### 3.4 根据环境选择配置
@@ -322,10 +334,58 @@ const queryClient = new QueryClient({ defaultOptions: config })
 | 配置项 | development | production | test |
 |--------|-------------|------------|------|
 | staleTime | 0 | 10 分钟 | 0 |
-| retry | 1 | 3 | 0 |
+| retry (Query) | 智能重试* | 智能重试* | 0 |
+| retry (Mutation) | 0 | 0 | 0 |
 | refetchOnWindowFocus | true | true | false |
 
-### 3.5 添加 DevTools（开发环境）
+*智能重试：4XX 不重试，5XX 最多 1 次，网络错误最多 2 次
+
+### 3.5 自定义重试策略
+
+如果默认的重试策略不满足你的需求，可以使用 `createSafeRetryStrategy` 和 `createErrorSafeConfig` 来自定义：
+
+```tsx
+import { 
+  createSafeRetryStrategy, 
+  createErrorSafeConfig 
+} from '@qiaopeng/tanstack-query-plus/core'
+
+// 方式一：创建自定义重试策略
+const customRetry = createSafeRetryStrategy(
+  0,  // 4XX 错误重试次数
+  1,  // 5XX 错误重试次数
+  2   // 其他错误重试次数
+)
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: customRetry,
+    }
+  }
+})
+
+// 方式二：使用错误安全配置（推荐）
+const errorSafeConfig = createErrorSafeConfig({
+  maxRetries4xx: 0,       // 4XX 不重试
+  maxRetries5xx: 0,       // 5XX 不重试（严格模式）
+  maxRetriesOther: 1,     // 网络错误最多 1 次
+  disableFocus: false,    // 是否禁用窗口聚焦时 refetch
+  disableReconnect: false // 是否禁用重连时 refetch
+})
+
+const queryClient = new QueryClient({
+  defaultOptions: errorSafeConfig
+})
+```
+
+**使用场景：**
+
+1. **严格模式**：完全禁用 4XX/5XX 重试，避免不必要的请求
+2. **宽松模式**：增加重试次数，适合网络不稳定的环境
+3. **自定义场景**：根据业务需求精确控制重试行为
+
+### 3.6 添加 DevTools（开发环境）
 
 在开发环境中，强烈建议添加 DevTools 来调试查询状态：
 
@@ -3902,8 +3962,8 @@ useEnhancedQuery({
   - `QueryClient`、`QueryClientProvider`、`useQueryClient`、`skipToken`、`useIsMutating`（直接再导出原生 API）
 
 - `@qiaopeng/tanstack-query-plus/core`
-  - 配置：`GLOBAL_QUERY_CONFIG`、`createCustomConfig`、`DEFAULT_STALE_TIME`、`DEFAULT_GC_TIME`
-  - 重试：`defaultQueryRetryStrategy`、`defaultMutationRetryStrategy`、`exponentialBackoff`
+  - 配置：`GLOBAL_QUERY_CONFIG`、`createCustomConfig`、`createErrorSafeConfig`、`DEFAULT_STALE_TIME`、`DEFAULT_GC_TIME`
+  - 重试：`defaultQueryRetryStrategy`、`defaultMutationRetryStrategy`、`createSafeRetryStrategy`、`exponentialBackoff`
   - 环境：`isDev`、`isProd`、`isTest`
   - DevTools：`ReactQueryDevtools`、`isDevToolsEnabled`、`createDevToolsConfig`（src/core/devtools.ts:28）
   - 焦点管理：`focusManager`、`getSmartFocusManager`、`pauseFocusManager`、`resumeFocusManager`

package/dist/core/config.d.ts

@@ -11,7 +11,19 @@ export declare const TIME_CONSTANTS: {
 };
 export declare const DEFAULT_STALE_TIME: number;
 export declare const DEFAULT_GC_TIME: number;
+/**
+ * 默认 Query 重试策略
+ * - 4XX 客户端错误：不重试（客户端问题，重试无意义）
+ * - 5XX 服务端错误：最多重试 1 次（避免过度重试）
+ * - 其他错误（网络等）：最多重试 2 次
+ */
 export declare function defaultQueryRetryStrategy(failureCount: number, error: unknown): boolean;
+/**
+ * 默认 Mutation 重试策略
+ * - 4XX 客户端错误：不重试
+ * - 5XX 服务端错误：不重试（Mutation 更谨慎，避免重复操作）
+ * - 其他错误：最多重试 1 次
+ */
 export declare function defaultMutationRetryStrategy(failureCount: number, error: unknown): boolean;
 export declare function exponentialBackoff(attemptIndex: number): number;
 export declare const DEFAULT_QUERY_CONFIG: DefaultOptions["queries"];
@@ -33,9 +45,32 @@ export declare function validateConfig(config: DefaultOptions): {
     warnings: string[];
 };
 export declare function ensureBestPractices(config: DefaultOptions): DefaultOptions;
-export declare function createSafeRetryStrategy(maxRetries500?: number, maxRetriesOther?: number): (failureCount: number, error: unknown) => boolean;
+/**
+ * 创建安全的重试策略
+ * @param maxRetries4xx - 4XX 错误最大重试次数（默认 0，不重试）
+ * @param maxRetries5xx - 5XX 错误最大重试次数（默认 0，不重试）
+ * @param maxRetriesOther - 其他错误最大重试次数（默认 1）
+ */
+export declare function createSafeRetryStrategy(maxRetries4xx?: number, maxRetries5xx?: number, maxRetriesOther?: number): (failureCount: number, error: unknown) => boolean;
+/**
+ * 创建错误安全配置
+ * 适用于需要严格控制重试和 refetch 行为的场景
+ *
+ * @example
+ * ```typescript
+ * // 完全禁用重试
+ * const config = createErrorSafeConfig({
+ *   maxRetries4xx: 0,
+ *   maxRetries5xx: 0,
+ *   maxRetriesOther: 0,
+ *   disableFocus: true,
+ *   disableReconnect: true
+ * });
+ * ```
+ */
 export declare function createErrorSafeConfig(options?: {
-    maxRetries500?: number;
+    maxRetries4xx?: number;
+    maxRetries5xx?: number;
     maxRetriesOther?: number;
     disableFocus?: boolean;
     disableReconnect?: boolean;

package/dist/core/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D,eAAO,MAAM,cAAc;;;;;;;;;CASjB,CAAC;AAEX,eAAO,MAAM,kBAAkB,QAAgC,CAAC;AAChE,eAAO,MAAM,eAAe,QAA6B,CAAC;AAO1D,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAIvF;AAED,wBAAgB,4BAA4B,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAK1F;AAED,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,eAAO,MAAM,oBAAoB,EAAE,cAAc,CAAC,SAAS,CAQ1D,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,cAAc,CAAC,WAAW,CAI/D,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,cAGjC,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,cAAc,CAAC,WAAW,CAInE,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,cAYhC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAY/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAa/B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,cAW7B,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,aAAa,GAAG,YAAY,GAAG,MAAM,GAAG,cAAc,CAwBjG;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAWrF;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAQxG;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CA2B/F;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAkC1E;AAED,wBAAgB,uBAAuB,CAAC,aAAa,GAAE,MAAU,EAAE,eAAe,GAAE,MAAU,IACpF,cAAc,MAAM,EAAE,OAAO,OAAO,KAAG,OAAO,CAMvD;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE;IAC7C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,0BAA0B,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,KAAK,MAAM,GAAG,KAAK,CAAC,CAAC;IACtF,SAAS,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CAChC,GAAG,cAAc,CA6BtB"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D,eAAO,MAAM,cAAc;;;;;;;;;CASjB,CAAC;AAEX,eAAO,MAAM,kBAAkB,QAAgC,CAAC;AAChE,eAAO,MAAM,eAAe,QAA6B,CAAC;AAkC1D;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAevF;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAe1F;AAED,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,eAAO,MAAM,oBAAoB,EAAE,cAAc,CAAC,SAAS,CAQ1D,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,cAAc,CAAC,WAAW,CAI/D,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,cAGjC,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,cAAc,CAAC,WAAW,CAInE,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,cAYhC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAY/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAa/B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,cAW7B,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,aAAa,GAAG,YAAY,GAAG,MAAM,GAAG,cAAc,CAwBjG;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAWrF;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAQxG;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CA2B/F;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAkC1E;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,GAAE,MAAU,EACzB,aAAa,GAAE,MAAU,EACzB,eAAe,GAAE,MAAU,IAEnB,cAAc,MAAM,EAAE,OAAO,OAAO,KAAG,OAAO,CAgBvD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE;IAC7C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,0BAA0B,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,KAAK,MAAM,GAAG,KAAK,CAAC,CAAC;IACtF,SAAS,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CAChC,GAAG,cAAc,CAsCtB"}

package/dist/core/config.js

@@ -11,19 +11,65 @@ export const TIME_CONSTANTS = {
 };
 export const DEFAULT_STALE_TIME = TIME_CONSTANTS.THIRTY_SECONDS;
 export const DEFAULT_GC_TIME = TIME_CONSTANTS.TEN_MINUTES;
+/**
+ * 从错误对象中提取 HTTP 状态码
+ * 兼容多种错误对象结构：axios、fetch、自定义等
+ */
+function extractHttpStatus(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const err = error;
+    // 直接在错误对象上的 status
+    if (typeof err.status === "number")
+        return err.status;
+    if (typeof err.statusCode === "number")
+        return err.statusCode;
+    // 在 response 对象中的 status (axios 等)
+    if (err.response) {
+        if (typeof err.response.status === "number")
+            return err.response.status;
+        if (typeof err.response.statusCode === "number")
+            return err.response.statusCode;
+    }
+    return undefined;
+}
+/**
+ * 默认 Query 重试策略
+ * - 4XX 客户端错误：不重试（客户端问题，重试无意义）
+ * - 5XX 服务端错误：最多重试 1 次（避免过度重试）
+ * - 其他错误（网络等）：最多重试 2 次
+ */
 export function defaultQueryRetryStrategy(failureCount, error) {
-    const httpError = error;
-    if (httpError?.status && httpError.status >= 400 && httpError.status < 600)
-        return failureCount < 2;
+    const status = extractHttpStatus(error);
+    // 4XX 客户端错误：不重试
+    if (status && status >= 400 && status < 500) {
+        return false;
+    }
+    // 5XX 服务端错误：最多重试 1 次
+    if (status && status >= 500 && status < 600) {
+        return failureCount < 1;
+    }
+    // 其他错误（网络错误等）：最多重试 2 次
     return failureCount < 2;
 }
+/**
+ * 默认 Mutation 重试策略
+ * - 4XX 客户端错误：不重试
+ * - 5XX 服务端错误：不重试（Mutation 更谨慎，避免重复操作）
+ * - 其他错误：最多重试 1 次
+ */
 export function defaultMutationRetryStrategy(failureCount, error) {
-    const httpError = error;
-    if (httpError?.status && httpError.status >= 400 && httpError.status < 500)
+    const status = extractHttpStatus(error);
+    // 4XX 客户端错误：不重试
+    if (status && status >= 400 && status < 500) {
         return false;
-    if (httpError?.status && httpError.status >= 500)
-        return failureCount < 2;
-    return failureCount < 2;
+    }
+    // 5XX 服务端错误：不重试（Mutation 避免重复操作）
+    if (status && status >= 500 && status < 600) {
+        return false;
+    }
+    // 其他错误（网络错误等）：最多重试 1 次
+    return failureCount < 1;
 }
 export function exponentialBackoff(attemptIndex) {
     return Math.min(1000 * 2 ** attemptIndex, 30000);
@@ -209,21 +255,48 @@ export function ensureBestPractices(config) {
     }
     return result;
 }
-export function createSafeRetryStrategy(maxRetries500 = 1, maxRetriesOther = 2) {
+/**
+ * 创建安全的重试策略
+ * @param maxRetries4xx - 4XX 错误最大重试次数（默认 0，不重试）
+ * @param maxRetries5xx - 5XX 错误最大重试次数（默认 0，不重试）
+ * @param maxRetriesOther - 其他错误最大重试次数（默认 1）
+ */
+export function createSafeRetryStrategy(maxRetries4xx = 0, maxRetries5xx = 0, maxRetriesOther = 1) {
     return (failureCount, error) => {
-        const httpError = error;
-        if (httpError?.status && httpError.status >= 400 && httpError.status < 500)
-            return false;
-        if (httpError?.status && httpError.status >= 500)
-            return failureCount < maxRetries500;
+        const status = extractHttpStatus(error);
+        // 4XX 客户端错误
+        if (status && status >= 400 && status < 500) {
+            return failureCount < maxRetries4xx;
+        }
+        // 5XX 服务端错误
+        if (status && status >= 500 && status < 600) {
+            return failureCount < maxRetries5xx;
+        }
+        // 其他错误（网络等）
         return failureCount < maxRetriesOther;
     };
 }
+/**
+ * 创建错误安全配置
+ * 适用于需要严格控制重试和 refetch 行为的场景
+ *
+ * @example
+ * ```typescript
+ * // 完全禁用重试
+ * const config = createErrorSafeConfig({
+ *   maxRetries4xx: 0,
+ *   maxRetries5xx: 0,
+ *   maxRetriesOther: 0,
+ *   disableFocus: true,
+ *   disableReconnect: true
+ * });
+ * ```
+ */
 export function createErrorSafeConfig(options = {}) {
-    const { maxRetries500 = 1, maxRetriesOther = 2, disableFocus = false, disableReconnect = false, conditionalRefetchInterval, overrides } = options;
+    const { maxRetries4xx = 0, maxRetries5xx = 0, maxRetriesOther = 1, disableFocus = false, disableReconnect = false, conditionalRefetchInterval, overrides } = options;
     const queries = {
         ...DEFAULT_QUERY_CONFIG,
-        retry: createSafeRetryStrategy(maxRetries500, maxRetriesOther),
+        retry: createSafeRetryStrategy(maxRetries4xx, maxRetries5xx, maxRetriesOther),
         retryDelay: exponentialBackoff,
         refetchOnWindowFocus: disableFocus ? false : true,
         refetchOnReconnect: disableReconnect ? false : true
@@ -236,7 +309,10 @@ export function createErrorSafeConfig(options = {}) {
             queries.refetchInterval = conditionalRefetchInterval;
         }
     }
-    const mutations = { ...DEFAULT_MUTATION_CONFIG };
+    const mutations = {
+        ...DEFAULT_MUTATION_CONFIG,
+        retry: createSafeRetryStrategy(maxRetries4xx, maxRetries5xx, maxRetriesOther)
+    };
     const result = {
         queries: { ...queries, ...(overrides?.queries || {}) },
         mutations: { ...mutations, ...(overrides?.mutations || {}) }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qiaopeng/tanstack-query-plus",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "Enhanced TanStack Query toolkit: defaults, hooks, persistence, offline, data guard, utils",
   "author": "qiaopeng",
   "license": "MIT",