Node.js http 模块所有 API 详解 + 常用 API 解析

一、模块引入

使用 http 模块前需先引入（Node.js 内置，无需额外安装）：

const http = require('http'); 
// 或 ES6 模块语法
import http from 'http';

二、核心 API 分类解析

1. 服务器相关 API（创建 HTTP 服务器）

用于构建接收客户端请求的 HTTP 服务器，核心是 http.createServer() 及返回的 Server 对象。

http.createServer([options][, requestListener])

• 作用：创建一个 http.Server 实例（HTTP 服务器）。
• 参数：
  • options（可选）：配置对象，常用属性：
    • IncomingMessage：自定义请求对象的构造函数（默认 http.IncomingMessage）。
    • ServerResponse：自定义响应对象的构造函数（默认 http.ServerResponse）。
    • noDelay：是否禁用 Nagle 算法（默认 false，启用）。
  • requestListener（可选）：请求处理回调，接收两个参数：
    • req：http.IncomingMessage 实例（客户端请求对象）。
    • res：http.ServerResponse 实例（服务器响应对象）。
• 返回值：http.Server 实例。

// 示例：创建简单服务器
const server = http.createServer((req, res) => {
  res.end('Hello, Node.js HTTP Server!');
});

http.Server 类（服务器实例）

http.createServer() 返回的服务器实例，包含以下核心方法和事件：

// 示例：启动服务器并监听事件
server.listen(3000, 'localhost', () => {
  console.log('Server running at http://localhost:3000/');
});

server.on('error', (err) => {
  console.error('Server error:', err);
});

server.on('close', () => {
  console.log('Server closed');
});

2. 客户端相关 API（发送 HTTP 请求）

用于向其他服务器发送 HTTP 请求，核心是 http.request() 和 http.get()。

http.request(options[, callback])

• 作用：发送 HTTP 请求（支持 GET、POST 等所有方法）。
• 参数：
  • options：请求配置（必填），可以是对象或字符串（URL）。常用属性：
    • protocol：协议（'http:' 或 'https:'，默认 'http:'）。
    • host：目标主机（默认 'localhost'）。
    • port：目标端口（默认 80）。
    • method：请求方法（默认 'GET'）。
    • path：请求路径（默认 '/'，含查询参数，如 '/api?name=test'）。
    • headers：请求头对象（如 { 'Content-Type': 'application/json' }）。
  • callback（可选）：响应处理回调，参数为 res（http.IncomingMessage 实例，服务器响应对象）。
• 返回值：http.ClientRequest 实例（请求对象）。

// 示例：发送 POST 请求
const postData = JSON.stringify({ name: 'Node.js' });
const options = {
  hostname: 'localhost',
  port: 3000,
  path: '/api',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(postData)
  }
};

const req = http.request(options, (res) => {
  console.log(`状态码: ${res.statusCode}`);
  res.on('data', (chunk) => {
    console.log('响应内容:', chunk.toString());
  });
});

req.on('error', (err) => {
  console.error('请求错误:', err);
});

// 发送请求体
req.write(postData);
// 结束请求（必须调用，否则服务器不会收到完整请求）
req.end();

http.get(options[, callback])

• 作用：http.request() 的简化版，专门用于发送 GET 请求（自动调用 req.end()）。
• 参数：与 http.request() 相同，但 method 固定为 'GET'。
• 返回值：http.ClientRequest 实例。

// 示例：发送 GET 请求
http.get('http://localhost:3000', (res) => {
  let data = '';
  res.on('data', (chunk) => { data += chunk; });
  res.on('end', () => {
    console.log('完整响应:', data);
  });
}).on('error', (err) => {
  console.error('GET 请求错误:', err);
});

http.ClientRequest 类（客户端请求对象）

http.request() 和 http.get() 返回的请求实例，用于控制请求发送过程：

3. 请求对象（http.IncomingMessage）

代表客户端发送的请求（服务器端）或服务器返回的响应（客户端），包含请求 / 响应的元数据和数据体。

核心属性

• url：请求的 URL 路径（服务器端，如 '/api?name=test'）。
• method：请求方法（服务器端，如 'GET'、'POST'）。
• headers：请求头对象（键值对，如 { 'user-agent': 'curl/7.68.0' }）。
• statusCode：响应状态码（客户端，如 200、404）。
• statusMessage：响应状态消息（客户端，如 'OK'、'Not Found'）。
• httpVersion：HTTP 协议版本（如 '1.1'）。

核心方法与事件

• req.setEncoding([encoding])：设置数据编码（如 'utf8'、'base64'），后续 'data' 事件的 chunk 会以该编码返回。
• req.pause()：暂停数据接收。
• req.resume()：恢复数据接收。
• 'data' 事件：收到数据块时触发，参数为 chunk（Buffer 或字符串，取决于 setEncoding）。
• 'end' 事件：数据接收完成时触发。
• 'error' 事件：请求 / 响应发生错误时触发。

