Node.js 开发者入门教程

Node.js 开发者入门教程

第一部分：基础概念与环境配置

Node.js 简介

Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行时环境，使开发者能够在服务器端运行 JavaScript 代码。其核心特点包括事件驱动、非阻塞 I/O 模型，特别适用于构建数据密集型的实时应用程序。

核心架构理解

Node.js 采用单线程事件循环机制处理并发请求。当执行 I/O 操作时，系统不会阻塞主线程，而是将操作委托给系统层面处理，通过回调函数在操作完成后返回结果。这种设计使 Node.js 在处理大量并发连接时表现出色。

环境安装与配置

访问 Node.js 官方网站下载对应操作系统的安装包。建议选择 LTS（长期支持）版本以确保稳定性。安装完成后，通过命令行验证安装：

node --version
npm --version

包管理工具

npm（Node Package Manager）是 Node.js 的默认包管理工具，负责依赖管理、脚本执行和包发布等功能。现代开发中，yarn 和 pnpm 也是常用的替代方案，提供更快的安装速度和更好的依赖管理。

第二部分：核心模块详解

文件系统模块（fs）

文件系统模块提供与操作系统文件系统交互的功能。包含同步和异步两种操作方式：

const fs = require('fs');

// 异步读取文件
fs.readFile('example.txt', 'utf8', (err, data) => {
  if (err) {
    console.error('读取文件出错:', err);
    return;
  }
  console.log('文件内容:', data);
});

// 使用 Promise 版本
const fsPromises = require('fs').promises;

async function readFileAsync() {
  try {
    const data = await fsPromises.readFile('example.txt', 'utf8');
    console.log('文件内容:', data);
  } catch (error) {
    console.error('读取文件出错:', error);
  }
}

HTTP 模块

HTTP 模块是构建 Web 服务器和客户端的基础：

const http = require('http');

// 创建 HTTP 服务器
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  
  const responseData = {
    method: req.method,
    url: req.url,
    headers: req.headers,
    timestamp: new Date().toISOString()
  };
  
  res.end(JSON.stringify(responseData, null, 2));
});

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

路径模块（path）

路径模块提供处理文件和目录路径的实用工具：

const path = require('path');

// 路径拼接
const fullPath = path.join(__dirname, 'data', 'users.json');
console.log('完整路径:', fullPath);

// 获取文件扩展名
const extension = path.extname('document.pdf');
console.log('文件扩展名:', extension);

// 获取文件名
const filename = path.basename('/users/documents/report.xlsx');
console.log('文件名:', filename);

事件模块（events）

事件模块实现了观察者模式，是 Node.js 异步编程的核心：

const EventEmitter = require('events');

class UserManager extends EventEmitter {
  createUser(userData) {
    // 模拟用户创建过程
    const user = { id: Date.now(), ...userData };
    
    // 触发事件
    this.emit('userCreated', user);
    this.emit('audit', { action: 'CREATE_USER', userId: user.id });
    
    return user;
  }
}

const userManager = new UserManager();

// 监听事件
userManager.on('userCreated', (user) => {
  console.log('新用户创建:', user.id);
});

userManager.on('audit', (auditData) => {
  console.log('审计日志:', auditData);
});

// 使用
userManager.createUser({ name: '张三', email: 'zhang@example.com' });

第三部分：异步编程模式

回调函数模式

传统的 Node.js 异步编程采用回调函数，遵循错误优先的约定：

const fs = require('fs');

function processFile(filename, callback) {
  fs.readFile(filename, 'utf8', (err, data) => {
    if (err) {
      return callback(err, null);
    }
    
    // 处理数据
    const processedData = data.toUpperCase();
    callback(null, processedData);
  });
}

// 使用回调函数
processFile('input.txt', (err, result) => {
  if (err) {
    console.error('处理失败:', err.message);
    return;
  }
  console.log('处理结果:', result);
});

Promise 模式

Promise 提供更清晰的异步流程控制：

const fs = require('fs').promises;

