Skill de Revisión de Diseño de API Go

Convenciones de manejadores, errores y contexto para revisión automatizada: una Skill de Agente estilo manual para auditar manejadores HTTP y gRPC de Go 1.26 sin correcciones automáticas inseguras.

Qué Hace Esta Skill

Produce una lista de verificación de revisión estructurada para manejadores: propagación de context, mapeo de errores, códigos de estado, validación de solicitudes, orden de middleware y forma de respuesta, cada hallazgo vinculado a referencias de archivo y línea.

Cuándo Invocar

• Antes de fusionar cambios de manejadores o middleware
• Cuando un agente redacta un nuevo paquete REST
• Durante la revisión de diseño para superficies de API públicas
• Al estandarizar respuestas de error en servicios
• Después de incidentes causados por tiempos de espera faltantes o códigos de estado incorrectos

Entradas

Salidas

• Lista de verificación agrupada por: contexto, errores, validación, middleware, respuestas
• Severidad: bloqueador / advertencia / detalle menor con referencias archivo:línea
• Fragmentos de corrección sugeridos (aplicados por humanos - sin fusión automática)
• Comandos de verificación: go test ./pkg/..., golangci-lint run ./pkg/...

Barreras de Seguridad

1. Propagar r.Context() a todas las E/S salientes: DB, cliente HTTP, gRPC.
2. Mapear errores en una sola capa: manejadores o un paquete apierr dedicado, no ambos.
3. Nunca devolver 500 para fallos de validación del cliente: usar 400/422 según la política del equipo.
4. Nunca registrar y devolver cadenas de error internas a los clientes: usar IDs opacos.
5. No deshabilitar linters (errcheck, contextcheck) sin excepción ADR.
6. ServeMux de Stdlib en Go 1.22+: verificar patrones conscientes de métodos antes de sugerir migración a chi.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

// Objetivos de revisión (manejador stdlib)
func getUser(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context() // debe fluir a store.GetUser(ctx, id)
    id := r.PathValue("id")
    if id == "" {
        writeError(w, apierr.BadRequest("falta id"))
        return
    }
    u, err := store.GetUser(ctx, id)
    if err != nil {
        writeError(w, mapStoreErr(err))
        return
    }
    writeJSON(w, http.StatusOK, u)
}

# Verificación después de las correcciones de revisión
go test ./internal/api/...
golangci-lint run ./internal/api/...
go vet ./internal/api/...

Cuándo usar esta skill:

• El líder técnico necesita una revisión de manejadores consistente antes del despliegue del viernes
• El agente redactó manejadores sin leer el ADR de errores del equipo
• La primera PR HTTP de un nuevo ingeniero necesita retroalimentación con barreras de seguridad

Ejemplo de Trabajo

Paso 0 - Recopilar entradas

go list ./internal/api/...
grep -r "ServeHTTP\|HandleFunc\|chi\|gin\." internal/api/

Paso 1 - Auditoría de contexto

Verificar que cada llamada saliente reciba ctx derivado de r.Context():

// MAL: context.Background() en el manejador
user, err := repo.Find(context.Background(), id)
 
// BIEN: contexto con ámbito de solicitud
user, err := repo.Find(r.Context(), id)

• Los tiempos de espera del servidor (ReadHeaderTimeout, WriteTimeout) cancelan r.Context() - el downstream debe respetarlo
• Ver Cadenas de Middleware y Contexto de Solicitud

Paso 2 - Auditoría de mapeo de errores

func mapStoreErr(err error) apierr.Response {
    if errors.Is(err, store.ErrNotFound) {
        return apierr.NotFound("usuario")
    }
    if errors.Is(err, store.ErrInvalid) {
        return apierr.BadRequest("id de usuario inválido")
    }
    return apierr.Internal("fallo al buscar usuario") // opaco para el cliente
}

• Una función de mapeo por contexto delimitado
• gRPC: mapear a codes.InvalidArgument, codes.NotFound - ver patrones grpc-Go en secciones hermanas

Paso 3 - Estado y forma de respuesta

Paso 4 - Verificar

go test ./internal/api/... -count=1
golangci-lint run ./internal/api/...

Análisis Profundo

El orden del middleware afecta los hallazgos de la revisión.

El middleware de registro y de ID de solicitud debe envolver la autenticación, que envuelve los manejadores de negocio.

La recuperación de pánicos pertenece más externamente.

Los agentes a menudo insertan la autenticación después de los manejadores en los borradores; marcar como bloqueador.

La validación pertenece en el límite: parámetros de ruta, consulta, cuerpo JSON.

Usar encoding/json con decodificación estricta (DisallowUnknownFields) cuando el ADR lo requiera.

Para chi/gin, confirmar que la extracción de parámetros coincide con los patrones de ruta registrados.

Idempotencia y métodos: GET y HEAD no deben mutar el estado.

La política de POST para crear vs PUT para actualizar debe coincidir con OpenAPI.

ServeMux de Go 1.22+ con patrones de métodos (GET /users/{id}) evita manejadores accidentales para todos los métodos.

Trampas Comunes

• http.Error con err.Error(): filtra detalles de implementación y a menudo usa un estado incorrecto.
• context.WithTimeout anidado sin defer cancel(): los linters detectan algunos; revisar manualmente.
• Escribir JSON después de WriteHeader: el estado se bloquea en la primera escritura; usar un ayudante que establezca las cabeceras una vez.
• http.Client predeterminado no tiene tiempo de espera: marcar llamadas salientes desde manejadores que usan http.DefaultClient.
• Parámetros de URL de chi vs PathValue: APIs diferentes; la skill debe conocer el enrutador a partir de las entradas.

Alternativas

Preguntas Frecuentes

Relacionados

• Fundamentos de las Skills de Agente - estructura de SKILL.md
• Patrones de Servidores, Manejadores y ServeMux HTTP - referencia de enrutamiento
• Cadenas de Middleware y Contexto de Solicitud - flujo de contexto
• Validación de Entrada y Manejo Seguro de HTML/JSON - validación de límites
• httptest para Pruebas de Integración de Manejadores - patrones de prueba
• Mejores Prácticas para Skills de Agente - reglas para todo el equipo

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