@stdex/request 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 安坚实
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# 简洁、灵活的日志模块
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+- 支持浏览器、Node.js 环境
+- 可扩展性强（可继承子类或添加自定义 handler）
+- 代码简洁，结构清晰

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 实现一个功能完善、异常处理逻辑全面的请求发起器。
+ * 可通过继承子类来扩展其功能。
+ */
+import { type Logger } from '@stdex/logging';
+import { type Result, type Success, type Failure } from '@stdex/utils/result.js';
+import { type RequestFailure } from './error.js';
+import type { Options, PredefinedOptions, FormattedOptions } from './options.js';
+/** 此基类不可直接使用，因其未对错误格式进行具体约定 */
+export declare abstract class BaseRequestClient<FailureT extends Failure> {
+    logger: Logger;
+    prefefinedOptions: PredefinedOptions;
+    constructor(options?: PredefinedOptions & {
+        logger?: string | Logger;
+    });
+    /** 生成一个快捷方式函数，调用它相当于调用 client.request() */
+    asFunction(): <T>(inputUrl: string, inputOptions?: Options<T>) => Promise<Result<T, FailureT>>;
+    request<T>(inputUrl: string, inputOptions?: Options<T>): Promise<Result<T, FailureT>>;
+    protected realRequest<T>(options: FormattedOptions): Promise<Result<T, FailureT>>;
+    formatOptions<T>(input: Options<T>): Promise<FormattedOptions<T>>;
+    /** 请求发起前调用此方法补充 Headers 内容 */
+    protected getHeaders(options: FormattedOptions, inputOptions: Options): Record<string, string> | undefined | Promise<Record<string, string> | undefined>;
+    /**
+     * 解析响应内容
+     * - 若 options.binary 为 true，返回二进制结果
+     * - 若 response Content-Type 为 'text/' 开头，返回文本结果
+     * - 尝试解析 JSON，若成功，返回 JSON 结果；
+     * - 若 JSON 解析失败：
+     *   - 若 response Content-Type 为 'application/json' 开头，返回解析失败信息
+     *   - 其他情况，返回纯文本结果
+     */
+    protected parseResponse(options: FormattedOptions, response: Response): Promise<Result<unknown, FailureT>>;
+    protected handleError(result: RequestFailure): FailureT;
+    /** 生成符合 FailureT 约定的失败结果 */
+    protected abstract makeFailureResult(result: RequestFailure): FailureT;
+    /**
+     * 对请求成功得到的数据进行格式化。
+     *
+     * - 此步骤在 applyInputFormat() 之前运行，子类可在此进行一些通用的格式化工作，
+     * - 输出 Success 或 Failure 结果均可，但输出的 Failure 结果不会交给 makeFailureResult() 进行格式化，需自行保证符合 FailureT 约定。
+     * - 若此方法抛出异常，会生成 ResponseDataFormattingFailed，此错误会照常交给 makeFailureResult() 处理。
+     */
+    protected formatSuccessResult(result: Success<unknown>, options: FormattedOptions): Result<unknown, FailureT>;
+}
+/** 默认的 RequestClient 实现。出现错误时，会把错误对象原样放入错误信息中。 */
+export declare class RequestClient extends BaseRequestClient<RequestFailure> {
+    protected makeFailureResult(result: RequestFailure): RequestFailure;
+}

package/dist/client.js

