nstarter-http-request 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+* 0.1.3
+    * 修复 `dns` 解析在 `ACK` 等带集群后缀的环境会 `ENOTFOUND`.
+    * 默认配置关闭 `ip` 与 `dns` 校验.
+
 * 0.1.2
     * 流处理修复
 

package/README.md

@@ -105,12 +105,12 @@ nx run-many -t test
 ```typescript
 import { NsHttpClient, EClientAdapter } from 'nstarter-http-request';
 
-// 创建客户端实例
+// 创建客户端实例（SSRF 防护默认关闭，如需开启请设置 security.enableDnsValidation / enableIpValidation 为 true）
 const client = new NsHttpClient({
   adapter: EClientAdapter.axios,
   security: {
-    enableDnsValidation: true,
-    enableIpValidation: true,
+    enableDnsValidation: false,
+    enableIpValidation: false,
     allowPrivateIp: false
   }
 });
@@ -127,7 +127,7 @@ const user = await client.post('https://api.example.com/users', {
 
 ### 完整配置示例
 
-详细配置说明请参考 [配置文档](./docs/configuration.md)
+详细配置说明请参考 [使用文档 - 完整配置](https://nstarter-docs.jdydevelop.com/docs/extension/plugins/http-request/configuration)
 
 ```typescript
 import { NsHttpClient, EClientAdapter } from 'nstarter-http-request';
