uuid

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Dec 3, 2025 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package uuid provides utilities for generating unique identifiers.

This package offers two main approaches for ID generation:

  1. Sonyflake-based distributed ID generation (Sid struct)
  2. Standard UUID generation (UUID functions)

The Sid struct provides distributed ID generation using Sonyflake algorithm, which generates unique IDs across multiple machines without coordination. Generated IDs are converted to base62 format for compact string representation.

Example usage: 

// Sonyflake-based ID generation
sid := uuid.NewSid()
id, err := sid.GenString() // Returns base62 string
rawID, err := sid.GenUint64() // Returns raw uint64

// Standard UUID generation
uuidStr := uuid.UUID() // Returns standard UUID string
uuid32 := uuid.UUID32() // Returns UUID without hyphens

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func UUID 

func UUID() (string, error)

UUID generates a new random UUID and returns it as a standard string format. The returned string follows the standard UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

This function uses the Google UUID library and will return an error if UUID generation fails. For production use, consider using the Sid struct for distributed ID generation.

Example: 

id, err := uuid.UUID()
fmt.Println(id) // Output: "550e8400-e29b-41d4-a716-446655440000"
Example

ExampleUUID demonstrates basic UUID generation 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Generate a standard UUID
	id, err := uuid.UUID()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Standard UUID: %s\n", id)
}

Output:
Standard UUID: 550e8400-e29b-41d4-a716-446655440000

func UUID32 

func UUID32() string

UUID32 generates a new random UUID and returns it as a 32-character string without hyphens. This is useful when you need a compact UUID format for database keys or URLs.

Example: 

id := uuid.UUID32()
fmt.Println(id) // Output: "550e8400e29b41d4a716446655440000"
Example

ExampleUUID32 demonstrates UUID generation without hyphens 

package main

import (
	"fmt"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Generate a UUID without hyphens
	id := uuid.UUID32()
	fmt.Printf("UUID32: %s\n", id)
}

Output:
UUID32: 550e8400e29b41d4a716446655440000

func UUIDSafe 

func UUIDSafe() string

UUIDSafe generates a new random UUID and returns it as a standard string format. The returned string follows the standard UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

This function uses the Google UUID library and will panic if UUID generation fails. For production use, consider using the Sid struct for distributed ID generation.

Example: 

id := uuid.UUIDSafe()
fmt.Println(id) // Output: "550e8400-e29b-41d4-a716-446655440000"

Types

type Sid 

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

Sid represents a Sonyflake-based distributed ID generator. Sonyflake is a distributed unique ID generator inspired by Twitter's Snowflake. It generates 64-bit unique IDs that are roughly sortable by time.

The generated IDs are guaranteed to be unique across multiple machines without requiring coordination between them.

func NewSid 

func NewSid() *Sid

NewSid creates a new Sonyflake ID generator instance. This function will panic if the Sonyflake instance cannot be created, which typically happens when the machine ID cannot be determined.

Example: 

sid := uuid.NewSid()
id, err := sid.GenString()
Example

ExampleNewSid demonstrates creating a Sonyflake ID generator 

package main

import (
	"fmt"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create a new Sonyflake ID generator
	_ = uuid.NewSid()
	fmt.Printf("Sonyflake generator created\n")
}

Output:
Sonyflake generator created

func (Sid) GenString 

func (s Sid) GenString() (string, error)

GenString generates a new unique ID and returns it as a base62 string. The returned string is more compact than the raw numeric representation and is safe for use in URLs and filenames.

Example: 

sid := uuid.NewSid()
id, err := sid.GenString()
if err != nil {
	log.Fatal(err)
}
fmt.Println(id) // Output: "1Z3k9X2m"
Example

ExampleSid_GenString demonstrates generating string IDs 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Generate string ID
	id, err := sid.GenString()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("String ID: %s\n", id)
}

Output:
String ID: 1Z3k9X2m
Example (Batch)

