stringx

package
v0.53.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 15 Imported by: 8

Documentation

Overview

Package stringx 提供常用的字符串操作工具函数。

包含字符串查找、过滤、截取、反转、大小写转换、多模式替换 (Replacer trie 最长匹配 / NewMask 敏感词遮罩)等功能。 所有函数均安全处理 UTF-8 编码的字符串。

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	// ErrInvalidStartPosition indicates the start position is invalid.
	ErrInvalidStartPosition = errors.New("start position is invalid")
	// ErrInvalidStopPosition indicates the stop position is invalid.
	ErrInvalidStopPosition = errors.New("stop position is invalid")
	// ErrInvalidRange indicates the substring range is inverted (start > stop).
	ErrInvalidRange = errors.New("substring range is inverted")
)

Functions

func Contains

func Contains(list []string, str string) bool

Contains 检查 str 是否在 list 中。

语义单源在 stdlib slices.Contains(slicex.Contains 已 Deprecated 委托 stdlib,#536d;本函数相应直调 stdlib,保留仅为字符串场景的可读性—— 实现是一行转发,不是第二份副本,#242)。

func ContainsAny

func ContainsAny(text string, keywords ...string) bool

ContainsAny 检查 text 中是否包含 keywords 中的任意一个关键词(不区分大小写)。

用法:

stringx.ContainsAny("Security vulnerability found", "security", "vuln") // true
stringx.ContainsAny("normal text", "critical", "major")                 // false

func DeleteFunc added in v0.33.0

func DeleteFunc(s string, del func(r rune) bool) string

DeleteFunc 从 s 中删除满足 del 条件的字符(剔除命中;方向自解释,命名对齐 slices.DeleteFunc 的口径)。

这是 Filter 在 v0.32 及以前的行为(#173 语义对齐后迁移至此):

// 剔除控制字符(净化回显)
clean := stringx.DeleteFunc(s, unicode.IsControl)

func Filter

func Filter(s string, filter func(r rune) bool) string

Filter 返回 s 中满足 filter 条件的字符(保留命中)。

⚠️ 语义变更(#173,破坏性):v0.32 及以前本函数是「剔除命中」(命中即删), 与同库 slicex.Filter(保留命中)同名反方向——谓词写反零报错,只是结果里 多/少了字符(实测事故:净化函数按「保留命中」的肌肉记忆写谓词,控制字符 被留在回显里)。v0.33.0 起与 slicex.Filter / 主流 filter 语义对齐(JS Array.filter、Java Stream.filter、Rust Iterator::filter 皆保留命中)。

迁移(按意图二选一):

  • 原「剔除命中」(filter(x)=true 的字符被删):改用 DeleteFunc;
  • 原谓词写的是「保留条件」却以为在删:改用 Filter/KeepFunc(结果反转)。

方向要在调用点自解释时用 KeepFunc(保留命中)/ DeleteFunc(剔除命中)对偶入口。

func FirstN

func FirstN(s string, n int, ellipsis ...string) string

FirstN 返回 s 的前 n 个字符,可选添加省略号。

边界口径:n <= 0 一律按「保留 0 个」处理(返回空串+省略号),与 LastN 同口径——#183 修复了 n<0 静默返回整串,#300 补上 n==0 的缝隙:此前空串 + n==0 落进 range 循环(循环体零次)返回裸空串,是 (空串,0) 格上唯一 不带省略号的结论。

func FormatTemplate

func FormatTemplate(template string, vars map[string]any) string

FormatTemplate 用 vars 替换 template 里的 {key} 占位符。

模板语法: `{key}` 形式,key 在 vars 里查找。

  • 未找到的 key 保留原 `{key}` 不替换(避免静默替换空字符串导致歧义)
  • 嵌套 key 不支持(只 1 层)
  • 业务场景: 错误信息模板("user {user_id} not found in tenant {tenant_id}") SQL 模板("SELECT * FROM users WHERE id = {id}"),log 模板

用法:

msg := stringx.FormatTemplate("user {user_id} not found", map[string]any{
    "user_id": 42,
})
// → "user 42 not found"

注意: 这个函数不转义;如果业务需要把用户输入嵌入 SQL/HTML,先做 业务自己的转义/参数化(否则是注入漏洞)。

func GenerateID

func GenerateID() string

GenerateID 生成基于时间戳的唯一 ID,格式: 20060102150405-<8位hex>。 适用于非严格唯一性要求的场景(如日志关联、临时标识)。 如需全局唯一,请使用 UUIDv4。

func HasEmpty

func HasEmpty(args ...string) bool

HasEmpty 检查 args 中是否存在空字符串。

func IndentText

func IndentText(text, prefix string) string

IndentText 为多行文本的第二行及之后每行添加缩进前缀。 第一行不缩进,适用于续行对齐场景。

用法:

stringx.IndentText("line1\nline2\nline3", "  ")
// => "line1\n  line2\n  line3"

func Join

func Join(sep byte, elem ...string) string

Join 将多个字符串用 sep 连接,忽略空字符串。

func JoinByComma

func JoinByComma(str []string) string

JoinByComma 将字符串切片用逗号连接。

func JoinWith

func JoinWith(elem []string, sep string) string

JoinWith 将字符串切片用指定分隔符连接。

⚠️ 与 strings.Join 语义不同(#299 声明,非缺陷修复):空元素被静默丢弃 (不占位)——JoinWith([]string{"a","","b"}, ",") = "a,b",而 strings.Join 得 "a,,b"。本函数名与 strings.Join(elem, sep) 签名同形,跳过语义却相反, 故在此显式声明。同族 Join(变参版)的「忽略空字符串」与此一致。

需要空位占位的按位解析场景(CSV 行/按位拆字段/缓存 key 域数固定)请用 strings.Join 或 JoinByComma——按 stdlib 语义保留空位。

func KeepFunc added in v0.33.0

func KeepFunc(s string, keep func(r rune) bool) string

KeepFunc 返回 s 中满足 keep 条件的字符(保留命中;方向自解释,命名对齐 slices.KeepFunc 的口径)。与 Filter 同语义——Filter 与 slicex.Filter 对齐后即「保留命中」(#173)。

func LastN added in v0.32.0

func LastN(s string, n int, ellipsis ...string) string

LastN 返回 s 的最后 n 个字符(保尾截断:丢前缀、留后缀——文件名限长保 扩展名、路径限长保末段这类「尾部比头部更有信息量」的场景),可选在头部 添加省略号。与 FirstN 互为镜像:FirstN 保头、省略号拼尾;LastN 保尾、 省略号拼头。未发生截断时原样返回(不拼省略号)。

边界口径:n <= 0 一律按「保留 0 个」处理(返回空串+省略号),与 FirstN 同口径——#183/#300 之后 FirstN 亦 n<=0 全截断(返回空串+省略号,含空串 +n==0 格),两者不再存在差异;此前注释声称的「有意不同」描述的是 FirstN 修复前的行为。

func MaskJSONFields added in v0.35.0

func MaskJSONFields(raw []byte, masks map[string]string) ([]byte, error)

MaskJSONFields 把 JSON 对象里指定字段的值替换为固定文案(字段级脱敏)。

语义(与既有消费方 kuboard-go maskSensitiveSystemConfig 逐字一致——已验证实现上移):

  • 输入必须是**顶层 JSON 对象**;解析失败时返回 json 包的**原始错误**(不包装—— 消费方会把错误文本透传到响应,包装即改文案,这是刻意的);
  • 输入为 JSON null 时与 `{}` 同口径处理(#254):null 是合法 JSON 且 Unmarshal 后得到 nil map(err==nil,错误分支拦不住),nil map 写入 会 panic——脱敏常在日志/错误处理旁路上调用,panic 会盖掉真正的错误。 null 无字段可脱敏 ⇒ 原样返回;
  • masks 里声明的字段**缺省时也会补上**(map 赋值语义);
  • 输出经 json.Marshal 重序列化(map 键按字典序输出——与消费方既有行为一致)。

func NotEmpty

func NotEmpty(args ...string) bool

NotEmpty 检查 args 中所有字符串是否都不为空。

func Pluralize

func Pluralize(count int, word string) string

Pluralize 返回英文单词的复数形式。 规则:

  • count == 1 → "1 word"
  • 以 "y" 结尾且前一个字符为辅音 → 去 "y" 加 "ies" (story → stories)
  • 以 "s", "sh", "ch", "x", "z" 结尾 → 加 "es" (box → boxes)
  • 其他 → 加 "s" (file → files)
  • word 为空 → "<count> "(计数仍然保留)

用法:

stringx.Pluralize(3, "file")   // "3 files"
stringx.Pluralize(1, "file")   // "1 file"
stringx.Pluralize(5, "story")  // "5 stories"

func RandomToken added in v0.53.0

func RandomToken(nBytes int, enc TokenEncoding) (string, error)

RandomToken 生成 nBytes 字节纯随机令牌并按 enc 编码(#528)。

与 GenerateID 的分工:GenerateID = 时间戳前缀 + 4 字节随机的**可读 ID** (日志关联、临时标识这类非严格唯一场景);本函数是**纯随机令牌**—— 分布式锁 ownerID、版本/幂等令牌、会话 ID 等安全性敏感或必须不可预测的 场景,没有时间戳语义,不接受降级。

长度(nBytes 字节随机性恒定,编码只影响字符数):

  • TokenHex:2×nBytes 字符;
  • TokenBase64Std / TokenBase64RawURL:4×⌈nBytes/3⌉ 字符(std 带 Equal padding,raw URL 无 padding)。

错误(仓规总则①③):

  • nBytes <= 0 或 enc 非法:参数非法,返回 error——确定性编程错误, fail-fast,不做任何隐式替换;
  • crypto/rand 读取失败:显式上抛,**不静默退化**(Go 1.24+ 的 crypto/rand.Read 保证填满且不返回错误,熵源不可用直接 panic 在其 内部——此分支仅为显式契约,理论不可达;静默退化会产出可预测令牌, 对安全令牌是不可接受的下界)。需要降级语义的调用方请用 RandomTokenOrFallback,降级策略由调用方显式提供。

func RandomTokenOrFallback added in v0.53.0

func RandomTokenOrFallback(nBytes int, enc TokenEncoding, fallback func() string) (string, error)

RandomTokenOrFallback 是 RandomToken 的显式降级变体(#528):随机源 失败时改返回 fallback() 的结果——fallback 由调用方提供(如退回 GenerateID 时间戳 ID),包不做隐式退化。

返回值语义:

  • err 非 nil:仅参数/用法错误(nBytes<=0、enc 非法、fallback 为 nil) ——确定性编程错误**不触发降级**(fallback 每次都吞掉同一个 bug 会让 假令牌静默常态化),原样上抛;
  • err 为 nil 且值为 fallback 结果:仅随机源失败这一运行期失败发生时, 按调用方的显式选择降级。降级成功返回 nil error——若随值带回原始 错误,`if err != nil` 风格的调用方会把降级值当失败丢掉,本变体形同 虚设;调用方选择降级即已知晓失败可能,需要观测时应在 fallback 内 自行记录。

func Remove

func Remove(list []string, strs ...string) []string

Remove 从 strings 中移除指定的 strs。

func Reverse

func Reverse(s string) string

Reverse 反转字符串。

func SplitByComma

func SplitByComma(str string) []string

SplitByComma 将字符串按逗号分割。

func SplitCSVNonEmpty added in v0.22.0

func SplitCSVNonEmpty(s string) []string

SplitCSVNonEmpty 按逗号拆分字符串(RFC 4180 引号语义),逐项去掉首尾 空白并丢弃空项。

与 SplitByComma 的区别:SplitByComma 就是 strings.Split(s, ",")——不认 引号、不 trim、不过滤空项、空串返回 [""](1 个空元素),名字叫「按逗号 拆」但实际把「拆完顺手清干净」这层留给每个消费方各写一遍(典型样板: strings.Split → 逐项 TrimSpace → 跳过空项)。本原语把那层样板一次收进去。

与 SplitWith 的区别(不要拿 SplitWith 顶替):SplitWith 走 strings.Fields, 按**空白**切分,值里含空格时(如 glob 列表 "my glob")会被静默拆成两项, 改变语义。CSV 值的空白是有意义的("a b" 是一个值,不是两个),所以这条 面需要按逗号切的专门原语,而不是拿现有函数拼。

引号口径([#259],RFC 4180):

  • 字段以双引号开头即按引号字段解析:引号内的逗号**不切分**( `"a,b",c` → ["a,b" "c"]——此前被静默切成 ["\"a" "b\"" "c"], 含逗号的地址 / JSON 片段 / SQL 条件等产品名一个字段拆成两段且不报错);
  • 引号内的 `""` 是字面引号(`"a""b"` → `a"b`);
  • 引号在值外**剥离**(`"x"` → `x`——此前第三种不一致状态:不解释、 也不剥离,原样保留);
  • 引号内的空白是值的一部分,不 trim 内部;两端引号外的空白仍按 「逐项去首尾空白」处理(`"a, b" , c` → ["a, b" "c"]);
  • 未闭合引号宽松兜底:余下全部并入当前字段,不报错(本函数族 「拆分不做尽力校验」的既有立场);
  • 闭合引号后到下一逗号之间的残余字符(如 `"a"x` 的 x)宽松并入 当前字段,与 RFC 对畸形输入「未定义」的行为不同,这里选择不丢字。

口径(写死在本函数契约里):

  • 逐项去掉**首尾**空白(strings.TrimSpace,含 Unicode 空白);
  • 去掉空白后为空的项**丢弃**("a,,b" → ["a","b"],引号空字段 "" 同样丢弃);
  • **空串返回 nil**(不是空切片)——调用方普遍用 != nil / len()>0 区分 「没配」与「配了空」,返回空切片会把两者混同;
  • 全是空白或空项的输入(""、" "、",,")同样返回 nil。

用法:

stringx.SplitCSVNonEmpty(`"a,b",c`)  // ["a,b" "c"]
stringx.SplitCSVNonEmpty(`"x"`)      // ["x"]
stringx.SplitCSVNonEmpty("a, b,,c")  // ["a" "b" "c"]
stringx.SplitCSVNonEmpty("")         // nil
stringx.SplitCSVNonEmpty("  ,  ")    // nil

func SplitWith

func SplitWith(str string, sep []string) []string

SplitWith 将字符串按指定分隔符列表分割后返回字段切片。

func Substr

func Substr(str string, start, stop int) (string, error)

Substr 返回 [start, stop) 范围内的子字符串,支持 UTF-8。

func TakeOne

func TakeOne(valid, or string) string

TakeOne 返回非空的字符串,如果 valid 非空则返回 valid,否则返回 or。

func TakeWithPriority

func TakeWithPriority(fns ...func() string) string

TakeWithPriority 返回第一个非空的函数返回值。

func ToCamelCase

func ToCamelCase(s string) string

ToCamelCase 将字符串首字母转为小写。

按 rune 处理(多字节首字符不被截断)。非法 UTF-8 字节不 panic:range 会把 非法字节解成 U+FFFD,其**实际**宽度是 1 字节,而 utf8.RuneLen(U+FFFD) 是 3 ⇒ 此前用 RuneLen 切片会越界(slice bounds out of range [3:1])。

func TruncBytes

func TruncBytes(s string, budget int) (string, bool)

TruncBytes 按字节预算截断(rune 对齐:预算落点切进多字节字符时回退到 RuneStart 边界,不产生非法 UTF-8 尾字节)。第二个返回值 = 是否真发生了 截断。budget<0 视为非法上限,按"全部截断"处理(返回空串),不 panic。

func TruncEllipsis

func TruncEllipsis(s string, n int) string

TruncEllipsis 截断并追加省略号(列表/标题/事件载荷展示面统一语义)。 n<=0 返回省略号;无需截断时原样返回。

**n 的语义是「截断到 n 个 rune」,不含省略号**:返回值长度为 n(未截断)或 n+1(发生截断,省略号算 1 个 rune)。若调用方的 n 是"总长度预算" (如提交状态描述的 140 字符上限),本函数会超出预算 1 个字符——那种场景用 TruncRunes 自行拼接,或先按预算减 1 再调用。

func TruncRunes

func TruncRunes(s string, n int) (string, bool)

TruncRunes 按 rune 截断,避免多字节字符被腰斩产生非法 UTF-8。 第二个返回值 = 是否真发生了截断。n<0 视为非法上限,按"全部截断"处理 (返回空串),不 panic。

func UUIDv4 added in v0.53.0

func UUIDv4() string

UUIDv4 生成 RFC 4122 version 4 随机 UUID(#531):crypto/rand 16 字节, b[6]&0x0f|0x40 置版本位、b[8]&0x3f|0x80 置变体位,标准 8-4-4-4-12 连字符格式(小写 hex)。

全矩阵 UUIDv4 的**单源**:kitx/uidgen 与 pkg/webhook(NewEventID 的 uuidv4 内联段)后续改为委托本函数,本单只加符号不迁消费方。

随机源失败直接 panic(与 tracing/traceid.NewID 同理,仓规总则③): UUID 的存在意义就是全局唯一,生成失败静默回退(空串/零串/时间戳)会让 两个调用方拿到同一个"UUID",撞车没有下界——这类失败必须显式炸出来。 crypto/rand.Read 自 Go 1.24 起保证填满且不返回错误(熵源不可用直接 panic 在其内部),此分支仅为显式契约,理论不可达。

func Union

func Union(first, second []string) []string

Union 合并两个字符串切片并去重。

Types

type Masker added in v0.16.0

type Masker struct {
	// contains filtered or unexported fields
}

Masker 形态脱敏器。

构造后只读,可安全并发使用。

func NewMasker added in v0.16.0

func NewMasker(rules []Rule) (*Masker, error)

NewMasker 创建形态脱敏器。

规则表由调用方完全提供,库不内置任何业务词表。返回 error 的情形:

  • Re == nil;
  • Name 为空;
  • Name 重复(形态标签重复会让审计结果有歧义);
  • Name 含定界符 '«' / '»' 或控制字符(输出将无法稳定解析);
  • Keep 为负数。

规则表为空(nil)时返回可用的空脱敏器,Mask 原样返回输入。

Example
rules := []Rule{
	{Name: "kv-secret", Re: regexp.MustCompile(`token=([^\s]+)`), Keep: 2},
}
m, err := NewMasker(rules)
if err != nil {
	fmt.Println("error:", err)
	return
}
fmt.Println(m.Mask("call api with token=abcdef123456"))
Output:
call api with to«kv-secret:****»56

func (*Masker) Mask added in v0.16.0

func (m *Masker) Mask(text string) string

Mask 对 text 做形态脱敏,返回打码后的文本。

打码是单次扫描合并:命中某条规则后,该段文本被替换为 head + «name:****» + tail(命中长度不足 Keep*4 时退化为 «name:****»), 替换结果不再参与任何规则的匹配。 未命中任何规则的文本原样保留。

type Replacer added in v0.7.0

type Replacer struct {
	// contains filtered or unexported fields
}

Replacer 多模式字符串替换器。 与 strings.Replacer 的差异:按 rune 对齐匹配(不撕裂 UTF-8), 且同一起点恒取最长匹配。

func NewMask added in v0.7.0

func NewMask(words []string, mask rune) (*Replacer, error)

NewMask 创建遮罩替换器:把 words 中每个词替换为等 rune 数的 mask 串。 用于敏感词遮罩场景,是 NewReplacer 的薄壳。

func NewReplacer added in v0.7.0

func NewReplacer(patterns, repls []string) (*Replacer, error)

NewReplacer 创建多模式替换器:patterns[i] 命中的子串替换为 repls[i]。 两者长度必须一致;空 pattern 或 nil patterns(不替换任何词)的处理见 返回值。同名 pattern 后写覆盖先写。

func (*Replacer) Replace added in v0.7.0

func (r *Replacer) Replace(text string) string

Replace 按 trie 最长匹配扫描 text 并替换。 按 rune 边界迭代:未命中的 rune 原字节保留(非法 UTF-8 序列不被 改写为 U+FFFD),命中的词整体替换。

type Rule added in v0.16.0

type Rule struct {
	// Name 形态标签,如 "url-userinfo";会原样出现在掩码里供审计读。
	// 不能为空、不能与同一规则表内其它规则的 Name 重复,也不能含定界符
	// '«' / '»' 或控制字符(否则输出无法被稳定解析)。
	Name string
	// Re 匹配待脱敏内容的正则。命中的**整段**文本被替换为掩码
	// (本库不区分捕获组,捕获组只影响匹配范围,不影响替换范围)。
	// 为 nil 时 NewMasker 报错。零宽匹配(空匹配)会被忽略。
	Re *regexp.Regexp
	// Keep 掩码保留首尾各几个字符作定位线索;0 = 全掩。
	// 语义是**封顶**:保留的字符数不随原值长度变化(见包内说明)。
	//
	// **命中长度不足 Keep*4 时整段全量打码(不做头尾保留)**——短值的头尾
	// 保留会首尾相接覆盖整段原文,原值会完整留在输出里,掩码形同虚设。
	// 调用方不必自己判断命中长度。
	//
	// 负数视为非法,NewMasker 报错。
	Keep int
}

Rule 一条脱敏规则。

规则表由调用方完全提供,库不内置任何词表:Re 负责「按形态认出」待脱敏 内容,Name 是形态标签(会出现在掩码里供审计读),Keep 控制保留的定位 线索位数。

type TokenEncoding added in v0.53.0

type TokenEncoding int

TokenEncoding 是 RandomToken 的令牌字节编码格式。

const (
	// TokenHex 小写十六进制(encoding/hex):每个字节 2 字符,nBytes=16
	// 得 32 字符。字符集最保守(0-9a-f),日志 / URL / header 全场景无歧义。
	TokenHex TokenEncoding = iota

	// TokenBase64Std 标准 base64(encoding/base64 StdEncoding,含 +/ 与
	// = padding):非 URL 安全,适合入库、报文等不经 URL 的场景。
	TokenBase64Std

	// TokenBase64RawURL URL 安全 base64、无 padding(RawURLEncoding):
	// 字符集 A-Za-z0-9-_,适合放进 URL path/query 与 HTTP header。
	TokenBase64RawURL
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL