De los Requisitos a las Especificaciones de Servicios Go

Producto te entrega historias de usuario.

Ingeniería necesita contratos de manejadores, formas de almacenamiento y SLOs medibles antes de que alguien abra main.go.

Este flujo de trabajo convierte requisitos ambiguos en una especificación de servicio Go que los stakeholders pueden aprobar y los ICs pueden implementar sin retrabajo.

Resumen

Una especificación completa de servicio Go nombra las superficies HTTP o gRPC, la persistencia, los requisitos no funcionales y los contratos de error.

Las historias proporcionan la voz del cliente; la especificación proporciona la verdad verificable.

Revisa la especificación con producto y consumidores antes del compromiso del sprint.

Itera en el documento compartido; genera código a partir de OpenAPI o protobuf solo después de que las firmas se estabilicen.

Receta

Esqueleto mínimo de especificación para un nuevo endpoint HTTP en chi.

## Feature: Exportación de PDF de facturas
 
### API
- `GET /v1/invoices/{id}/pdf` → 200 `application/pdf`
- Errores: 403 `invoice_unpaid`, 404 `invoice_not_found`, 500 `render_failed`
 
### Datos
- Leer tabla `invoices` (Postgres); sin nuevas columnas
- Bytes de PDF efímeros; clave de caché opcional en S3 `pdf/{invoice_id}`
 
### NFRs
- latencia p99 2s @ 100 RPS (staging)
- Idempotente: GET repetido devuelve los mismos bytes para la misma revisión de factura
- Auth: ámbito JWT `billing:read`
 
### Fuera de alcance
- Entrega por correo electrónico, exportación por lotes

Cuándo usar esto:

• Endpoints nuevos en servicios chi, gin o echo
• Métodos gRPC antes de la revisión de .proto
• Integraciones inter-equipos que requieren contratos escritos
• Funciones de cumplimiento que requieren pistas de auditoría en la especificación

Ejemplo de Trabajo

Fragmento de especificación más firma de manejador Go y mapeo de errores coincidentes.

// 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 (extracto)
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] }

Lo que esto demuestra:

• Los códigos de error de la especificación coinciden con los centinelas de Go y el mapeo de estado HTTP
• Las interfaces (InvoiceReader, PDFRenderer) siguen la capa manejador-servicio-repositorio
• OpenAPI documenta códigos de máquina estables, no texto de err.Error()
• La idempotencia de NFR está implícita por la lectura única GET en la revisión inmutable de la factura

Análisis Profundo

Cómo Funciona

Bucle de refinamiento de historias

1. Producto redacta la historia con criterios de aceptación.
2. El líder técnico añade el borrador de API y datos; señala conflictos.
3. Los consumidores (móvil, web, datos) comentan sobre los contratos.
4. SRE revisa la viabilidad de las NFRs y los puntos de observación.
5. La especificación se marca como aprobada; las tickets referencian la versión de la especificación.

Variante gRPC

Reemplaza las rutas OpenAPI con RPCs de .proto, campos de mensaje y detalles de google.rpc.Status.

Mantén las mismas secciones de NFR y datos.

Los stubs de Go generados aterrizan en gen/ o un módulo versionado.

Plantilla de Tabla de SLO

Notas de Go

// Prefiere el contexto en cada límite de E/S - la especificación debe indicar los tiempos de espera.
ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
defer cancel()

• Las especificaciones deben nombrar los plazos de context que coincidan con los presupuestos de latencia de las NFRs.
• Enumera cuáles errores son reintentables (500, 503) y cuáles no (403, 404).
• Nota go generate para oapi-codegen o buf generate en la sección de compilación.

Trampas Comunes

• "Tiempo real" vago - Producto significa segundos; ingeniería escucha milisegundos. Solución: Escribe p99 explícitos y el modelo de actualización en la especificación.
• Idempotencia faltante - Los reintentos POST duplican cargos. Solución: Documenta claves de idempotencia o claves naturales en la sección de API.
• Texto de error como contrato - Los clientes analizan las cadenas Error(). Solución: La especificación requiere un campo code estable; mapea en la capa del manejador.
• Alcance oculto en notas a pie de página - "Añadiremos autenticación más tarde" se convierte en deuda de producción. Solución: Encabezado "Fuera de alcance" por historia.
• Especificación después del código - La revisión se convierte en un sello de goma. Solución: No iniciar el sprint sin un enlace a la especificación aprobada en la épica.
• PII sin clasificación - El cumplimiento bloquea tarde. Solución: La sección de Datos etiqueta los campos (PII, financiero) y los días de retención.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Colaboración con Stakeholders - plantillas para historias y estado
• Estimación de Trabajo en Go: Módulos, Riesgo e Incógnitas - dimensionamiento a partir del alcance de la especificación
• Capas de Manejador-Servicio-Repositorio - diseño de paquetes para manejadores
• Registros de Decisiones de Arquitectura para Equipos Go - cuándo las especificaciones necesitan respaldo de ADR

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado GC Green Tea, go fix modernizers - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica los objetivos de la placa en la compilación), wazero (última versión - verifica en la compilación) y golangci-lint (última versión - verifica el conjunto de linters en la compilación).