ExampleSid_GenString_batch demonstrates batch ID generation 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Generate batch of string IDs
	ids := make([]string, 5)
	for i := 0; i < 5; i++ {
		id, err := sid.GenString()
		if err != nil {
			log.Fatal(err)
		}
		ids[i] = id
	}

	fmt.Printf("Generated %d IDs:\n", len(ids))
	for i, id := range ids {
		fmt.Printf("  %d: %s\n", i+1, id)
	}
}

Output:
Generated 5 IDs:
  1: 1Z3k9X2m
  2: 1Z3k9X2n
  3: 1Z3k9X2o
  4: 1Z3k9X2p
  5: 1Z3k9X2q
Example (Concurrent)

ExampleSid_GenString_concurrent demonstrates concurrent ID generation 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Channel for collecting results
	results := make(chan string, 3)

	// Generate IDs concurrently
	for i := 0; i < 3; i++ {
		go func() {
			id, err := sid.GenString()
			if err != nil {
				log.Fatal(err)
			}
			results <- id
		}()
	}

	// Collect results
	fmt.Println("Concurrent ID generation:")
	for i := 0; i < 3; i++ {
		id := <-results
		fmt.Printf("  ID: %s\n", id)
	}
}

Output:
Concurrent ID generation:
  ID: 1Z3k9X2m
  ID: 1Z3k9X2n
  ID: 1Z3k9X2o
Example (Database)

ExampleSid_GenString_database demonstrates database usage 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Generate ID for database record
	id, err := sid.GenString()
	if err != nil {
		log.Fatal(err)
	}

	// Simulate database record
	user := struct {
		ID   string
		Name string
	}{
		ID:   id,
		Name: "John Doe",
	}

	fmt.Printf("User record: ID=%s, Name=%s\n", user.ID, user.Name)
}

Output:
User record: ID=1Z3k9X2m, Name=John Doe
Example (Error_handling)

ExampleSid_GenString_error_handling demonstrates error handling 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Generate ID with error handling
	id, err := sid.GenString()
	if err != nil {
		log.Printf("Failed to generate ID: %v", err)
		return
	}

	fmt.Printf("Generated ID: %s\n", id)
}

Output:
Generated ID: 1Z3k9X2m
Example (Microservice)

ExampleSid_GenString_microservice demonstrates microservice usage 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Generate request ID for microservice
	requestID, err := sid.GenString()
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Microservice request ID: %s\n", requestID)
	fmt.Printf("Processing request %s\n", requestID)
}

Output:
Microservice request ID: 1Z3k9X2m
Processing request 1Z3k9X2m
Example (Multiple)

ExampleSid_GenString_multiple demonstrates generating multiple string IDs 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Generate multiple string IDs
	for i := 0; i < 3; i++ {
		id, err := sid.GenString()
		if err != nil {
			log.Fatal(err)
		}
		fmt.Printf("ID %d: %s\n", i+1, id)
	}
}

Output:
ID 1: 1Z3k9X2m
ID 2: 1Z3k9X2n
ID 3: 1Z3k9X2o
Example (Performance)

ExampleSid_GenString_performance demonstrates performance characteristics 

package main

import (
	"fmt"
	"log"
	"time"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Measure generation time
	start := time.Now()
	count := 1000

	for i := 0; i < count; i++ {
		_, err := sid.GenString()
		if err != nil {
			log.Fatal(err)
		}
	}

	duration := time.Since(start)
	fmt.Printf("Generated %d string IDs in %v\n", count, duration)
	fmt.Printf("Average time per ID: %v\n", duration/time.Duration(count))
}

Output:
Generated 1000 string IDs in 250µs
Average time per ID: 250ns

func (Sid) GenUint64 

func (s Sid) GenUint64() (uint64, error)

GenUint64 generates a new unique ID and returns it as a raw uint64. This is the underlying numeric ID before base62 conversion.

Example: 

sid := uuid.NewSid()
id, err := sid.GenUint64()
if err != nil {
	log.Fatal(err)
}
fmt.Println(id) // Output: 1234567890123456789
Example

ExampleSid_GenUint64 demonstrates generating raw uint64 IDs 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Generate raw uint64 ID
	id, err := sid.GenUint64()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Raw ID: %d\n", id)
}

Output:
Raw ID: 1234567890123456789
Example (Batch)

