@gz-fronted/gz-pc 0.1.0 → 0.1.1-beta.1

package/README.md

@@ -22,8 +22,9 @@ Axios 和 ahooks 是 gz-pc 的普通 dependencies，安装 gz-pc 时会自动安
 
 ## 请求协议
 
-gz-fetch **只有在 HTTP Status 为 200 时才认为请求成功**。201、204 以及其他
-所有状态都会进入统一错误处理。
+gz-fetch 默认将所有 HTTP `2xx` 状态视为成功，包括 200、201、202、204 和 206。
+非 `2xx` 状态进入统一错误处理并抛出 `GzFetchError`，错误中保留 `status` 和
+`responseData`。
 
 成功时直接返回后端原始的 `response.data`，不会返回 `AxiosResponse`，也不会：
 
@@ -31,6 +32,29 @@ gz-fetch **只有在 HTTP Status 为 200 时才认为请求成功**。201、204
 - 自动解包 `data`
 - 转换分页、字段、日期或任何服务端数据
 
+例如后端返回以下内容时，调用方取得的是包含 `code`、`data`、`message` 的完整
+对象：
+
+```ts
+interface CreateOrderResponse {
+  code: number;
+  data: {
+    orderId: string;
+  };
+  message: string;
+}
+
+const response = await gzFetch<CreateOrderResponse, CreateOrderParams>({
+  url: '/order/create',
+  method: 'POST',
+  params,
+});
+
+response.code;
+response.data.orderId;
+response.message;
+```
+
 ```ts
 import { configureGzFetch, gzFetch } from '@gz-fronted/gz-pc/fetch';
 
@@ -105,6 +129,7 @@ function gzFetch<TResponse, TRequestParams = unknown>(
 | `skipAuth`         | `boolean`                              | 否   | 为 `true` 时跳过 Token 注入                |
 | `responseType`     | `'json' \| 'blob' \| 'text'`           | 否   | 响应数据类型，默认 `json`                  |
 | `signal`           | `AbortSignal`                          | 否   | 取消请求的标准 AbortSignal                 |
+| `withCredentials`  | `boolean`                              | 否   | 是否携带跨域 Cookie 等凭证                 |
 
 请求入参字段统一使用 `params`，业务代码不需要区分 Axios 的 `params` 和 `data`：
 
@@ -112,6 +137,8 @@ function gzFetch<TResponse, TRequestParams = unknown>(
 - POST、PUT：`params` 转为 Request Body。
 
 业务请求配置不支持 `data`，也不得混用 `params` 和 `data`。
+POST、PUT 的 `params` 支持 JSON 对象、`FormData`、`URLSearchParams` 和 `Blob`；
+自定义请求头通过 `headers` 传入。
 
 完整示例：
 
@@ -153,15 +180,37 @@ const result = await gzFetch<SaveResult, SaveParams>({
 | ------------------ | ----------------------------------------------------------- | ----------------- | -------------------------- |
 | `baseURL`          | `string`                                                    | 无                | 所有业务请求的基础地址     |
 | `timeout`          | `number`                                                    | `15000`           | 默认请求超时时间，单位毫秒 |
+| `validateStatus`   | `(status: number) => boolean`                               | 所有 `2xx`        | 自定义 HTTP 成功状态范围   |
 | `getToken`         | `() => string \| undefined \| Promise<string \| undefined>` | 无                | 每次请求前动态获取 Token   |
 | `showErrorMessage` | `boolean`                                                   | `true`            | 实例级错误提示开关         |
 | `auth.headerName`  | `string`                                                    | `Authorization`   | Token 请求头名称           |
 | `auth.formatToken` | `(token: string) => string`                                 | `Bearer ${token}` | Token 格式化函数           |
 | `middlewares`      | `readonly GzFetchMiddleware[]`                              | `[]`              | 请求、响应和错误中间件     |
 
-当前稳定 API 没有开放 Axios 的 `withCredentials`、`paramsSerializer`、
-`onUploadProgress`、`validateStatus` 等配置，也暂不支持 `PATCH`。业务代码只应传入
-上表列出的字段；如果后续确有通用场景，再通过 gz-pc 统一扩展类型和请求核心。
+需要覆盖默认成功状态时，只在应用初始化层配置：
+
+```ts
+configureGzFetch({
+  validateStatus: (status) => status === 200 || status === 304,
+});
+```
+
+当前稳定 API 没有开放 Axios 的 `paramsSerializer`、`onUploadProgress` 等配置，也
+暂不支持 `PATCH`。业务代码只应传入上表列出的字段；如果后续确有通用场景，再
+通过 gz-pc 统一扩展类型和请求核心。
+
+### 跨域凭证
+
+需要浏览器携带跨域 Cookie 等凭证时，在单次请求中开启 `withCredentials`：
+
+```ts
+await gzFetch<QueryPresetResponse, QueryPresetParams>({
+  url: '/queryFilterTemplate/list',
+  method: 'POST',
+  params,
+  withCredentials: true,
+});
+```
 
 ## Token
 
@@ -196,7 +245,7 @@ configureGzFetch({
 
 ## 错误提示
 
-HTTP 非 200 时仅尝试读取响应体的 `msg`。没有有效 `msg` 时使用默认文案，最终
+HTTP 非 `2xx` 时仅尝试读取响应体的 `msg`。没有有效 `msg` 时使用默认文案，最终
 抛出 `GzFetchError`。
 
 错误类型包括：

package/dist/fetch/index.cjs

@@ -99,6 +99,7 @@ async function runErrorMiddlewares(error, context, middlewares) {
 // src/fetch/client.ts
 var DEFAULT_TIMEOUT = 15e3;
 var DEFAULT_AUTH_HEADER = "Authorization";
+var DEFAULT_VALIDATE_STATUS = (status) => status >= 200 && status < 300;
 function toHeaderRecord(headers) {
   const result = {};
   for (const [name, value] of Object.entries(headers)) {
@@ -109,7 +110,7 @@ function toHeaderRecord(headers) {
   return result;
 }
 function createGzFetch(options = {}) {
-  var _a, _b, _c, _d, _e, _f, _g;
+  var _a, _b, _c, _d, _e, _f, _g, _h;
   const middlewares = (_a = options.middlewares) != null ? _a : [];
   const showInstanceErrorMessage = (_b = options.showErrorMessage) != null ? _b : true;
   const headerName = (_d = (_c = options.auth) == null ? void 0 : _c.headerName) != null ? _d : DEFAULT_AUTH_HEADER;
@@ -117,7 +118,7 @@ function createGzFetch(options = {}) {
   const instance = axios__default.default.create({
     ...options.baseURL === void 0 ? {} : { baseURL: options.baseURL },
     timeout: (_g = options.timeout) != null ? _g : DEFAULT_TIMEOUT,
-    validateStatus: (status) => status === 200
+    validateStatus: (_h = options.validateStatus) != null ? _h : DEFAULT_VALIDATE_STATUS
   });
   async function request(initialConfig) {
     var _a2;
@@ -143,7 +144,8 @@ function createGzFetch(options = {}) {
         ...usesRequestBody || currentConfig.params === void 0 ? {} : { params: currentConfig.params },
         ...currentConfig.timeout === void 0 ? {} : { timeout: currentConfig.timeout },
         ...currentConfig.responseType === void 0 ? {} : { responseType: currentConfig.responseType },
-        ...currentConfig.signal === void 0 ? {} : { signal: currentConfig.signal }
+        ...currentConfig.signal === void 0 ? {} : { signal: currentConfig.signal },
+        ...currentConfig.withCredentials === void 0 ? {} : { withCredentials: currentConfig.withCredentials }
       };
       const response = await instance.request(axiosConfig);
       const context = {

package/dist/fetch/index.d.cts

@@ -31,6 +31,7 @@ interface GzRequestConfig<TRequestParams = unknown> {
     skipAuth?: boolean;
     responseType?: GzResponseType;
     signal?: AbortSignal;
+    withCredentials?: boolean;
 }
 interface GzInternalRequestConfig extends Omit<GzRequestConfig<unknown>, 'headers'> {
     headers?: GzRequestHeaders;
@@ -56,6 +57,7 @@ interface GzFetchAuthOptions {
 interface CreateGzFetchOptions {
     baseURL?: string;
     timeout?: number;
+    validateStatus?: (status: number) => boolean;
     getToken?: () => string | undefined | Promise<string | undefined>;
     showErrorMessage?: boolean;
     auth?: GzFetchAuthOptions;

package/dist/fetch/index.d.ts

@@ -31,6 +31,7 @@ interface GzRequestConfig<TRequestParams = unknown> {
     skipAuth?: boolean;
     responseType?: GzResponseType;
     signal?: AbortSignal;
+    withCredentials?: boolean;
 }
 interface GzInternalRequestConfig extends Omit<GzRequestConfig<unknown>, 'headers'> {
     headers?: GzRequestHeaders;
@@ -56,6 +57,7 @@ interface GzFetchAuthOptions {
 interface CreateGzFetchOptions {
     baseURL?: string;
     timeout?: number;
+    validateStatus?: (status: number) => boolean;
     getToken?: () => string | undefined | Promise<string | undefined>;
     showErrorMessage?: boolean;
     auth?: GzFetchAuthOptions;

package/dist/fetch/index.js

@@ -93,6 +93,7 @@ async function runErrorMiddlewares(error, context, middlewares) {
 // src/fetch/client.ts
 var DEFAULT_TIMEOUT = 15e3;
 var DEFAULT_AUTH_HEADER = "Authorization";
+var DEFAULT_VALIDATE_STATUS = (status) => status >= 200 && status < 300;
 function toHeaderRecord(headers) {
   const result = {};
   for (const [name, value] of Object.entries(headers)) {
@@ -103,7 +104,7 @@ function toHeaderRecord(headers) {
   return result;
 }
 function createGzFetch(options = {}) {
-  var _a, _b, _c, _d, _e, _f, _g;
+  var _a, _b, _c, _d, _e, _f, _g, _h;
   const middlewares = (_a = options.middlewares) != null ? _a : [];
   const showInstanceErrorMessage = (_b = options.showErrorMessage) != null ? _b : true;
   const headerName = (_d = (_c = options.auth) == null ? void 0 : _c.headerName) != null ? _d : DEFAULT_AUTH_HEADER;
@@ -111,7 +112,7 @@ function createGzFetch(options = {}) {
   const instance = axios.create({
     ...options.baseURL === void 0 ? {} : { baseURL: options.baseURL },
     timeout: (_g = options.timeout) != null ? _g : DEFAULT_TIMEOUT,
-    validateStatus: (status) => status === 200
+    validateStatus: (_h = options.validateStatus) != null ? _h : DEFAULT_VALIDATE_STATUS
   });
   async function request(initialConfig) {
     var _a2;
@@ -137,7 +138,8 @@ function createGzFetch(options = {}) {
         ...usesRequestBody || currentConfig.params === void 0 ? {} : { params: currentConfig.params },
         ...currentConfig.timeout === void 0 ? {} : { timeout: currentConfig.timeout },
         ...currentConfig.responseType === void 0 ? {} : { responseType: currentConfig.responseType },
-        ...currentConfig.signal === void 0 ? {} : { signal: currentConfig.signal }
+        ...currentConfig.signal === void 0 ? {} : { signal: currentConfig.signal },
+        ...currentConfig.withCredentials === void 0 ? {} : { withCredentials: currentConfig.withCredentials }
       };
       const response = await instance.request(axiosConfig);
       const context = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gz-fronted/gz-pc",
-  "version": "0.1.0",
+  "version": "0.1.1-beta.1",
   "description": "Shared fetch, hooks and utility primitives for GZ frontend applications.",
   "license": "MIT",
   "type": "module",