Undici使用指南与问题攻克

一、项目速览：Node.js高性能HTTP客户端

核心价值主张

Undici是专为Node.js打造的HTTP/1.1协议（超文本传输协议第1.1版）客户端，以意大利语"十一"命名，象征对HTTP/1.1协议的深度优化。其核心价值在于通过从头设计的架构，提供比传统HTTP客户端更高的吞吐量和更低的延迟，特别适合需要处理大量并发请求的Node.js应用。

技术特性对比

特性	Undici	Node.js内置http模块
连接池	内置高效连接池	基础连接管理
管道支持	原生支持请求管道	需手动实现
性能	高吞吐量，低延迟	中等性能
API设计	现代化Promise API	传统回调模式
内存占用	优化的资源利用	较高内存消耗

适用场景说明

• 微服务架构中的服务间通信
• 高并发API请求处理
• 数据抓取与爬虫开发
• 实时数据流处理
• 需要低延迟网络操作的应用

二、核心操作：场景化任务实践

场景一：构建基础API请求

📌 三步掌握API数据获取

1. 安装依赖

# 使用npm安装Undici
npm install undici

2. 引入模块并发送请求

// 导入Undici的request方法
const { request } = require('undici');

async function getApiData() {
  try {
    // 发送GET请求到目标API
    const { statusCode, body } = await request('https://api.example.com/data');
    
    // 检查响应状态码
    if (statusCode === 200) {
      // 解析响应体为JSON
      const data = await body.json();
      console.log('API响应数据:', data);
      return data;
    } else {
      console.error('请求失败，状态码:', statusCode);
    }
  } catch (error) {
    console.error('请求发生错误:', error);
  }
}

// 调用函数
getApiData();

3. 处理响应数据

// 扩展上面的示例，添加数据处理逻辑
async function processApiData() {
  const data = await getApiData();
  if (data) {
    // 对数据进行处理和转换
    const processed = data.map(item => ({
      id: item.id,
      name: item.name.toUpperCase(),
      timestamp: new Date(item.createdAt).toLocaleString()
    }));
    return processed;
  }
}

⚠️ 注意事项：

始终处理可能的异常，包括网络错误、超时和非预期的响应状态码。生产环境中建议添加重试机制。

场景二：文件上传与表单提交

📌 文件上传三步法

1. 准备表单数据

const { request } = require('undici');
const fs = require('fs');

async function uploadFile() {
  // 创建表单数据
  const formData = new FormData();
  formData.append('file', fs.createReadStream('./document.pdf'), 'document.pdf');
  formData.append('description', 'API文档');

2. 配置请求选项

  // 配置请求参数
  const options = {
    method: 'POST',
    headers: formData.getHeaders(),
    body: formData
  };

3. 发送上传请求

  try {
    const { statusCode, body } = await request('https://api.example.com/upload', options);
    const response = await body.json();
    
    if (statusCode === 201) {
      console.log('文件上传成功:', response);
      return response;
    } else {
      console.error('上传失败:', response);
    }
  } catch (error) {
    console.error('上传发生错误:', error);
  }
}

最佳实践专栏：连接池优化

const { Agent } = require('undici');

// 创建自定义连接池配置
const agent = new Agent({
  // 最大连接数
  connections: 100,
  // 每个连接的最大请求数
  pipelining: 10,
  // 连接超时时间(毫秒)
  connectTimeout: 5000,
  // 保持连接活跃的时间(毫秒)
  keepAliveTimeout: 30000
});

// 在请求中使用自定义agent
async function optimizedRequest() {
  return request('https://api.example.com/data', { agent });
}

三、故障排查：错误类型与解决方案

超时错误 (TimeoutError)

错误特征

请求在指定时间内未得到响应，抛出TimeoutError异常。

排查流程

1. 检查网络连接是否稳定
2. 验证目标服务器响应时间
3. 确认超时设置是否合理

解决方案

const { request, TimeoutError } = require('undici');

async function requestWithTimeout() {
  try {
    return await request('https://api.example.com/data', {
      // 设置超时时间为5秒
      timeout: 5000,
      // 配置重试策略
      retry: {
        limit: 3,
        delay: {
          min: 100,
          max: 500
        }
      }
    });
  } catch (error) {
    if (error instanceof TimeoutError) {
      console.error('请求超时，已自动重试');
      // 可以实现更复杂的退避策略
    }
    throw error;
  }
}

