Noções Básicas de Estudos de Caso

11 exemplos para você começar com Estudos de Caso - 8 básicos e 3 intermediários.

Pré-requisitos

• Instale o Go 1.26.x ou posterior em go.dev/dl.
• Clone ou navegue pelas páginas site/go/case-studies/ deste site junto com seu próprio módulo.
• Opcional: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest para comparar a postura de linting com builds de referência.
• Leia rapidamente Aprendendo com Sistemas Go de Produção para entender como os estudos de caso diferem de tutoriais.

Exemplos Básicos

1. Identifique o Contrato Operacional

Antes de ler o código, liste os SLOs, o alvo de implantação e as dependências externas para a história.

# Contrato de build de referência REST (exemplo)
- Alvo: Implantação Kubernetes atrás de Ingress
- SLO: p99 < 100ms para endpoints de leitura a 500 RPS
- Dependências: Postgres, coletor OTel, scrape Prometheus

• Cada build de referência assume um contrato. Encontre-o nas seções de introdução e Resumo.
• Mapeie o contrato para os pacotes que você espera: cmd/, internal/, migrações, trechos de Helm ou manifestos.
• Se o contrato não for declarado, escreva o seu antes de copiar os padrões.

Relacionado: Aprendendo com Sistemas Go de Produção - Por que os estudos de caso importam

2. Rastreie o Fluxo de Requisição no Papel

Desenhe o protocolo de entrada para as dependências de saída antes de abrir os arquivos de implementação.

Cliente -> Ingress -> middleware chi -> handler -> service -> store -> Postgres
                              |-> slog + trace span
                              |-> /healthz /readyz

• Builds de referência são fatias verticais. Diagramas de fluxo expõem timeouts ou sondas ausentes precocemente.
• Observe onde o contexto é propagado e onde os erros são convertidos em códigos de status HTTP ou gRPC.
• Compare o diagrama do seu serviço com os links Relacionados do estudo de caso para análise de lacunas.

Relacionado: Build de Referência: Microserviço REST Cloud-Native - Fatia HTTP completa

3. Mapeie os Limites do Pacote

Liste quais pacotes podem importar quais outros no layout de referência.

// Direção permitida em builds de referência típicos:
// cmd/api -> internal/http -> internal/service -> internal/store
// internal/service não deve importar cmd/api

• internal/ significa "não é uma API de módulo pública". Builds de referência mantêm a integração nas bordas.
• Procure por interfaces nas junções de store e cliente para duplos de teste.
• Pacotes "God" antes dos estados violam este grafo; depois dos estados restauram importações acíclicas.

Relacionado: Antes/Depois: Refatorando um Pacote God - História de reparo de limites

4. Extraia o Checklist de Observabilidade

Copie os requisitos de sinal, não o JSON do dashboard.

// Nomes mínimos de métricas estilo RED para procurar em um build de referência
var (
    httpRequests = prometheus.NewCounterVec(/* ... */)
    httpDuration = prometheus.NewHistogramVec(/* ... */)
)

• Logs estruturados devem usar slog com IDs de requisição em builds HTTP.
• Endpoints de saúde separam liveness (processo ativo) de readiness (dependências OK).
• Rastreamentos devem abranger chamadas de entrada e saída em exemplos cloud-native.

Relacionado: Produção Go: Logs, Métricas, Rastreamentos e Sinais - Vocabulário de sinais

5. Leia Testes como Documentação de Design

Encontre testes orientados por tabela e tags de build de integração primeiro.

func TestServiceCreateUser(t *testing.T) {
    tests := []struct {
        name    string
        input   CreateUserInput
        wantErr bool
    }{
        {name: "valid email", input: CreateUserInput{Email: "a@b.co"}},
        {name: "empty email", input: CreateUserInput{}, wantErr: true},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // ...
        })
    }
}

• Builds de referência simulam via interfaces, não monkey-patching de globais.
• httptest registra contratos de handler sem iniciar uma porta real.
• Histórias de Operator e WASM adicionam envtest ou etapas de smoke test WASM - observe a conexão CI.

Relacionado: Testes Orientados por Tabela e Subtestes - Estilo de teste usado em todos os builds