// 服务器端处理 POST 请求体（流式接收）
server.on('request', (req, res) => {
  if (req.method === 'POST' && req.url === '/data') {
    let body = '';
    req.setEncoding('utf8'); // 设为字符串编码
    req.on('data', (chunk) => { body += chunk; }); // 累加数据
    req.on('end', () => {
      console.log('收到 POST 数据:', body);
      res.end('数据已接收');
    });
  }
});

4. 响应对象（http.ServerResponse）

仅在服务器端使用，用于向客户端发送响应。

核心方法

• res.writeHead(statusCode[, statusMessage][, headers])：发送响应头（需在 res.write() 或 res.end() 前调用）。
  • statusCode：状态码（如 200）。
  • statusMessage：状态消息（默认由状态码决定）。
  • headers：响应头对象。
• res.setHeader(name, value)：设置单个响应头（若已用 writeHead，此方法无效）。
• res.getHeader(name)：获取已设置的响应头值。
• res.removeHeader(name)：移除响应头。
• res.write(chunk[, encoding][, callback])：发送响应体（可多次调用）。
• res.end([chunk][, encoding][, callback])：结束响应（必须调用，否则客户端会一直等待）。
• res.statusCode：设置响应状态码（替代 writeHead 中的 statusCode）。
• res.statusMessage：设置响应状态消息。

// 示例：发送带响应头的响应
server.on('request', (req, res) => {
  // 方法1：通过 writeHead 设置头和状态码
  res.writeHead(200, 'OK', {
    'Content-Type': 'text/plain; charset=utf-8',
    'X-Powered-By': 'Node.js'
  });
  
  // 方法2：单独设置状态码和头（需在 write/end 前）
  // res.statusCode = 200;
  // res.setHeader('Content-Type', 'text/plain');
  
  res.write('第一部分响应\n');
  res.end('结束响应'); // 结束响应（可带最后一段数据）
});

5. 辅助方法与常量

• http.METHODS：数组，包含所有支持的 HTTP 方法（如 'GET'、'POST'、'PUT' 等）。
• http.STATUS_CODES：对象，映射状态码到描述（如 http.STATUS_CODES[200] // 'OK'）。
• http.validateHeaderName(name)：验证响应头名称是否合法，不合法则抛出错误。
• http.validateHeaderValue(name, value)：验证响应头值是否合法，不合法则抛出错误。

三、常用 API 实战场景

1. 创建基础 HTTP 服务器

const http = require('http');

const server = http.createServer((req, res) => {
  // 处理不同路径和方法
  if (req.url === '/' && req.method === 'GET') {
    res.writeHead(200, { 'Content-Type': 'text/html' });
    res.end('<h1>首页</h1>');
  } else if (req.url === '/api' && req.method === 'GET') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ message: 'API 响应' }));
  } else {
    res.writeHead(404, { 'Content-Type': 'text/plain' });
    res.end('404 未找到');
  }
});

server.listen(3000, () => {
  console.log('服务器运行在 http://localhost:3000');
});

2. 发送 POST 请求（客户端）

const http = require('http');
const querystring = require('querystring');

// 表单数据（x-www-form-urlencoded 格式）
const postData = querystring.stringify({
  username: 'test',
  password: '123'
});

const options = {
  hostname: 'localhost',
  port: 3000,
  path: '/login',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': Buffer.byteLength(postData)
  }
};

const req = http.request(options, (res) => {
  console.log(`状态码: ${res.statusCode}`);
  res.on('data', (chunk) => {
    console.log('响应:', chunk.toString());
  });
});

req.on('error', (e) => {
  console.error(`请求错误: ${e.message}`);
});

req.write(postData);
req.end();

3. 处理跨域请求（服务器端）

通过设置响应头 Access-Control-Allow-* 实现跨域：

server.on('request', (req, res) => {
  // 允许所有域名跨域
  res.setHeader('Access-Control-Allow-Origin', '*');
  // 允许的请求方法
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
  // 允许的请求头
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
  
  // 处理 OPTIONS 预检请求
  if (req.method === 'OPTIONS') {
    res.statusCode = 204; // 无内容
    res.end();
    return;
  }
  
  // 处理实际请求
  res.end('跨域响应');
});

四、总结

http 模块是 Node.js 构建 HTTP 应用的基础，核心能力包括：

• 服务器端：通过 http.createServer() 创建服务器，监听 'request' 事件处理请求，使用 ServerResponse 发送响应。
• 客户端：通过 http.request() 或 http.get() 发送请求，通过 IncomingMessage 处理响应。
• 数据流：请求体和响应体均以流（Stream）形式处理，需通过 'data' 和 'end' 事件接收完整数据。