function processFilePromise(filename) {
  return fs.readFile(filename, 'utf8')
    .then(data => data.toUpperCase())
    .catch(err => {
      console.error('文件处理出错:', err.message);
      throw err;
    });
}

// 使用 Promise
processFilePromise('input.txt')
  .then(result => console.log('处理结果:', result))
  .catch(err => console.error('最终错误:', err.message));

Async/Await 模式

现代 JavaScript 推荐使用 async/await 语法简化异步代码：

const fs = require('fs').promises;

async function processFileAsync(filename) {
  try {
    const data = await fs.readFile(filename, 'utf8');
    const processedData = data.toUpperCase();
    return processedData;
  } catch (error) {
    console.error('文件处理出错:', error.message);
    throw error;
  }
}

// 使用 async/await
async function main() {
  try {
    const result = await processFileAsync('input.txt');
    console.log('处理结果:', result);
  } catch (error) {
    console.error('程序执行出错:', error.message);
  }
}

main();

第四部分：模块系统

CommonJS 模块系统

Node.js 原生支持 CommonJS 模块系统：

// math.js - 导出模块
function add(a, b) {
  return a + b;
}

function multiply(a, b) {
  return a * b;
}

const PI = 3.14159;

module.exports = {
  add,
  multiply,
  PI
};

// 或者单独导出
// module.exports.subtract = (a, b) => a - b;

// main.js - 引入模块
const math = require('./math');
// 或者使用解构
const { add, multiply, PI } = require('./math');

console.log('加法结果:', math.add(5, 3));
console.log('乘法结果:', multiply(4, 7));
console.log('PI 值:', PI);

ES6 模块系统

现代 Node.js 版本支持 ES6 模块语法（需要配置或使用 .mjs 扩展名）：

// math.mjs - ES6 模块导出
export function add(a, b) {
  return a + b;
}

export function multiply(a, b) {
  return a * b;
}

export const PI = 3.14159;

// 默认导出
export default function calculate(operation, a, b) {
  switch (operation) {
    case 'add': return add(a, b);
    case 'multiply': return multiply(a, b);
    default: throw new Error('不支持的操作');
  }
}

// main.mjs - ES6 模块导入
import calculate, { add, multiply, PI } from './math.mjs';

console.log('默认计算:', calculate('add', 10, 5));
console.log('直接加法:', add(3, 7));

第五部分：包管理与依赖处理

package.json 配置

package.json 是项目的配置文件，定义依赖、脚本和元信息：

{
  "name": "my-node-project",
  "version": "1.0.0",
  "description": "示例 Node.js 项目",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest",
    "build": "webpack --mode production"
  },
  "dependencies": {
    "express": "^4.18.2",
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "nodemon": "^2.0.20",
    "jest": "^29.3.1"
  },
  "engines": {
    "node": ">=14.0.0"
  }
}

依赖管理策略

理解语义化版本控制对依赖管理至关重要。版本号格式为 MAJOR.MINOR.PATCH，符号含义如下：

• ^1.2.3 兼容更新，允许 1.x.x 范围内的更新
• ~1.2.3 保守更新，仅允许 1.2.x 范围内的更新
• 1.2.3 精确版本，不允许自动更新

npm 脚本使用

npm 脚本提供便捷的任务自动化方式：

{
  "scripts": {
    "start": "node server.js",
    "dev": "cross-env NODE_ENV=development nodemon server.js",
    "test": "jest --coverage",
    "test:watch": "jest --watch",
    "build": "webpack --config webpack.prod.js",
    "lint": "eslint src/**/*.js",
    "clean": "rimraf dist"
  }
}

第六部分：错误处理与调试

错误处理最佳实践

// 统一错误处理类
class AppError extends Error {
  constructor(message, statusCode, isOperational = true) {
    super(message);
    this.statusCode = statusCode;
    this.isOperational = isOperational;
    
    Error.captureStackTrace(this, this.constructor);
  }
}

// 异步错误处理包装器
function asyncHandler(fn) {
  return (req, res, next) => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };
}

