nstarter-http-request 0.1.0

package/docs/logging.md

@@ -0,0 +1,70 @@
+# 日志配置详解
+
+## 自定义日志记录器
+
+```typescript
+import { ILogger } from 'nstarter-http-request';
+
+const customLogger: ILogger = {
+  debug: (msg, meta) => console.debug(msg, meta),
+  info: (msg, meta) => console.info(msg, meta),
+  warn: (msg, meta) => console.warn(msg, meta),
+  error: (msg, meta) => console.error(msg, meta)
+};
+
+const client = new NsHttpClient({
+  logging: { logger: customLogger }
+});
+```
+
+## 日志过滤
+
+```typescript
+const client = new NsHttpClient({
+  logging: {
+    enabled: true,
+    filter: {
+      // 只记录失败的 POST 请求
+      methods: ['POST'],
+      onlyFailed: true,
+      minDuration: 1000  // 且耗时超过 1 秒
+    }
+  }
+});
+```
+
+## 完整日志配置示例
+
+```typescript
+const client = new NsHttpClient({
+  // 日志配置
+  logging: {
+    enabled: true,                   // 是否启用日志
+    logRequestBody: true,            // 是否记录请求体
+    logResponseBody: true,           // 是否记录响应体
+    bodyMaxLength: 1024 * 1024,      // 请求/响应体最大记录长度（字节，默认 1MB）
+    logger: customLogger,            // 自定义日志记录器（可选，实现 ILogger 接口）
+    httpLogger: customHttpLogger,    // 自定义 HTTP 日志记录器（可选，实现 IHttpClientLogger 接口）
+    filter: {                        // 日志过滤配置
+      methods: ['POST', 'PUT'],      // 只记录指定 HTTP 方法
+      urlPatterns: [                 // 只记录匹配的 URL（支持正则）
+        /\/api\//,
+        'https://api.example.com'
+      ],
+      scenarios: ['payment'],        // 只记录指定业务场景
+      statusCodes: [404, 500],       // 只记录指定状态码
+      statusCodeRanges: [            // 只记录指定状态码范围
+        { min: 400, max: 499 },      // 客户端错误
+        { min: 500, max: 599 }       // 服务端错误
+      ],
+      onlyFailed: false,             // 是否只记录失败请求
+      onlySuccess: false,             // 是否只记录成功请求
+      minDuration: 100,              // 只记录耗时超过指定毫秒的请求
+      customFilter: (options) => {   // 自定义过滤函数
+        return options.request.method === 'POST';
+      }
+    }
+  }
+});
+```
+

package/docs/proxy.md

@@ -0,0 +1,44 @@
+# 正向代理配置
+
+## 基础使用
+
+```typescript
+const client = new NsHttpClient()
+  .withForwardProxy({
+    enabled: true,
+    http_proxy: 'http://proxy.example.com:8080',
+    https_proxy: 'https://proxy.example.com:8443',
+    no_proxy: [          // 不使用代理的域名（支持传统模式）
+      'localhost',       // 精确匹配
+      '127.0.0.1',       // 精确匹配
+      '.internal.com',   // 后缀匹配（匹配所有子域名）
+      '.local',          // 后缀匹配
+      '192.168.'         // 前缀匹配（IP地址）
+    ]
+  });
+```
+
+## no_proxy 支持的模式
+
+- `example.com` - 精确匹配该域名
+- `.example.com` - 后缀匹配，匹配所有以 `.example.com` 结尾的域名（包括子域名）
+- `192.168.` - 前缀匹配，主要用于 IP 地址范围匹配
+
+## HTTP 代理配置（不同于正向代理）
+
+```typescript
+const client = new NsHttpClient({
+  request: {
+    proxy: {                         // HTTP 代理配置（可选，不同于正向代理）
+      host: 'proxy.example.com',
+      port: 8080,
+      protocol: 'http',              // 'http' | 'https'
+      auth: {                        // 代理认证（可选）
+        username: 'user',
+        password: 'pass'
+      }
+    }
+  }
+});
+```
+

package/docs/security.md

