Padrões de Camada de Repositório e Serviço

As camadas de repositório e serviço separam o acesso a dados da lógica de negócios para que os serviços Go permaneçam testáveis sem a necessidade de levantar o Postgres em todos os testes unitários.

Handlers traduzem HTTP ou gRPC em chamadas de serviço; repositórios traduzem as necessidades do serviço em operações SQL, RPC ou de cache.

Resumo

Um repositório oculta como as linhas são carregadas e salvas.

Um serviço orquestra regras: validação, verificações de autorização, idempotência e fluxos de trabalho de várias etapas.

A camada de handler lida com preocupações de transporte: códigos de status, cabeçalhos e análise de requisição.

Interfaces são definidas onde são consumidas (tipicamente o pacote de serviço) e satisfeitas por implementações concretas de repositório em internal/storage ou similar.

Receita

Cartão de referência rápida - pronto para copiar e colar.

type UserRepo interface {
    Get(ctx context.Context, id string) (User, error)
}
 
type UserService struct {
    repo UserRepo
}
 
func (s *UserService) DisplayName(ctx context.Context, id string) (string, error) {
    u, err := s.repo.Get(ctx, id)
    if err != nil { return "", err }
    return strings.TrimSpace(u.First + " " + u.Last), nil
}

Quando usar isso:

• Regras de negócios que sobrevivem a escolhas de tecnologia de armazenamento
• Serviços que precisam de testes unitários rápidos sem Docker
• Equipes onde os handlers HTTP estavam acumulando strings SQL

Exemplo de Trabalho

package app
 
import (
    "context"
    "errors"
    "fmt"
)
 
type Order struct {
    ID     string
    UserID string
    Total  int64
    Status string
}
 
var ErrNotFound = errors.New("não encontrado")
 
type OrderRepo interface {
    Get(ctx context.Context, id string) (Order, error)
    Save(ctx context.Context, o Order) error
}
 
type OrderService struct {
    repo OrderRepo
}
 
func NewOrderService(repo OrderRepo) *OrderService {
    return &OrderService{repo: repo}
}
 
func (s *OrderService) Cancel(ctx context.Context, id string) error {
    o, err := s.repo.Get(ctx, id)
    if err != nil {
        return err
    }
    if o.Status == "shipped" {
        return fmt.Errorf("não é possível cancelar pedido enviado")
    }
    o.Status = "cancelled"
    return s.repo.Save(ctx, o)
}
 
// PostgresRepo vive em internal/storage; testes usam memRepo.
type memRepo struct {
    data map[string]Order
}
 
func (m *memRepo) Get(_ context.Context, id string) (Order, error) {
    o, ok := m.data[id]
    if !ok { return Order{}, ErrNotFound }
    return o, nil
}
 
func (m *memRepo) Save(_ context.Context, o Order) error {
    m.data[o.ID] = o
    return nil
}
 
func Example() {
    svc := NewOrderService(&memRepo{data: map[string]Order{
        "1": {ID: "1", Status: "pending"},
    }})
    _ = svc.Cancel(context.Background(), "1")
}

O que isso demonstra:

• OrderService codifica a regra de cancelamento
• OrderRepo é uma interface estreita com dois métodos
• Fake em memória implementa o mesmo contrato que o Postgres
• Erros de domínio permanecem no serviço; o mapeamento HTTP acontece em outro lugar

Mergulho Profundo

Como Funciona

HTTP handler  -->  Serviço  -->  Repositório  -->  database/driver
     |                |               |
 transporte      negócios       persistência

• Handlers analisam a entrada, chamam um método de serviço, mapeiam erros para códigos de status
• Serviços compõem repositórios e outros clientes (email, faturamento)
• Repositórios mapeiam tipos de domínio para linhas SQL ou payloads de API
• main conecta repositórios concretos em serviços e serviços em handlers

Granularidade da Interface

Tratamento de Erros

• Repositórios retornam ErrNotFound ou erros de driver encapsulados
• Serviços adicionam significado de negócio (cannot cancel shipped order)
• Handlers mapeiam para 404, 409, 500 usando errors.Is / errors.As

Notas Go

// Conectado em cmd/api/main.go
repo := postgres.NewOrderRepo(pool)
svc := app.NewOrderService(repo)
handler := httpapi.NewOrdersHandler(svc)

• Mantenha SQL fora de handlers e serviços
• Passe context.Context por todas as camadas para cancelamento e rastreamento
• Evite retornar *sql.Rows de repositórios - retorne structs de domínio

Armadilhas

• Vazamento de sql.DB para serviços - O pacote de negócios importa database/sql e se torna intratável. Correção: interface de repositório no pacote de serviço; SQL em internal/storage.
• Repositório retorna inteiros de status HTTP - Preocupações de transporte infectam a camada de persistência. Correção: retorne erros; mapeie no handler.
• Struct de serviço "Deus" - Um tipo Service com 40 métodos espelha um pacote "Deus". Correção: divida por contexto delimitado (OrderService, BillingService).
• Interfaces com apenas uma implementação "para mocks" - Abstração prematura sem um segundo backend. Correção: comece com o repositório concreto; extraia a interface quando os testes ou uma segunda loja precisarem dela.
• Contexto omitido nos métodos do repositório - Cancelamento e rastreamento param na fronteira do serviço. Correção: ctx como primeiro parâmetro onde I/O pode bloquear.
• Explosão de DTOs - Estruturas de API, DB e de domínio separadas para cada campo. Correção: comece com uma única struct de domínio; adicione DTOs quando as formas divergirem.

Alternativas

FAQs

Relacionado

• Noções Básicas de Padrões Go - snippet de interface de repositório
• Funções Construtoras e APIs de Pacote - conexão em main
• Middleware e Padrões Decorator - handlers enxutos
• Idiomas Go: Composição Sobre Herança - composição de interface

Versões da Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique na compilação). cGJxcnRodnFyZi52YnxwdHZiNDQ2fDIwMjYwNw==