xMagic- 仓湖云函数数字应用平台
首页
🍓 函数引擎
更多产品
更多产品
  • 微澜组网
首页
🍓 函数引擎
更多产品
更多产品
  • 微澜组网
  1. xScript - x16.25.11
  • xMagic - 仓湖云函数数字应用平台
  • xScript - 仓湖云函数数字应用引擎
  • xMagic - 二开应用场景案例
  • 数据应用
    • 消息订阅(WSS)
    • 消息订阅(SSE)
    • 用户信息
    • 免密登陆(短信)
  • xScript - x16.25.11
    • assert
    • buffer
    • color
    • compress
    • console
    • crontab
    • crypto
    • encoding
    • events
    • evenloop
    • esm
    • fetch
    • fs
    • image
    • kv
    • mail
    • ml
    • mqtt
    • multipart
    • net
    • os
    • path
    • process
    • protobuf
    • querystring
    • redis
    • request
    • require
    • sql
    • tty
    • tui
    • ua
    • url
    • util
    • websocket
    • xml
    • yaml
    • mongo
    • http
    • stream
    • runtime
  • 小工具
    • APS - 代理转发
      • Any Proxy Service - 高级 HTTP/HTTPS/gRPC 代理转发工具
      • 配置指南 - 双向 Headers 和 Match/Replace
  • 数据模型
    • Schemas
      • AdminChangeAvatarReq
      • casbin.CasbinRule
      • AdminDelBatchReq
      • entity.DeptLable
      • AdminDelReq
      • entity.DevGenTable
      • AdminListReq
      • entity.DevGenTableColumn
      • AdminLoginReq
      • entity.FlowWorkClassify
      • AdminPostReq
      • entity.FlowWorkInfo
      • AdminReply
      • entity.FlowWorkTemplates
      • AdminUpdatePwdReq
      • entity.LogLogin
      • MenuDelBatchReq
      • entity.LogOper
      • MenuDelReq
      • entity.LoginM
      • MenuListReq
      • entity.MenuLable
      • MenuPostReq
      • entity.MenuPath
      • MenuReply
      • entity.ResEmail
      • RoleApisReq
      • entity.ResOss
      • SystemApiDelBatchReq
      • entity.ScreenGroupLabel
      • SystemApiDelReq
      • entity.SysApi
      • SystemApiListReq
      • entity.SysConfig
      • SystemApiPostReq
      • entity.SysDept
      • SystemApiReply
      • entity.SysDictData
      • SystemDepartmentDelBatchReq
      • entity.SysDictType
      • SystemDepartmentDelReq
      • entity.SysJob
      • SystemDepartmentListReq
      • entity.SysMenu
      • SystemDepartmentPostReq
      • entity.SysNotice
      • SystemDepartmentReply
      • entity.SysPost
      • SystemRoleApiDelBatchReq
      • entity.SysRole
      • SystemRoleApiDelReq
      • entity.SysTenants
      • SystemRoleApiListReq
      • entity.SysUser
      • SystemRoleApiPostReq
      • entity.SysUserB
      • SystemRoleApiReply
      • entity.SysUserId
      • SystemRoleDelBatchReq
      • entity.SysUserView
      • SystemRoleDelReq
      • entity.VisualRuleChain
      • SystemRoleListReq
      • entity.VisualScreen
      • SystemRoleMenuAddReq
      • entity.VisualScreenGroup
      • SystemRoleMenuDelBatchReq
      • form.Login
      • SystemRoleMenuDelReq
      • from.SendMail
      • SystemRoleMenuListReq
      • map[string]interface {}
      • SystemRoleMenuPostReq
      • map[string]string
      • SystemRoleMenuReply
      • model.BaseAutoModel
      • SystemRolePostReq
      • model.BaseModel
      • SystemRoleReply
      • model.ResultPage
      • model.ResultPage.data
      • vo.AuthVo
      • vo.DeptTreeVo
      • vo.MenuTreeVo
      • vo.MetaVo
      • vo.RouterVo
      • vo.TableInfoVo
      • vo.TokenVo
      • vo.UserRolePost
      • vo.UserVo
      • vo.UserVo.data
首页
🍓 函数引擎
更多产品
更多产品
  • 微澜组网
首页
🍓 函数引擎
更多产品
更多产品
  • 微澜组网
  1. xScript - x16.25.11

util

Util 模块#

实用工具模块,提供字符串格式化、模板渲染、ID生成、时间测量等实用功能。

功能特性#

