Importación de paquetes locales en Go: guía paso a paso con código

¿Por qué la importación de paquetes locales en Go genera tantas preguntas?

Si alguna vez ha intentado organizar código Go en archivos y carpetas separados, seguramente se ha encontrado con un error como could not import "myproject/utils". Este es uno de los problemas más comunes entre los desarrolladores Go principiantes. En Stack Overflow, la pregunta "How to import local packages in go?" ha acumulado miles de visitas, y no es casualidad.

A diferencia de Python, donde basta con colocar un archivo al lado y escribir import mymodule, Go requiere una estructura clara y una configuración correcta de módulos. Pero, una vez que domine este mecanismo, comprenderá lo elegante que es. Aclaremos esto de una vez por todas.

Breve teoría: cómo entiende Go los paquetes

Antes de escribir código, recuerde tres principios clave:

\n
• Go es un lenguaje con una estructura modular estricta. Cada directorio es un paquete (package).
\n
• El nombre del paquete no tiene que coincidir con el nombre de la carpeta, pero se recomienda encarecidamente hacerlo para facilitar la lectura.
\n
• La importación de paquetes locales desde 2019 se realiza a través de módulos (Go modules). Olvídese de GOPATH — use go mod.
\n

Ahora pasemos a la práctica.

Paso 1: Crear un proyecto con módulo

Abra la terminal y cree una nueva carpeta para su proyecto:

mkdir go-local-imports\ncd go-local-imports\n

Ahora inicialice el módulo. El nombre del módulo puede ser cualquiera, pero es lógico usar una ruta que sea única (por ejemplo, un enlace al repositorio):

go mod init github.com/su-usuario/go-local-imports\n

Después de este comando, aparecerá un archivo go.mod en la carpeta. Este se encargará de gestionar las dependencias, tanto locales como externas.

Paso 2: Crear un paquete local

Creemos una carpeta utils dentro del proyecto. Dentro de ella, un archivo math.go:

mkdir utils\ncd utils\ntouch math.go\n

Abra utils/math.go y escriba:

package utils\n\n// Add devuelve la suma de dos números enteros\nfunc Add(a, b int) int {\n    return a + b\n}\n

Observe que la función Add está escrita con mayúscula inicial. En Go, esto significa que se exporta (es pública). Si escribe add, será privada e inaccesible desde otros paquetes.

Paso 3: Importar y usar el paquete local

Volvamos a la carpeta raíz del proyecto y creemos main.go:

cd ..\ntouch main.go\n

Contenido de main.go:

package main\n\nimport (\n    "fmt"\n    "github.com/su-usuario/go-local-imports/utils"\n)\n\nfunc main() {\n    result := utils.Add(3, 5)\n    fmt.Println("Suma:", result)\n}\n

Ahora ejecute el programa:

go run main.go\n

Debería ver:

Suma: 8\n

¡Todo funciona! Pero si obtuvo un error, lea la siguiente sección.

Errores típicos y su solución

Error 1: "package is not in GOROOT"

Verá algo como:

package myproject/utils is not in GOROOT (/usr/local/go/src/myproject/utils)

Causa: Está intentando importar un paquete sin un módulo. Go lo busca en la biblioteca estándar, no en su proyecto.

Solución: Asegúrese de que en la raíz del proyecto exista go.mod. Si no, ejecute go mod init nombre-del-módulo.

Error 2: "undefined: utils.Add"

Causa: La función está escrita con minúscula inicial (privada), o importó el paquete pero no usa su nombre.

Solución: Verifique que todas las funciones necesarias se exporten (con mayúscula inicial) y que las esté llamando