Conceptos básicos de paquetes y módulos

10 ejemplos para empezar con Paquetes y Módulos: 7 básicos y 3 intermedios.

Prerrequisitos

• Instala Go 1.26.x o posterior desde go.dev/dl.
• Crea un directorio de espacio de trabajo: mkdir moddemo && cd moddemo.
• Inicializa un módulo: go mod init example.com/moddemo.
• Ejecuta fragmentos desde la raíz del módulo con go run . después de guardarlos como main.go (o la ruta mostrada).

Ejemplos básicos

1. Inicializar un módulo

go mod init escribe go.mod con la ruta de tu módulo.

// Ejecutar primero en la shell:
// go mod init example.com/moddemo

• La ruta del módulo debe coincidir con dónde se alojará el código (o usa example.com/... para aprender).
• go.mod es la raíz versionada para cada paquete bajo este árbol de directorios.
• Los subdirectorios añaden segmentos a la ruta de importación; no necesitan su propio go.mod a menos que dividas módulos.

Relacionado: Paquetes y Módulos: La Unidad de Distribución de Go - modelo mental de paquetes vs. módulos

2. Crear e importar un paquete local

Divide el código entre paquetes dentro del mismo módulo.

// greet/greet.go
package greet
 
import "fmt"
 
func Hello(name string) string {
    return fmt.Sprintf("hola, %s", name)
}

// main.go
package main
 
import (
    "fmt"
    "example.com/moddemo/greet"
)
 
func main() {
    fmt.Println(greet.Hello("Go"))
}

• La ruta de importación es ruta del módulo + /directorio.
• Solo los nombres exportados (en mayúsculas) son visibles fuera del paquete.
• Ejecuta desde la raíz del módulo: go run .

Relacionado: Nomenclatura de Paquetes y Directorios internal/ - reglas de nomenclatura y visibilidad

3. Añadir una dependencia

go get registra un requisito semver en go.mod.

go get github.com/google/uuid@latest

package main
 
import (
    "fmt"
    "github.com/google/uuid"
)
 
func main() {
    fmt.Println(uuid.NewString())
}

• go get actualiza go.mod y go.sum.
• Las compilaciones descargan módulos en la caché de módulos automáticamente.
• Fija una versión específica con @v1.6.0 en lugar de @latest.

Relacionado: go.mod, go.sum y Selección Mínima de Versiones - cómo se resuelven las versiones

4. Sincronizar el grafo de módulos

Elimina requisitos no utilizados y añade los faltantes.

go mod tidy

• Ejecuta después de refactorizaciones que añaden o eliminan importaciones.
• CI debería fallar si go mod tidy cambiara archivos; usa go mod tidy -diff o hooks de commit.
• Mantiene go.sum alineado con las importaciones reales.

Relacionado: Mejores Prácticas de Paquetes, Módulos y Diseño de Proyectos - hábitos de higiene

5. Listar versiones de módulos

Inspecciona cuáles seleccionó la cadena de herramientas.

go list -m all
go list -m -versions github.com/google/uuid

• all imprime la lista de compilación para el módulo actual.
• -versions consulta las etiquetas disponibles desde el origen (requiere red).
• Útil al depurar actualizaciones inesperadas.

Relacionado: Directivas Pseudo-Versiones, replace y retract - anulaciones y lanzamientos erróneos

6. Usar internal/ para paquetes privados

internal/ bloquea importaciones desde fuera del árbol padre.

moddemo/
  go.mod
  cmd/app/main.go
  internal/config/config.go

// internal/config/config.go
package config
 
const Port = 8080

// cmd/app/main.go
package main
 
import (
    "fmt"
    "example.com/moddemo/internal/config"
)
 
func main() {
    fmt.Println(config.Port)
}

• El código fuera de example.com/moddemo no puede importar internal/config.
• Prefiere internal/ sobre comentarios para APIs de "no usar".
• Mantiene pequeña la superficie pública para bibliotecas.

Relacionado: Diseño Estándar de Proyectos para Servicios y Bibliotecas - diseño de cmd e internal

7. Importación en blanco para efectos secundarios de registro

Importa solo para init, no para uso directo de símbolos.

package main
 
import (
    "fmt"
    _ "example.com/moddemo/register" // activa init en el paquete register
)
 
func main() {
    fmt.Println("drivers registrados")
}

// register/register.go
package register
 
func init() {
    // registra plugin, driver o manejador http
}

• La importación en blanco ejecuta las funciones init en orden de dependencia.
• Común para drivers de bases de datos (_ "github.com/lib/pq") y formatos de imagen.
• No usar cuando necesites llamar a funciones exportadas del paquete.

Relacionado: Ciclos de Importación, Importaciones en Blanco y Dot Imports - cuándo encajan las importaciones con efectos secundarios

Ejemplos intermedios

8. Reemplazo local para un fork o módulo hermano

Apuntar un requisito a una ruta local durante el desarrollo.

// fragmento de go.mod
module example.com/moddemo
 
go 1.26
 
require example.com/lib v0.0.0
 
replace example.com/lib => ../lib

• replace es para desarrollo; evita confirmar rutas específicas de la máquina en ramas principales compartidas sin documentación.
• Los consumidores de tu módulo publicado no ven rutas replace no publicadas en tu portátil a menos que las confirmes.
• Usa go.work para repositorios multi-módulo cuando varios módulos se editan mutuamente a diario.

Relacionado: go work: Modo de Espacio de Trabajo para Repositorios Multi-Módulo - espacio de trabajo sin hacks de replace

9. Modo de espacio de trabajo con go.work

Desarrolla múltiples módulos juntos sin editar cada go.mod.

# Desde la raíz del repositorio con módulos hermanos app/ y lib/
go work init ./app ./lib
go work use ./app ./lib

// app/go.mod
module example.com/app
 
go 1.26
 
require example.com/lib v0.0.0

• go.work solo se aplica en tu máquina; no lo publiques como el contrato de la biblioteca.
• GOWORK=off fuerza el modo solo de módulos para comparaciones de CI reproducibles.
• Añade líneas use a medida que nuevos módulos se unen al monorepo.

Relacionado: go work: Modo de Espacio de Trabajo para Repositorios Multi-Módulo - flujo de trabajo completo del espacio de trabajo

10. Esquema de diseño estándar de servicio

main delgado, lógica en paquetes, código privado en internal/.

myapp/
  go.mod
  cmd/myapp/main.go
  internal/server/server.go
  pkg/client/client.go   // opcional: API pública estable para otros repos

// cmd/myapp/main.go
package main
 
import "example.com/myapp/internal/server"
 
func main() {
    server.Run()
}

• cmd/ contiene un directorio por binario; cada uno es package main.
• internal/ es forzosamente privado; pkg/ es la API pública convencional (aún depende de ti si la soportas).
• Un módulo puede distribuir múltiples comandos bajo cmd/.

Relacionado: Diseño Estándar de Proyectos para Servicios y Bibliotecas - guía completa de diseño

Versiones de la pila: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, modernizadores go fix - verifica el parche en la compilación), chi (última - verifica en la compilación), gin (última - verifica en la compilación), echo (última - verifica en la compilación), google.golang.org/grpc (última - verifica en la compilación), sigs.k8s.io/controller-runtime (última - verifica en la compilación), kubebuilder (última - verifica en la compilación), tinygo (última - verifica objetivos de placa en la compilación), wazero (última - verifica en la compilación) y golangci-lint (última - verifica el conjunto de linters en la compilación).

636f64656775696465732e696f7c6367696f3530387c323032363037