✅ 字符串格式化(类似printf)
✅ 支持多种格式占位符
✅ 自动类型转换
✅ JSON序列化支持
✅ UUID生成
✅ Snowflake ID生成
✅ 随机字符串生成
✅ 字符串分割
✅ 高精度时间测量
✅ TOTP验证码生成
✅ User-Agent解析
✅ 全局变量存取
✅ Go模板引擎支持
✅ Node.js 兼容 API
util.inspect() - 对象检查和格式化
util.inspect.custom - 自定义检查符号
util.deprecate() - 函数废弃警告
util.inherits() - 原型继承

基本使用#

简单格式化#

多个占位符#

JSON格式化#

API参考#

util.format(format, ...args)#

使用占位符格式化字符串。
参数:
format (string): 格式化字符串,包含占位符
...args (any): 要插入的值
返回值: string - 格式化后的字符串
支持的占位符:
%s - 字符串
%d - 数字
%j - JSON(对象序列化)
%% - 百分号字符本身
示例:

Node.js 兼容 API#

util.inspect(object, [options])#

检查并格式化对象,返回字符串表示形式(Node.js 兼容方法)。
参数:
object (any): 要检查的对象
options (object, 可选): 检查选项(当前实现忽略此参数)
返回值: string - 对象的字符串表示
示例:
注意事项:
当前实现使用 JSON.stringify() 进行序列化
不可序列化的对象会回退到 toString()
支持 util.inspect.custom 符号用于自定义检查行为
符号通过 Symbol.for('nodejs.util.inspect.custom') 创建

util.deprecate(fn, message, [code])#

包装函数并在首次调用时打印废弃警告(Node.js 兼容方法)。
参数:
fn (function): 要包装的函数
message (string): 废弃警告消息
code (string, 可选): 废弃代码标识符
返回值: function - 包装后的函数
示例:
注意事项:
警告只在首次调用时打印一次
使用互斥锁确保线程安全
原始函数的返回值和参数完全保留
如果原始函数抛出异常,异常会被传递

util.inherits(constructor, superConstructor)#

实现原型继承,使子类继承父类的原型(Node.js 兼容方法)。
参数:
constructor (function): 子类构造函数
superConstructor (function): 父类构造函数
返回值: undefined
示例:
更复杂的继承示例:
注意事项:
设置 constructor.prototype.__proto__ = superConstructor.prototype
设置 constructor.super_ = superConstructor 以便访问父类
必须在定义子类原型方法之前调用 util.inherits()
推荐在子类构造函数中使用 SuperClass.call(this, ...) 调用父类构造函数
ES6 环境中推荐使用 class 和 extends 语法

util.uuid()#

