Noções Básicas de Arquitetura Go

10 exemplos para você começar com Arquitetura - 7 básicos e 3 intermediários.

Pré-requisitos

• Go 1.26.x instalado (go version).
• Crie um módulo: mkdir archdemo && cd archdemo && go mod init example.com/archdemo.
• Os exemplos usam apenas a biblioteca padrão, a menos que observado.

Exemplos Básicos

1. Layout de serviço padrão

Binários separados, implementação privada e código de biblioteca pública.

archdemo/
  cmd/api/main.go
  internal/service/
  internal/store/
  pkg/api/          # tipos de API compartilhados opcionais

• cmd/ contém pacotes main - uma pasta por binário.
• internal/ oculta a implementação de importadores externos.
• pkg/ é opcional para bibliotecas que você deseja que outros módulos importem.

Relacionado: Arquitetura em Go: Interfaces Pequenas, Dependências Explícitas - por que os limites importam

2. Injeção de construtor

Passe dependências explicitamente em vez de globais.

package service
 
type Greeter struct {
    prefix string
}
 
func New(prefix string) *Greeter {
    return &Greeter{prefix: prefix}
}
 
func (g *Greeter) Hello(name string) string {
    return g.prefix + ", " + name
}

• New valida as entradas e retorna uma struct pronta.
• Os chamadores controlam a configuração; testes passam fakes sem mutar globais.
• Mantenha a superfície exportada pequena - os campos podem permanecer não exportados.

Relacionado: Injeção de Dependência: wire, dig & Wiring Manual - dimensionando o wiring além do main feito à mão

3. Interface do lado do consumidor

Defina o contrato onde ele é usado.

package handler
 
import "context"
 
type Lister interface {
    List(ctx context.Context) ([]string, error)
}
 
type HTTP struct {
    svc Lister
}
 
func New(svc Lister) *HTTP {
    return &HTTP{svc: svc}
}

• Lister tem um método - fácil de mockar em testes de handler.
• Tipos de armazenamento concretos vivem em internal/store sem importar HTTP.
• Interfaces pertencem perto do consumidor, nem sempre no provedor.

4. Manipulador HTTP enxuto

Traduza HTTP para chamadas de domínio; sem SQL em handlers.

package handler
 
import (
    "encoding/json"
    "net/http"
)
 
func (h *HTTP) List(w http.ResponseWriter, r *http.Request) {
    items, err := h.svc.List(r.Context())
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    _ = json.NewEncoder(w).Encode(items)
}

• Use r.Context() para cancelamento e prazos.
• Mapeie erros para códigos de status consistentemente (envolva erros de domínio na borda).
• A codificação JSON permanece na camada do adaptador.

Relacionado: Camadas de Handler-Serviço-Repositório - fluxo completo de três camadas

5. Camada de serviço com erros de domínio

Regras de negócios vivem entre HTTP e armazenamento.

package service
 
import (
    "context"
    "fmt"
)
 
type Repo interface {
    All(ctx context.Context) ([]string, error)
}
 
type Service struct {
    repo Repo
}
 
func New(repo Repo) *Service {
    return &Service{repo: repo}
}
 
func (s *Service) List(ctx context.Context) ([]string, error) {
    items, err := s.repo.All(ctx)
    if err != nil {
        return nil, fmt.Errorf("list: %w", err)
    }
    return items, nil
}

• Serviços envolvem erros de repositório com contexto (%w) para observabilidade.
• List satisfaz a interface Lister do handler do exemplo 3.
• Serviços permanecem ignorantes de códigos de status HTTP.

6. Limite do repositório

Isole a persistência atrás de uma pequena API.

package store
 
import "context"
 
type Memory struct {
    data []string
}
 
func (m *Memory) All(ctx context.Context) ([]string, error) {
    return append([]string(nil), m.data...), nil
}

• Trocar memória por Postgres muda um pacote.
• O contexto é aceito mesmo que este exemplo ignore o cancelamento - E/S real deve respeitá-lo.
• Retorne tipos amigáveis ao domínio, não linhas do driver, de repositórios.

7. Raiz de composição em main

Conecte tipos concretos apenas em cmd/api/main.go.

package main
 
import (
    "log"
    "net/http"
 
    "example.com/archdemo/internal/handler"
    "example.com/archdemo/internal/service"
    "example.com/archdemo/internal/store"
)
 
func main() {
    repo := &store.Memory{data: []string{"alpha", "beta"}}
    svc := service.New(repo)
    h := handler.New(svc)
 
    mux := http.NewServeMux()
    mux.HandleFunc("GET /items", h.List)
    log.Fatal(http.ListenAndServe(":8080", mux))
}

• main é o único lugar que conhece todos os tipos concretos.
• O roteamento usa padrões cientes de métodos Go 1.22+ em ServeMux.
• Adicionar um banco de dados significa mudar a fiação aqui, não os pacotes de negócios.

Exemplos Intermediários

8. Aplicação de internal/

Pacotes sob internal/ não podem ser importados fora da árvore pai.

// internal/store/pg.go
package store
 
// Apenas example.com/archdemo/... pode importar este pacote.
type PG struct{}

• O compilador rejeita importações externas de caminhos internal.
• Use para código que não é uma promessa semver para outros módulos.
• Bibliotecas públicas pertencem a caminhos não internos com estabilidade documentada.

Relacionado: Arquitetura Limpa & Hexagonal em Go - portas na borda do domínio

9. Pacote de recurso em vez de pastas apenas de camada

Organize por capacidade quando os domínios forem claros.

internal/
  billing/
    service.go
    handler.go
    postgres.go
  shipping/
    ...

• Pastas de recursos reduzem conflitos de merge entre equipes.
• Kernels compartilhados (internal/platform/) contêm helpers de logging e autenticação.
• Divida em serviços apenas quando os limites de lançamento e escala justificarem.

Relacionado: Monolito vs Microserviços em Go - quando dividir binários

10. Stub de ADR para uma decisão de limite

Registre por que você escolheu um layout antes que o debate se repita.

# ADR 0003: Camadas de handler-serviço-repositório
 
## Status
Aceito
 
## Contexto
Nova API HTTP; a equipe quer lógica de negócios testável.
 
## Decisão
Usar pacotes handler / service / repository com interfaces do lado do consumidor.
 
## Consequências
Mais pacotes; wiring explícito em main; testes unitários mais fáceis.

• Armazene ADRs em docs/adr/ ou .adr/ na raiz do repositório.
• Vincule decisões a restrições específicas do Go (sem container DI na stdlib).
• Reavalie quando a carga, a topologia da equipe ou os requisitos de conformidade mudarem.

Relacionado: Registros de Decisão de Arquitetura para Equipes Go - decisões classificadas para serviços Go

Links Externos Relacionados

• Tutoriais Go (Oficial) - Tutoriais oficiais em várias partes.
• Effective Go - Guia oficial para escrever Go claro e idiomático.
• Cursos Go do Boot.dev - Caminhos de aprendizado Go interativos e baseados em projetos.
• Get Programming with Go (Manning) - Nathan Youngman & Roger Peppé.
• Learning Go (2nd Edition) - Jon Bodner.

Versões de 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 o conjunto de linters na compilação).