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
ctxcomo 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.Contextem 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
%we 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.Iseerrors.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 importedatabase/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.