@@ -0,0 +1,236 @@
+/**
+ * 实现一个功能完善、异常处理逻辑全面的请求发起器。
+ * 可通过继承子类来扩展其功能。
+ */
+import { getLogger } from '@stdex/logging';
+import { success, failure, formatFailure, exceptionToFailure, } from '@stdex/utils/result.js';
+import { combineUrl } from '@stdex/utils/url.js';
+import isPlainObject from 'lodash/isPlainObject.js';
+import pick from 'lodash/pick.js';
+/** 此基类不可直接使用，因其未对错误格式进行具体约定 */
+export class BaseRequestClient {
+    logger;
+    prefefinedOptions;
+    constructor(options = {}) {
+        this.logger = !options.logger
+            ? getLogger('request')
+            : typeof options.logger === 'string'
+                ? getLogger(options.logger)
+                : options.logger;
+        this.prefefinedOptions = options;
+    }
+    /** 生成一个快捷方式函数，调用它相当于调用 client.request() */
+    asFunction() {
+        return async (inputUrl, inputOptions) => this.request(inputUrl, inputOptions);
+    }
+    // -------------------------------
+    // 发起请求
+    // -------------------------------
+    async request(inputUrl, inputOptions) {
+        const options = await this.formatOptions({
+            url: inputUrl,
+            ...(inputOptions ?? {}),
+        });
+        let result;
+        let tryCount = 0;
+        do {
+            tryCount += 1;
+            if (tryCount > 1) {
+                this.logger.warn('Retrying Request', { ...options, tryCount });
+            }
+            result = await this.realRequest(options);
+        } while (!result.success && tryCount < options.retry + 1);
+        return result;
+    }
+    async realRequest(options) {
+        const { url, method, headers, body, timeout, signal: manualSignal, format } = options;
+        const timeoutSignal = timeout ? AbortSignal.timeout(timeout) : undefined;
+        const signal = manualSignal || timeoutSignal
+            ? AbortSignal.any([manualSignal, timeoutSignal].filter(Boolean))
+            : undefined;
+        // 发起请求
+        let response;
+        try {
+            response = await fetch(url, { method, headers, body, signal });
+        }
+        catch (error) {
+            // 失败情形“手动取消”
+            if (manualSignal?.aborted && manualSignal.reason === error) {
+                const reason = error instanceof DOMException && error.name === 'AbortError' ? null : error;
+                return this.handleError(failure('Request Was Canceled', 'RequestAborted', { options, reason }));
+            }
+            // 失败情形“请求超时”
+            if (error instanceof DOMException && error.name === 'TimeoutError') {
+                return this.handleError(failure('Request Timed Out', 'RequestTimeout', { options }));
+            }
+            // 失败情形“请求发起失败”
+            return this.handleError(failure("Couldn't Send Request", 'RequestSendFailed', { options, originalError: error }));
+        }
+        // 失败情形“失败状态码”
+        if (!response.status.toString().startsWith('2')) {
+            // 此时服务端仍可能输出一些内容，试着解析出来
+            // 但因此情况下后端输出数据往往和成功时不同，因此不调用用户提供的 format() 函数来格式化
+            const responseDataRes = await this.parseResponse(options, response);
+            const responseData = responseDataRes.success ? responseDataRes.data : undefined;
+            return this.handleError(failure('Unexpected Response HTTP Status', 'UnexpectedHttpStatus', {
+                options,
+                status: response.status,
+                response,
+                responseData,
+            }));
+        }
+        // 解析响应内容
+        let result = await this.parseResponse(options, response);
+        // 格式化响应数据
+        if (result.success) {
+            try {
+                result = this.formatSuccessResult(result, options);
+            }
+            catch (error) {
+                return this.handleError(failure('Failed To Format Response Data', 'ResponseDataFormattingFailed', {
+                    options,
+                    originalError: error,
+                    response,
+                    responseData: result.data,
+                }));
+            }
+        }
+        if (result.success && format) {
+            try {
+                const formattedData = format(result.data);
+                result = success(formattedData);
+            }
+            catch (error) {
+                return this.handleError(failure('Failed To Format Response Data Using options.format', 'ResponseDataFormattingFailed', {
+                    options,
+                    originalError: error,
+                    response,
+                    responseData: result.data,
+                }));
+            }
+        }
+        return result;
+    }
+    // -------------------------------
+    // 请求预处理
+    // -------------------------------
+    async formatOptions(input) {
+        const predefined = this.prefefinedOptions;
+        const { urlPrefix = predefined.urlPrefix ?? '', url: rawUrl, query = {}, method = predefined.method ?? 'GET', headers: rawHeaders = {}, body: rawBody = null, data, // eslint-disable-line @typescript-eslint/no-unsafe-assignment
+        binary = false, timeout = predefined.timeout ?? 0, signal, retry = predefined.retry ?? 0, format, } = input;
+        const headers = {
+            ...(predefined.headers ?? {}),
+            ...rawHeaders,
+        };
+        let body = rawBody;
+        if (data !== undefined) {
+            if (method === 'GET') {
+                if (isPlainObject(data)) {
+                    Object.assign(query, data);
+                }
+            }
+            else {
+                body = data instanceof FormData ? data : JSON.stringify(data);
+                headers['Content-Type'] = 'application/json; charset=utf-8';
+            }
+        }
+        const url = combineUrl(urlPrefix + (rawUrl ?? ''), query);
+        const options = {
+            method,
+            url,
+            headers,
+            body,
+            timeout,
+            binary,
+            signal,
+            format,
+            retry,
+        };
+        Object.assign(options.headers, await this.getHeaders(options, input));
+        return options;
+    }
+    /** 请求发起前调用此方法补充 Headers 内容 */
+    getHeaders(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    options, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    inputOptions) {
+        return undefined;
+    }
+    // -------------------------------
+    // 请求结果、错误处理
+    // -------------------------------
+    /**
+     * 解析响应内容
+     * - 若 options.binary 为 true，返回二进制结果
+     * - 若 response Content-Type 为 'text/' 开头，返回文本结果
+     * - 尝试解析 JSON，若成功，返回 JSON 结果；
+     * - 若 JSON 解析失败：
+     *   - 若 response Content-Type 为 'application/json' 开头，返回解析失败信息
+     *   - 其他情况，返回纯文本结果
+     */
+    async parseResponse(options, response) {
+        const contentType = (response.headers.get('Content-Type') ?? '').toLowerCase().trim();
+        if (options.binary) {
+            const blobResult = await exceptionToFailure(response.blob());
+            return formatFailure(blobResult, result => this.handleError(failure('Blob Body Parsing Failed', 'ResponseBodyParseFailed', {
+                options,
+                status: response.status,
+                originalError: result.data,
+                response,
+            })));
+        }
+        const textResult = await exceptionToFailure(response.text());
+        if (contentType.startsWith('text/') || !textResult.success) {
+            return formatFailure(textResult, result => this.handleError(failure('Text Body Parsing Failed', 'ResponseBodyParseFailed', {
+                options,
+                status: response.status,
+                originalError: result.data,
+                response,
+            })));
+        }
+        let jsonParseError;
+        try {
+            return success(JSON.parse(textResult.data));
+        }
+        catch (error) {
+            jsonParseError = error;
+        }
+        if (contentType.startsWith('application/json')) {
+            return this.handleError(failure('JSON Body Parsing Failed', 'ResponseBodyParseFailed', {
+                options,
+                status: response.status,
+                originalError: jsonParseError,
+                response,
+            }));
+        }
+        return textResult;
+    }
+    handleError(result) {
+        const info = pick(result.data.options, ['url', 'method']);
+        for (const key of ['originalError', 'status', 'responseData']) {
+            if (key in result.data)
+                Object.assign(info, pick(result.data, [key]));
+        }
+        this.logger.error(result.code, info);
+        return this.makeFailureResult(result);
+    }
+    /**
+     * 对请求成功得到的数据进行格式化。
+     *
+     * - 此步骤在 applyInputFormat() 之前运行，子类可在此进行一些通用的格式化工作，
+     * - 输出 Success 或 Failure 结果均可，但输出的 Failure 结果不会交给 makeFailureResult() 进行格式化，需自行保证符合 FailureT 约定。
+     * - 若此方法抛出异常，会生成 ResponseDataFormattingFailed，此错误会照常交给 makeFailureResult() 处理。
+     */
+    formatSuccessResult(result, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    options) {
+        return result;
+    }
+}
+/** 默认的 RequestClient 实现。出现错误时，会把错误对象原样放入错误信息中。 */
+export class RequestClient extends BaseRequestClient {
+    makeFailureResult(result) {
+        return result;
+    }
+}

