Lista de verificación de refactorización y auditoría de arquitectura

Señales de alerta en el acoplamiento de paquetes, globales y abuso de init().

Siga esta lista de verificación antes de un lanzamiento importante, después de picos de incorporación, o cuando los tiempos de compilación y las tasas de incidentes aumenten juntos.

Cómo usar esta lista de verificación

• Puntué cada nivel durante una revisión de arquitectura de una hora o una retrospectiva sin culpa posterior a un incidente.
• Corrija los elementos Críticos antes de agregar características sobre la deuda.
• Rastree los hallazgos en tickets vinculados a ADRs cuando la corrección cambie los límites.
• Vuelva a ejecutar trimestralmente o cuando el recuento de módulos o el tamaño del equipo se dupliquen.

Crítico - Detenga la hemorragia

1. Estado mutable global para DB, configuración o clientes: Reemplace con inyección de constructor desde main.

   • Globales: var db *sql.DB usado en varios paquetes
   • Inyección: NewService(repo Repository) cableado una vez al inicio

2. Ciclos de importación entre paquetes de producción: Extraiga contratos compartidos o invierta la dirección de la dependencia.

   • Ciclo: handler importa service importa handler
   • Corrección: Mueva las interfaces al consumidor o a internal/contracts

3. init() realiza E/S o entra en pánico por una configuración incorrecta: Fallo en main con errores claros en su lugar.

   • Efecto secundario de init: Abre la DB en init()
   • Fallo rápido en main: cfg, err := Load(); if err != nil { log.Fatal(err) }

4. Reglas de negocio solo en manejadores HTTP: Mueva la validación y los flujos de trabajo a servicios con pruebas unitarias.

   • Manejador gordo: ServeHTTP de 200 líneas con SQL
   • Servicio: Register(ctx, email) probado sin httptest

5. Secretos o puntos de conexión codificados en paquetes de biblioteca: Cargue desde el entorno/flags solo en la raíz de composición.

   • Codificado: const apiURL = "https://prod..."
   • Estructura de configuración: Config.APIURL validado al arrancar

Alto - Acoplamiento y Límites

6. Paquete Dios (util, common, helpers): Divida por capacidad (internal/timeutil, internal/validate).
7. Los paquetes de dominio importan código generado por net/http, gin o gRPC: Mueva los adaptadores a internal/adapter/*.
8. Interfaces amplias (10+ métodos) consumidas por un solo llamador: Divida o defina puertos de un solo método del lado del consumidor.
9. Identificadores exportados que ningún módulo externo utiliza: Desexporte o mueva a internal/ para congelar la superficie de la API.
10. Binarios cmd/ que duplican el cableado de forma divergente: Extraiga ayudantes Provide* compartidos o el conjunto Wire.
11. Los repositorios devuelven DTOs HTTP o modelos ORM con etiquetas de framework: Mapee a estructuras de dominio en el límite del repositorio.
12. Falta context.Context en funciones de E/S: Agregue ctx como primer parámetro; canalice desde los manejadores.

Medio - Señales de Mantenibilidad

13. Suite de pruebas requiere Docker para pruebas de lógica de negocio puras: Introduzca fakes en los límites del servicio.
14. Cadenas de error duplicadas en lugar de centinelas: Use var ErrNotFound = errors.New(...) y errors.Is.
15. Pánicos para errores esperados en bibliotecas: Devuelva errores; reserve el pánico para errores de programador.
16. Importaciones en blanco (_) sin comentario que explique el efecto secundario: Documente el propósito del registro o elimínelo.
17. Paquetes nombrados solo por capas (models, controllers) con importaciones cruzadas: Reorganice por corte de características.
18. Más de tres niveles de paquetes anidados sin propiedad: Aplane o alinee con los límites del equipo.
19. Directivas replace confirmadas para rutas de portátil local: Use go.work localmente; mantenga go.mod portátil.
20. No hay ADR para el último cambio importante de límites (división, adopción de ORM, RPC): Escriba ADR antes de que se acumule el próximo cambio.

Bajo - Pulido y Costo Futuro

21. Registro inconsistente (fmt, log, slog mezclados): Estandarice en slog o el registrador del equipo en los bordes.
22. Manejadores sin límites de tamaño de solicitud o tiempos de espera: Agregue tiempos de espera de http.Server y MaxBytesReader.
23. Módulo público sin LICENSE y lanzamientos etiquetados: Agregue LICENSE; etiquete semver para los consumidores.
24. Código generado editado a mano: Regenerar desde go generate, sqlc o buf en CI.
25. Comentarios describen arquitectura obsoleta ("temporal hasta v2") años después: Actualice la documentación o finalice la migración.

Aplicando la lista de verificación en orden

• Crítico (1-5): Aborde antes de escalar el tráfico o el equipo: los incidentes y el riesgo de corrupción de datos dominan.
• Alto (6-12): Programe en el trimestre actual: cada elemento ralentiza cada característica posterior.
• Medio (13-20): Agrupe en refactorizaciones adyacentes al trabajo de características: regla del boy scout por paquete.
• Bajo (21-25): Ate a un sprint de tareas de plataforma: reduce la fricción de incorporación.

Preguntas frecuentes

Relacionado

• Arquitectura en Go: Interfaces Pequeñas, Dependencias Explícitas - Arquitectura objetivo
• Capas de Handler-Service-Repository - Destino de refactorización de capas
• Registros de Decisiones de Arquitectura para Equipos Go - Registrar resultados
• Antipatrones Comunes en Bases de Código Go - Olores a nivel de código
• Mejores Prácticas de Arquitectura y Diseño - Hábitos de prevención

Enlaces Relacionados Externos

• Effective Go - Guía oficial para escribir Go claro e idiomático.
• Learn Go with Tests - Introducción a Go centrada en TDD.
• Stack Overflow – Etiqueta Go - Preguntas y respuestas para programación Go.
• The Go Programming Language (ebook) - Donovan & Kernighan.
• Learning Go (2nd Edition, O'Reilly) - Jon Bodner en O'Reilly.

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