Prácticas recomendadas de arquitectura y diseño

Evoluciona bases de código Go sin reescrituras de 'big bang'.

Estos hábitos mantienen los servicios testeables, los módulos publicables y las refactorizaciones incrementales a medida que cambian los requisitos.

Cómo usar esta lista

• Adóptala durante la configuración de proyectos nuevos (greenfield) y antes de cada versión principal o división de servicio.
• Hazla cumplir con revisiones de código, reglas de golangci-lint depguard y reuniones de arquitectura.
• Combínala con ADRs (Architecture Decision Records) cuando una regla sea controvertida o costosa a corto plazo.
• Revísala cuando el tamaño del equipo, el alcance del cumplimiento o el orden de magnitud del tráfico cambien.

A - Límites y dependencias

• Mantén la composición solo en cmd/. main construye tipos concretos; las bibliotecas exponen funciones New.
• Define interfaces en los consumidores. Puertos de uno o dos métodos son mejores que volcar interfaces del lado del proveedor.
• Usa internal/ para implementación no pública. Deja que el compilador imponga los límites de los módulos.
• Prohíbe los ciclos de importación en código de producción. Los ciclos señalan una división incorrecta; extrae contratos o invierte dependencias.
• Pasa context.Context a través de las rutas de solicitud. La cancelación pertenece a los métodos de servicio y repositorio.

B - Capas y paquetes

• Los manejadores adaptan el transporte; los servicios poseen las reglas. No hay llamadas SQL o de SDK de terceros en los manejadores HTTP.
• Organiza por característica cuando los equipos se alinean con los dominios. internal/billing es mejor que carpetas solo de capas que se importan mutuamente.
• Mapea DTOs en los bordes. JSON, protobuf y filas de SQL se detienen en los adaptadores; las estructuras de dominio permanecen sin etiquetas.
• Mantén los frameworks en el borde. Los routers y ORMs no deben filtrarse a los paquetes del dominio.
• Prefiere errgroup para concurrencia acotada. Vincula la vida útil de las goroutines al context de la solicitud.

C - Módulos, APIs y evolución

• Ejecuta go mod tidy antes de fusionar. Los gráficos limpios reducen las sorpresas en las actualizaciones en CI.
• Etiqueta los lanzamientos de bibliotecas con semver. Las rupturas importantes obtienen rutas de módulo /v2 y notas de migración.
• Escribe ADRs para movimientos de límites. Las divisiones, el estilo de DI y las elecciones de almacén de datos necesitan un rastro de papel.
• Refactoriza en porciones verticales. Extrae una característica de extremo a extremo antes de movimientos horizontales de 'big bang'.
• Mide antes de dividir microservicios. El sesgo de CPU, el acoplamiento de lanzamientos o el cumplimiento impulsan las divisiones, no la estética.

D - Pruebas y puertas de calidad

• Prueba unitariamente los servicios con fakes, no con Docker. Reserva las pruebas de integración para los límites del adaptador.
• Usa errores centinela y envoltura %w consistentemente. Los manejadores mapean con errors.Is, no con comparación de cadenas.
• Ejecuta go test ./... y go vet ./... en CI. Agrega golangci-lint con depguard para globales y ciclos.
• Prueba de contrato de esquemas RPC y de eventos. Las comprobaciones de rotura de Buf o las pruebas impulsadas por el consumidor evitan la deriva.
• Haz benchmarks de las rutas críticas antes de optimizar la arquitectura. Perfila antes de introducir cachés, fragmentos o servicios.

E - Operaciones y observabilidad

• Configura el registro estructurado al inicio. slog o el estándar del equipo con IDs de rastreo/solicitud en los bordes.
• Exporta OpenTelemetry desde el primer día. Los rastreos a través de manejadores, DB y HTTP salientes simplifican los incidentes.
• Establece tiempos de espera del servidor HTTP y límites de cuerpo. Protege contra ataques de slowloris y cargas excesivas.
• Envía binarios estáticos desde CI. El mismo artefacto desde el portátil hasta producción; sin go build en el servidor.
• Documenta el apagado elegante en main. Drena las solicitudes en curso en SIGTERM antes de salir.

Preguntas frecuentes

Relacionado

• Arquitectura en Go: Interfaces pequeñas, dependencias explícitas - Base conceptual
• Conceptos básicos de arquitectura Go - Ejemplos iniciales ejecutables
• Lista de verificación de refactorización y auditoría de arquitectura - Encuentra deuda para arreglar
• Registros de decisiones de arquitectura para equipos Go - Plantillas de decisiones
• Capas de manejador-servicio-repositorio - Patrón de capas predeterminado

Enlaces externos relacionados

• Effective Go - Guía oficial para escribir Go claro e idiomático.
• Go Wiki – Learn - Recursos de aprendizaje curados por la comunidad.
• Go Daily / Community News - Noticias diarias curadas, lanzamientos y discusiones de Go.
• Learning Go (2nd Edition) - Jon Bodner.
• Concurrency in Go - Katherine Cox-Buday.

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