// 使用示例
const express = require('express');
const app = express();

app.get('/users/:id', asyncHandler(async (req, res) => {
  const userId = req.params.id;
  
  if (!userId) {
    throw new AppError('用户ID不能为空', 400);
  }
  
  const user = await getUserById(userId);
  
  if (!user) {
    throw new AppError('用户不存在', 404);
  }
  
  res.json(user);
}));

// 全局错误处理中间件
app.use((err, req, res, next) => {
  const { statusCode = 500, message } = err;
  
  console.error(`错误: ${message}`);
  console.error(err.stack);
  
  res.status(statusCode).json({
    status: 'error',
    message: err.isOperational ? message : '服务器内部错误'
  });
});

调试技巧

使用 Node.js 内置调试器：

// debug.js
function complexCalculation(data) {
  debugger; // 设置断点
  
  let result = 0;
  for (let item of data) {
    result += item.value * item.multiplier;
  }
  
  return result;
}

const testData = [
  { value: 10, multiplier: 2 },
  { value: 5, multiplier: 3 }
];

console.log(complexCalculation(testData));

启动调试模式：

node inspect debug.js

第七部分：性能优化

内存管理

// 避免内存泄漏的最佳实践
class DataProcessor {
  constructor() {
    this.cache = new Map();
    this.maxCacheSize = 1000;
  }
  
  processData(key, data) {
    // 限制缓存大小
    if (this.cache.size >= this.maxCacheSize) {
      const firstKey = this.cache.keys().next().value;
      this.cache.delete(firstKey);
    }
    
    const processed = this.expensiveOperation(data);
    this.cache.set(key, processed);
    
    return processed;
  }
  
  expensiveOperation(data) {
    // 模拟耗时操作
    return data.map(item => item * 2);
  }
  
  // 清理资源
  cleanup() {
    this.cache.clear();
  }
}

// 使用 WeakMap 避免内存泄漏
const privateData = new WeakMap();

class SecureUser {
  constructor(name) {
    this.name = name;
    privateData.set(this, { password: null, sessions: [] });
  }
  
  setPassword(password) {
    privateData.get(this).password = password;
  }
  
  addSession(sessionId) {
    privateData.get(this).sessions.push(sessionId);
  }
}

流式处理

处理大型文件或数据时使用流可以显著降低内存使用：

const fs = require('fs');
const { Transform } = require('stream');

// 创建转换流
class JSONProcessor extends Transform {
  constructor(options) {
    super({ objectMode: true, ...options });
  }
  
  _transform(chunk, encoding, callback) {
    try {
      const data = JSON.parse(chunk);
      data.processed = true;
      data.timestamp = new Date().toISOString();
      
      this.push(JSON.stringify(data) + '\n');
      callback();
    } catch (error) {
      callback(error);
    }
  }
}

// 使用流处理大文件
function processLargeFile(inputPath, outputPath) {
  const readStream = fs.createReadStream(inputPath, { encoding: 'utf8' });
  const writeStream = fs.createWriteStream(outputPath);
  const processor = new JSONProcessor();
  
  readStream
    .pipe(processor)
    .pipe(writeStream)
    .on('finish', () => {
      console.log('文件处理完成');
    })
    .on('error', (error) => {
      console.error('处理过程中出错:', error);
    });
}

第八部分：测试策略

单元测试

使用 Jest 框架进行单元测试：

// utils.js
function calculateTotal(items) {
  if (!Array.isArray(items)) {
    throw new Error('参数必须是数组');
  }
  
  return items.reduce((total, item) => {
    if (typeof item.price !== 'number' || typeof item.quantity !== 'number') {
      throw new Error('商品价格和数量必须是数字');
    }
    return total + (item.price * item.quantity);
  }, 0);
}

module.exports = { calculateTotal };

// utils.test.js
const { calculateTotal } = require('./utils');

