sk-go-service

Implementar, estender ou depurar um handler, service ou repository em um serviço backend Go, cobrindo propagação de contexto, encapsulamento de erros, limites de transação, escopo de tenência e testes orientados por tabela. Use ao escrever ou alterar código de servidor Go, adicionar um endpoint ou método gRPC, tocar em uma consulta de repositório, ou diagnosticar um pânico, vazamento ou teste instável em um serviço Go.

O que é sk-go-service?

Esta skill fornece convenções e boas práticas para trabalhar com serviços Go em camadas, especialmente em ambientes concorrentes e multi-tenant. Ela cobre desde a verificação da toolchain e versão do Go, passando pela propagação correta de contexto, tratamento e encapsulamento de erros, gerenciamento de transações e escopo de tenência, até regras para goroutines e testes orientados por tabela. A skill é útil para desenvolvedores que mantêm ou estendem serviços Go, garantindo consistência, correção sob concorrência e facilidade de manutenção. Ela suporta plataformas como Claude Code, Cursor e Codex, e descreve padrões como não armazenar contexto em structs, usar `errors.Is` e `errors.As` para comparação de erros, abrir transações na camada de serviço, e sempre incluir predicado de tenente em consultas de repositório.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-go-service

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Trabalho com serviço Go

Convenções que mantêm um serviço Go em camadas correto sob concorrência e multi-tenência. Leia o pacote ao redor primeiro — um padrão local que é aplicado consistentemente prevalece sobre qualquer coisa aqui.

Antes de escrever código

Verifique a toolchain. O go.mod decide quais funcionalidades da biblioteca padrão e da linguagem estão disponíveis, e serviços no mesmo workspace geralmente estão em versões diferentes. Uma captura de variável de loop é um bug real abaixo do Go 1.22 e não é problema acima dele; errors.Join, slices e maps precisam de 1.21. Leia a versão em vez de assumir a mais nova.

Depois, encontre a camada que é dona da decisão que você está prestes a alterar. Handlers traduzem transporte para domínio e nada mais. Serviços contêm a decisão. Repositórios contêm a consulta. Uma validação adicionada no handler é invisível para todos os outros chamadores do serviço.

Contexto

O contexto pertence à requisição e morre com ela.

  • Passe ctx como primeiro parâmetro, até a chamada do banco de dados. Uma função que não recebe contexto não pode ser cancelada e não pode carregar um prazo.
  • Nunca armazene um context.Context em um campo de struct.
  • Nunca passe um contexto de requisição para uma goroutine que sobrevive ao handler. Trabalho em segundo plano destacado precisa de seu próprio contexto com seu próprio timeout, e os valores que ele precisa devem ser copiados explicitamente antes do handler retornar.
  • O mesmo se aplica a qualquer recurso derivado da requisição — uma transação, uma conexão, um acessador de banco de dados com escopo de requisição. Usá-los após o handler retornar é um use-after-free com uma mensagem de erro mais amigável.

Erros

  • Encapsule com %w e adicione o que o chamador já não pode saber: o identificador, a operação. fmt.Errorf("carregar pedido %d: %w", id, err). Não prefixe com o nome da função; uma pilha dessas soa como ruído.
  • Compare com errors.Is e errors.As. Um == direto quebra no momento em que alguém encapsula.
  • Traduza para um status de transporte em exatamente um lugar, na fronteira do handler. Um repositório que retorna um código HTTP vazou duas camadas.
  • sql.ErrNoRows é um resultado de domínio, não uma falha. Mapeie-o para o "não encontrado" do domínio na borda do repositório para que o serviço nunca importe database/sql.
  • Nunca descarte um erro para satisfazer o compilador. Se for genuinamente ignorável, atribua a _ com um comentário explicando o porquê.

Transações

Abra a transação na camada que detém o invariante — geralmente o serviço, nunca o repositório, porque um repositório que abre sua própria transação não pode ser composto em uma maior. Passe o identificador da transação para baixo.

Commit e rollback em todo caminho, incluindo pânico. O rollback após um commit bem-sucedido deve ser inofensivo; é isso que torna defer tx.Rollback() seguro.

Não faça E/S dentro de uma transação que não precisa ser atômica com ela. Uma chamada HTTP para um provedor de pagamento dentro de uma transação aberta mantém bloqueios de banco de dados pelo tempo que durar a indisponibilidade de outra pessoa.

Tenência

Se o serviço é multi-tenant, o identificador do tenant é imposto no código, não pelo banco de dados. Cada consulta de repositório — leitura e escrita — carrega o predicado do tenant. Uma consulta que filtra apenas pela chave primária retornará felizmente uma linha de outro tenant. Derive o identificador do acessador de contexto de requisição que o código base já usa, e verifique qual deles está correto: um serviço agindo em nome de um sub-tenant geralmente tem dois, e o óbvio frequentemente é o errado.

Goroutines

Cada goroutine precisa de um tempo de vida conhecido e um dono conhecido. Antes de escrever go, responda: quem espera por ela, como ela para, e para onde seu erro vai? Uma goroutine cujo erro é descartado é uma falha silenciosa.

Use errgroup quando o chamador espera. Use um sync.WaitGroup explícito mais um canal de erro coletado quando não se encaixa. Um go f() puro no tratamento de requisição é quase sempre um defeito.

Testes

Orientado por tabela, um t.Run por caso, nomeado pelo comportamento em vez da entrada. Cada caso informa sua entrada, sua expectativa, e nada mais; a configuração compartilhada por todos os casos pertence acima da tabela.

Sempre passe um timeout ao executá-los:

go test -count=1 -timeout 60s ./...

-count=1 derrota o cache de resultados, que de outra forma relata uma aprovação para código que você acabou de alterar. O timeout é mais importante do que parece: um teste deadlocked sem timeout consome memória até a máquina travar.

Teste o comportamento exportado do pacote. Um teste que alcança internos não exportados prende a implementação no lugar e falha em toda refatoração honesta.

Quando um teste é instável, ele está relatando uma condição de corrida real na maioria das vezes. Execute-o com -race antes de concluir o contrário, e nunca o corrija adicionando um sleep.

Antes de considerar finalizado

Execute o teste mais restrito que cobre a alteração, depois amplie se um contrato compartilhado mudou. Execute golangci-lint run no serviço em vez de um alvo make que pode engolir o código de saída. Relate falhas com sua saída em vez de enfraquecer o teste.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

Habilidades Relacionadas