@@ -0,0 +1,56 @@
+# 安全配置详解
+
+## SSL 证书验证
+
+```typescript
+const client = new NsHttpClient({
+  security: {
+    rejectUnauthorized: true  // 生产环境必须为 true，开发环境可设为 false
+  }
+});
+```
+
+## SSRF 防护
+
+```typescript
+const client = new NsHttpClient({
+  security: {
+    enableDnsValidation: true,     // 启用 DNS 解析验证
+    enableIpValidation: true,      // 启用 IP 地址验证
+    allowPrivateIp: false,         // 禁止访问内网 IP（10.x.x.x, 192.168.x.x, 127.x.x.x 等）
+    whitelist: [                   // 白名单（支持以下模式）
+      'api.example.com',           // 1. 精确匹配
+      '*.safe.com',                // 2. 通配符匹配（只匹配一级子域名）
+      'trusted.com', '*.trusted.com' // 3. 组合使用：匹配根域名和一级子域名
+    ],
+    blacklist: ['malicious.com', '*.malicious.com'] // 黑名单：根域名 + 一级子域名
+  }
+});
+```
+
+## 支持的域名模式
+
+| 模式 | 匹配规则 | 示例 |
+|------|---------|------|
+| `example.com` | 精确匹配 | ✅ `example.com`<br>❌ `api.example.com` |
+| `*.example.com` | 通配符匹配<br>只匹配一级子域名（不含根域名） | ❌ `example.com`<br>✅ `api.example.com`<br>✅ `www.example.com`<br>❌ `v2.api.example.com`（多级不匹配） |
+| 组合使用<br>`['example.com', '*.example.com']` | 精确匹配 + 通配符匹配<br>匹配根域名和一级子域名 | ✅ `example.com`<br>✅ `api.example.com`<br>✅ `www.example.com`<br>❌ `v2.api.example.com`（多级不匹配） |
+
+## DNS 缓存机制
+
+为提升性能，DNS 解析结果会被缓存。缓存使用 [lru-cache](https://www.npmjs.com/package/lru-cache) 实现，具有以下特性：
+
+- ✅ **TTL 自动过期**：缓存条目到期后自动释放内存
+- ✅ **LRU 淘汰策略**：缓存满时自动淘汰最近最少使用的条目
+- ✅ **容量限制**：默认最多缓存 500 个域名解析结果
+- ✅ **可配置**：支持自定义 TTL 和缓存容量
+
+```typescript
+const client = new NsHttpClient({
+  security: {
+    dnsCacheTtl: 60000,       // 缓存时间：60 秒（默认）
+    dnsCacheMaxSize: 500      // 最大缓存条目数（默认）
+  }
+});
+```
+

package/docs/trace-context.md

@@ -0,0 +1,436 @@
+# W3C Trace Context 支持
+
+本 HTTP 客户端完全支持 [W3C Trace Context](https://www.w3.org/TR/trace-context/) 规范，允许你在分布式系统中进行跨服务的链路追踪。
+
+## 什么是 Trace Context？
+
+W3C Trace Context 定义了标准的 HTTP 头格式，用于在分布式系统中传播追踪上下文信息。核心是 `traceparent` 头，格式如下：
+
+```
+traceparent: version-trace-id-parent-id-trace-flags
+```
+
+例如：
+```
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
+```
+
+其中：
+- `version`（2位）：当前固定为 `00`
+- `trace-id`（32位十六进制）：唯一标识整个追踪链路
+- `parent-id`（16位十六进制）：唯一标识当前 span/操作
+- `trace-flags`（2位十六进制）：标志位，`01` 表示已采样，`00` 表示未采样
+
+## 基础使用
+
+### 1. 在请求中传递 traceparent
+
+```typescript
+import { NsHttpClient, TraceContext } from '@nstarter/plugin-http-request';
+
+const client = new NsHttpClient();
+
+// 生成新的 traceparent
+const traceparent = TraceContext.generate();
+
+// 在请求中使用
+const response = await client.get('https://api.example.com/users', {
+    traceparent
+});
+```
+
+### 2. 传播现有的 traceparent
+
+在微服务架构中，你通常需要从上游服务接收 traceparent 并传递给下游服务：
+
+```typescript
+// 从上游请求中获取 traceparent
+const incomingTraceparent = request.headers.traceparent;
+
+// 创建子 span 并传递给下游服务
+const childTraceparent = TraceContext.createChild(incomingTraceparent);
+
+const response = await client.post('https://downstream-service.com/api', data, {
+    traceparent: childTraceparent
+});
+```
+
+### 3. 自定义 traceparent 生成
+
+```typescript
+// 生成未采样的 traceparent
+const unsampled = TraceContext.generate({ sampled: false });
+
+// 使用自定义的 trace ID
+const customTrace = TraceContext.generate({
+    traceId: '0af7651916cd43dd8448eb211c80319c',
+    sampled: true
+});
+```
+
+## TraceContext 工具类
+
+`TraceContext` 类提供了完整的工具方法来处理 W3C Trace Context：
+
+### 生成方法
+
+```typescript
+// 生成新的 traceparent
+const traceparent = TraceContext.generate({
+    traceId?: string,    // 可选，自定义 trace ID
+    parentId?: string,   // 可选，自定义 parent/span ID
+    sampled?: boolean    // 可选，是否采样，默认 true
+});
+
+// 生成 trace ID（32位十六进制）
+const traceId = TraceContext.generateTraceId();
+
+// 生成 span ID（16位十六进制）
+const spanId = TraceContext.generateSpanId();
+```
+
+### 解析和验证
+
+```typescript
+// 解析 traceparent
+const parsed = TraceContext.parse('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+// 返回：
+// {
+//   version: '00',
+//   traceId: '0af7651916cd43dd8448eb211c80319c',
+//   parentId: 'b7ad6b7169203331',
+//   traceFlags: '01'
+// }
+
+// 验证 traceparent 是否有效
+const isValid = TraceContext.isValid('00-...-...-01'); // true or false
+
+// 验证 trace ID
+const isValidTraceId = TraceContext.isValidTraceId('0af7651916cd43dd8448eb211c80319c');
+
+// 验证 span ID
+const isValidSpanId = TraceContext.isValidSpanId('b7ad6b7169203331');
+```
+
+### 创建子 Span
+
+```typescript
+// 从父 traceparent 创建子 span
+const parentTraceparent = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01';
+const childTraceparent = TraceContext.createChild(parentTraceparent);
+
+// 子 span 会继承父 span 的 trace ID 和采样决策
+// 但会生成新的 span ID
+
+// 覆盖采样决策
+const unsampledChild = TraceContext.createChild(parentTraceparent, false);
+```
+
+### 检查采样状态
+
+```typescript
+// 检查 traceparent 是否已采样
+const sampled = TraceContext.isSampled('00-...-...-01'); // true
+const notSampled = TraceContext.isSampled('00-...-...-00'); // false
+```
+
+## 完整示例：微服务链路追踪
+
+### 服务 A（入口服务）
+
+```typescript
+import express from 'express';
+import { NsHttpClient, TraceContext } from '@nstarter/plugin-http-request';
+
+const app = express();
+const client = new NsHttpClient();
+
+app.get('/api/users/:id', async (req, res) => {
+    // 检查是否有上游的 traceparent
+    let traceparent = req.headers.traceparent as string;
+    
+    // 如果没有，生成新的
+    if (!traceparent || !TraceContext.isValid(traceparent)) {
+        traceparent = TraceContext.generate();
+        console.log('生成新的 trace:', traceparent);
+    }
+    
+    // 创建子 span 调用服务 B
+    const childTraceparent = TraceContext.createChild(traceparent);
+    
+    try {
+        const userResponse = await client.get(
+            `https://service-b.com/users/${req.params.id}`,
+            { traceparent: childTraceparent }
+        );
+        
+        res.json(userResponse.data);
+    } catch (error) {
+        console.error('Error with trace:', traceparent);
+        res.status(500).json({ error: 'Internal error' });
+    }
+});
+```
+
+### 服务 B（中间服务）
+
+```typescript
+import express from 'express';
+import { NsHttpClient, TraceContext } from '@nstarter/plugin-http-request';
+
+const app = express();
+const client = new NsHttpClient();
+
+app.get('/users/:id', async (req, res) => {
+    // 接收上游的 traceparent
+    const incomingTraceparent = req.headers.traceparent as string;
+    
+    if (!TraceContext.isValid(incomingTraceparent)) {
+        return res.status(400).json({ error: 'Invalid traceparent' });
+    }
+    
+    const parsed = TraceContext.parse(incomingTraceparent);
+    console.log('处理 trace:', parsed?.traceId);
+    
+    // 创建子 span 调用服务 C
+    const childTraceparent = TraceContext.createChild(incomingTraceparent);
+    
+    const ordersResponse = await client.get(
+        `https://service-c.com/orders?userId=${req.params.id}`,
+        { traceparent: childTraceparent }
+    );
+    
+    res.json({
+        user: { id: req.params.id },
+        orders: ordersResponse.data
+    });
+});
+```
+
+### 服务 C（下游服务）
+
+```typescript
+import express from 'express';
+import { TraceContext } from '@nstarter/plugin-http-request';
+
+const app = express();
+
+app.get('/orders', async (req, res) => {
+    // 接收上游的 traceparent
+    const traceparent = req.headers.traceparent as string;
+    
+    if (TraceContext.isValid(traceparent)) {
+        const parsed = TraceContext.parse(traceparent);
+        console.log('查询订单，trace:', parsed?.traceId);
+        console.log('当前 span:', parsed?.parentId);
+        console.log('已采样:', TraceContext.isSampled(traceparent));
+    }
+    
+    // 执行业务逻辑
+    const orders = await getOrdersByUserId(req.query.userId);
+    
+    res.json(orders);
+});
+```
+
+## 与追踪系统集成
+
+### 与 OpenTelemetry 集成
+
+```typescript
+import { trace } from '@opentelemetry/api';
+import { NsHttpClient, TraceContext } from '@nstarter/plugin-http-request';
+
+const tracer = trace.getTracer('my-service');
+const client = new NsHttpClient();
+
+async function makeTracedRequest() {
+    return tracer.startActiveSpan('http-request', async (span) => {
+        // 从 OpenTelemetry span 获取 trace context
+        const spanContext = span.spanContext();
+        const traceId = spanContext.traceId;
+        const spanId = spanContext.spanId;
+        const traceFlags = spanContext.traceFlags.toString(16).padStart(2, '0');
+        
+        // 生成 W3C traceparent
+        const traceparent = `00-${traceId}-${spanId}-${traceFlags}`;
+        
+        try {
+            const response = await client.get('https://api.example.com/data', {
+                traceparent
+            });
+            
+            span.setStatus({ code: SpanStatusCode.OK });
+            return response.data;
+        } catch (error) {
+            span.setStatus({ 
+                code: SpanStatusCode.ERROR,
+                message: error.message 
+            });
+            throw error;
+        } finally {
+            span.end();
+        }
+    });
+}
+```
+
+### 日志关联
+
+```typescript
+import { NsHttpClient, TraceContext } from '@nstarter/plugin-http-request';
+
+const client = new NsHttpClient();
+
+async function makeRequestWithLogging() {
+    const traceparent = TraceContext.generate();
+    const parsed = TraceContext.parse(traceparent);
+    
+    // 在日志中包含 trace ID，方便日志聚合和查询
+    console.log({
+        message: 'Making API request',
+        traceId: parsed?.traceId,
+        spanId: parsed?.parentId,
+        timestamp: new Date().toISOString()
+    });
+    
+    const response = await client.get('https://api.example.com/data', {
+        traceparent
+    });
+    
+    console.log({
+        message: 'API request completed',
+        traceId: parsed?.traceId,
+        spanId: parsed?.parentId,
+        status: response.status,
+        timestamp: new Date().toISOString()
+    });
+    
+    return response.data;
+}
+```
+
+## 最佳实践
+
+### 1. 始终验证 traceparent
+
+```typescript
+const traceparent = req.headers.traceparent as string;
+
+if (traceparent && TraceContext.isValid(traceparent)) {
+    // 使用有效的 traceparent
+} else {
+    // 生成新的或记录警告
+}
+```
+
+### 2. 创建子 span 而不是重用
+
+```typescript
+// ✅ 正确：创建子 span
+const childTraceparent = TraceContext.createChild(incomingTraceparent);
+await client.get(url, { traceparent: childTraceparent });
+
+// ❌ 错误：直接重用父 span
+await client.get(url, { traceparent: incomingTraceparent });
+```
+
+### 3. 在日志中包含 trace 信息
+
+```typescript
+const parsed = TraceContext.parse(traceparent);
+logger.info('Processing request', {
+    traceId: parsed?.traceId,
+    spanId: parsed?.parentId,
+    // 其他日志信息
+});
+```
+
+### 4. 采样策略
+
+```typescript
+// 根据业务需求决定是否采样
+const shouldSample = Math.random() < 0.1; // 10% 采样率
+
+const traceparent = TraceContext.generate({
+    sampled: shouldSample
+});
+
+// 或者基于特定条件
+const traceparent = TraceContext.generate({
+    sampled: request.path.includes('/api/critical')
+});
+```
+
+### 5. 错误处理
+
+```typescript
+try {
+    await client.get(url, { traceparent });
+} catch (error) {
+    // 在错误日志中包含 trace 信息，便于追踪问题
+    const parsed = TraceContext.parse(traceparent);
+    logger.error('Request failed', {
+        error: error.message,
+        traceId: parsed?.traceId,
+        spanId: parsed?.parentId
+    });
+    throw error;
+}
+```
+
+## 规范参考
+
+- [W3C Trace Context](https://www.w3.org/TR/trace-context/)
+- [W3C Trace Context Level 2](https://www.w3.org/TR/trace-context-2/)
+
+## API 文档
+
+### TraceContext
+
+完整的 API 文档：
+
+```typescript
+class TraceContext {
+    // 生成 traceparent
+    static generate(options?: TraceParentOptions): string;
+    
+    // 解析 traceparent
+    static parse(traceparent: string): TraceParent | null;
+    
+    // 验证 traceparent
+    static isValid(traceparent: string): boolean;
+    
+    // 创建子 span
+    static createChild(parentTraceparent: string, sampled?: boolean): string;
+    
+    // 检查是否采样
+    static isSampled(traceparent: string): boolean;
+    
+    // 生成 trace ID
+    static generateTraceId(): string;
+    
+    // 生成 span ID
+    static generateSpanId(): string;
+    
+    // 验证 trace ID
+    static isValidTraceId(traceId: string): boolean;
+    
+    // 验证 span ID
+    static isValidSpanId(spanId: string): boolean;
+}
+
+interface TraceParentOptions {
+    traceId?: string;    // 自定义 trace ID（32位十六进制）
+    parentId?: string;   // 自定义 parent ID（16位十六进制）
+    sampled?: boolean;   // 是否采样，默认 true
+}
+
+interface TraceParent {
+    version: string;     // 版本号，当前为 '00'
+    traceId: string;     // Trace ID（32位十六进制）
+    parentId: string;    // Parent/Span ID（16位十六进制）
+    traceFlags: string;  // Trace 标志位（2位十六进制）
+}
+```
+

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "nstarter-http-request",
+  "version": "0.1.0",
+  "description": "nstarter HTTP 请求客户端插件",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jiandaoyun/nstarter.git",
+    "directory": "packages/plugin-http-request"
+  },
+  "keywords": [
+    "nstarter",
+    "plugin",
+    "http"
+  ],
+  "scripts": {
+    "build": "rimraf dist && tsc --build tsconfig.json && tsc --build tsconfig.esm.json",
+    "test": "nyc --nycrc-path ../../.nycrc mocha --config .mocharc.yml",
+    "eslint": "eslint --ext .js,.ts --config ../../.eslintrc.js ./src",
+    "eslint:fix": "npm run eslint -- --fix",
+    "eslint:html": "npm run eslint -- --output-file ./lint/eslint.html --format html",
+    "clean": "rimraf dist && rimraf lint && rimraf coverage && rimraf .nyc_output",
+    "upload": "npm-publish ./"
+  },
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "default": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "dependencies": {
+    "axios": "^1.7.5",
+    "https-proxy-agent": "^7.0.6",
+    "lru-cache": "^11.2.4",
+    "undici": "^6.0.0"
+  },
+  "peerDependencies": {
+    "nstarter-core": ">=1.2.0 <2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "nock": "^14.0.10",
+    "nstarter-core": "*"
+  }
+}