go

Go Utils

Go 常用工具库集合，提供 Web 开发中常用的功能组件。

安装

go get github.com/kainonly/go

模块

vd - 验证器

基于 go-playground/validator 的验证器封装，支持 Hertz 框架集成和自定义验证规则。

基础用法

import "github.com/kainonly/go/vd"

// 使用默认规则 (snake, sort)
v := vd.Default()

// 自定义规则
v := vd.New(
    vd.SetTag("vd"),  // 可选，默认为 "vd"
    vd.SetRules(
        vd.Snake(),
        vd.Sort(),
        vd.Phone(),
        vd.IDCard(),
        vd.PasswordMedium(),
    ),
)

// 验证结构体
type User struct {
    Name  string `vd:"required,snake"`
    Phone string `vd:"required,phone"`
}
err := v.Validate(&User{Name: "user_name", Phone: "13800138000"})

Hertz 集成

import (
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/kainonly/go/vd"
)

func main() {
    v := vd.New(vd.SetRules(vd.All()...))

    h := server.Default(
        server.WithHostPorts(":8080"),
        server.WithCustomValidator(v.Engine()),
    )

    h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
        var req struct {
            Name  string `json:"name" vd:"required,snake"`
            Phone string `json:"phone" vd:"required,phone"`
        }
        if err := c.BindAndValidate(&req); err != nil {
            c.JSON(400, map[string]any{"error": err.Error()})
            return
        }
        c.JSON(200, map[string]any{"message": "ok"})
    })

    h.Spin()
}

可用验证规则

规则分组

中国本地化

密码强度

命名规范

其他规则

自定义规则

v := vd.New(vd.SetRules(
    vd.Rule{
        Tag: "even",
        Fn: func(fl vd.FieldLevel) bool {
            return fl.Field().Int() % 2 == 0
        },
    },
))

passport - JWT 认证

基于 HS256 的 JWT 认证。

import "github.com/kainonly/go/passport"

// 创建认证器
auth := passport.New(
    passport.SetKey("your-secret-key"),
    passport.SetIssuer("your-app"),
)

// 创建 Token
claims := passport.NewClaims()
claims.ID = "user-123"
claims.SetData(map[string]any{"role": "admin"})
token, err := auth.Create(claims)

// 验证 Token
claims, err := auth.Verify(token)

csrf - CSRF 防护

双重 Cookie 验证的 CSRF 防护中间件。

import "github.com/kainonly/go/csrf"

// 创建 CSRF 防护
c := csrf.New(
    csrf.SetKey("your-secret-key"),
    csrf.SetDomain("example.com"),
)

// Hertz 中间件
h.Use(c.VerifyToken())

// 设置 Token Cookie
h.GET("/csrf", func(ctx context.Context, c *app.RequestContext) {
    csrf.SetToken(c)
})

captcha - 验证码

基于 Redis 的验证码管理。

import "github.com/kainonly/go/captcha"

// 创建验证码管理器
cap := captcha.New(redisClient)

// 创建验证码
cap.Create(ctx, "login:user123", "123456", 5*time.Minute)

// 验证
err := cap.Verify(ctx, "login:user123", "123456")
if errors.Is(err, captcha.ErrInvalidCode) {
    // 验证码错误
}
if errors.Is(err, captcha.ErrNotExists) {
    // 验证码不存在或已过期
}

locker - 限流器

基于 Redis 的限流与尝试次数计数。

import "github.com/kainonly/go/locker"

// 创建限流器
lock := locker.New(redisClient)

// 增加计数
count, err := lock.Increment(ctx, "login:user123", time.Minute)

// 检查是否锁定
err := lock.Check(ctx, "login:user123", 5) // 最多 5 次
if errors.Is(err, locker.ErrLocked) {
    // 已锁定
}

passlib - 密码哈希

基于 Argon2id 的密码哈希。

import "github.com/kainonly/go/passlib"

// 哈希密码
hash, err := passlib.Hash("password123")

// 验证密码
err := passlib.Verify("password123", hash)

// 检查是否需要重新哈希
if passlib.NeedsRehash(hash) {
    newHash, _ := passlib.Hash("password123")
}

totp - 一次性密码

TOTP 一次性密码生成与验证。

import "github.com/kainonly/go/totp"

// 生成密钥
secret, err := totp.GenerateSecret()

// 验证 OTP
valid, err := totp.Validate(code, secret)

cipher - 加密

对称加密工具。

import "github.com/kainonly/go/cipher"

// 创建加密器
c := cipher.New(cipher.SetKey("your-32-byte-key"))

// 加密
encrypted, err := c.Encode(data)

// 解密
decrypted, err := c.Decode(encrypted)

help - 工具函数

公共工具函数集合。

随机生成

import "github.com/kainonly/go/help"

help.Random(16)           // 随机字符串
help.RandomNumber(6)      // 随机数字
help.RandomAlphabet(8)    // 随机字母
help.RandomUppercase(8)   // 随机大写
help.RandomLowercase(8)   // 随机小写

ID 生成

help.Uuid()               // UUID v4
help.SID()                // Snowflake ID

加密工具

help.Sha256hex(s)         // SHA256 哈希
help.HmacSha256(s, key)   // HMAC-SHA256

国密 SM2/SM4

// SM2 签名验签
sig, _ := help.Sm2Sign(privateKey, data)
valid := help.Sm2Verify(publicKey, data, sig)

// SM4 加解密
encrypted, _ := help.SM4Encrypt(key, plaintext)
decrypted, _ := help.SM4Decrypt(key, encrypted)

其他工具

help.Ptr(value)           // 获取值的指针
help.IsEmpty(value)       // 检查是否为空
help.Reverse(slice)       // 反转切片
help.Shuffle(slice)       // 打乱切片

License

BSD-3-Clause License