nstarter-http-request 0.1.0

package/src/adapter/axios.adapter.ts

@@ -0,0 +1,228 @@
+/**
+ * Axios 适配器实现
+ */
+
+import type {
+    HttpRequestOptions,
+    HttpResponse,
+    ProxyConfig
+} from '../types';
+import { HttpError } from '../types';
+import { BaseHttpAdapter } from './base';
+import type {
+    AxiosProxyConfig,
+    AxiosRequestConfig
+} from 'axios';
+import axios from 'axios';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import * as https from 'https';
+import { EClientAdapter } from '../const';
+
+
+/**
+ * Axios 适配器
+ */
+export class AxiosAdapter extends BaseHttpAdapter {
+    public readonly name = EClientAdapter.axios as const;
+
+    /**
+     * 检查 Axios 是否可用
+     */
+    public isAvailable(): boolean {
+        return !!axios;
+    }
+
+    /**
+     * 发送请求
+     * @param options 请求选项
+     */
+    protected async sendRequest<T>(options: HttpRequestOptions): Promise<HttpResponse<T>> {
+        if (!this.isAvailable()) {
+            throw new Error('Axios is not available. Please install it: npm install axios');
+        }
+
+        const url = this.buildUrl(options.url, options.params);
+        const axiosConfig = this.buildAxiosConfig(options, url);
+
+        try {
+            const startTime = Date.now();
+            const axiosResponse = await axios(axiosConfig);
+            const duration = Date.now() - startTime;
+
+            this.logger?.debug('HTTP request completed', {
+                method: options.method,
+                url,
+                status: axiosResponse.status,
+                duration
+            });
+
+            // 转换为标准响应格式
+            const response: HttpResponse<T> = {
+                status: axiosResponse.status,
+                statusText: axiosResponse.statusText,
+                headers: this.normalizeHeaders(axiosResponse.headers),
+                data: axiosResponse.data,
+                config: options
+            };
+
+            return response;
+        } catch (error: any) {
+            throw this.handleAxiosError(error, options);
+        }
+    }
+
+    /**
+     * 构建 Axios 配置
+     * @param options 请求选项
+     * @param url 完整 URL
+     */
+    private buildAxiosConfig(options: HttpRequestOptions, url: string): AxiosRequestConfig {
+        const axiosConfig: AxiosRequestConfig = {
+            method: options.method.toLowerCase(),
+            url,
+            headers: options.headers || {},
+            timeout: options.timeout ?? this.requestConfig.timeout,
+            maxRedirects: this.requestConfig.maxRedirects,
+            maxContentLength: this.requestConfig.maxResponseBodySize,
+            maxBodyLength: this.requestConfig.maxRequestBodySize,
+            validateStatus: () => true,
+            httpsAgent: new https.Agent({
+                rejectUnauthorized: this.securityConfig.rejectUnauthorized
+            })
+        };
+
+        // 设置请求体
+        if (options.body !== undefined) {
+            axiosConfig.data = options.body;
+        }
+
+        // 设置响应类型
+        if (options.responseType) {
+            axiosConfig.responseType = options.responseType;
+        }
+
+        // 配置代理
+        this.configureAxiosProxy(axiosConfig, options);
+
+        return axiosConfig;
+    }
+
+    /**
+     * 配置 Axios 代理
+     * @param axiosConfig Axios 配置对象
+     * @param options 请求选项
+     */
+    private configureAxiosProxy(axiosConfig: AxiosRequestConfig, options: HttpRequestOptions): void {
+        // 设置代理（全局配置）
+        if (this.requestConfig.proxy) {
+            axiosConfig.proxy = this.buildProxyConfig(this.requestConfig.proxy);
+        } else {
+            // 显式的禁用代理, 防止axios默认从环境变量中 HTTP_PROXY、HTTPS_PROXY 读取代理配置. 
+            axiosConfig.proxy = false;
+        }
+
+        // 设置正向代理（如果请求元数据中包含代理信息）
+        const forwardProxyMeta = options.meta?.__forwardProxy;
+        if (forwardProxyMeta) {
+            this.applyForwardProxy(axiosConfig, forwardProxyMeta);
+        }
+    }
+
+    /**
+     * 应用正向代理配置
+     * @param axiosConfig Axios 配置对象
+     * @param forwardProxyMeta 正向代理元数据
+     */
+    private applyForwardProxy(
+        axiosConfig: AxiosRequestConfig,
+        forwardProxyMeta: { proxyUrl: string, isHttps: boolean }
+    ): void {
+        const { proxyUrl, isHttps } = forwardProxyMeta;
+
+        if (isHttps) {
+            // HTTPS 请求使用 HttpsProxyAgent，并应用证书校验配置
+            axiosConfig.httpsAgent = new HttpsProxyAgent(proxyUrl as `https://${ string }`, {
+                rejectUnauthorized: this.securityConfig.rejectUnauthorized
+            });
+            axiosConfig.proxy = false;
+            this.logger?.debug('Using HttpsProxyAgent for HTTPS request', {
+                proxyUrl,
+                rejectUnauthorized: this.securityConfig.rejectUnauthorized
+            });
+        } else {
+            // HTTP 请求直接设置 proxy
+            const parsedProxyUrl = new URL(proxyUrl);
+            axiosConfig.proxy = {
+                host: parsedProxyUrl.hostname,
+                port: Number(parsedProxyUrl.port),
+                protocol: 'http'
+            };
+
+            // 处理代理认证
+            if (parsedProxyUrl.username && parsedProxyUrl.password) {
+                axiosConfig.proxy.auth = {
+                    username: decodeURIComponent(parsedProxyUrl.username),
+                    password: decodeURIComponent(parsedProxyUrl.password)
+                };
+            }
+
+            this.logger?.debug('Using proxy for HTTP request', {
+                host: axiosConfig.proxy.host,
+                port: axiosConfig.proxy.port
+            });
+        }
+    }
+
+    /**
+     * 处理 Axios 错误
+     * @param error 错误对象
+     * @param options 请求选项
+     */
+    private handleAxiosError(error: any, options: HttpRequestOptions): HttpError {
+        if (error.isAxiosError) {
+            return new HttpError(
+                error.message,
+                error.code || 'AXIOS_ERROR',
+                error.response?.status,
+                error.response ? {
+                    status: error.response.status,
+                    statusText: error.response.statusText,
+                    headers: this.normalizeHeaders(error.response.headers),
+                    data: error.response.data,
+                    config: options
+                } : undefined,
+                options
+            );
+        }
+
+        return new HttpError(
+            error.message || 'Unknown error',
+            'UNKNOWN_ERROR',
+            undefined,
+            undefined,
+            options
+        );
+    }
+
+    /**
+     * 构建代理配置
+     * @param proxy 代理配置
+     */
+    private buildProxyConfig(proxy: ProxyConfig): AxiosProxyConfig {
+        const config: AxiosProxyConfig = {
+            host: proxy.host,
+            port: proxy.port,
+            protocol: proxy.protocol
+        };
+
+        if (proxy.auth) {
+            config.auth = {
+                username: proxy.auth.username,
+                password: proxy.auth.password
+            };
+        }
+
+        return config;
+    }
+}
+