package/dist/error.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 定义请求失败类型。
+ *
+ * 有两类失败情形不在处理范围内：
+ * 1. client 或子类自身代码报错，例如 formatOptions() 方法意外报错
+ * 2. 请求本身成功，但相应内容表达了业务上的失败，例如登录接口返回密码错误。
+ * 如有需要，可继承子类来处理这些失败情形。
+ */
+import { type Failure } from '@stdex/utils/result.js';
+import { type FormattedOptions } from './options.js';
+export type RequestFailure = RequestSendFailed | RequestAborted | RequestTimeout | UnexpectedHttpStatus | ResponseBodyParseFailed | ResponseDataFormattingFailed;
+export interface RequestFailureInfo {
+    options: FormattedOptions;
+}
+/** 请求发起失败（如网络异常） */
+export type RequestSendFailed = Failure<'RequestSendFailed', RequestSendFailedInfo>;
+export interface RequestSendFailedInfo extends RequestFailureInfo {
+    /** 原始错误对象 */
+    originalError: unknown;
+}
+/** 手动取消 */
+export type RequestAborted = Failure<'RequestAborted', RequestAbortedInfo>;
+export interface RequestAbortedInfo extends RequestFailureInfo {
+    /** 取消原因，即调用 abortController.abort() 时传入的值，若未传值则为 null */
+    reason: unknown;
+}
+/** 请求超时 */
+export type RequestTimeout = Failure<'RequestTimeout', RequestFailureInfo>;
+/** 失败状态码（服务端响应了代表失败的状态码，如 500） */
+export type UnexpectedHttpStatus = Failure<'UnexpectedHttpStatus', UnexpectedHttpStatusInfo>;
+export interface UnexpectedHttpStatusInfo extends RequestFailureInfo {
+    /** HTTP Status */
+    status: number;
+    /** Response 对象 */
+    response: Response;
+    /** 尝试着从 response body 中解析出的数据 */
+    responseData: unknown;
+}
+/** 响应体解析失败 */
+export type ResponseBodyParseFailed = Failure<'ResponseBodyParseFailed', ResponseBodyParseFailedInfo>;
+export interface ResponseBodyParseFailedInfo extends RequestFailureInfo {
+    /** HTTP Status */
+    status: number;
+    /** 原始错误对象 */
+    originalError: unknown;
+    /** Response 对象 */
+    response: Response;
+}
+/** 响应体数据格式化失败 */
+export type ResponseDataFormattingFailed = Failure<'ResponseDataFormattingFailed', ResponseDataFormattingFailedInfo>;
+export interface ResponseDataFormattingFailedInfo extends RequestFailureInfo {
+    /** 原始错误对象 */
+    originalError: unknown;
+    /** Response 对象 */
+    response: Response;
+    /** 未经格式化的响应数据 */
+    responseData: unknown;
+}