@@ -135,8 +135,8 @@ import { NsHttpClient, EClientAdapter } from 'nstarter-http-request';
 const client = new NsHttpClient({
   adapter: EClientAdapter.axios,
   security: {
-    enableDnsValidation: true,
-    enableIpValidation: true,
+    enableDnsValidation: false,
+    enableIpValidation: false,
     allowPrivateIp: false
   },
   logging: {
@@ -151,10 +151,7 @@ const client = new NsHttpClient({
 
 ## 详细文档
 
-- [完整配置示例](./docs/configuration.md) - 所有配置选项的详细说明
-- [安全配置](./docs/security.md) - SSRF 防护、SSL 验证、域名黑白名单等安全特性
-- [日志配置](./docs/logging.md) - 日志记录、过滤、自定义日志器等
-- [正向代理配置](./docs/proxy.md) - HTTP/HTTPS 正向代理和 no_proxy 配置
-- [适配器切换](./docs/adapters.md) - Axios 和 Undici 适配器的选择与切换
-- [W3C Trace Context 支持](./docs/trace-context.md) - 分布式链路追踪支持
+完整配置、安全、日志、代理、适配器、W3C Trace Context 等说明已统一放在使用文档站点，请查看：
+
+- [nstarter-http-request 插件文档](https://nstarter-docs.jdydevelop.com/docs/extension/plugins/http-request/)
 

package/dist/cjs/const/config.const.js

@@ -13,8 +13,8 @@ exports.MAX_DNS_CACHE_TTL = 5 * 60 * 1000; // 300000ms (5 分钟)
  */
 exports.DEFAULT_SECURITY_CONFIG = {
     rejectUnauthorized: true,
-    enableDnsValidation: true,
-    enableIpValidation: true,
+    enableDnsValidation: false,
+    enableIpValidation: false,
     allowPrivateIp: false,
     whitelist: [],
     blacklist: [],

package/dist/cjs/const/config.const.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.const.js","sourceRoot":"","sources":["../../../src/const/config.const.ts"],"names":[],"mappings":";;;AAMA,6CAA8C;AAC9C,2CAAgF;AAEhF;;;GAGG;AACU,QAAA,iBAAiB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,mBAAmB;AAEnE;;GAEG;AACU,QAAA,uBAAuB,GAAmB;IACnD,kBAAkB,EAAE,IAAI;IACxB,mBAAmB,EAAE,IAAI;IACzB,kBAAkB,EAAE,IAAI;IACxB,cAAc,EAAE,KAAK;IACrB,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;IACb,WAAW,EAAE,iCAAqB;IAClC,eAAe,EAAE,sCAA0B;CAC9C,CAAC;AAEF;;GAEG;AACU,QAAA,sBAAsB,GAAkB;IACjD,OAAO,EAAE,IAAI;IACb,cAAc,EAAE,IAAI;IACpB,eAAe,EAAE,IAAI;IACrB,aAAa,EAAE,IAAI,GAAG,IAAI,CAAC,MAAM;CACpC,CAAC;AAEF;;GAEG;AACU,QAAA,sBAAsB,GAAkB;IACjD,OAAO,EAAE,KAAK,EAAE,OAAO;IACvB,OAAO,EAAE,CAAC;IACV,UAAU,EAAE,IAAI,EAAE,MAAM;IACxB,YAAY,EAAE,CAAC;IACf,kBAAkB,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,OAAO;IAC7C,mBAAmB,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,OAAO;CAChD,CAAC;AAEF;;GAEG;AACU,QAAA,0BAA0B,GAAqB;IACxD,OAAO,EAAE,2BAAc,CAAC,KAAK;IAC7B,QAAQ,EAAE,+BAAuB;IACjC,OAAO,EAAE,8BAAsB;IAC/B,OAAO,EAAE,8BAAsB;CAClC,CAAC"}
+{"version":3,"file":"config.const.js","sourceRoot":"","sources":["../../../src/const/config.const.ts"],"names":[],"mappings":";;;AAMA,6CAA8C;AAC9C,2CAAgF;AAEhF;;;GAGG;AACU,QAAA,iBAAiB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,mBAAmB;AAEnE;;GAEG;AACU,QAAA,uBAAuB,GAAmB;IACnD,kBAAkB,EAAE,IAAI;IACxB,mBAAmB,EAAE,KAAK;IAC1B,kBAAkB,EAAE,KAAK;IACzB,cAAc,EAAE,KAAK;IACrB,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;IACb,WAAW,EAAE,iCAAqB;IAClC,eAAe,EAAE,sCAA0B;CAC9C,CAAC;AAEF;;GAEG;AACU,QAAA,sBAAsB,GAAkB;IACjD,OAAO,EAAE,IAAI;IACb,cAAc,EAAE,IAAI;IACpB,eAAe,EAAE,IAAI;IACrB,aAAa,EAAE,IAAI,GAAG,IAAI,CAAC,MAAM;CACpC,CAAC;AAEF;;GAEG;AACU,QAAA,sBAAsB,GAAkB;IACjD,OAAO,EAAE,KAAK,EAAE,OAAO;IACvB,OAAO,EAAE,CAAC;IACV,UAAU,EAAE,IAAI,EAAE,MAAM;IACxB,YAAY,EAAE,CAAC;IACf,kBAAkB,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,OAAO;IAC7C,mBAAmB,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,OAAO;CAChD,CAAC;AAEF;;GAEG;AACU,QAAA,0BAA0B,GAAqB;IACxD,OAAO,EAAE,2BAAc,CAAC,KAAK;IAC7B,QAAQ,EAAE,+BAAuB;IACjC,OAAO,EAAE,8BAAsB;IAC/B,OAAO,EAAE,8BAAsB;CAClC,CAAC"}

package/dist/cjs/security/dns.validator.js

@@ -55,6 +55,19 @@ class DnsValidator {
             catch {
                 // IPv6 解析失败
             }
+            // resolve4/resolve6 不拼接 search 域，在 ACK 等带集群后缀的环境会 ENOTFOUND；
+            // 失败时回退到 lookup（走 getaddrinfo，会按 resolv.conf 拼 search），与建连时行为一致
+            if (addresses.length === 0) {
+                try {
+                    const lookupResult = await utils_1.CommonUtils.withTimeout(node_dns_1.promises.lookup(hostname, { all: true }), this.resolveTimeout, 'DNS lookup timed out');
+                    for (const { address } of lookupResult) {
+                        addresses.push(address);
+                    }
+                }
+                catch {
+                    // lookup 也失败，下面统一抛错
+                }
+            }
             if (addresses.length === 0) {
                 throw new Error(`Unable to resolve hostname: ${hostname}`);
             }

package/dist/cjs/security/dns.validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"dns.validator.js","sourceRoot":"","sources":["../../../src/security/dns.validator.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,uCAA2C;AAC3C,yCAAqC;AACrC,oCAAuC;AACvC,oCAIkB;AAIlB,iDAA6C;AAG7C;;GAEG;AACH,MAAa,YAAY;IAKrB,YACI,QAAQ,GAAG,6BAAqB,EAChC,cAAc,GAAG,mCAA2B,EAC5C,YAAY,GAAG,kCAA0B;QAEzC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,IAAI,CAAC,KAAK,GAAG,IAAI,oBAAQ,CAAoB;YACzC,GAAG,EAAE,YAAY;YACjB,GAAG,EAAE,QAAQ;YACb,cAAc;YACd,YAAY,EAAE,IAAI;YAClB,mBAAmB;YACnB,cAAc,EAAE,IAAI;YACpB,sBAAsB;YACtB,cAAc,EAAE,IAAI;SACvB,CAAC,CAAC;IACP,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,OAAO,CAAC,QAAgB;QACjC,OAAO;QACP,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,MAAM,EAAE,CAAC;YACT,OAAO,MAAM,CAAC;QAClB,CAAC;QAED,IAAI,CAAC;YACD,mBAAmB;YACnB,MAAM,SAAS,GAAa,EAAE,CAAC;YAE/B,IAAI,CAAC;gBACD,MAAM,aAAa,GAAG,MAAM,mBAAW,CAAC,WAAW,CAAC,mBAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,0BAA0B,CAAC,CAAC;gBAC7H,SAAS,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC;YACrC,CAAC;YAAC,MAAM,CAAC;gBACL,sBAAsB;YAC1B,CAAC;YAED,IAAI,CAAC;gBACD,MAAM,aAAa,GAAG,MAAM,mBAAW,CAAC,WAAW,CAAC,mBAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,0BAA0B,CAAC,CAAC;gBAC7H,SAAS,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC;YACrC,CAAC;YAAC,MAAM,CAAC;gBACL,YAAY;YAChB,CAAC;YAED,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CAAC,+BAAgC,QAAS,EAAE,CAAC,CAAC;YACjE,CAAC;YAED,MAAM,MAAM,GAAc;gBACtB,QAAQ;gBACR,SAAS;gBACT,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;gBACrB,GAAG,EAAE,IAAI,CAAC,QAAQ;aACrB,CAAC;YAEF,gCAAgC;YAChC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAEjC,OAAO,MAAM,CAAC;QAClB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACX,6BAA8B,QAAS,KAAM,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAE,EAAE,CACzG,CAAC;QACN,CAAC;IACL,CAAC;IAGD;;;;;OAKG;IACI,KAAK,CAAC,kBAAkB,CAC3B,QAAgB,EAChB,cAAc,GAAG,KAAK;QAEtB,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC/C,MAAM,iBAAiB,GAAG,0BAAW,CAAC,YAAY,CAAC,SAAS,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QAExF,MAAM,UAAU,GAAG,iBAAiB;aAC/B,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC/B,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAE9B,OAAO;YACH,SAAS;YACT,QAAQ,EAAE,UAAU,CAAC,MAAM,KAAK,CAAC;YACjC,UAAU;SACb,CAAC;IACN,CAAC;IAED;;OAEG;IACI,UAAU;QACb,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED;;;OAGG;IACI,aAAa,CAAC,QAAgB;QACjC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAED;;;OAGG;IACI,YAAY;QACf,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACI,iBAAiB;QACpB,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACI,eAAe;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACI,QAAQ,CAAC,QAAgB;QAC5B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;CACJ;AApJD,oCAoJC"}
+{"version":3,"file":"dns.validator.js","sourceRoot":"","sources":["../../../src/security/dns.validator.ts"],"names":[],"mappings":"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"}

package/dist/esm/const/config.const.js

@@ -10,8 +10,8 @@ export const MAX_DNS_CACHE_TTL = 5 * 60 * 1000; // 300000ms (5 分钟)
  */
 export const DEFAULT_SECURITY_CONFIG = {
     rejectUnauthorized: true,
-    enableDnsValidation: true,
-    enableIpValidation: true,
+    enableDnsValidation: false,
+    enableIpValidation: false,
     allowPrivateIp: false,
     whitelist: [],
     blacklist: [],

package/dist/esm/const/config.const.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.const.js","sourceRoot":"","sources":["../../../src/const/config.const.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,mBAAmB;AAEnE;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAmB;IACnD,kBAAkB,EAAE,IAAI;IACxB,mBAAmB,EAAE,IAAI;IACzB,kBAAkB,EAAE,IAAI;IACxB,cAAc,EAAE,KAAK;IACrB,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;IACb,WAAW,EAAE,qBAAqB;IAClC,eAAe,EAAE,0BAA0B;CAC9C,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAkB;IACjD,OAAO,EAAE,IAAI;IACb,cAAc,EAAE,IAAI;IACpB,eAAe,EAAE,IAAI;IACrB,aAAa,EAAE,IAAI,GAAG,IAAI,CAAC,MAAM;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAkB;IACjD,OAAO,EAAE,KAAK,EAAE,OAAO;IACvB,OAAO,EAAE,CAAC;IACV,UAAU,EAAE,IAAI,EAAE,MAAM;IACxB,YAAY,EAAE,CAAC;IACf,kBAAkB,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,OAAO;IAC7C,mBAAmB,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,OAAO;CAChD,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAqB;IACxD,OAAO,EAAE,cAAc,CAAC,KAAK;IAC7B,QAAQ,EAAE,uBAAuB;IACjC,OAAO,EAAE,sBAAsB;IAC/B,OAAO,EAAE,sBAAsB;CAClC,CAAC"}
+{"version":3,"file":"config.const.js","sourceRoot":"","sources":["../../../src/const/config.const.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,mBAAmB;AAEnE;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAmB;IACnD,kBAAkB,EAAE,IAAI;IACxB,mBAAmB,EAAE,KAAK;IAC1B,kBAAkB,EAAE,KAAK;IACzB,cAAc,EAAE,KAAK;IACrB,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;IACb,WAAW,EAAE,qBAAqB;IAClC,eAAe,EAAE,0BAA0B;CAC9C,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAkB;IACjD,OAAO,EAAE,IAAI;IACb,cAAc,EAAE,IAAI;IACpB,eAAe,EAAE,IAAI;IACrB,aAAa,EAAE,IAAI,GAAG,IAAI,CAAC,MAAM;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAkB;IACjD,OAAO,EAAE,KAAK,EAAE,OAAO;IACvB,OAAO,EAAE,CAAC;IACV,UAAU,EAAE,IAAI,EAAE,MAAM;IACxB,YAAY,EAAE,CAAC;IACf,kBAAkB,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,OAAO;IAC7C,mBAAmB,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,OAAO;CAChD,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAqB;IACxD,OAAO,EAAE,cAAc,CAAC,KAAK;IAC7B,QAAQ,EAAE,uBAAuB;IACjC,OAAO,EAAE,sBAAsB;IAC/B,OAAO,EAAE,sBAAsB;CAClC,CAAC"}

package/dist/esm/security/dns.validator.js

@@ -52,6 +52,19 @@ export class DnsValidator {
             catch {
                 // IPv6 解析失败
             }
+            // resolve4/resolve6 不拼接 search 域，在 ACK 等带集群后缀的环境会 ENOTFOUND；
+            // 失败时回退到 lookup（走 getaddrinfo，会按 resolv.conf 拼 search），与建连时行为一致
+            if (addresses.length === 0) {
+                try {
+                    const lookupResult = await CommonUtils.withTimeout(dns.lookup(hostname, { all: true }), this.resolveTimeout, 'DNS lookup timed out');
+                    for (const { address } of lookupResult) {
+                        addresses.push(address);
+                    }
+                }
+                catch {
+                    // lookup 也失败，下面统一抛错
+                }
+            }
             if (addresses.length === 0) {
                 throw new Error(`Unable to resolve hostname: ${hostname}`);
             }

package/dist/esm/security/dns.validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"dns.validator.js","sourceRoot":"","sources":["../../../src/security/dns.validator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dns.validator.js","sourceRoot":"","sources":["../../../src/security/dns.validator.ts"],"names":[],"mappings":"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"}

package/dist/types/security/dns.validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dns.validator.d.ts","sourceRoot":"","sources":["../../../src/security/dns.validator.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,OAAO,KAAK,EACR,SAAS,EACZ,MAAM,UAAU,CAAC;AAIlB;;GAEG;AACH,qBAAa,YAAY;IACrB,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,cAAc,CAAS;gBAG3B,QAAQ,SAAwB,EAChC,cAAc,SAA8B,EAC5C,YAAY,SAA6B;IAgB7C;;;;OAIG;IACU,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAgD1D;;;;;OAKG;IACU,kBAAkB,CAC3B,QAAQ,EAAE,MAAM,EAChB,cAAc,UAAQ,GACvB,OAAO,CAAC;QAAE,SAAS,EAAE,SAAS,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAe7E;;OAEG;IACI,UAAU,IAAI,IAAI;IAIzB;;;OAGG;IACI,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI5C;;;OAGG;IACI,YAAY,IAAI,MAAM;IAI7B;;;OAGG;IACI,iBAAiB,IAAI,IAAI;IAIhC;;;OAGG;IACI,eAAe,IAAI,MAAM;IAIhC;;;;OAIG;IACI,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;CAG7C"}
+{"version":3,"file":"dns.validator.d.ts","sourceRoot":"","sources":["../../../src/security/dns.validator.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,OAAO,KAAK,EACR,SAAS,EACZ,MAAM,UAAU,CAAC;AAIlB;;GAEG;AACH,qBAAa,YAAY;IACrB,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,cAAc,CAAS;gBAG3B,QAAQ,SAAwB,EAChC,cAAc,SAA8B,EAC5C,YAAY,SAA6B;IAgB7C;;;;OAIG;IACU,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAiE1D;;;;;OAKG;IACU,kBAAkB,CAC3B,QAAQ,EAAE,MAAM,EAChB,cAAc,UAAQ,GACvB,OAAO,CAAC;QAAE,SAAS,EAAE,SAAS,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAe7E;;OAEG;IACI,UAAU,IAAI,IAAI;IAIzB;;;OAGG;IACI,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI5C;;;OAGG;IACI,YAAY,IAAI,MAAM;IAI7B;;;OAGG;IACI,iBAAiB,IAAI,IAAI;IAIhC;;;OAGG;IACI,eAAe,IAAI,MAAM;IAIhC;;;;OAIG;IACI,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;CAG7C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nstarter-http-request",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "nstarter HTTP 请求客户端插件",
   "license": "MIT",
   "repository": {

package/src/const/config.const.ts

@@ -18,8 +18,8 @@ export const MAX_DNS_CACHE_TTL = 5 * 60 * 1000; // 300000ms (5 分钟)
  */
 export const DEFAULT_SECURITY_CONFIG: SecurityConfig = {
     rejectUnauthorized: true,
-    enableDnsValidation: true,
-    enableIpValidation: true,
+    enableDnsValidation: false,
+    enableIpValidation: false,
     allowPrivateIp: false,
     whitelist: [],
     blacklist: [],

package/src/security/dns.validator.ts

@@ -73,6 +73,23 @@ export class DnsValidator {
                 // IPv6 解析失败
             }
 
+            // resolve4/resolve6 不拼接 search 域，在 ACK 等带集群后缀的环境会 ENOTFOUND；
+            // 失败时回退到 lookup（走 getaddrinfo，会按 resolv.conf 拼 search），与建连时行为一致
+            if (addresses.length === 0) {
+                try {
+                    const lookupResult = await CommonUtils.withTimeout(
+                        dns.lookup(hostname, { all: true }),
+                        this.resolveTimeout,
+                        'DNS lookup timed out'
+                    );
+                    for (const { address } of lookupResult) {
+                        addresses.push(address);
+                    }
+                } catch {
+                    // lookup 也失败，下面统一抛错
+                }
+            }
+
             if (addresses.length === 0) {
                 throw new Error(`Unable to resolve hostname: ${ hostname }`);
             }

package/docs/adapters.md

@@ -1,53 +0,0 @@
-# 适配器切换
-
-## 支持的适配器
-
-本库支持多种 HTTP 客户端适配器，你可以根据场景选择最适合的：
-
-- **Axios** - 适合通用场景，功能丰富，生态完善
-- **Undici** - Node.js 原生高性能 HTTP 客户端，适合高并发场景
-
-## 切换适配器
-
-```typescript
-import { EClientAdapter } from 'nstarter-http-request';
-
-// 使用 Axios 适配器（适合通用场景）
-const axiosClient = new NsHttpClient().withAdapter(EClientAdapter.axios);
-
-// 使用 Undici 适配器（高性能，Node.js 原生）
-const undiciClient = new NsHttpClient().withAdapter(EClientAdapter.undici);
-```
-
-## 在初始化时指定适配器
-
-```typescript
-import { NsHttpClient, EClientAdapter } from 'nstarter-http-request';
-
-// 创建客户端实例时指定适配器
-const client = new NsHttpClient({
-  adapter: EClientAdapter.axios,
-  security: {
-    enableDnsValidation: true,
-    enableIpValidation: true,
-    allowPrivateIp: false
-  }
-});
-```
-
-## 适配器选择建议
-
-### 使用 Axios 的场景
-
-- 需要丰富的配置选项
-- 需要拦截器功能
-- 需要广泛的浏览器兼容性（通过 polyfill）
-- 团队熟悉 Axios API
-
-### 使用 Undici 的场景
-
-- 需要极致性能
-- 高并发场景
-- 纯 Node.js 环境
-- 希望减少依赖体积
-

package/docs/configuration.md

@@ -1,149 +0,0 @@
-# 完整配置示例
-
-以下是一个包含所有配置选项的完整示例：
-
-```typescript
-import { NsHttpClient, EClientAdapter } from 'nstarter-http-request';
-
-const client = new NsHttpClient({
-  // 适配器配置
-  adapter: EClientAdapter.axios,
-
-  // 安全配置
-  security: {
-    rejectUnauthorized: true,        // 是否验证 SSL 证书（生产环境建议 true）
-    enableDnsValidation: true,       // 开启 DNS 验证
-    enableIpValidation: true,        // 开启 IP 验证
-    allowPrivateIp: false,           // 是否允许访问私有 IP（内网地址）
-    whitelist: [                     // 域名白名单
-      'trusted.com', '*.trusted.com', // 匹配根域名和一级子域名
-      'api.example.com'               // 仅匹配该域名
-    ],
-    blacklist: [                     // 域名黑名单
-      'malicious.com', '*.malicious.com', // 根域名和一级子域名
-      'unsafe.net'
-    ],
-    dnsCacheTtl: 60000,              // DNS 缓存 TTL（毫秒，默认 60 秒）
-    dnsCacheMaxSize: 500             // DNS 缓存最大条目数（默认 500，使用 LRU 淘汰策略）
-  },
-
-  // 日志配置
-  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';
-      }
-    }
-  },
-
-  // 请求配置
-  request: {
-    timeout: 30000,                  // 请求超时（毫秒，默认 30 秒）
-    retries: 3,                      // 重试次数（默认 0）
-    retryDelay: 1000,                // 重试延迟（毫秒，默认 1 秒）
-    maxRedirects: 5,                 // 最大重定向次数（默认 5）
-    maxRequestBodySize: 10 * 1024 * 1024,   // 最大请求体大小（字节，默认 10MB）
-    maxResponseBodySize: 50 * 1024 * 1024,  // 最大响应体大小（字节，默认 50MB）
-    proxy: {                         // HTTP 代理配置（可选，不同于正向代理）
-      host: 'proxy.example.com',
-      port: 8080,
-      protocol: 'http',              // 'http' | 'https'
-      auth: {                        // 代理认证（可选）
-        username: 'user',
-        password: 'pass'
-      }
-    }
-  }
-});
-```
-
-## 配置说明
-
-### 适配器配置
-
-- `adapter`: 指定使用的 HTTP 客户端适配器，可选值：`EClientAdapter.axios` 或 `EClientAdapter.undici`
-
-### 安全配置
-
-详细说明请参考 [安全配置文档](./security.md)
-
-### 日志配置
-
-详细说明请参考 [日志配置文档](./logging.md)
-
-### 请求配置
-
-- `timeout`: 请求超时时间（毫秒）
-- `retries`: 请求失败时的重试次数
-- `retryDelay`: 重试延迟时间（毫秒）
-- `maxRedirects`: 最大重定向次数
-- `maxRequestBodySize`: 最大请求体大小限制（字节）
-- `maxResponseBodySize`: 最大响应体大小限制（字节）
-- `proxy`: HTTP 代理配置（注意：这与正向代理不同，详见 [代理配置文档](./proxy.md)）
-
-## 默认配置值
-
-以下是所有配置项的默认值，如果你不指定某个配置项，将使用以下默认值：
-
-### 适配器配置
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `adapter` | `EClientAdapter.axios` | 默认使用 Axios 适配器 |
-
-### 安全配置
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `rejectUnauthorized` | `true` | 默认验证 SSL 证书（生产环境建议保持为 true） |
-| `enableDnsValidation` | `true` | 默认启用 DNS 验证 |
-| `enableIpValidation` | `true` | 默认启用 IP 验证 |
-| `allowPrivateIp` | `false` | 默认禁止访问私有 IP（内网地址） |
-| `whitelist` | `[]` | 默认无白名单 |
-| `blacklist` | `[]` | 默认无黑名单 |
-| `dnsCacheTtl` | `60000` | DNS 缓存 TTL，默认 60 秒（60000 毫秒） |
-| `dnsCacheMaxSize` | `500` | DNS 缓存最大条目数，默认 500，使用 LRU 淘汰策略 |
-
-> **注意**：DNS 缓存最大 TTL 限制为 5 分钟（300000 毫秒），即使设置更大的值也会被限制为 5 分钟，避免过长的缓存时间导致内存积压。
-
-### 日志配置
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `enabled` | `true` | 默认启用日志 |
-| `logRequestBody` | `true` | 默认记录请求体 |
-| `logResponseBody` | `true` | 默认记录响应体 |
-| `bodyMaxLength` | `1048576` | 请求/响应体最大记录长度，默认 1MB（1024 * 1024 字节） |
-
-### 请求配置
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `timeout` | `30000` | 请求超时时间，默认 30 秒（30000 毫秒） |
-| `retries` | `0` | 默认不重试 |
-| `retryDelay` | `1000` | 重试延迟时间，默认 1 秒（1000 毫秒） |
-| `maxRedirects` | `5` | 最大重定向次数，默认 5 次 |
-| `maxRequestBodySize` | `10485760` | 最大请求体大小，默认 10MB（10 * 1024 * 1024 字节） |
-| `maxResponseBodySize` | `52428800` | 最大响应体大小，默认 50MB（50 * 1024 * 1024 字节） |
-| `proxy` | `undefined` | 默认不使用 HTTP 代理 |
-

package/docs/logging.md

@@ -1,70 +0,0 @@
-# 日志配置详解
-
-## 自定义日志记录器
-
-```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

@@ -1,44 +0,0 @@
-# 正向代理配置
-
-## 基础使用
-
-```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

@@ -1,56 +0,0 @@
-# 安全配置详解
-
-## 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

@@ -1,436 +0,0 @@
-# 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位十六进制）
-}
-```
-