package/src/adapter/base.ts

@@ -0,0 +1,180 @@
+/**
+ * HTTP 适配器基础实现
+ */
+
+import type {
+    IHttpAdapter,
+    HttpRequestOptions,
+    HttpResponse,
+    RequestConfig,
+    SecurityConfig,
+    ILogger
+} from '../types';
+import { CommonUtils } from '../utils';
+import type { EClientAdapter } from '../const';
+
+/**
+ * HTTP 适配器抽象基类
+ */
+export abstract class BaseHttpAdapter implements IHttpAdapter {
+    protected requestConfig: RequestConfig;
+    protected securityConfig: SecurityConfig;
+    protected logger?: ILogger;
+
+    constructor(requestConfig: RequestConfig, securityConfig: SecurityConfig, logger?: ILogger) {
+        this.requestConfig = requestConfig;
+        this.securityConfig = securityConfig;
+        this.logger = logger;
+    }
+
+    public abstract readonly name: EClientAdapter;
+
+    /**
+     * 发送 HTTP 请求（由子类实现）
+     * @param options 请求选项
+     */
+    protected abstract sendRequest<T>(options: HttpRequestOptions): Promise<HttpResponse<T>>;
+
+    /**
+     * 检查适配器是否可用
+     */
+    public abstract isAvailable(): boolean;
+
+    /**
+     * 发送请求（带重试机制）
+     * @param options 请求选项
+     */
+    public async request<T = any>(options: HttpRequestOptions): Promise<HttpResponse<T>> {
+        const retries = options.retries ?? this.requestConfig.retries;
+        const retryDelay = this.requestConfig.retryDelay;
+        const timeout = options.timeout ?? this.requestConfig.timeout;
+
+        // 合并选项
+        const finalOptions: HttpRequestOptions = {
+            ...options,
+            timeout
+        };
+
+        let lastError: any;
+
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                this.logger?.debug(`HTTP request attempt ${ attempt + 1 }/${ retries + 1 }`, {
+                    method: options.method,
+                    url: options.url,
+                    scenario: options.scenario
+                });
+
+                const response = await this.sendRequest<T>(finalOptions);
+
+                if (attempt > 0) {
+                    this.logger?.debug(`HTTP request succeeded after ${ attempt } retries`, {
+                        method: options.method,
+                        url: options.url,
+                        status: response.status
+                    });
+                }
+
+                return response;
+            } catch (error) {
+                lastError = error;
+
+                this.logger?.debug(`HTTP request attempt ${ attempt + 1 } failed`, {
+                    method: options.method,
+                    url: options.url,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+
+                // 最后一次尝试，不再重试
+                if (attempt === retries) {
+                    break;
+                }
+
+                // 等待后重试
+                await CommonUtils.delay(retryDelay * (attempt + 1));
+            }
+        }
+
+        // 所有尝试都失败了
+        this.logger?.debug('All HTTP request attempts failed', {
+            method: options.method,
+            url: options.url,
+            attempts: retries + 1,
+            error: lastError instanceof Error ? lastError.message : String(lastError)
+        });
+
+        throw lastError;
+    }
+
+    /**
+     * 更新请求配置
+     * @param config 新的请求配置
+     */
+    public updateConfig(config: Partial<RequestConfig>): void {
+        this.requestConfig = { ...this.requestConfig, ...config };
+    }
+
+    /**
+     * 设置日志记录器
+     * @param logger 日志记录器
+     */
+    public setLogger(logger: ILogger): void {
+        this.logger = logger;
+    }
+
+    /**
+     * 构建查询字符串
+     * @param params 查询参数
+     */
+    protected buildQueryString(params?: Record<string, string | number | boolean>): string {
+        if (!params || Object.keys(params).length === 0) {
+            return '';
+        }
+
+        const searchParams = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            searchParams.append(key, String(value));
+        }
+
+        return searchParams.toString();
+    }
+
+    /**
+     * 构建完整 URL
+     * @param url 基础 URL
+     * @param params 查询参数
+     */
+    protected buildUrl(url: string, params?: Record<string, string | number | boolean>): string {
+        const queryString = this.buildQueryString(params);
+        if (!queryString) {
+            return url;
+        }
+
+        const separator = url.includes('?') ? '&' : '?';
+        return `${ url }${ separator }${ queryString }`;
+    }
+
+    /**
+     * 标准化响应头
+     * @param headers 原始响应头
+     */
+    protected normalizeHeaders(headers: any): Record<string, string> {
+        const normalized: Record<string, string> = {};
+
+        if (!headers) {
+            return normalized;
+        }
+
+        // 处理不同的头格式
+        if (typeof headers === 'object') {
+            for (const [key, value] of Object.entries(headers)) {
+                if (value !== undefined && value !== null) {
+                    normalized[key.toLowerCase()] = String(value);
+                }
+            }
+        }
+
+        return normalized;
+    }
+}
+

