Node.js中util模块详解

Node.js 中 util 模块全部 API 详解

一、类型检查函数

const util = require('util');// 1. util.types
// 检查对象类型
console.log(util.types.isDate(new Date()));  // true
console.log(util.types.isRegExp(/abc/));  // true
console.log(util.types.isArrayBuffer(new ArrayBuffer(10)));  // true
console.log(util.types.isArrayBufferView(new Uint8Array(10)));  // true
console.log(util.types.isAsyncFunction(async function() {}));  // true
console.log(util.types.isDataView(new DataView(new ArrayBuffer(10))));  // true
console.log(util.types.isExternal(new Int32Array(10)));  // false
console.log(util.types.isMap(new Map()));  // true
console.log(util.types.isMapIterator(new Map().entries()));  // true
console.log(util.types.isPromise(new Promise(() => {})));  // true
console.log(util.types.isSet(new Set()));  // true
console.log(util.types.isSetIterator(new Set().entries()));  // true
console.log(util.types.isTypedArray(new Uint8Array()));  // true
console.log(util.types.isUint8Array(new Uint8Array()));  // true
console.log(util.types.isUint8ClampedArray(new Uint8ClampedArray()));  // true
console.log(util.types.isUint16Array(new Uint16Array()));  // true
console.log(util.types.isUint32Array(new Uint32Array()));  // true
console.log(util.types.isInt8Array(new Int8Array()));  // true
console.log(util.types.isInt16Array(new Int16Array()));  // true
console.log(util.types.isInt32Array(new Int32Array()));  // true
console.log(util.types.isFloat32Array(new Float32Array()));  // true
console.log(util.types.isFloat64Array(new Float64Array()));  // true
console.log(util.types.isBigInt64Array(new BigInt64Array()));  // true
console.log(util.types.isBigUint64Array(new BigUint64Array()));  // true
console.log(util.types.isWeakMap(new WeakMap()));  // true
console.log(util.types.isWeakSet(new WeakSet()));  // true
console.log(util.types.isWeakRef(new WeakRef({})));  // true
console.log(util.types.isGeneratorFunction(function*() {}));  // true
console.log(util.types.isGeneratorObject((function*() {})()));  // true
console.log(util.types.isFinalizationRegistry(new FinalizationRegistry(() => {})));  // true

二、工具函数

const util = require('util');// 1. util.callbackify(original)
// 将 async 函数转换为回调函数
async function asyncFn() {return 'hello';
}
const callbackFn = util.callbackify(asyncFn);
callbackFn((err, result) => {console.log(result);  // 'hello'
});// 2. util.debuglog(section)
// 创建调试日志函数
const debug = util.debuglog('app');
debug('调试信息');  // 当 NODE_DEBUG=app 时输出// 3. util.deprecate(fn, msg[, code])
// 标记函数为废弃
const deprecatedFn = util.deprecate(() => {console.log('这是一个废弃的函数');
}, '这个函数将在未来版本中移除');
deprecatedFn();  // 输出警告信息// 4. util.format(format[, ...args])
// 格式化字符串
console.log(util.format('Hello %s', 'World'));  // 'Hello World'
console.log(util.format('Count: %d', 42));  // 'Count: 42'
console.log(util.format('Object: %o', { a: 1 }));  // 'Object: { a: 1 }'// 5. util.inherits(constructor, superConstructor)
// 实现继承
function Animal(name) {this.name = name;
}
function Dog(name) {Animal.call(this, name);
}
util.inherits(Dog, Animal);// 6. util.inspect(object[, options])
// 检查对象
const obj = {a: 1,b: { c: 2 },d: [1, 2, 3]
};
console.log(util.inspect(obj, { depth: null, colors: true }));// 7. util.promisify(original)
// 将回调函数转换为 Promise
const fs = require('fs');
const readFile = util.promisify(fs.readFile);
readFile('file.txt').then(data => {console.log(data);
});// 8. util.stripVTControlCharacters(str)
// 移除 VT 控制字符
const str = 'Hello\x1b[31mWorld\x1b[0m';
console.log(util.stripVTControlCharacters(str));  // 'HelloWorld'

三、TextEncoder 和 TextDecoder

const util = require('util');// 1. util.TextEncoder
const encoder = new util.TextEncoder();
const encoded = encoder.encode('Hello World');
console.log(encoded);  // Uint8Array// 2. util.TextDecoder
const decoder = new util.TextDecoder();
const decoded = decoder.decode(encoded);
console.log(decoded);  // 'Hello World'

四、自定义工具函数

const util = require('util');// 1. 深度克隆对象
function deepClone(obj) {return util.inspect(obj, { depth: null });
}// 2. 格式化日期
function formatDate(date) {return util.format('%s-%s-%s', date.getFullYear(),String(date.getMonth() + 1).padStart(2, '0'),String(date.getDate()).padStart(2, '0'));
}// 3. 检查对象是否为空
function isEmpty(obj) {return Object.keys(obj).length === 0;
}// 4. 延迟执行
function delay(ms) {return new Promise(resolve => setTimeout(resolve, ms));
}// 5. 重试函数
async function retry(fn, retries = 3, delay = 1000) {try {return await fn();} catch (err) {if (retries === 0) throw err;await new Promise(resolve => setTimeout(resolve, delay));return retry(fn, retries - 1, delay);}
}

