Estructurando Proyectos en Go: Guía del "Standard Layout" para Aplicaciones Reales

Cuando empiezas en Go, la libertad de su sistema de archivos puede ser abrumadora. A diferencia de frameworks como Laravel o Django, Go no te impone una estructura de carpetas. Sin embargo, la comunidad ha consolidado un patrón conocido como Standard Go Project Layout.

En este post analizamos cómo organizar una aplicación profesional (usando como ejemplo un proyecto de integración de APIs) para lograr un código escalable, testeable y fácil de mantener.

🏗️ La Anatomía del Proyecto

Una estructura robusta se ve así:

.
├── cmd/                # Entry points (Puntos de entrada)
│   └── wasabi/         # Nombre de tu aplicación
│       └── main.go     # Archivo principal
├── internal/           # Lógica privada del negocio
│   ├── handlers/       # Capa de transporte (HTTP/gRPC)
│   ├── models/         # Estructuras de datos compartidas
│   └── wuzapi/         # Clientes o adaptadores de servicios
├── go.mod              # Gestión de dependencias
└── LICENSE             # Licencia del proyecto

1. El Directorio cmd/: El Centro de Mandos

La carpeta cmd/ contiene los subdirectorios para cada ejecutable que produzca el proyecto.

¿Qué va aquí?
Solo el código necesario para inicializar la aplicación: leer variables de entorno, conectar bases de datos y arrancar el servidor.

Regla de oro:
El código en cmd/ debe ser mínimo. Si tu main.go tiene 500 líneas, probablemente estás mezclando lógica de negocio con inicialización.

2. El Poder de internal/: Encapsulamiento Real

Esta es la carpeta más importante. En Go, cualquier paquete dentro de internal/ tiene una protección especial: solo puede ser importado por paquetes del mismo proyecto.

¿Por qué usar internal/?
Evita el acoplamiento externo: nadie fuera de tu repositorio podrá usar estas librerías, permitiéndote cambiar la lógica interna sin romper código de terceros.

Organización por dominios

• internal/handlers/: lógica de los endpoints, validación de input y respuestas.
• internal/wuzapi/: clientes y adaptadores para APIs externas.
• internal/models/: structs compartidos para evitar importaciones circulares.

3. Manejo de Dependencias y Modelos

Un error común es duplicar estructuras de datos. Centralizar los structs en internal/models/ crea un lenguaje común para toda la aplicación.

Flujo recomendado:
1️⃣ El Handler recibe el JSON y lo mapea a un Model.
2️⃣ El Handler pasa el Model al servicio (Wuzapi).
3️⃣ El Servicio procesa y retorna otro Model.

💡 3 Buenas Prácticas para Recordar

• Mantén los handlers delgados: el handler solo se ocupa de HTTP (status, headers, parsing). La lógica pesada vive en internal/.
• Inyección de dependencias: pasa clientes y servicios como dependencias. Facilita muchísimo el testing.
• Evita pkg/ al inicio: úsalo solo si vas a exponer librerías reutilizables. Para APIs y servidores, internal/ es el estándar de oro.

Conclusión

Seguir el Standard Go Project Layout no es una ley, pero sí la forma más rápida de que tu proyecto se sienta profesional. Separar la inicialización (cmd/) de la lógica privada (internal/) permite que tu código crezca sin convertirse en una maraña imposible de mantener.