package/src/adapter/index.ts

@@ -0,0 +1,3 @@
+export * from './base';
+export * from './axios.adapter';
+export * from './undici.adapter';

package/src/adapter/undici.adapter.ts

@@ -0,0 +1,282 @@
+/**
+ * Undici 适配器实现
+ */
+
+import type {
+    HttpRequestOptions,
+    HttpResponse,
+    ResponseType,
+} from '../types';
+import { HttpError } from '../types';
+import { BaseHttpAdapter } from './base';
+import undici, {
+    Agent,
+    ProxyAgent,
+    type Dispatcher
+} from 'undici';
+import { STATUS_CODES } from 'http';
+import { EClientAdapter } from '../const';
+
+/**
+ * Undici 适配器
+ */
+export class UndiciAdapter extends BaseHttpAdapter {
+    public readonly name = EClientAdapter.undici as const;
+
+    /**
+     * 检查 Undici 是否可用
+     */
+    public isAvailable(): boolean {
+        return !!undici;
+    }
+
+    /**
+     * 发送请求
+     * @param options 请求选项
+     */
+    protected async sendRequest<T>(options: HttpRequestOptions): Promise<HttpResponse<T>> {
+        if (!this.isAvailable()) {
+            throw new Error('Undici is not available. Please install it: npm install undici');
+        }
+
+        const fullUrl = this.buildUrl(options.url, options.params);
+        const headers = this.prepareHeaders(options.headers);
+        const body = this.prepareBody(options.body, headers);
+        const dispatcher = this.buildDispatcher(options);
+        const undiciOptions = this.buildUndiciOptions(options, headers, body, dispatcher);
+
+        try {
+            const startTime = Date.now();
+            const response = await undici.request(fullUrl, undiciOptions);
+            const duration = Date.now() - startTime;
+
+            this.logger?.debug('HTTP request completed', {
+                method: options.method,
+                url: fullUrl,
+                status: response.statusCode,
+                duration
+            });
+
+            const data = await this.readResponseBody<T>(response, options.responseType);
+
+            const httpResponse: HttpResponse<T> = {
+                status: response.statusCode,
+                statusText: this.getStatusText(response.statusCode),
+                headers: this.normalizeHeaders(response.headers),
+                data,
+                config: options
+            };
+
+            return httpResponse;
+        } catch (error: unknown) {
+            throw this.handleUndiciError(error, options);
+        }
+    }
+
+    /**
+     * 准备请求头
+     * @param headers 原始请求头
+     */
+    private prepareHeaders(headers?: Record<string, string | number | string[]>): Record<string, string | string[]> {
+        const prepared: Record<string, string | string[]> = {};
+        if (headers) {
+            for (const [key, value] of Object.entries(headers)) {
+                prepared[key] = typeof value === 'number' ? String(value) : value;
+            }
+        }
+        return prepared;
+    }
+
+    /**
+     * 准备请求体
+     * @param body 原始请求体
+     * @param headers 请求头
+     */
+    private prepareBody(body: any, headers: Record<string, string | string[]>): Dispatcher.DispatchOptions['body'] {
+        if (body === undefined) {
+            return undefined;
+        }
+
+        if (typeof body === 'object' && !(body instanceof Buffer)) {
+            // 自动设置 Content-Type
+            if (!headers['content-type'] && !headers['Content-Type']) {
+                headers['Content-Type'] = 'application/json';
+            }
+            return JSON.stringify(body);
+        }
+
+        return body;
+    }
+
+    /**
+     * 构建 Dispatcher（代理或 TLS 配置）
+     * @param options 请求选项
+     */
+    private buildDispatcher(options: HttpRequestOptions): Dispatcher | undefined {
+        let dispatcher: Dispatcher | undefined;
+
+        // 如果 rejectUnauthorized 为 false，需要创建 Agent 来设置 TLS 选项
+        if (!this.securityConfig.rejectUnauthorized) {
+            dispatcher = new Agent({
+                connect: {
+                    rejectUnauthorized: false
+                }
+            });
+        }
+
+        // 有代理时，创建 ProxyAgent
+        if (this.requestConfig.proxy) {
+            dispatcher = this.createGlobalProxyAgent();
+        }
+
+        // 设置正向代理（如果请求元数据中包含代理信息，会覆盖全局代理配置）
+        const forwardProxyMeta = options.meta?.__forwardProxy;
+        if (forwardProxyMeta) {
+            dispatcher = this.createForwardProxyAgent(forwardProxyMeta.proxyUrl);
+        }
+
+        return dispatcher;
+    }
+
+    /**
+     * 创建全局代理 Agent
+     */
+    private createGlobalProxyAgent(): ProxyAgent {
+        const { protocol, host, port, auth } = this.requestConfig.proxy!;
+        let proxyUrl = `${ protocol }://${ host }:${ port }`;
+
+        if (auth) {
+            const encodedUsername = encodeURIComponent(auth.username);
+            const encodedPassword = encodeURIComponent(auth.password);
+            proxyUrl = `${ protocol }://${ encodedUsername }:${ encodedPassword }@${ host }:${ port }`;
+        }
+
+        const agent = new ProxyAgent({
+            uri: proxyUrl,
+            connect: {
+                rejectUnauthorized: this.securityConfig.rejectUnauthorized
+            }
+        });
+
+        this.logger?.debug('Using ProxyAgent with global proxy config', {
+            host,
+            port,
+            protocol,
+            rejectUnauthorized: this.securityConfig.rejectUnauthorized
+        });
+
+        return agent;
+    }
+
+    /**
+     * 创建正向代理 Agent
+     * @param proxyUrl 代理 URL
+     */
+    private createForwardProxyAgent(proxyUrl: string): ProxyAgent {
+        const agent = new ProxyAgent({
+            uri: proxyUrl,
+            connect: {
+                rejectUnauthorized: this.securityConfig.rejectUnauthorized
+            }
+        });
+
+        this.logger?.debug('Using ProxyAgent for forward proxy (overrides global proxy)', {
+            proxyUrl,
+            rejectUnauthorized: this.securityConfig.rejectUnauthorized
+        });
+
+        return agent;
+    }
+
+    /**
+     * 构建 Undici 请求选项
+     */
+    private buildUndiciOptions(
+        options: HttpRequestOptions,
+        headers: Record<string, string | string[]>,
+        body: Dispatcher.DispatchOptions['body'],
+        dispatcher?: Dispatcher
+    ): Parameters<typeof undici.request>[1] {
+        return {
+            method: options.method as Dispatcher.HttpMethod,
+            headers,
+            body,
+            bodyTimeout: options.timeout ?? this.requestConfig.timeout,
+            headersTimeout: options.timeout ?? this.requestConfig.timeout,
+            maxRedirections: this.requestConfig.maxRedirects,
+            ...(dispatcher && { dispatcher }),
+        };
+    }
+
+    /**
+     * 处理 Undici 错误
+     * @param error 错误对象
+     * @param options 请求选项
+     */
+    private handleUndiciError(error: unknown, options: HttpRequestOptions): HttpError {
+        const errorMessage = error instanceof Error ? error.message : 'Undici request failed';
+        const errorCode = (error && typeof error === 'object' && 'code' in error && typeof error.code === 'string')
+            ? error.code
+            : 'UNDICI_ERROR';
+
+        return new HttpError(
+            errorMessage,
+            errorCode,
+            undefined,
+            undefined,
+            options
+        );
+    }
+
+    /**
+     * 读取响应体
+     * @param response Undici 响应对象
+     * @param responseType 响应类型
+     */
+    private async readResponseBody<T>(response: Dispatcher.ResponseData, responseType?: ResponseType): Promise<T> {
+        try {
+            switch (responseType) {
+                case 'text': {
+                    return (await response.body.text()) as T;
+                }
+                case 'arraybuffer': {
+                    return (await response.body.arrayBuffer()) as T;
+                }
+                case 'stream': {
+                    // undici 返回 BodyReadable (继承自 Node.js Readable)
+                    return response.body as T;
+                }
+                case 'blob': {
+                    return (await response.body.blob()) as T;
+                }
+                case 'formdata': {
+                    return (await response.body.formData()) as T;
+                }
+                case 'json': {
+                    return (await response.body.json()) as T;
+                }
+                default: {
+                    const text = await response.body.text();
+                    try {
+                        return JSON.parse(text) as T;
+                    } catch {
+                        // 如果不是有效的 JSON，返回原文本
+                        return text as T;
+                    }
+                }
+
+            }
+        } catch (error) {
+            throw new Error(`Failed to read response body: ${ error instanceof Error ? error.message : String(error) }`);
+        }
+    }
+
+    /**
+     * 获取状态文本
+     * @param statusCode 状态码
+     */
+    private getStatusText(statusCode: number): string {
+        return STATUS_CODES[statusCode] || 'Unknown';
+    }
+}
+