Help us shape the future of Go! Take the 2026 Go Developer Survey

kit

module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Oct 4, 2026 License: Apache-2.0

README

FilesCodeBox kit

CI Release License Go

FilesCodeBox 生态的共享 Go 工具库：28 个零生态依赖的通用包（重试、并发编排、限流、优雅停机、工作流等），供 core / server / fnos / p2p 及任意 Go 项目复用。

Shared Go toolkit for the FilesCodeBox ecosystem — 28 general-purpose packages with zero ecosystem dependencies.

设计原则

  • 零生态依赖（叶子仓）：不 import 任何 github.com/filescodebox/* 兄弟模块，CI 强制守卫；被任何模块依赖都不会成环。
  • stdlib 优先：绝大多数包纯标准库实现；仅 3 个包带轻量外部依赖（ratelimit → golang.org/x/time，uidgen → google/uuid，validator → go-playground/validator）。
  • 带测试发布：全部包附 -race 通过的单元测试；lint 棘轮从 0 issues 起步只收紧不放宽。

包总览

并发与重试
包 说明
async 安全 goroutine 启动工具（GoSafe 等 panic 恢复原语，进程兜底层）
group Actor 组：多长驻 goroutine 并发执行，任一返回即中断其余
singleflight 并发请求合并（防击穿）：同 key 并发调用只执行一次、共享结果
syncx 并发编排原语：按键在飞闸门 + 按序扇出收集
retry 可取消的重试与轮询：带退避的动作重试 + 到 deadline 的条件轮询
ratelimit 通用限流器（令牌桶 + 按键限流管理器，空闲键自动回收）
cache 进程内检查缓存：TTL 缓存 + 刷新进行中合一
progress 多阶段工作流进度追踪（有序阶段生命周期 + 总进度）
错误与校验
包 说明
errors 线程安全的多错误聚合
validator 统一参数验证（go-playground/validator 封装）
enumx 枚举管理
网络与数据
包 说明
httpjson HTTP+JSON 调用纪律单源：ctx 感知构造请求、重试与 Retry-After 尊重
jsonrepair LLM 输出宽容 JSON 修复：栅栏剥离 → 散文抽对象 → 逐层修复
encoding 编码与哈希工具
pagination 框架无关的分页参数定义
uidgen 分布式唯一 ID / 随机串生成
基础类型工具
包 说明
convert 常用类型转换
slicex 泛型 Slice 工具
stringx 字符串操作（截断等）
mathx 数学工具（统计等）
timex 时间操作 + cron 子包
pathx 文件路径匹配
ptrx 指针泛型工具
构建信息
包 说明
version 编译时版本注入（-ldflags）+ 运行时查询（Metadata()）
服务治理与网络
包 说明
shutdown 优雅停机管理器：信号接入 + 引用计数请求阻断 + 资源逆序释放（日志走 stdlib slog）
workflow 流程编排：Pipe 串行 / Parallel 并行 / Async+Future / Switch 条件分支，可任意嵌套，Hook AOP 递归传播
streamx 跨协议流式事件抽象（Event/Source/Sink/Hub）：一次写 Event，SSE/WS/Chunked 多协议扇出，零框架依赖
wsutil WebSocket 房间广播器：Conn 接口解耦不绑具体 ws 库，空房间自动清理、容错广播

日志约定：以上包的运行日志统一走 stdlib log/slog（slog.Default()），消费方可用自定义 handler 接管输出格式。

快速开始

go get github.com/filescodebox/kit/retry@latest

// 带退避的重试
err := retry.Do(ctx, retry.Config{Attempts: 3, Delay: 100 * time.Millisecond},
    func(attempt int) error { return doSomething() })

// 按键在飞闸门：同 key 并发上限（如按分片 ID 限在飞）
gate := syncx.NewKeyedGate(8) // cap<=0 = 不限
release, err := gate.Acquire(ctx, "chunk-42")
if err != nil { /* ctx 取消/排队失败 */ }
defer release()

各包自带 doc 注释与 _test.go 用例，行为以测试为准。

本仓库在生态中的位置

server / fnos / frontend ──► core ──► contracts ──► thrift runtime
p2p（叶子仓）                  └────► kit（本仓，叶子仓）

纯库仓：无二进制、无镜像、无 chart；以 git tag（v*）发布，go get 直接消费。

License

Apache-2.0。其中通用工具包移植自 enjoydream/ekit（MIT License, Copyright (c) 2024-2026 enjoydream），归属声明见 NOTICE。

Directories

Path Synopsis
Package async 提供安全的 goroutine 启动工具。
 Package async 提供安全的 goroutine 启动工具。