package/dist/error.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type * from './options.js';
+export type * from './error.js';
+export type * as errors from './error.js';
+export * from './client.js';
+export * from './instance.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './client.js';
+export * from './instance.js';

package/dist/instance.d.ts

@@ -0,0 +1,4 @@
+import { RequestClient } from './client.js';
+/** 提供一个即取即用的 RequestClient 实例及其函数版本 */
+export declare const client: RequestClient;
+export declare const request: <T>(inputUrl: string, inputOptions?: import("./options.js").Options<T> | undefined) => Promise<import("@stdex/utils/result.js").Result<T, import("./error.js").RequestFailure>>;

package/dist/instance.js

@@ -0,0 +1,4 @@
+import { RequestClient } from './client.js';
+/** 提供一个即取即用的 RequestClient 实例及其函数版本 */
+export const client = new RequestClient();
+export const request = client.asFunction();

package/dist/options.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 请求参数
+ */
+export interface Options<T = unknown> {
+    urlPrefix?: string;
+    url?: string;
+    query?: Record<string, string | number | undefined>;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string | FormData | null;
+    /**
+     * 向后端传递的数据。
+     * 1. 对于 GET 请求：若 data 为 plain object 会合并到 query 中，否则会被忽略。
+     * 2. 对于 POST 请求：会作为 POST body，代替 body 参数。
+     *    其中若为 FormData，会原样交给 fetch()；否则进行 JSON 化。
+     * 3. 为了支持传入 interface 类型的值，Record 只能定义成 Record<string, any>
+     */
+    data?: any;
+    /** 是否把响应内容作为二进制处理（结果是 blob） */
+    binary?: boolean;
+    /** 超时时间，不指定或设为 0 代表不限 */
+    timeout?: number;
+    /** 可通过此信号手动终止请求 */
+    signal?: AbortSignal;
+    /** 请求结果为失败（无论原因为何）时的重试次数，默认值为 0，表示不重试 */
+    retry?: number;
+    /** 对请求成功时得到的数据进行最终格式化 */
+    format?: (responseData: any) => T;
+}
+/** 可预指定的请求参数 */
+export type PredefinedOptions = Pick<Options, 'urlPrefix' | 'method' | 'headers' | 'timeout' | 'retry'>;
+/** 经过整理的请求参数（client 内部使用） */
+export type FormattedOptions<T = unknown> = Required<Pick<Options, 'url' | 'method' | 'headers' | 'body' | 'binary' | 'timeout' | 'retry'>> & Pick<Options<T>, 'signal' | 'format'>;

package/dist/options.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@stdex/request",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "可靠、简洁的网络请求模块",
+  "homepage": "https://github.com/anjianshi/stdex-request",
+  "bugs": {
+    "url": "https://github.com/anjianshi/stdex-request/issues",
+    "email": "anjianshi@gmail.com"
+  },
+  "license": "MIT",
+  "author": "anjianshi <anjianshi@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anjianshi/stdex-request.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "src",
+    "dist/"
+  ],
+  "dependencies": {
+    "@stdex/logging": "^1.1.0",
+    "@stdex/utils": "^1.0.2",
+    "lodash": "^4.18.1"
+  },
+  "devDependencies": {
+    "@stdex/presets-eslint-typescript": "^1.0.2",
+    "@stdex/presets-prettier": "^1.0.2",
+    "@stdex/presets-typescript": "^1.0.2",
+    "@types/lodash": "^4.17.27",
+    "eslint": "^10.6.0",
+    "typescript": "^6.0.3"
+  },
+  "prettier": "@stdex/presets-prettier/prettierrc",
+  "scripts": {
+    "build": "npm run clear && tsc",
+    "watch": "npm run clear && tsc --watch",
+    "clear": "rm -rf dist",
+    "lint": "tsc --noEmit && eslint './src/'"
+  }
 }

package/src/client.ts

