Ya inicializaste tu módulo, nombraste el repositorio correctamente y descargaste tus dependencias. Abres tu editor de texto, creas un main.go y empiezas a escribir. Todo va genial hasta que tu archivo alcanza las 1000 líneas de código, tienes rutas HTTP mezcladas con consultas a la base de datos y la navegación se vuelve un caos.
A diferencia de frameworks monolíticos en otros lenguajes que te imponen una estructura estricta, Go es famoso por no opinar sobre cómo organizas tus archivos. Puedes poner todo en la raíz si quieres. Pero para proyectos serios, la comunidad ha convergido en un patrón conocido como el Standard Go Project Layout.
Adoptar este estándar no solo hace que tu código sea entendible para cualquier otro desarrollador de Go, sino que hace que moverte por el proyecto usando atajos de teclado o buscadores de archivos en la terminal (como fzf o Telescope) sea increíblemente rápido y predecible.
Vamos a desglosar los tres pilares de un backend bien estructurado.
El directorio cmd/: Los puntos de entrada
Tus archivos main.go no deberían estar en la raíz del proyecto. Deberían vivir dentro del directorio /cmd.
El propósito de /cmd es alojar los puntos de entrada principales de tus aplicaciones. Es muy común que un mismo proyecto genere múltiples binarios (por ejemplo, el servidor API principal y una pequeña herramienta de línea de comandos para migraciones).
La regla de oro aquí es: el código dentro de cmd/ no debe contener lógica de negocio. Solo debe encargarse de inicializar configuraciones, conectar a la base de datos, instanciar los servicios y arrancar la aplicación.
Ejemplo de estructura:
mi-proyecto/
├── cmd/
│ ├── api-server/
│ │ └── main.go # Arranca tu backend HTTP
│ └── cli-admin/
│ └── main.go # Una herramienta para tareas administrativasEl directorio internal/: Tu fuerte de seguridad
Aquí es donde escribes el 90% de tu código. La carpeta /internal tiene un comportamiento mágico, reforzado directamente por el compilador de Go.
Cualquier paquete que coloques dentro de un directorio llamado internal solo puede ser importado por código que viva en el mismo nivel del árbol de directorios o por debajo. Es decir, si alguien descarga tu repositorio e intenta importar un paquete de tu carpeta /internal en su propio proyecto, el compilador de Go lanzará un error y no se lo permitirá.
Esto es vital para proteger tu código. Te permite refactorizar tu lógica de negocio, tus modelos de base de datos y tus controladores sin miedo a romper el código de terceros que dependa de ti.
Ejemplo de estructura:
mi-proyecto/
├── internal/
│ ├── database/ # Lógica de conexión a PostgreSQL, repositorios
│ ├── handlers/ # Controladores HTTP
│ └── models/ # Estructuras de datos de tu dominioEl directorio pkg/: La vitrina pública
Si internal/ es privado, /pkg es explícitamente público.
Si has escrito una pieza de código, una librería o una utilidad de la cual te sientes orgulloso y crees que otros proyectos (incluso fuera de tu empresa) podrían beneficiarse importándola, la colocas aquí.
Una advertencia: La tendencia actual en la comunidad de Go es usar /pkg con mucha moderación. La recomendación es poner todo en /internal por defecto y solo mover código a /pkg o a la raíz del proyecto cuando estés 100% seguro de que quieres mantenerlo estable y público para siempre.
La foto completa
Si juntamos todo esto, tu nuevo proyecto backend, listo para compilarse eficientemente, se vería algo así:
github.com/tu-usuario/api-finanzas/
├── cmd/
│ └── api/
│ └── main.go # Punto de entrada (inicializa dependencias y arranca)
├── internal/
│ ├── config/ # Carga de variables de entorno (godotenv)
│ ├── handlers/ # Lógica de las rutas HTTP
│ └── repository/ # Interacciones con la base de datos
├── go.mod # Definición de tu módulo
├── go.sum # Hashes de seguridad de tus dependencias
└── Makefile # (Opcional) Scripts para automatizar tareas localesResumen
- Usa
cmd/para los puntos de arranque (main.go). Mantén estos archivos pequeños. - Usa
internal/para todo el código de tu aplicación que no quieres que nadie más use. Es tu zona segura. - Usa
pkg/solo si estás creando código genérico que quieres que el mundo exterior importe.
Con esta estructura, tu código está listo para crecer de 10 a 100,000 líneas sin volverse inmanejable.
En el próximo y último artículo de esta serie introductoria, subiremos el nivel técnico y hablaremos de Go Workspaces, la herramienta definitiva para cuando necesitas trabajar en múltiples módulos locales interconectados al mismo tiempo.