https://github.com/totvs/go-sdk

https://github.com/totvs/go-sdk

Last synced: 10 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/totvs/go-sdk
• Owner: totvs
• Created: 2025-09-01T19:57:25.000Z (11 months ago)
• Default Branch: main
• Last Pushed: 2025-09-16T21:16:01.000Z (10 months ago)
• Last Synced: 2025-09-16T23:22:36.197Z (10 months ago)
• Language: Go
• Size: 104 KB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# go-sdk

SDK Go com utilitários reutilizáveis para logging, tracing e integrações.

Resumo

- Fachada de logging pública em `log/` para desacoplar consumidores de implementações

  concretas (por exemplo `zerolog`).

- Implementações concretas ficam em `log/internal` (não exportadas).

- Helpers de trace e propagation em `trace/`.

- Exemplos em `examples/` e alvos úteis no `Makefile`.

Estrutura principal

- `log/` — pacote de fachada: `facade.go`, testes e documentação (`log/README.md`).

  - `log/adapter/` — adaptadores públicos que retornam `LoggerFacade` (ex.: `NewLog`, `NewDefaultLog`).

  - `log/internal/` — implementações concretas (por exemplo `internal/backend/zerolog.go`).

  - `log/middleware/`, `log/util/` — middlewares e helpers relacionados a logging.

- `trace/` — helpers de propagation (`ContextWithTrace`, `TraceIDFromContext`, `GenerateTraceID`).

- `examples/` — exemplos executáveis (ex.: `examples/logger/main.go`).

- `Makefile` — targets comuns: `test`, `test-v`, `test-race`, `cover`, `cover-html`, `fmt`, `vet`, `build`, `tidy`, `ci`, `run-example`.

Logging: API rápida

- Construtores (adapter):

  - `adapter.NewLog(w io.Writer, level)` — cria um `LoggerFacade` que escreve para `w`.

  - `adapter.NewDefaultLog()` — cria um logger com configurações padrão.

- Context helpers (em `trace` e `log`):

  - `trace.ContextWithTrace`, `trace.TraceIDFromContext`, `trace.GenerateTraceID` — propagation de trace id.

  - `log.ContextWithLogger(ctx, l)`, `log.LoggerFromContext(ctx)`, `log.FromContext(ctx)` — injeção/recuperação de `LoggerFacade`.

- Helpers de campos: `WithField`, `WithFields` (disponíveis no `LoggerFacade`).

- Erros: use `LoggerFacade.Error(err)` seguido de `Msg`/`Msgf` para incluir o campo `error` no payload. Ex.: `f.Error(err).Msg("failed")` ou `f.WithFields(...).Error(err).Msgf("failed %s", name)`.

- Globais/atalhos: `log.SetGlobal(l)`, `log.GetGlobal()` e helpers de nível `log.Debug()/Info()/Warn()/Error(err)` que retornam um `LogEvent` fluente.

Adicionando um adapter

- Para suportar outra biblioteca, adicione um adaptador em `log/adapter/` que construa/retorne um `log.LoggerFacade`.

- Mantenha a dependência concreta dentro de `log/internal` quando for necessário usar bibliotecas externas.

Testes e desenvolvimento

- Coloque testes ao lado do código (`*_test.go`). Use `bytes.Buffer` e `httptest` para capturar saída e comportamento HTTP.

- Se um teste alterar o logger global (`log.SetGlobal`), restaure o valor anterior com `defer log.SetGlobal(prev)`.

- Alvos úteis:

  - `make test` — roda todos os testes.

  - `make test-v` — testes em modo verbose.

  - `make test-race` — com detector de race e cobertura.

  - `make run-example` — executa `examples/logger` (use `LOG_LEVEL` para alterar o nível).

Formatação e análise estática

- Rode `make fmt` (gofmt) e `make vet` (go vet) antes de submeter mudanças.

Build / CI

- `make build` — compila os pacotes.

- `make ci` — target para CI que executa `fmt`, `vet` e `test`.

Boas práticas

- Prefira usar a abstração `log.LoggerFacade` nas bibliotecas para não acoplar

  consumidores a uma implementação concreta.

- Mantenha implementações concretas em `log/internal` para evitar vazamento de dependências.

- O logger global é armazenado com `sync/atomic.Value`: definir o global uma vez no

  startup é a prática recomendada; swaps em runtime são suportados mas use com cuidado.

Exemplos e documentação adicional

- Veja `examples/logger` para um exemplo de uso.

- Consulte `log/README.md` para documentação detalhada da fachada e exemplos de adapters.

Licença e contato

- Ver `LICENSE` (se presente) e abra issues/pull requests para contribuições.