samber/golang-samber-oops

O que golang-samber-oops faz?

Tratamento estruturado de erros em Golang com samber/oops — construtores de erro, stack traces, códigos de erro, contexto de erro, encapsulamento de erro, atributos de erro, mensagens para usuário vs desenvolvedor, recuperação de pânico e integração com logger. Aplicável ao usar ou adotar samber/oops, ou quando a base de código já importa github.com/samber/oops.

Visão Geral

O samber/oops é uma biblioteca Go que adiciona contexto estruturado a erros. Ela permite anexar stack traces, códigos de erro, atributos (pares chave-valor) e mensagens separadas para o usuário final e o desenvolvedor. Erros podem ser encapsulados (wrapped) para preservar a cadeia de erros, e a biblioteca oferece um builder (oops.Builder) para construir erros complexos de forma fluente.

Como Usar

Importação

import (
    "github.com/samber/oops"
)

Construtor Básico

func getUser(id string) (User, error) {
    // Retorna um erro com stack trace automático e atributos
    return User{}, oops.Errorf("usuário não encontrado: %s", id)
}

Erro com Atributos

func getUser(id string) (User, error) {
    return User{}, oops.
        Code("user.not_found").
        Tags("database", "critical").
        With("user_id", id).
        Errorf("usuário não encontrado: %s", id)
}

Encapsulamento (Wrap)

func getUser(id string) (User, error) {
    err := db.FindUser(id)
    if err != nil {
        return User{}, oops.
            Code("user.find_failed").
            Wrapf(err, "falha ao buscar usuário %s", id)
    }
    // ...
}

Mensagens para Usuário vs Desenvolvedor

err := oops.
    UserMessage("Usuário não encontrado.").
    Errorf("usuário com ID %s não encontrado no banco de dados", id)

Recuperação de Pânico

func handler() {
    defer oops.Recover(func(err error) {
        log.Printf("pânico recuperado: %v", err)
    })
    // código que pode gerar pânico
    panic("algo deu errado")
}

Integração com Logger

import (
    "log/slog"
    "github.com/samber/oops"
)

func main() {
    logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
    oops.SetLogger(logger)

    err := oops.Errorf("erro de exemplo")
    logger.Error("ocorreu um erro", "error", err)
}

Por que Usar?

• Stack traces automáticos: Cada erro captura a pilha de chamadas no momento da criação.
• Contexto rico: Adicione atributos, códigos e tags que ajudam na depuração.
• Separação de mensagens: Mensagens amigáveis para o usuário e detalhadas para o desenvolvedor.
• Compatibilidade: Funciona com errors.Is, errors.As e fmt.Errorf.
• Integração com logging: Funciona perfeitamente com log/slog, zerolog, logrus.

Boas Práticas

• Use Wrap para adicionar contexto a erros de bibliotecas.
• Defina códigos de erro consistentes (ex.: "user.not_found", "payment.failed").
• Evite expor detalhes internos nas mensagens para o usuário.
• Utilize Recover para capturar pânicos e convertê-los em erros estruturados.

Recursos Adicionais

• Documentação oficial do samber/oops
• Exemplos de uso

---

Este skill é aplicável a qualquer código-fonte Go que utilize ou adote github.com/samber/oops.