五、错误处理工具

const util = require('util');// 1. 自定义错误类
class CustomError extends Error {constructor(message) {super(message);this.name = 'CustomError';}
}// 2. 错误包装
function wrapError(err, message) {return new Error(`${message}: ${err.message}`);
}// 3. 错误日志
function logError(err) {console.error(util.inspect(err, {depth: null,colors: true}));
}// 4. 错误重试
async function withRetry(fn, retries = 3) {for (let i = 0; i < retries; i++) {try {return await fn();} catch (err) {if (i === retries - 1) throw err;console.error(`重试 ${i + 1}/${retries}:`, err);await new Promise(resolve => setTimeout(resolve, 1000));}}
}

六、调试工具

const util = require('util');// 1. 创建调试日志
const debug = util.debuglog('app');// 2. 性能计时
function measureTime(fn) {const start = process.hrtime();fn();const [seconds, nanoseconds] = process.hrtime(start);console.log(`执行时间: ${seconds}s ${nanoseconds}ns`);
}// 3. 内存使用
function logMemoryUsage() {const used = process.memoryUsage();console.log(util.inspect(used, {depth: null,colors: true}));
}// 4. 对象比较
function compareObjects(obj1, obj2) {return util.inspect(obj1) === util.inspect(obj2);
}

七、Promise 工具

const util = require('util');// 1. Promise 超时
function timeout(promise, ms) {return Promise.race([promise,new Promise((_, reject) => setTimeout(() => reject(new Error('超时')), ms))]);
}// 2. Promise 重试
function retryPromise(fn, retries = 3) {return new Promise((resolve, reject) => {fn().then(resolve).catch(err => {if (retries === 0) reject(err);else retryPromise(fn, retries - 1).then(resolve).catch(reject);});});
}// 3. Promise 队列
class PromiseQueue {constructor() {this.queue = [];this.running = false;}add(fn) {return new Promise((resolve, reject) => {this.queue.push({ fn, resolve, reject });this.process();});}async process() {if (this.running) return;this.running = true;while (this.queue.length > 0) {const { fn, resolve, reject } = this.queue.shift();try {const result = await fn();resolve(result);} catch (err) {reject(err);}}this.running = false;}
}

八、实际应用示例

const util = require('util');
const fs = require('fs');
const path = require('path');// 1. 文件操作工具
class FileUtils {static async readFile(filePath) {const readFileAsync = util.promisify(fs.readFile);return readFileAsync(filePath, 'utf8');}static async writeFile(filePath, content) {const writeFileAsync = util.promisify(fs.writeFile);return writeFileAsync(filePath, content, 'utf8');}static async copyFile(src, dest) {const copyFileAsync = util.promisify(fs.copyFile);return copyFileAsync(src, dest);}
}// 2. 日志工具
class Logger {static debug = util.debuglog('app:debug');static info = util.debuglog('app:info');static error = util.debuglog('app:error');static log(level, message, ...args) {const timestamp = new Date().toISOString();console.log(util.format('[%s] %s: %s', timestamp, level, message), ...args);}
}// 3. 配置管理
class Config {static load(configPath) {const config = require(configPath);return util.inspect(config, { depth: null });}static validate(config) {// 配置验证逻辑return util.types.isObject(config);}
}// 4. 性能监控
class PerformanceMonitor {static measure(name, fn) {const start = process.hrtime();const result = fn();const [seconds, nanoseconds] = process.hrtime(start);console.log(util.format('%s: %ds %dns',name,seconds,nanoseconds));return result;}static async measureAsync(name, fn) {const start = process.hrtime();const result = await fn();const [seconds, nanoseconds] = process.hrtime(start);console.log(util.format('%s: %ds %dns',name,seconds,nanoseconds));return result;}
}

九、最佳实践

const util = require('util');// 1. 错误处理
function handleError(err) {if (util.types.isNativeError(err)) {console.error('原生错误:', err);} else {console.error('自定义错误:', err);}
}// 2. 类型检查
function validateInput(input) {if (!util.types.isString(input)) {throw new TypeError('输入必须是字符串');}
}// 3. 异步操作
async function asyncOperation() {try {const result = await util.promisify(someAsyncFunction)();return result;} catch (err) {handleError(err);throw err;}
}// 4. 对象序列化
function serializeObject(obj) {return util.inspect(obj, {depth: null,colors: true,maxArrayLength: null});
}// 5. 性能优化
function optimizePerformance(fn) {return util.callbackify(async (...args) => {const start = process.hrtime();const result = await fn(...args);const [seconds, nanoseconds] = process.hrtime(start);console.log(`执行时间: ${seconds}s ${nanoseconds}ns`);return result;});
}

util 模块的主要特点：

1. 提供类型检查功能
2. 提供工具函数
3. 支持 Promise 转换
4. 提供调试工具
5. 支持文本编码解码

使用建议：

1. 合理使用类型检查
2. 注意错误处理
3. 使用 Promise 工具
4. 优化性能监控
5. 规范代码风格