@@ -0,0 +1,314 @@
+/**
+ * 实现一个功能完善、异常处理逻辑全面的请求发起器。
+ * 可通过继承子类来扩展其功能。
+ */
+import { getLogger, type Logger } from '@stdex/logging'
+import {
+  success,
+  failure,
+  formatFailure,
+  exceptionToFailure,
+  type Result,
+  type Success,
+  type Failure,
+} from '@stdex/utils/result.js'
+import { combineUrl } from '@stdex/utils/url.js'
+import isPlainObject from 'lodash/isPlainObject.js'
+import pick from 'lodash/pick.js'
+import { type RequestFailure } from './error.js'
+import type { Options, PredefinedOptions, FormattedOptions } from './options.js'
+
+/** 此基类不可直接使用，因其未对错误格式进行具体约定 */
+export abstract class BaseRequestClient<FailureT extends Failure> {
+  logger: Logger
+  prefefinedOptions: PredefinedOptions
+
+  constructor(options: PredefinedOptions & { logger?: string | Logger } = {}) {
+    this.logger = !options.logger
+      ? getLogger('request')
+      : typeof options.logger === 'string'
+        ? getLogger(options.logger)
+        : options.logger
+    this.prefefinedOptions = options
+  }
+
+  /** 生成一个快捷方式函数，调用它相当于调用 client.request() */
+  asFunction() {
+    return async <T>(inputUrl: string, inputOptions?: Options<T>) =>
+      this.request<T>(inputUrl, inputOptions)
+  }
+
+  // -------------------------------
+  // 发起请求
+  // -------------------------------
+
+  async request<T>(inputUrl: string, inputOptions?: Options<T>): Promise<Result<T, FailureT>> {
+    const options = await this.formatOptions<T>({
+      url: inputUrl,
+      ...(inputOptions ?? {}),
+    })
+
+    let result!: Result<T, FailureT>
+    let tryCount = 0
+    do {
+      tryCount += 1
+      if (tryCount > 1) {
+        this.logger.warn('Retrying Request', { ...options, tryCount })
+      }
+      result = await this.realRequest<T>(options)
+    } while (!result.success && tryCount < options.retry + 1)
+    return result
+  }
+
+  protected async realRequest<T>(options: FormattedOptions): Promise<Result<T, FailureT>> {
+    const { url, method, headers, body, timeout, signal: manualSignal, format } = options
+
+    const timeoutSignal = timeout ? AbortSignal.timeout(timeout) : undefined
+    const signal =
+      manualSignal || timeoutSignal
+        ? AbortSignal.any([manualSignal, timeoutSignal].filter(Boolean) as AbortSignal[])
+        : undefined
+
+    // 发起请求
+    let response: Response | undefined
+    try {
+      response = await fetch(url, { method, headers, body, signal })
+    } catch (error) {
+      // 失败情形“手动取消”
+      if (manualSignal?.aborted && manualSignal.reason === error) {
+        const reason = error instanceof DOMException && error.name === 'AbortError' ? null : error
+        return this.handleError(
+          failure('Request Was Canceled', 'RequestAborted', { options, reason }),
+        )
+      }
+      // 失败情形“请求超时”
+      if (error instanceof DOMException && error.name === 'TimeoutError') {
+        return this.handleError(failure('Request Timed Out', 'RequestTimeout', { options }))
+      }
+      // 失败情形“请求发起失败”
+      return this.handleError(
+        failure("Couldn't Send Request", 'RequestSendFailed', { options, originalError: error }),
+      )
+    }
+
+    // 失败情形“失败状态码”
+    if (!response.status.toString().startsWith('2')) {
+      // 此时服务端仍可能输出一些内容，试着解析出来
+      // 但因此情况下后端输出数据往往和成功时不同，因此不调用用户提供的 format() 函数来格式化
+      const responseDataRes = await this.parseResponse(options, response)
+      const responseData = responseDataRes.success ? responseDataRes.data : undefined
+      return this.handleError(
+        failure('Unexpected Response HTTP Status', 'UnexpectedHttpStatus', {
+          options,
+          status: response.status,
+          response,
+          responseData,
+        }),
+      )
+    }
+
+    // 解析响应内容
+    let result = await this.parseResponse(options, response)
+
+    // 格式化响应数据
+    if (result.success) {
+      try {
+        result = this.formatSuccessResult(result, options)
+      } catch (error) {
+        return this.handleError(
+          failure('Failed To Format Response Data', 'ResponseDataFormattingFailed', {
+            options,
+            originalError: error,
+            response,
+            responseData: result.data,
+          }),
+        )
+      }
+    }
+    if (result.success && format) {
+      try {
+        const formattedData = format(result.data)
+        result = success(formattedData)
+      } catch (error) {
+        return this.handleError(
+          failure(
+            'Failed To Format Response Data Using options.format',
+            'ResponseDataFormattingFailed',
+            {
+              options,
+              originalError: error,
+              response,
+              responseData: result.data,
+            },
+          ),
+        )
+      }
+    }
+    return result as Result<T, FailureT>
+  }
+
+  // -------------------------------
+  // 请求预处理
+  // -------------------------------
+
+  async formatOptions<T>(input: Options<T>): Promise<FormattedOptions<T>> {
+    const predefined = this.prefefinedOptions
+    const {
+      urlPrefix = predefined.urlPrefix ?? '',
+      url: rawUrl,
+      query = {},
+      method = predefined.method ?? 'GET',
+      headers: rawHeaders = {},
+      body: rawBody = null,
+      data, // eslint-disable-line @typescript-eslint/no-unsafe-assignment
+      binary = false,
+      timeout = predefined.timeout ?? 0,
+      signal,
+      retry = predefined.retry ?? 0,
+      format,
+    } = input
+
+    const headers = {
+      ...(predefined.headers ?? {}),
+      ...rawHeaders,
+    }
+
+    let body: string | FormData | null = rawBody
+    if (data !== undefined) {
+      if (method === 'GET') {
+        if (isPlainObject(data)) {
+          Object.assign(query, data)
+        }
+      } else {
+        body = data instanceof FormData ? data : JSON.stringify(data)
+        headers['Content-Type'] = 'application/json; charset=utf-8'
+      }
+    }
+
+    const url = combineUrl(urlPrefix + (rawUrl ?? ''), query)
+
+    const options: FormattedOptions<T> = {
+      method,
+      url,
+      headers,
+      body,
+      timeout,
+      binary,
+      signal,
+      format,
+      retry,
+    }
+    Object.assign(options.headers, await this.getHeaders(options, input))
+    return options
+  }
+
+  /** 请求发起前调用此方法补充 Headers 内容 */
+  protected getHeaders(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    options: FormattedOptions,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    inputOptions: Options,
+  ): Record<string, string> | undefined | Promise<Record<string, string> | undefined> {
+    return undefined
+  }
+
+  // -------------------------------
+  // 请求结果、错误处理
+  // -------------------------------
+
+  /**
+   * 解析响应内容
+   * - 若 options.binary 为 true，返回二进制结果
+   * - 若 response Content-Type 为 'text/' 开头，返回文本结果
+   * - 尝试解析 JSON，若成功，返回 JSON 结果；
+   * - 若 JSON 解析失败：
+   *   - 若 response Content-Type 为 'application/json' 开头，返回解析失败信息
+   *   - 其他情况，返回纯文本结果
+   */
+  protected async parseResponse(
+    options: FormattedOptions,
+    response: Response,
+  ): Promise<Result<unknown, FailureT>> {
+    const contentType = (response.headers.get('Content-Type') ?? '').toLowerCase().trim()
+
+    if (options.binary) {
+      const blobResult = await exceptionToFailure(response.blob())
+      return formatFailure(blobResult, result =>
+        this.handleError(
+          failure('Blob Body Parsing Failed', 'ResponseBodyParseFailed', {
+            options,
+            status: response.status,
+            originalError: result.data,
+            response,
+          }),
+        ),
+      )
+    }
+
+    const textResult = await exceptionToFailure(response.text())
+    if (contentType.startsWith('text/') || !textResult.success) {
+      return formatFailure(textResult, result =>
+        this.handleError(
+          failure('Text Body Parsing Failed', 'ResponseBodyParseFailed', {
+            options,
+            status: response.status,
+            originalError: result.data,
+            response,
+          }),
+        ),
+      )
+    }
+
+    let jsonParseError: unknown
+    try {
+      return success(JSON.parse(textResult.data))
+    } catch (error) {
+      jsonParseError = error
+    }
+    if (contentType.startsWith('application/json')) {
+      return this.handleError(
+        failure('JSON Body Parsing Failed', 'ResponseBodyParseFailed', {
+          options,
+          status: response.status,
+          originalError: jsonParseError,
+          response,
+        }),
+      )
+    }
+    return textResult
+  }
+
+  protected handleError(result: RequestFailure) {
+    const info: Record<string, unknown> = pick(result.data.options, ['url', 'method'])
+    for (const key of ['originalError', 'status', 'responseData'] as const) {
+      if (key in result.data) Object.assign(info, pick(result.data, [key]))
+    }
+    this.logger.error(result.code, info)
+    return this.makeFailureResult(result)
+  }
+
+  /** 生成符合 FailureT 约定的失败结果 */
+  protected abstract makeFailureResult(result: RequestFailure): FailureT
+
+  /**
+   * 对请求成功得到的数据进行格式化。
+   *
+   * - 此步骤在 applyInputFormat() 之前运行，子类可在此进行一些通用的格式化工作，
+   * - 输出 Success 或 Failure 结果均可，但输出的 Failure 结果不会交给 makeFailureResult() 进行格式化，需自行保证符合 FailureT 约定。
+   * - 若此方法抛出异常，会生成 ResponseDataFormattingFailed，此错误会照常交给 makeFailureResult() 处理。
+   */
+  protected formatSuccessResult(
+    result: Success<unknown>,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    options: FormattedOptions,
+  ): Result<unknown, FailureT> {
+    return result
+  }
+}
+
+/** 默认的 RequestClient 实现。出现错误时，会把错误对象原样放入错误信息中。 */
+export class RequestClient extends BaseRequestClient<RequestFailure> {
+  protected makeFailureResult(result: RequestFailure) {
+    return result
+  }
+}