预防方案

• 根据网络状况动态调整超时时间
• 实现指数退避重试机制
• 对重要请求使用请求队列控制并发量

连接错误 (ConnectError)

错误特征

无法建立与服务器的连接，通常表现为ECONNREFUSED或类似错误。

排查流程

1. 验证目标服务器地址和端口是否正确
2. 检查防火墙和网络策略
3. 确认服务器是否正常运行

解决方案

async function robustConnect() {
  const maxRetries = 3;
  let retries = 0;
  
  while (retries < maxRetries) {
    try {
      return await request('https://api.example.com/data');
    } catch (error) {
      retries++;
      if (retries >= maxRetries || !isConnectionError(error)) {
        throw error;
      }
      // 指数退避重试
      const delay = Math.pow(2, retries) * 100;
      console.log(`连接失败，${delay}ms后重试(${retries}/${maxRetries})`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

// 辅助函数：判断是否为连接错误
function isConnectionError(error) {
  return error.code === 'ECONNREFUSED' || 
         error.code === 'ENETUNREACH' ||
         error.code === 'EHOSTUNREACH';
}

最佳实践专栏：错误监控与日志

const { request } = require('undici');
const winston = require('winston');

// 配置日志记录器
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [new winston.transports.File({ filename: 'undici-errors.log' })]
});

async function monitoredRequest(url) {
  const start = Date.now();
  try {
    const response = await request(url);
    logger.info({
      type: 'request_success',
      url,
      duration: Date.now() - start,
      statusCode: response.statusCode
    });
    return response;
  } catch (error) {
    logger.error({
      type: 'request_error',
      url,
      duration: Date.now() - start,
      error: {
        message: error.message,
        code: error.code,
        stack: error.stack
      }
    });
    throw error;
  }
}

四、高级应用：性能优化与扩展

请求管道优化

const { pipeline } = require('undici');
const fs = require('fs');

async function streamData() {
  const source = await request('https://api.example.com/large-data');
  
  // 将响应流直接管道到文件
  await pipeline(
    source.body,
    fs.createWriteStream('./large-data.json'),
    (err) => {
      if (err) {
        console.error('管道处理错误:', err);
      } else {
        console.log('数据下载完成');
      }
    }
  );
}

全局请求拦截器

const { Agent, setGlobalDispatcher } = require('undici');

// 创建带有拦截功能的Agent
class InterceptingAgent extends Agent {
  dispatch(options, handler) {
    // 添加全局请求头
    options.headers = {
      ...options.headers,
      'X-Request-ID': generateRequestId(),
      'User-Agent': 'MyApp/1.0.0'
    };
    
    // 请求计时
    const start = Date.now();
    
    // 调用原始dispatch方法
    return super.dispatch(options, {
      ...handler,
      onHeaders(statusCode, headers) {
        console.log(`请求 ${options.path} 耗时: ${Date.now() - start}ms`);
        handler.onHeaders(statusCode, headers);
      }
    });
  }
}

// 设置为全局调度器
setGlobalDispatcher(new InterceptingAgent());

// 生成唯一请求ID
function generateRequestId() {
  return Date.now().toString(36) + Math.random().toString(36).substr(2);
}

最佳实践专栏：内存管理

// 处理大响应时的内存优化
async function processLargeResponse() {
  const { body } = await request('https://api.example.com/large-dataset');
  
  // 使用异步迭代器处理流数据
  for await (const chunk of body) {
    // 处理每个数据块
    processChunk(chunk);
    
    // 释放不再需要的资源
    chunk = null;
  }
}

function processChunk(chunk) {
  // 处理数据块的逻辑
  console.log(`处理 ${chunk.length} 字节的数据`);
}

通过本指南，您已经掌握了Undici的核心使用方法和故障处理技巧。无论是基础API请求还是高级性能优化，Undici都能为您的Node.js应用提供高效可靠的HTTP客户端解决方案。随着实践的深入，您可以进一步探索Undici的高级特性，如WebSocket支持、缓存机制和自定义调度策略，以满足更复杂的应用需求。