ExampleSid_GenUint64_batch demonstrates batch raw ID generation 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Generate batch of raw uint64 IDs
	ids := make([]uint64, 5)
	for i := 0; i < 5; i++ {
		id, err := sid.GenUint64()
		if err != nil {
			log.Fatal(err)
		}
		ids[i] = id
	}

	fmt.Printf("Generated %d raw IDs:\n", len(ids))
	for i, id := range ids {
		fmt.Printf("  %d: %d\n", i+1, id)
	}
}

Output:
Generated 5 raw IDs:
  1: 1234567890123456789
  2: 1234567890123456790
  3: 1234567890123456791
  4: 1234567890123456792
  5: 1234567890123456793
Example (Concurrent)

ExampleSid_GenUint64_concurrent demonstrates concurrent raw ID generation 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Channel for collecting results
	results := make(chan uint64, 3)

	// Generate IDs concurrently
	for i := 0; i < 3; i++ {
		go func() {
			id, err := sid.GenUint64()
			if err != nil {
				log.Fatal(err)
			}
			results <- id
		}()
	}

	// Collect results
	fmt.Println("Concurrent raw ID generation:")
	for i := 0; i < 3; i++ {
		id := <-results
		fmt.Printf("  Raw ID: %d\n", id)
	}
}

Output:
Concurrent raw ID generation:
  Raw ID: 1234567890123456789
  Raw ID: 1234567890123456790
  Raw ID: 1234567890123456791
Example (Database)

ExampleSid_GenUint64_database demonstrates raw ID database usage 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Generate raw ID for database record
	id, err := sid.GenUint64()
	if err != nil {
		log.Fatal(err)
	}

	// Simulate database record
	user := struct {
		ID   uint64
		Name string
	}{
		ID:   id,
		Name: "John Doe",
	}

	fmt.Printf("User record: ID=%d, Name=%s\n", user.ID, user.Name)
}

Output:
User record: ID=1234567890123456789, Name=John Doe
Example (Error_handling)

ExampleSid_GenUint64_error_handling demonstrates raw ID error handling 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Generate raw ID with error handling
	id, err := sid.GenUint64()
	if err != nil {
		log.Printf("Failed to generate raw ID: %v", err)
		return
	}

	fmt.Printf("Generated raw ID: %d\n", id)
}

Output:
Generated raw ID: 1234567890123456789
Example (Microservice)

ExampleSid_GenUint64_microservice demonstrates raw ID microservice usage 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Generate raw request ID for microservice
	requestID, err := sid.GenUint64()
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Microservice raw request ID: %d\n", requestID)
	fmt.Printf("Processing request %d\n", requestID)
}

Output:
Microservice raw request ID: 1234567890123456789
Processing request 1234567890123456789
Example (Multiple)

ExampleSid_GenUint64_multiple demonstrates generating multiple raw IDs 

package main

import (
	"fmt"
	"log"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Generate multiple raw uint64 IDs
	for i := 0; i < 3; i++ {
		id, err := sid.GenUint64()
		if err != nil {
			log.Fatal(err)
		}
		fmt.Printf("Raw ID %d: %d\n", i+1, id)
	}
}

Output:
Raw ID 1: 1234567890123456789
Raw ID 2: 1234567890123456790
Raw ID 3: 1234567890123456791
Example (Performance)

ExampleSid_GenUint64_performance demonstrates raw ID performance 

package main

import (
	"fmt"
	"log"
	"time"

	"github.com/go4x/goal/uuid"
)

func main() {
	// Create Sonyflake generator
	sid := uuid.NewSid()

	// Measure generation time
	start := time.Now()
	count := 1000

	for i := 0; i < count; i++ {
		_, err := sid.GenUint64()
		if err != nil {
			log.Fatal(err)
		}
	}

	duration := time.Since(start)
	fmt.Printf("Generated %d raw IDs in %v\n", count, duration)
	fmt.Printf("Average time per ID: %v\n", duration/time.Duration(count))
}

Output:
Generated 1000 raw IDs in 100µs
Average time per ID: 100ns

Source Files

View all Source files

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.