Biblioteca uuid para Go: guia completo para geração de UUID

1. O que é e para que serve

UUID (Universally Unique Identifier) é um padrão de identificação usado no desenvolvimento de software para criar identificadores únicos sem a necessidade de um coordenador centralizado. No ecossistema Go, a biblioteca github.com/google/uuid é o padrão de facto para trabalhar com UUID. Ela oferece ferramentas confiáveis e de alto desempenho para gerar, analisar e comparar UUIDs de diferentes versões.

Para que serve essa biblioteca? Em sistemas distribuídos modernos, arquitetura de microsserviços e bancos de dados, é frequente precisar criar identificadores únicos que não entrem em conflito entre diferentes nós do sistema. O UUID resolve esse problema: você pode gerar identificadores no cliente, servidor ou em qualquer outro lugar, sem medo de colisões. A biblioteca google/uuid suporta UUID versões 1 (baseado em tempo e endereço MAC), 4 (aleatório) e 5 (baseado em hash SHA-1).

A biblioteca é amplamente utilizada em projetos como Kubernetes, Docker, CockroachDB e muitos outros. Ela é otimizada para alta performance, suporta geração thread-safe e fornece uma API conveniente para todas as operações principais com UUID.

2. Instalação

Para instalar a biblioteca, execute o comando no terminal:

go get github.com/google/uuid

Depois disso, importe o pacote no seu código:

import "github.com/google/uuid"

Certifique-se de ter o Go versão 1.16 ou superior instalado. Se você estiver usando Go modules (recomendado), a biblioteca será adicionada automaticamente aos seus arquivos go.mod e go.sum.

3. Início rápido — exemplo mínimo funcional

Aqui está o exemplo mais simples de geração de UUID versão 4 (aleatório):

package main

import (
    "fmt"
    "github.com/google/uuid"
)

func main() {
    // Gera um novo UUID versão 4
    id := uuid.New()
    fmt.Println("UUID gerado:", id.String())
    
    // Verifica que é realmente um UUID
    fmt.Println("Tipo UUID:", id.Version())
    fmt.Println("Variante UUID:", id.Variant())
}

A saída do programa será algo como:

UUID gerado: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
Tipo UUID: 4
Variante: RFC 4122

4. Principais métodos e funções

4.1. `uuid.New()`

Assinatura: func New() UUID

Descrição: Gera um novo UUID versão 4 (aleatório). Este é o método mais popular para criar identificadores únicos. Utiliza um gerador de números aleatórios criptograficamente seguro.

package main

import (
    "fmt"
    "github.com/google/uuid"
)

func main() {
    id := uuid.New()
    fmt.Printf("UUID: %s\n", id.String())
    fmt.Printf("Versão: %d\n", id.Version())
    fmt.Printf("Variante: %d\n", id.Variant())
}

4.2. `uuid.NewUUID()`

Assinatura: func NewUUID() (UUID, error)

Descrição: Gera um UUID versão 1 baseado no horário atual e no endereço MAC. Pode retornar um erro se não for possível obter o endereço MAC.

package main

import (
    "fmt"
    "log"
    "github.com/google/uuid"
)

func main() {
    id, err := uuid.NewUUID()
    if err != nil {
        log.Fatal("Erro ao gerar UUID:", err)
    }
    fmt.Printf("UUID v1: %s\n", id.String())
    fmt.Printf("Horário de criação: %v\n", id.Time())
    fmt.Printf("Endereço MAC: %x\n", id.Node())
}