Cómo organizar tus proyectos de Go como un profesional

\ Cuando comencé a aprender Go, una de las primeras preguntas que tuve fue:

"¿Cómo estructuro realmente mi código?"

En lenguajes como C, es común poner todo en un solo archivo, o tal vez separar archivos de cabecera e implementación. Pero en Go, la estructura del proyecto es muy importante: afecta la facilidad con la que puedes escalar, probar y compartir tu código. En este artículo, explicaré por qué importa la estructura, cómo acceder a funciones desde diferentes archivos y qué mejores prácticas estoy aprendiendo mientras avanzo.

El Programa Go Más Simple

Un programa Go puede existir completamente en un solo archivo:

package main  import "fmt"  func main() {   fmt.Println("2 + 2 =", 2+2) } 

Esto funciona bien para "hola mundo" o experimentos rápidos.

Pero tan pronto como agregas más funcionalidad (resta, multiplicación, división...), el archivo se vuelve desordenado y difícilmente escalable.

Ahí es donde entran los paquetes y carpetas de Go.

Introducción a los Paquetes

En Go, cada archivo pertenece a un paquete.

Por convención:

• main → programa ejecutable
• otros (como calculator, utils, etc.) → lógica reutilizable

Así es como dividí el proyecto de calculadora:

calculator/ │ ├── main.go └── calculator/     └── operations.go 

\

• main.go → maneja entrada/salida
• operations.go → define funciones como Add, Subtract, etc.

Ejemplo: operations.go

package calculator  func Add(a, b int) int {   return a + b }  func Subtract(a, b int) int {   return a - b }  func Multiply(a, b int) int {   return a * b }  func Divide(a, b int) (int, error) {   if b == 0 {     return 0, fmt.Errorf("cannot divide by zero")   }   return a / b, nil } 

Ejemplo: main.go

package main  import (   "fmt"   "GoLang-progress/calculator" )  func main() {   fmt.Println("2 + 3 =", calculator.Add(2, 3))   fmt.Println("10 - 4 =", calculator.Subtract(10, 4))   fmt.Println("6 * 7 =", calculator.Multiply(6, 7))    result, err := calculator.Divide(8, 0)   if err != nil {     fmt.Println("Error:", err)   } else {     fmt.Println("8 / 0 =", result)   } } 

Observa cómo main.go ahora está limpio: no se preocupa por las matemáticas en sí, solo por cómo usarlas.

Accediendo a Funciones desde Diferentes Archivos

Una pregunta común de principiantes:

"¿Cómo llamo a una función desde otro archivo o carpeta?"

En mi repositorio, lo estructuré así:

calculator/ │ ├── main.go └── internal/     └── calc/         └── operations.go 

Aquí, las funciones matemáticas viven bajo internal/calc.

operations.go (dentro de internal/calc)

\

package calc  import "fmt"  func Add(a, b int) int {   return a + b }  func Divide(a, b int) (int, error) {   if b == 0 {     return 0, fmt.Errorf("cannot divide by zero")   }   return a / b, nil } 

main.go (importando internal/calc)

\

package main  import (   "fmt"   "github.com/turman17/GoLang-progress/calculator/internal/calc" )  func main() {   fmt.Println("2 + 3 =", calc.Add(2, 3))    result, err := calc.Divide(10, 0)   if err != nil {     fmt.Println("Error:", err)   } else {     fmt.Println("10 / 2 =", result)   } } 

Por qué se requiere esta ruta de importación

Tu importación debe coincidir con tu ruta de módulo desde go.mod más la ruta de la carpeta.

En tu repositorio, go.mod contiene:

module github.com/turman17/GoLang-progress 

El código de la calculadora que quieres usar vive en la carpeta:

calculator/internal/calc 

Así que la ruta de importación completa es:

github.com/turman17/GoLang-progress/calculator/internal/calc 

Algunas notas importantes

• Nombre de carpeta ≠ nombre de paquete → La carpeta es internal/calc, pero el paquete dentro se declara como package calc.
• Las importaciones usan la ruta del módulo → Siempre comienza con github.com/... si eso está en tu go.mod.
• Internal es especial → Los paquetes bajo /internal solo pueden ser importados por código dentro del mismo módulo.

Errores comunes y soluciones

❌ import "GoLang-progress/calculator/internal/calc"

→ Falta la organización/nombre de usuario de GitHub. Debe usar la ruta completa.

❌ import "github.com/turman17/GoLang-progress/internal/calc"

→ Falta el directorio calculator en la ruta.

❌ go: module not found errors

→ Asegúrate de que go.mod tenga module github.com/turman17/GoLang-progress y ejecuta go mod tidy.

Lista de verificación rápida

• go.mod tiene la línea de módulo correcta
• El directorio es calculator/internal/calc con el paquete calc dentro
• main.go importa github.com/turman17/GoLang-progress/calculator/internal/calc
• Construye desde la raíz del módulo:

\

go run ./calculator 

o

go build ./calculator 

Escalando la Estructura

A medida que los proyectos crecen, a menudo verás este patrón:

project-name/ │ ├── cmd/        → ejecutables (puntos de entrada principales) ├── internal/   → código privado (no para uso externo) ├── pkg/        → paquetes reutilizables ├── api/        → definiciones de API (gRPC, OpenAPI, etc.) └── go.mod 

Para principiantes, esto podría ser excesivo. Pero a medida que te mueves hacia aplicaciones web, servicios o herramientas MLOps, este diseño se vuelve esencial.

Mejores Prácticas que Estoy Aprendiendo

• Mantén los paquetes pequeños y enfocados
• Usa nombres significativos (calc, parser, storage)
• No sobre-ingenierices — comienza simple, refactoriza después
• Evita dependencias circulares (Go lo impone)

Lecciones del Proyecto Calculadora

• Separar la lógica (operations.go) del punto de entrada (main.go) facilita las pruebas.
• El manejo de errores (como división por cero) debe ser explícito.
• Las rutas de importación realmente importan — especialmente cuando se usa internal.

Continuaré compartiendo lo que aprendo mientras exploro Go para MLOps y desarrollo backend. Próximamente: manejo de errores y pruebas en Go.

\ 👉 Consulta mi repositorio aquí: https://github.com/turman17/GoLang-progress

¡Y mantente atento al próximo artículo!