6. Compare a Postura de Lançamento de CLI

Estude como os comandos cobra, a configuração e os artefatos se alinham.

# Sinais de higiene de CLI de produção em builds de referência
goreleaser release --clean
cosign sign-blob --key kms://... dist/myctl_linux_amd64.tar.gz
myctl version --output json

• Árvores de múltiplos comandos separam as preocupações de version, serve e migrate.
• Viper mescla flags, env e arquivo de configuração com precedência explícita.
• Pipelines de lançamento anexam SBOM ou checksums onde a história visa usuários corporativos.

Relacionado: Build de Referência: CLI de Produção com cobra - Fatia CLI de ponta a ponta

7. Estude os Hooks de Backpressure gRPC

Localize o controle de fluxo e os padrões de streaming em histórias de data plane.

func (s *server) StreamEvents(req *pb.SubscribeRequest, stream pb.Events_StreamEventsServer) error {
    for evt := range s.bus.Subscribe(req.GetTopic()) {
        if err := stream.Send(evt); err != nil {
            return err // desconexão do cliente ou controle de fluxo
        }
    }
    return nil
}

• Builds de alta vazão documentam limites do lado do cliente e configurações de keepalive.
• Seções de pprof e benchmark pertencem à mesma narrativa que o design de RPC.
• Observe onde os gateways JSON estão intencionalmente ausentes para proteger a vazão.

Relacionado: Build de Referência: Data Plane gRPC de Alta Vazão - Fatia de streaming

8. Observe os Artefatos de Implantação e Sonda

Colete Dockerfile, caminhos de sonda e manipuladores de desligamento gracioso.

readinessProbe:
  httpGet:
    path: /readyz
    port: 8080
  periodSeconds: 5

• Builds de referência REST conectam /healthz e /readyz separadamente.
• Imagens multi-stage compilam com CGO_ENABLED=0 para binários estáticos.
• Desligamento gracioso escuta SIGTERM e drena requisições em andamento.

Relacionado: Sondas de Saúde, Readiness e Liveness - Semântica das sondas

Exemplos Intermediários

9. Percorra uma Narrativa de Profiling

Reexecute as etapas do estudo de caso de benchmark contra suas métricas de staging.

go test -bench=. -benchmem ./internal/api/...
curl -s localhost:6060/debug/pprof/profile?seconds=30 > cpu.prof
go tool pprof -top cpu.prof

• Comece com uma violação do SLO de latência, não com micro-otimizações aleatórias.
• Compare os perfis de alloc_space e wall antes de alterar as camadas JSON ou SQL.
• Registre p50/p99 antes e depois de cada alteração; uma correção raramente resolve todas as caudas.

Relacionado: Estudo de Caso de Benchmark: Latência de API JSON - História de p99 de 200ms para 20ms

10. Audite a Idempotência do Reconcile do Operador

Para material de referência de operador Kubernetes, rastreie loops spec → status.

func (r *WidgetReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    var widget examplev1.Widget
    if err := r.Get(ctx, req.NamespacedName, &widget); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }
    // compare generation, patch status, requeue on transient error
    return ctrl.Result{}, nil
}

• Webhooks validam padrões; reconciliadores corrigem o status, não a spec, em erros.
• envtest executa a lógica do controlador sem um cluster real para feedback rápido.
• O envio de bundles OLM faz parte do contrato operacional, não um apêndice.

Relacionado: Build de Referência: Operador Kubernetes de Ponta a Ponta - CRD para bundle

11. Avalie Contratos Host/Guest WASM

Leia as exportações de módulos TinyGo ao lado da incorporação do host wazero.

// Host carrega o guest; guest exporta _start ou WASI main
mod, err := runtime.InstantiateModule(ctx, compiled, wazero.NewModuleConfig().
    WithStdout(os.Stdout))

• Orçamentos de tamanho e listas de permissão de chamadas de sistema fazem parte da história de segurança.
• CI executa testes de fumaça WASM em cada PR para capturar exports quebrados.
• Mesmo equipes não-WASM aprendem pensamento rigoroso de ABI com este build.

Relacionado: Build de Referência: Módulo de Borda WASI com Host wazero - Fatia de módulo de borda

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