describe('calculateTotal', () => {
  test('正确计算商品总价', () => {
    const items = [
      { price: 10, quantity: 2 },
      { price: 5, quantity: 3 }
    ];
    
    expect(calculateTotal(items)).toBe(35);
  });
  
  test('处理空数组', () => {
    expect(calculateTotal([])).toBe(0);
  });
  
  test('参数不是数组时抛出错误', () => {
    expect(() => {
      calculateTotal('not an array');
    }).toThrow('参数必须是数组');
  });
  
  test('商品数据格式错误时抛出错误', () => {
    const invalidItems = [{ price: '10', quantity: 2 }];
    
    expect(() => {
      calculateTotal(invalidItems);
    }).toThrow('商品价格和数量必须是数字');
  });
});

集成测试

// server.test.js
const request = require('supertest');
const app = require('./app');

describe('API 集成测试', () => {
  test('GET /api/users 返回用户列表', async () => {
    const response = await request(app)
      .get('/api/users')
      .expect(200);
    
    expect(response.body).toHaveProperty('users');
    expect(Array.isArray(response.body.users)).toBe(true);
  });
  
  test('POST /api/users 创建新用户', async () => {
    const newUser = {
      name: '测试用户',
      email: 'test@example.com'
    };
    
    const response = await request(app)
      .post('/api/users')
      .send(newUser)
      .expect(201);
    
    expect(response.body).toHaveProperty('id');
    expect(response.body.name).toBe(newUser.name);
  });
});

第九部分：最佳实践总结

代码组织结构

建议采用以下项目结构：

project/
├── src/
│   ├── controllers/      # 控制器层
│   ├── services/         # 业务逻辑层
│   ├── models/           # 数据模型
│   ├── middleware/       # 中间件
│   ├── utils/            # 工具函数
│   └── config/           # 配置文件
├── tests/                # 测试文件
├── docs/                 # 文档
├── package.json
└── README.md

环境配置管理

// config/index.js
const config = {
  development: {
    port: 3000,
    database: {
      host: 'localhost',
      name: 'dev_db'
    },
    logLevel: 'debug'
  },
  production: {
    port: process.env.PORT || 8080,
    database: {
      host: process.env.DB_HOST,
      name: process.env.DB_NAME
    },
    logLevel: 'error'
  }
};

const environment = process.env.NODE_ENV || 'development';
module.exports = config[environment];

安全性考虑

const helmet = require('helmet');
const rateLimit = require('express-rate-limit');
const express = require('express');

const app = express();

// 安全头设置
app.use(helmet());

// 请求限制
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15分钟
  max: 100, // 限制每个IP 100个请求
  message: '请求过于频繁，请稍后再试'
});
app.use('/api/', limiter);

// 输入验证中间件
function validateInput(schema) {
  return (req, res, next) => {
    const { error } = schema.validate(req.body);
    if (error) {
      return res.status(400).json({
        error: '输入数据验证失败',
        details: error.details
      });
    }
    next();
  };
}

日志记录

const winston = require('winston');

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ filename: 'logs/error.log', level: 'error' }),
    new winston.transports.File({ filename: 'logs/combined.log' })
  ]
});

if (process.env.NODE_ENV !== 'production') {
  logger.add(new winston.transports.Console({
    format: winston.format.simple()
  }));
}

module.exports = logger;

性能监控

// 性能监控中间件
function performanceMonitor(req, res, next) {
  const start = Date.now();
  
  res.on('finish', () => {
    const duration = Date.now() - start;
    const memUsage = process.memoryUsage();
    
    console.log({
      method: req.method,
      url: req.url,
      statusCode: res.statusCode,
      duration: `${duration}ms`,
      memory: `${Math.round(memUsage.heapUsed / 1024 / 1024)}MB`
    });
  });
  
  next();
}

总结

Node.js 开发需要掌握异步编程思维、模块化设计、错误处理和性能优化等核心技能。通过系统学习这些概念和实践，您将能够构建高效、可维护的服务器端应用程序。建议在实际项目中逐步应用这些知识，并持续关注 Node.js 生态系统的发展动态。