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 模块的主要特点：
- 提供类型检查功能
- 提供工具函数
- 支持 Promise 转换
- 提供调试工具
- 支持文本编码解码
使用建议：
- 合理使用类型检查
- 注意错误处理
- 使用 Promise 工具
- 优化性能监控
- 规范代码风格