Package cache 进程内检查缓存原语（stdlib-only）：TTL 缓存 + 刷新进行中 并发合并（inflight singleflight）+ 失败短 TTL。
 Package cache 进程内检查缓存原语（stdlib-only）：TTL 缓存 + 刷新进行中 并发合并（inflight singleflight）+ 失败短 TTL。
Package convert 提供常用类型转换工具函数。
 Package convert 提供常用类型转换工具函数。
Package encoding 提供常用的编码和哈希工具函数。
 Package encoding 提供常用的编码和哈希工具函数。
Package enumx 提供枚举管理能力。
 Package enumx 提供枚举管理能力。
Package errors 提供线程安全的多错误聚合。
 Package errors 提供线程安全的多错误聚合。
Package group 提供并发 Actor 生命周期管理和 WaitGroup 封装。
 Package group 提供并发 Actor 生命周期管理和 WaitGroup 封装。
Package httpjson stdlib-only 的 HTTP+JSON 调用纪律单源：ctx 感知构造请求 → 执行 → 限容读体（读错误不吞）→ 状态码检查（错误体 rune 安全截断，不腰斩 UTF-8）→ JSON 解码，外加可选的指数退避重试与服务端 Retry-After 建议捕获。
 Package httpjson stdlib-only 的 HTTP+JSON 调用纪律单源：ctx 感知构造请求 → 执行 → 限容读体（读错误不吞）→ 状态码检查（错误体 rune 安全截断，不腰斩 UTF-8）→ JSON 解码，外加可选的指数退避重试与服务端 Retry-After 建议捕获。
Package jsonrepair LLM 输出宽容 JSON 修复骨架：栅栏剥离 → 散文抽对象 → 语法级修复 → 标量归一。
 Package jsonrepair LLM 输出宽容 JSON 修复骨架：栅栏剥离 → 散文抽对象 → 语法级修复 → 标量归一。
Package mathx 提供常用的数学工具函数。
 Package mathx 提供常用的数学工具函数。
Package pagination 提供框架无关的分页参数定义。
 Package pagination 提供框架无关的分页参数定义。
Package pathx 提供文件路径匹配工具。
 Package pathx 提供文件路径匹配工具。
Package progress 提供多阶段工作流的进度追踪模型。
 Package progress 提供多阶段工作流的进度追踪模型。
Package ptrx 提供指针相关的泛型工具函数。
 Package ptrx 提供指针相关的泛型工具函数。
Package ratelimit 提供通用限流器实现。
 Package ratelimit 提供通用限流器实现。
Package retry 可取消的重试与轮询原语（stdlib-only）：带退避的动作重试 + 到 deadline 为止的条件轮询。
 Package retry 可取消的重试与轮询原语（stdlib-only）：带退避的动作重试 + 到 deadline 为止的条件轮询。
Package shutdown 提供优雅关闭管理器。
 Package shutdown 提供优雅关闭管理器。
Package singleflight 提供并发请求合并（防击穿）工具。
 Package singleflight 提供并发请求合并（防击穿）工具。
Package slicex 提供泛型 Slice 工具函数。
 Package slicex 提供泛型 Slice 工具函数。
Package streamx 提供跨 SSE / WebSocket / Chunked Transfer 协议的 流式响应抽象(Event/Source/Sink/Hub),与 wsutil(Broadcaster 房间广播) 协同工作,业务可一次写 Event,多协议扇出。
 Package streamx 提供跨 SSE / WebSocket / Chunked Transfer 协议的 流式响应抽象(Event/Source/Sink/Hub),与 wsutil(Broadcaster 房间广播) 协同工作,业务可一次写 Event,多协议扇出。
Package stringx 提供常用的字符串操作工具函数。
 Package stringx 提供常用的字符串操作工具函数。
Package syncx 并发编排原语（stdlib-only）：按键在飞闸门 + 按序扇出收集。
 Package syncx 并发编排原语（stdlib-only）：按键在飞闸门 + 按序扇出收集。
Package timex 提供常用的时间操作工具函数。
 Package timex 提供常用的时间操作工具函数。
cron
Package cron 提供 Cron 表达式解析和调度功能。
 Package cron 提供 Cron 表达式解析和调度功能。
Package uidgen 提供分布式唯一 ID 生成器.
 Package uidgen 提供分布式唯一 ID 生成器.
Package validator 提供统一的参数验证能力。
 Package validator 提供统一的参数验证能力。
Package version 提供编译时版本信息注入和运行时查询。
 Package version 提供编译时版本信息注入和运行时查询。
Package workflow 提供组合式流程编排框架。
 Package workflow 提供组合式流程编排框架。
Package wsutil 提供通用 WebSocket 基础设施。
 Package wsutil 提供通用 WebSocket 基础设施。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.