Buenas Prácticas para la Depuración y Escenarios de Defectos

Listas de verificación de prevención y plantillas de RCA para incidentes en Go.

Estas reglas convierten los puntos débiles recurrentes en hábitos de revisión, puertas de CI y notas post-incidente que evitan que la misma clase de defecto se envíe dos veces.

Cómo Usar Esta Lista

• Recorra las secciones A-D durante la revisión de código para manejadores concurrentes, analizadores y capas de repositorio.
• Habilite go test -race, govet y golangci-lint en paquetes que comparten estado mutable.
• En caso de incidentes, clasifique los síntomas utilizando la taxonomía explicativa antes de reescribir la lógica de negocio.
• Almacene los resultados de RCA como ADRs o habilitaciones de linter, no solo en hilos de Slack.

A - Triaje y Observabilidad

• Clasifique primero la familia de síntomas (nil, slice, race, leak, time). Empareje pilas y métricas con un cubo de defectos antes de realizar cambios profundos en el código.
• Capture pilas de pánico completas y recuentos de goroutines al inicio del incidente. GOTRACEBACK=all y los endpoints de pprof aceleran la causa raíz.
• Registre IDs de solicitud, metadatos RPC y marcas de tiempo RFC3339 en los errores. Correlacione los informes de usuarios con rastreos de solicitudes individuales.
• Reproduzca bajo -race y paralelismo realista. Los pases locales inestables ocultan carreras de datos que la carga de producción expone.
• Distinga las interrupciones de dependencias de los defectos del lenguaje. DNS, DB y 5xx de terceros imitan errores de aplicación hasta que se verifican los límites.

B - Nil, interfaces y errores

• Nunca devuelva (nil, nil) para "no encontrado" en tipos puntero. Devuelva ErrNotFound o un centinela tipado que los llamadores manejen con errors.Is.
• Compruebe los punteros después de errores nil cuando las APIs permiten valores ausentes. err == nil no garantiza *T no nil.
• Evite punteros nil tipados en interfaces error. Devuelva un error nil sin tipo o un valor de error concreto, no (*MyError)(nil) a menos que los llamadores lo esperen.
• Valide los punteros decodificados por JSON antes de usarlos. null se desempaqueta a nil sin error.
• Habilite el análisis estático nil (nilaway, staticcheck) en los límites del servicio. Capture las rutas de retorno que los analizadores marcan antes del pánico en tiempo de ejecución.

C - Slices, mapas y compartición de memoria

• Copie o limite la capacidad antes de entregar sub-slices a los llamadores. Use s[low:high:high] o append([]T(nil), s...) cuando los consumidores puedan agregar.
• Registre len, cap y mutaciones de respaldo al depurar errores de append. La corrupción silenciosa rara vez provoca pánico.
• No comparta mapas entre goroutines sin sincronización. Use mutex, sync.Map o bloqueos de fragmentos para cachés.
• Trate las vistas de bytes.Buffer.Bytes() como efímeras. Copie si las conserva más allá de la siguiente mutación del búfer.
• Ejecute -race cuando los slices o las estructuras se muten desde manejadores y bucles de actualización en segundo plano.

D - Concurrencia, contexto y bucles

• Pase r.Context() a través de los manejadores HTTP a todas las E/S bloqueantes. La desconexión del cliente y Shutdown deben detener el trabajo.
• Siempre llame a cancel() desde WithCancel/WithTimeout. defer cancel() inmediatamente después de la creación.
• Agregue select en ctx.Done() para goroutines bloqueadas en canales. Evite fugas cuando los productores nunca envían.
• Copie las variables de bucle en las goroutines en bibliotecas dirigidas a versiones anteriores de Go. v := v o el paso de parámetros sigue siendo defensivo después de Go 1.22.
• Evite defer dentro de bucles sin una función por iteración. Los defer se apilan hasta la salida de la función y provocan fugas de descriptores de archivo.
• Use sync.Once para singletons perezosos, no para inicialización de doble verificación no sincronizada. El detector de carreras valida los caminos de Once de forma económica.

E - Tiempo, apagado e higiene de producción

• Analice las marcas de tiempo con zonas explícitas o ParseInLocation. Los diseños sin zona usan UTC, no la zona del portátil del desarrollador.
• Almacene los instantes en UTC; convierta con In(loc) para mostrar. Compare con Equal, no con cadenas formateadas.
• Incorpore time/tzdata o instale tzdata en contenedores mínimos. LoadLocation falla silenciosamente en CI si nunca se llama.
• Limite el apagado elegante con el tiempo de espera de http.Server.Shutdown. Cancele el contexto raíz cuando llegue la señal.
• Documente los campos de la plantilla RCA: familia de síntomas, primer frame defectuoso, guardia faltante, prueba de corrección permanente. Cierre los incidentes con una prueba de regresión o una regla de linter.

Preguntas Frecuentes

Relacionado

• Depuración de Go: Fallos Observables y Puntos Débiles - taxonomía de síntomas
• Conceptos Básicos de Depuración en Go - punto de entrada a las herramientas
• Tutorial de Defectos de Interfaz Nil vs Puntero Nil - reglas de nil en profundidad
• Escenarios de Carreras de Datos y Correcciones del Detector de Carreras - correcciones de carreras
• Fugas de Goroutines y Cancelación de Contexto Faltante - apagado y fugas
• Staticcheck y golangci-lint en CI - automatizar guardias

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, 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).

3730363230327c3230356f6967637c6f692e73656469756765646f63