package/src/error.ts

@@ -0,0 +1,78 @@
+/**
+ * 定义请求失败类型。
+ *
+ * 有两类失败情形不在处理范围内：
+ * 1. client 或子类自身代码报错，例如 formatOptions() 方法意外报错
+ * 2. 请求本身成功，但相应内容表达了业务上的失败，例如登录接口返回密码错误。
+ * 如有需要，可继承子类来处理这些失败情形。
+ */
+import { type Failure } from '@stdex/utils/result.js'
+import { type FormattedOptions } from './options.js'
+
+export type RequestFailure =
+  | RequestSendFailed
+  | RequestAborted
+  | RequestTimeout
+  | UnexpectedHttpStatus
+  | ResponseBodyParseFailed
+  | ResponseDataFormattingFailed
+
+export interface RequestFailureInfo {
+  options: FormattedOptions
+}
+
+/** 请求发起失败（如网络异常） */
+export type RequestSendFailed = Failure<'RequestSendFailed', RequestSendFailedInfo>
+export interface RequestSendFailedInfo extends RequestFailureInfo {
+  /** 原始错误对象 */
+  originalError: unknown
+}
+
+/** 手动取消 */
+export type RequestAborted = Failure<'RequestAborted', RequestAbortedInfo>
+export interface RequestAbortedInfo extends RequestFailureInfo {
+  /** 取消原因，即调用 abortController.abort() 时传入的值，若未传值则为 null */
+  reason: unknown
+}
+
+/** 请求超时 */
+export type RequestTimeout = Failure<'RequestTimeout', RequestFailureInfo>
+
+/** 失败状态码（服务端响应了代表失败的状态码，如 500） */
+export type UnexpectedHttpStatus = Failure<'UnexpectedHttpStatus', UnexpectedHttpStatusInfo>
+export interface UnexpectedHttpStatusInfo extends RequestFailureInfo {
+  /** HTTP Status */
+  status: number
+  /** Response 对象 */
+  response: Response
+  /** 尝试着从 response body 中解析出的数据 */
+  responseData: unknown
+}
+
+/** 响应体解析失败 */
+export type ResponseBodyParseFailed = Failure<
+  'ResponseBodyParseFailed',
+  ResponseBodyParseFailedInfo
+>
+export interface ResponseBodyParseFailedInfo extends RequestFailureInfo {
+  /** HTTP Status */
+  status: number
+  /** 原始错误对象 */
+  originalError: unknown
+  /** Response 对象 */
+  response: Response
+}
+
+/** 响应体数据格式化失败 */
+export type ResponseDataFormattingFailed = Failure<
+  'ResponseDataFormattingFailed',
+  ResponseDataFormattingFailedInfo
+>
+export interface ResponseDataFormattingFailedInfo extends RequestFailureInfo {
+  /** 原始错误对象 */
+  originalError: unknown
+  /** Response 对象 */
+  response: Response
+  /** 未经格式化的响应数据 */
+  responseData: unknown
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export type * from './options.js'
+
+export type * from './error.js'
+export type * as errors from './error.js'
+
+export * from './client.js'
+export * from './instance.js'

package/src/instance.ts

@@ -0,0 +1,5 @@
+import { RequestClient } from './client.js'
+
+/** 提供一个即取即用的 RequestClient 实例及其函数版本 */
+export const client = new RequestClient()
+export const request = client.asFunction()

package/src/options.ts

@@ -0,0 +1,49 @@
+/**
+ * 请求参数
+ */
+export interface Options<T = unknown> {
+  urlPrefix?: string
+  url?: string
+  query?: Record<string, string | number | undefined>
+  method?: string
+  headers?: Record<string, string>
+  body?: string | FormData | null
+
+  /**
+   * 向后端传递的数据。
+   * 1. 对于 GET 请求：若 data 为 plain object 会合并到 query 中，否则会被忽略。
+   * 2. 对于 POST 请求：会作为 POST body，代替 body 参数。
+   *    其中若为 FormData，会原样交给 fetch()；否则进行 JSON 化。
+   * 3. 为了支持传入 interface 类型的值，Record 只能定义成 Record<string, any>
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data?: any
+
+  /** 是否把响应内容作为二进制处理（结果是 blob） */
+  binary?: boolean
+
+  /** 超时时间，不指定或设为 0 代表不限 */
+  timeout?: number
+
+  /** 可通过此信号手动终止请求 */
+  signal?: AbortSignal
+
+  /** 请求结果为失败（无论原因为何）时的重试次数，默认值为 0，表示不重试 */
+  retry?: number
+
+  /** 对请求成功时得到的数据进行最终格式化 */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  format?: (responseData: any) => T
+}
+
+/** 可预指定的请求参数 */
+export type PredefinedOptions = Pick<
+  Options,
+  'urlPrefix' | 'method' | 'headers' | 'timeout' | 'retry'
+>
+
+/** 经过整理的请求参数（client 内部使用） */
+export type FormattedOptions<T = unknown> = Required<
+  Pick<Options, 'url' | 'method' | 'headers' | 'body' | 'binary' | 'timeout' | 'retry'>
+> &
+  Pick<Options<T>, 'signal' | 'format'>