Documentation
¶
Overview ¶
Package common 提供常规业务通用工具：按应用时区生成 ID、格式化时间、精确转换百分比及名称脱敏。
GenerateIDWithYYMMDDHHmmssSSS 和非 nil 时间的 FormatTime 依赖已初始化的 infra/env。 本包不初始化环境、不持有客户端或连接；百分比转换和名称脱敏无需初始化环境。
ID 与时间 ¶
GenerateIDWithYYMMDDHHmmssSSS(prefix) 返回原样前缀、15 位时间和 4 位随机数字： YY 为两位年，MM 为月，DD 为日，HH 为 24 小时制小时，mm 为分钟，ss 为秒，SSS 为毫秒。 例如前缀 PD、上海时间 2026-10-30 12:34:56.007、随机数 7，返回 PD2610301234560070007。 时间使用应用时区，随机数字使用 crypto/rand；不保证唯一，落库须依靠唯一索引和冲突重试。 FormatTime(*time.Time) 按应用时区输出 RFC3339，省略小数秒；nil 返回空字符串。
百分比 ¶
FormatPercent 和 ParsePercent 在 int64 万分之一整数与百分比字符串之间精确转换， 支持正数、负数和零，不使用浮点运算。例如 1000 对应 10%，-1001 对应 -10.01%。 FormatPercent 最多保留两位小数并去除末尾零，零输出为 0%。 ParsePercent 必须有 ASCII % 后缀，数值接受整数或一至两位小数、前导负号和前导零。 拒绝空白、正号、科学计数法、千位分隔符、全角字符及多余小数位，不自动清理或舍入。 -0%、-0.00% 等负零输入转换为 0；是否允许负数或超过 100% 由业务层判断。 可解析范围为 -92233720368547758.08% 至 92233720368547758.07%，覆盖 int64 完整范围。 格式错误返回 ErrInvalidPercent，格式合法但超出范围返回 ErrPercentOverflow； 失败时数值返回 0，调用方通过 errors.Is 判断错误。
以下示例需导入 fmt 和 github.com/bpcoder16/pixiu/biz/common：
value, err := common.ParsePercent("-10.01%")
if err != nil {
return err
}
fmt.Println(value) // -1001
fmt.Println(common.FormatPercent(value)) // -10.01%
名称脱敏 ¶
MaskName(value, symbols...) 按 Unicode 码点处理展示名称，空串和单字符原样返回， 双字符仅保留首字并追加一个符号，三字符及以上保留首尾，中间使用 min(码点数-2, 3) 个符号。 例如张仍为张，张三变为张*，张小三变为张*三，欧阳娜娜变为欧**娜，快乐卡牌收藏变为快***藏。 默认符号为 *；可传入自定义字符串作为完整符号重复，仅使用首个 symbols 参数， 空字符串或非法 UTF-8 符号回退为 *，非法 UTF-8 名称整体替换为一个符号。 本函数不裁剪空白、不推断姓氏、不做 Unicode 规范化，也不按字素簇分割组合音标或复合表情。 单字符按展示规则保留原值；需要完全隐藏的场景由业务另行处理。
fmt.Println(common.MaskName("张三")) // 张*
fmt.Println(common.MaskName("欧阳娜娜", "#")) // 欧##娜
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidPercent 表示百分比缺少 % 后缀，或数值不是带可选负号的整数或一至两位小数。 ErrInvalidPercent = errors.New("common: invalid percent format") // ErrPercentOverflow 表示百分比转换为万分之一整数后超出 int64 范围。 ErrPercentOverflow = errors.New("common: percent overflows int64") )
Functions ¶
func FormatPercent ¶
FormatPercent 将万分之一整数转换为百分比字符串，最多两位小数并去除末尾零。 例如 1000 返回 10%，-1001 返回 -10.01%；支持 int64 完整范围，不使用浮点运算。
func FormatTime ¶
FormatTime 按应用时区输出 RFC3339 时间，nil 返回空字符串；调用前须初始化 Pixiu env。
func GenerateIDWithYYMMDDHHmmssSSS ¶
GenerateIDWithYYMMDDHHmmssSSS 返回原样前缀 + 应用时区的两位年月日时分秒 + 三位毫秒 + 四位随机数字（0000–9999）。 调用前须初始化 Pixiu env；结果可能重复，落库时须通过唯一索引和冲突重试保证唯一。
func MaskName ¶ added in v0.1.3
MaskName 对展示名称脱敏，按Unicode码点计数，空值和单字符原样返回，双字符只隐藏尾字。 三字符及以上保留首尾，中间分别使用1个、2个、最多3个符号；不裁剪空白或推断姓氏。 symbols仅取首项，省略、为空或不是合法UTF-8时使用*；非空字符串作为完整符号重复。 非法UTF-8名称整体替换为一个符号；组合音标和复合表情不按字素簇分割。
func ParsePercent ¶
ParsePercent 将带 % 后缀的百分比字符串转换为万分之一整数，例如 -10.01% 返回 -1001。 接受整数或一至两位小数、前导负号和前导零；负零返回 0，不限制在 0% 至 100%。 不清理空白，不接受正号、科学计数法或多余小数位，不舍入。 失败返回 0 和 ErrInvalidPercent 或 ErrPercentOverflow，可用 errors.Is 判断。
Types ¶
This section is empty.
Source Files