go

Go Utils

English | 简体中文

A collection of commonly used Go utilities for web development (with Hertz-friendly integrations).

Install

go get github.com/kainonly/go

Modules

Quick Start

vd (validator)

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

v := vd.Default()

type User struct {
	Name  string `vd:"required,snake"`
	Phone string `vd:"required,phone"`
}
_ = v.Validate(&User{Name: "user_name", Phone: "13800138000"})

passport (JWT HS256)

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

auth := passport.New(
	passport.SetKey("your-secret-key"),
	passport.SetIssuer("your-app"),
)

claims := passport.NewClaims()
claims.ID = "user-123"
claims.SetData(map[string]any{"role": "admin"})

token, _ := auth.Create(claims)
_, _ = auth.Verify(token)

csrf (double-submit cookie)

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

_ = csrf.New(
	csrf.SetKey("your-secret-key"),
	csrf.SetDomain("example.com"),
)

vd - Validator

Wrapper around go-playground/validator with Hertz integration and a set of commonly used rules.

Basic usage

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

v := vd.Default()

v := vd.New(
	vd.SetTag("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"})
_ = err

Hertz integration

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.Spin()
}

Available rules

Rule groups

CN localized

Password strength

Naming conventions

Misc

Custom rule

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

passport - JWT Auth

JWT authentication based on HS256.

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

auth := passport.New(
	passport.SetKey("your-secret-key"),
	passport.SetIssuer("your-app"),
)

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

claims, err = auth.Verify(token)
_ = claims
_ = err

csrf - CSRF Protection

CSRF middleware using the double-submit cookie approach.

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

c := csrf.New(
	csrf.SetKey("your-secret-key"),
	csrf.SetDomain("example.com"),
)
_ = c

captcha - Captcha

Captcha management backed by 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 - Lockout

Redis-based counter and lockout helper for scenarios like login failures and rate limiting.

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

lock := locker.New(redisClient)

count, err := lock.Increment(ctx, "login:user123", time.Minute)
_ = count
_ = err

err = lock.Check(ctx, "login:user123", 5)
if errors.Is(err, locker.ErrLocked) {
}

lock.Delete(ctx, "login:user123")

passlib - Password Hashing

Argon2id-based password hashing.

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

hash, err := passlib.Hash("password123")
_ = err

err = passlib.Verify("password123", hash)

if passlib.NeedsRehash(hash) {
	newHash, _ := passlib.Hash("password123")
	_ = newHash
}

totp - One-time Password

TOTP secret generation and code validation.

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

secret, err := totp.GenerateSecret()
_ = secret
_ = err

valid, err := totp.Validate(code, secret)
_ = valid
_ = err

cipher - Encryption

Symmetric encryption helpers.

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

c := cipher.New(cipher.SetKey("your-32-byte-key"))

encrypted, err := c.Encode(data)
_ = encrypted
_ = err

decrypted, err := c.Decode(encrypted)
_ = decrypted
_ = err

help - Helpers

Misc helper functions.

Random

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

help.Random(16)
help.RandomNumber(6)
help.RandomAlphabet(8)
help.RandomUppercase(8)
help.RandomLowercase(8)

ID

help.Uuid7()
help.MustUuid7()
help.Uuid7Time(id)
help.Uuid()
help.SID()

Why UUIDv7?

• Time-ordered IDs; new records naturally come later
• Better index locality for databases with sequential inserts
• Extract creation time from the ID

Crypto helpers

help.Sha256hex(s)
help.HmacSha256(s, key)

SM2/SM4 (GM/T)

sig, _ := help.Sm2Sign(privateKey, data)
valid := help.Sm2Verify(publicKey, data, sig)
_ = valid

encrypted, _ := help.SM4Encrypt(key, plaintext)
decrypted, _ := help.SM4Decrypt(key, encrypted)
_ = decrypted

Misc

help.Ptr(value)
help.IsEmpty(value)
help.Reverse(slice)
help.Shuffle(slice)

License

BSD-3-Clause License