Dos Requisitos às Especificações de Serviço Go

O Produto entrega histórias de usuário.

A Engenharia precisa de contratos de handler, formatos de armazenamento e SLOs mensuráveis antes que alguém abra o main.go.

Este fluxo de trabalho transforma requisitos ambíguos em uma especificação de serviço Go que os stakeholders podem aprovar e os ICs podem implementar sem retrabalho.

Resumo

Uma especificação completa de serviço Go nomeia superfícies HTTP ou gRPC, persistência, requisitos não funcionais e contratos de erro.

Histórias fornecem a voz do cliente; a especificação fornece a verdade testável.

Revise a especificação com o produto e os consumidores antes do compromisso do sprint.

Itere no documento compartilhado; gere código a partir de OpenAPI ou protobuf somente após as assinaturas estabilizarem.

Receita

Esqueleto mínimo de especificação para um novo endpoint HTTP em chi.

## Funcionalidade: Exportação de PDF de Fatura
 
### API
- `GET /v1/invoices/{id}/pdf` → 200 `application/pdf`
- Erros: 403 `invoice_unpaid`, 404 `invoice_not_found`, 500 `render_failed`
 
### Dados
- Ler tabela `invoices` (Postgres); sem novas colunas
- Bytes de PDF efêmeros; chave de cache S3 opcional `pdf/{invoice_id}`
 
### NFRs
- Latência p99 2s @ 100 RPS (staging)
- Idempotente: GET repetido retorna os mesmos bytes para a mesma revisão da fatura
- Autenticação: escopo JWT `billing:read`
 
### Fora do escopo
- Entrega por e-mail, exportação em lote

Quando usar isso:

• Endpoints Greenfield em serviços chi, gin ou echo
• Métodos gRPC antes da revisão de .proto
• Integrações inter-equipes que necessitam de contratos escritos
• Funcionalidades de conformidade que exigem trilhas de auditoria na especificação

Exemplo de Trabalho

Trecho da especificação mais assinatura de handler Go correspondente e mapeamento de erros.

// internal/api/export.go
package api
 
import (
    "context"
    "errors"
    "net/http"
 
    "github.com/go-chi/chi/v5"
)
 
var (
    ErrInvoiceUnpaid    = errors.New("invoice_unpaid")
    ErrInvoiceNotFound  = errors.New("invoice_not_found")
    ErrRenderFailed     = errors.New("render_failed")
)
 
type InvoiceReader interface {
    GetInvoice(ctx context.Context, id string) (Invoice, error)
}
 
type PDFRenderer interface {
    RenderInvoicePDF(ctx context.Context, inv Invoice) ([]byte, error)
}
 
func MountExport(r chi.Router, inv InvoiceReader, pdf PDFRenderer) {
    r.Get("/v1/invoices/{id}/pdf", func(w http.ResponseWriter, r *http.Request) {
        id := chi.URLParam(r, "id")
        inv, err := inv.GetInvoice(r.Context(), id)
        if err != nil {
            writeErr(w, mapErr(err))
            return
        }
        if inv.Status != "paid" {
            writeErr(w, http.StatusForbidden, ErrInvoiceUnpaid)
            return
        }
        bytes, err := pdf.RenderInvoicePDF(r.Context(), inv)
        if err != nil {
            writeErr(w, http.StatusInternalServerError, ErrRenderFailed)
            return
        }
        w.Header().Set("Content-Type", "application/pdf")
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write(bytes)
    })
}

# api/openapi.yaml (trecho)
paths:
  /v1/invoices/{id}/pdf:
    get:
      operationId: getInvoicePdf
      responses:
        "200":
          content:
            application/pdf:
              schema: { type: string, format: binary }
        "403":
          content:
            application/json:
              schema:
                properties:
                  code: { enum: [invoice_unpaid] }

O que isso demonstra:

• Códigos de erro da especificação correspondem a sentinelas Go e mapeamento de status HTTP
• Interfaces (InvoiceReader, PDFRenderer) seguem o empacotamento handler-service-repository
• OpenAPI documenta códigos de máquina estáveis, não texto de err.Error()
• Idempotência de NFR é implícita pela leitura somente GET em revisão imutável da fatura

Análise Profunda

Como Funciona

Loop de refinamento da história

1. O Produto rascunha a história com critérios de aceitação.
2. O líder técnico adiciona o rascunho da API e dos dados; sinaliza conflitos.
3. Consumidores (mobile, web, dados) comentam sobre os contratos.
4. SRE revisa a viabilidade de NFRs e os ganchos de observabilidade.
5. Especificação marcada como aprovada; tickets referenciam a versão da especificação.

Variante gRPC

Substitua os caminhos OpenAPI por RPCs .proto, campos de mensagem e detalhes de google.rpc.Status.

Mantenha as mesmas seções de NFR e dados.

Stubs Go gerados ficam em gen/ ou em um módulo versionado.

Modelo de Tabela de SLO

Notas Go

// Prefira context em toda fronteira de I/O - a especificação deve indicar timeouts.
ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
defer cancel()

• As especificações devem nomear prazos de context que correspondam aos orçamentos de latência de NFR.
• Liste quais erros são retentáveis (500, 503) e quais não são (403, 404).
• Observe go generate para oci-codegen ou buf generate na seção de build.

Armadilhas

• "Tempo real" vago - O produto entende segundos; a engenharia ouve milissegundos. Correção: Escreva p99 explícito e modelo de atualização na especificação.
• Idempotência ausente - Retentativas de POST cobram em duplicidade. Correção: Documente chaves de idempotência ou chaves naturais na seção de API.
• Texto de erro como contrato - Clientes analisam strings de Error(). Correção: A especificação exige um campo code estável; mapeie na camada do handler.
• Escopo oculto em notas de rodapé - "Adicionaremos autenticação depois" torna-se dívida de produção. Correção: Cabeçalho "Fora do escopo" por história.
• Especificação após o código - A revisão se torna um carimbo de borracha. Correção: Nenhum sprint começa sem um link de especificação aprovado no épico.
• PII sem classificação - Conformidade bloqueia tardiamente. Correção: A seção de dados marca campos (PII, financeiro) e dias de retenção.

Alternativas

FAQs

Relacionados

• Noções Básicas de Colaboração com Stakeholders - modelos para histórias e status
• Estimando Trabalho em Go: Módulos, Risco e Desconhecidos - dimensionamento a partir do escopo da especificação
• Camadas Handler-Service-Repository - layout de pacotes para handlers
• Registros de Decisão de Arquitetura para Equipes Go - quando as especificações precisam de suporte de ADR

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão GC 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).