Documentation
¶
Overview ¶
Package help provides common utility functions for Go applications.
It includes:
- Random string generation (cryptographically secure)
- UUID and Snowflake ID generation
- Slice/string manipulation (reverse, shuffle)
- Map to query string conversion
- SM2/SM4 cryptographic utilities
- Hertz framework integration helpers
Index ¶
- Variables
- func E(code int64, msg string) *errors.Error
- func ErrorHandler() app.HandlerFunc
- func HmacSha256(s, key string) string
- func IsEmpty(i any) bool
- func MapToSignText(d map[string]any) string
- func MustUuid7() string
- func PrivKeySM2FromBase64(v string) (*sm2.PrivateKey, error)
- func Ptr[T any](i T) *T
- func PubKeySM2FromBase64(v string) (*ecdsa.PublicKey, error)
- func Random(n int, charset ...string) string
- func RandomAlphabet(n int) string
- func RandomLowercase(n int) string
- func RandomNumber(n int) string
- func RandomUppercase(n int) string
- func Reverse[T any](v []T)
- func ReverseString(v string) string
- func SID() string
- func SIDWithError() (string, error)
- func SM4Decrypt(hexkey string, ciphertext string) (string, error)
- func SM4Encrypt(hexkey string, plaintext string) (string, error)
- func SM4Verify(key string, ciphertext string, plaintext string) (bool, error)
- func Sha256hex(s string) string
- func Shuffle[T any](v []T)
- func ShuffleString(v string) string
- func Sm2Sign(key *sm2.PrivateKey, text string) (string, error)
- func Sm2Verify(pubKey *ecdsa.PublicKey, text string, sign string) (bool, error)
- func Uuid() stringdeprecated
- func Uuid7() string
- func Uuid7Time(s string) (int64, bool)
- func Validator() *vd.Validatordeprecated
- type ErrorMeta
- type R
Constants ¶
This section is empty.
Variables ¶
var ( ErrSM2InvalidPublicKey = errors.New("sm2: invalid public key format") ErrSM2InvalidPrivateKey = errors.New("sm2: invalid private key format") ErrSM2InvalidSignature = errors.New("sm2: invalid signature format") )
SM2 related errors.
var ( ErrSM4InvalidKey = errors.New("sm4: invalid key, must be 32 hex characters (16 bytes)") ErrSM4InvalidCiphertext = errors.New("sm4: invalid ciphertext") ErrSM4InvalidPadding = errors.New("sm4: invalid PKCS5 padding") ErrSM4EmptyData = errors.New("sm4: data is empty") )
SM4 related errors.
var ErrSonyflakeNil = &sonyflakeError{"sonyflake: not initialized, SF is nil"}
ErrSonyflakeNil is returned when SF is nil (Sonyflake initialization failed).
var ErrorTypePublic = errors.ErrorTypePublic
ErrorTypePublic is the type for public errors in Hertz framework.
var SF = sonyflake.NewSonyflake(sonyflake.Settings{})
SF is a global Sonyflake instance for generating distributed unique IDs. Sonyflake generates 63-bit unique IDs inspired by Twitter's Snowflake.
Default Configuration:
- MachineID: Lower 16 bits of the private IP address
- StartTime: 2014-09-01 00:00:00 UTC (Sonyflake default)
For containerized/distributed environments where multiple instances may share the same IP (e.g., Kubernetes pods), you should replace SF with a custom configured instance at application startup:
func init() {
help.SF = sonyflake.NewSonyflake(sonyflake.Settings{
MachineID: func() (uint16, error) {
// Use pod name hash, environment variable, or other unique identifier
id, _ := strconv.Atoi(os.Getenv("MACHINE_ID"))
return uint16(id), nil
},
})
}
Note: SF may be nil if initialization fails (rare, typically only when the machine has no valid private IP). SID() and SIDWithError() handle this case gracefully.
var SM2UID = []byte{0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38}
SM2UID is the default user ID for SM2 signing/verification. This is the standard 16-byte UID "1234567812345678".
Functions ¶
func E ¶
E creates a public Hertz error with a code. Use this for business logic errors that should be shown to users.
func ErrorHandler ¶
func ErrorHandler() app.HandlerFunc
ErrorHandler returns a Hertz middleware that handles errors. It processes different error types:
- Public errors: Returns 400 with code and message
- Validation errors: Returns 400 with field details
- Other errors: Returns 500 (with details in dev mode)
Set MODE=release environment variable for production mode.
func HmacSha256 ¶
HmacSha256 computes HMAC-SHA256 and returns raw bytes as string. For hex output, use hex.EncodeToString on the result.
func IsEmpty ¶
IsEmpty checks if a value is considered empty. Returns true for nil, empty strings, zero values, empty slices/maps, etc.
func MapToSignText ¶
MapToSignText converts a map to a URL-encoded query string format. Keys are sorted alphabetically, nil and empty values are omitted. Format: "key1=value1&key2=value2"
func MustUuid7 ¶ added in v1.0.1
func MustUuid7() string
MustUuid7 generates a new UUID v7 string or panics on error. Use this when UUID generation failure should be fatal.
func PrivKeySM2FromBase64 ¶
func PrivKeySM2FromBase64(v string) (*sm2.PrivateKey, error)
PrivKeySM2FromBase64 parses a base64-encoded SM2 private key. The key should be in PKCS8 format (DER encoded, then base64).
func Ptr ¶
func Ptr[T any](i T) *T
Ptr returns a pointer to the given value. Useful for creating pointers to literals.
func PubKeySM2FromBase64 ¶
PubKeySM2FromBase64 parses a base64-encoded SM2 public key. The key should be in PKIX format (DER encoded, then base64).
func Random ¶
Random generates a cryptographically secure random string of length n. By default, it uses alphanumeric characters (a-zA-Z0-9). An optional charset can be provided to customize the character set.
func RandomAlphabet ¶
RandomAlphabet generates a random alphabetic string of length n. Uses both uppercase and lowercase letters.
func RandomLowercase ¶
RandomLowercase generates a random lowercase alphabetic string of length n.
func RandomNumber ¶
RandomNumber generates a random numeric string of length n. Uses only digits 0-9.
func RandomUppercase ¶
RandomUppercase generates a random uppercase alphabetic string of length n.
func Reverse ¶
func Reverse[T any](v []T)
Reverse reverses the order of elements in a slice in place.
func ReverseString ¶
ReverseString returns a new string with characters in reverse order. Properly handles Unicode characters.
func SID ¶
func SID() string
SID generates a new Sonyflake ID as a string. Returns an empty string if ID generation fails (e.g., SF is nil or clock overflow).
For production use where errors must be handled explicitly, use SIDWithError() instead.
func SIDWithError ¶ added in v1.0.0
SIDWithError generates a new Sonyflake ID as a string. Returns the ID and any error that occurred during generation.
Possible errors:
- ErrSonyflakeNil: SF is nil (initialization failed)
- Clock overflow: Time exceeded Sonyflake's 174-year limit from StartTime
- Clock moved backwards: System time was adjusted
func SM4Decrypt ¶
SM4Decrypt decrypts ciphertext using SM4-ECB mode with PKCS5 padding. The key must be a 32-character hex string (16 bytes). The ciphertext must be hex-encoded. Returns the decrypted plaintext.
func SM4Encrypt ¶
SM4Encrypt encrypts plaintext using SM4-ECB mode with PKCS5 padding. The key must be a 32-character hex string (16 bytes). Returns hex-encoded ciphertext.
func SM4Verify ¶
SM4Verify decrypts and compares ciphertext with expected plaintext. Returns true if the decrypted text matches the plaintext.
func Shuffle ¶
func Shuffle[T any](v []T)
Shuffle randomly shuffles the elements in a slice in place. Uses cryptographically secure random numbers.
func ShuffleString ¶
ShuffleString returns a new string with characters randomly shuffled. Uses cryptographically secure random numbers.
func Sm2Sign ¶
func Sm2Sign(key *sm2.PrivateKey, text string) (string, error)
Sm2Sign signs text using SM2 private key. Returns base64-encoded ASN.1 DER signature.
func Sm2Verify ¶
Sm2Verify verifies a signature using SM2 public key. The signature should be base64-encoded ASN.1 DER format. Returns true if the signature is valid.
func Uuid7 ¶ added in v1.0.1
func Uuid7() string
Uuid7 generates a new UUID v7 string. UUIDv7 is time-ordered and recommended for database primary keys. Benefits over UUIDv4:
- Time-ordered: new IDs sort after old ones
- Index-friendly: sequential inserts reduce B-tree page splits
- Extractable timestamp: creation time can be derived from the ID
Returns a string in the format "xxxxxxxx-xxxx-7xxx-xxxx-xxxxxxxxxxxx".
func Uuid7Time ¶ added in v1.0.1
Uuid7Time extracts the timestamp from a UUID v7 string. Returns the Unix timestamp in milliseconds and true if successful, or 0 and false if the UUID is not a valid v7.
func Validator
deprecated
Validator creates a configured go-playground validator for Hertz. It sets "vd" as the validation tag and registers custom validators:
- snake: validates snake_case format (e.g., "user_name")
- sort: validates sort format (e.g., "created_at:1" or "name:-1")
Deprecated: Use vd.Default() instead.
Types ¶
type ErrorMeta ¶
type ErrorMeta struct {
Code int64
}
ErrorMeta contains error metadata for Hertz errors.
Source Files