生成一个随机的UUID(通用唯一识别码)。
参数: 无
返回值: string - UUID字符串(格式:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
示例:

util.suid(nodeId)#

生成一个Snowflake ID(分布式唯一ID)。
参数:
nodeId (number): 节点ID,范围0-1023,默认为0
返回值: string - Snowflake ID字符串
示例:

util.stuffing(length)#

生成指定长度的随机字符串(包含数字和大小写字母)。
参数:
length (number): 字符串长度
返回值: string - 随机字符串
示例:

util.split(input, chunkSize, separator)#

将字符串按指定长度分割,并用分隔符连接。
参数:
input (string): 要分割的字符串
chunkSize (number): 每段的长度
separator (string): 分隔符,默认为'-'
返回值: string - 分割后的字符串
示例:

util.hrtime([previousTime])#

获取高精度时间,用于性能测量。
参数:
previousTime (array, 可选): 上次调用hrtime返回的时间数组
返回值: array - [秒, 纳秒]
示例:

util.otpCode(secret)#

根据密钥生成TOTP(基于时间的一次性密码)验证码。
参数:
secret (string): TOTP密钥
返回值: string - 6位数字验证码
示例:

util.parseUserAgent(userAgentString)#

解析User-Agent字符串,提取浏览器、操作系统、设备信息。
参数:
userAgentString (string): User-Agent字符串
返回值: object - 包含os、deviceType、deviceModel、browser等信息的对象
示例:

util.set(key, value)#

设置全局变量。
参数:
key (string): 变量名
value (any): 变量值
返回值: boolean - 设置是否成功
示例:

util.get(key)#

获取全局变量。
参数:
key (string): 变量名
返回值: any - 变量值
示例:


### util.template(pattern, data)

使用Go模板引擎渲染模板字符串。

**参数:**
- `pattern` (string): 模板字符串,使用Go template语法
- `data` (object): 模板数据对象

**返回值:** string - 渲染后的字符串

**模板语法:**
- `{{.FieldName}}` - 访问字段
- `{{.Method arg}}` - 调用方法
- `{{if .Condition}}...{{end}}` - 条件判断
- `{{range .Array}}...{{end}}` - 循环遍历
- 更多语法请参考[Go template文档](https://pkg.go.dev/text/template)

**示例:**
```javascript
const util = require('util');

// 简单变量替换
const result = util.template('Hello {{.Name}}!', {Name: 'World'});
console.log(result); // 'Hello World!'

// 多个字段
const msg = util.template('User: {{.Name}}, Age: {{.Age}}', {
    Name: 'Alice',
    Age: 25
});
console.log(msg); // 'User: Alice, Age: 25'

// 条件判断
const greeting = util.template(
    '{{if .IsVIP}}Welcome VIP {{.Name}}!{{else}}Hello {{.Name}}{{end}}',
    {Name: 'John', IsVIP: true}
);
console.log(greeting); // 'Welcome VIP John!'

占位符详解#

%s - 字符串占位符#

将值转换为字符串。

%d - 数字占位符#

将值转换为数字。

%j - JSON占位符#

将值序列化为JSON字符串。

%% - 转义百分号#

输出百分号字符本身。

高级用法#

多余参数处理#

如果提供的参数多于占位符数量,多余的参数会追加到结果末尾。

缺少参数#

如果占位符数量多于提供的参数,占位符会保持原样。

无占位符#

如果没有占位符,所有参数会以空格连接。

实际应用场景#

日志格式化#

错误消息生成#

SQL查询构建#

模板字符串替换#

API响应格式化#

调试输出#

国际化消息格式化#

配置文件路径生成#

与其他功能结合#

与JSON.stringify比较#

字符串拼接替代方案#

util.template 详细用法#

基本变量替换#

条件语句#

循环遍历#

比较运算符#

实际应用场景#

邮件模板#

HTML生成#

配置文件生成#

日志格式化#

注意事项#

util.format#

1.
占位符顺序:占位符按顺序匹配参数,无法跳过或重排。
2.
类型转换:%s 和 %d 会自动进行类型转换。
3.
JSON格式:%j 使用的是标准JSON格式,不支持函数等非JSON类型。
4.
性能考虑:频繁格式化时注意性能影响。
5.
特殊字符:字符串中的特殊字符不会被转义。

util.template#

1.
Go模板语法:使用Go的text/template语法,与JavaScript模板字符串不同。
2.
字段访问:使用点号访问字段,如{{.FieldName}}。
3.
数据类型:data参数必须是对象(map),不能是基本类型。
4.
空格处理:模板中的空格和换行会保留在输出中。
5.
错误处理:模板解析或执行错误会抛出异常。

最佳实践#

util.format#

1.
选择合适的占位符:根据数据类型选择 %s、%d 或 %j
2.
避免过度格式化:简单字符串拼接可能更高效
3.
日志标准化:在日志系统中统一使用 util.format
4.
错误消息一致性:使用格式化确保错误消息格式统一
5.
调试信息:使用 %j 输出复杂对象便于调试

util.template#

1.
选择合适的工具:
简单变量替换:使用 util.format 更快
复杂逻辑(条件、循环):使用 util.template
2.
模板复用:将常用模板定义为常量,避免重复编写
3.
数据验证:确保传入的数据结构符合模板期望
4.
错误处理:使用try-catch捕获模板错误
5.
性能优化:频繁使用的模板可以预先测试和优化

工具选择指南#

场景推荐工具原因
简单变量插入util.format性能更好,语法简单
格式化数字/JSONutil.format内置类型转换
条件渲染util.template支持if-else逻辑
循环生成内容util.template支持range循环
复杂HTML/配置文件util.template更强大的模板功能
日志快速格式化util.format性能优先
生成唯一IDutil.uuid / util.suidUUID通用性强,SUID性能更好
生成随机字符串util.stuffing简单高效
格式化长字符串util.split提高可读性
性能测试util.hrtime纳秒级精度
两步验证util.otpCode标准TOTP算法
设备识别util.parseUserAgent自动解析UA
跨函数共享数据util.set/get简单的全局状态

性能提示#

字符串格式化示例#

性能测量示例#

全局状态管理示例#

User-Agent解析示例#

TOTP验证码示例#

完整API列表#

字符串处理#

util.format(format, ...args) - 格式化字符串
util.template(pattern, data) - 模板渲染
util.split(input, chunkSize, separator) - 字符串分割

ID生成#

util.uuid() - 生成UUID
util.suid(nodeId) - 生成Snowflake ID
util.stuffing(length) - 生成随机字符串

工具函数#

util.hrtime([previousTime]) - 高精度时间测量
util.otpCode(secret) - 生成TOTP验证码
util.parseUserAgent(ua) - 解析User-Agent

全局状态#

util.set(key, value) - 设置全局变量
util.get(key) - 获取全局变量
修改于 2025-11-05 07:30:50
上一页
url
下一页
websocket
Built with