¿Cómo organizan los paquetes y módulos el código Go?

Question

Accepted Answer

Go organiza el código con **paquetes** (colecciones de archivos fuente en un directorio) y **módulos** (colecciones de paquetes con gestión de versiones de dependencias). Juntos estructuran proyectos y administran dependencias.

## Paquetes — un directorio de código relacionado

```go
// every .go file starts by declaring its package
package main         // "main" is special — produces an executable

// or a library package (named after its directory, conventionally)
package mathutil

func Add(a, b int) int { return a + b }   // Exported (capitalized) — usable outside
func helper() {}                           // unexported (lowercase) — package-private
```

Todos los archivos en un directorio pertenecen a un paquete. **Las mayúsculas controlan la visibilidad**: los nombres en mayúsculas se exportan (públicos en todos los paquetes), las minúsculas son privados del paquete.

## Importar y usar paquetes

```go
import (
    "fmt"                          // standard library
    "strings"
    "github.com/user/repo/mathutil" // a third-party or local module package
)

fmt.Println(strings.ToUpper("hi"))
mathutil.Add(2, 3)                  // use Exported names via package.Name
```

## Módulos — gestión de versiones de dependencias

```bash
go mod init github.com/user/myapp   # create a module → makes go.mod
go get github.com/gin-gonic/gin     # add a dependency (records it in go.mod)
go mod tidy                          # add missing & remove unused dependencies
go build                             # build using the module's dependencies
```

```text
go.mod  — declares the module path, Go version, and direct dependencies (+ versions)
go.sum  — cryptographic checksums of dependencies (integrity/security)
```

Un **módulo** (introducido en Go 1.11) es la unidad de gestión de dependencias — `go.mod` enumera versiones exactas de dependencias, haciendo que las compilaciones sean reproducibles. `go.sum` verifica la integridad de las dependencias.

## La función init y main

```go
package main

func init() {    // runs automatically when the package loads (before main)
    // setup
}
func main() {    // entry point of an executable (package main only)
}
```

## Convenciones de estructura de proyectos

```text
myapp/
  go.mod
  main.go              package main
  internal/            packages here are PRIVATE to this module (can't be imported externally)
  pkg/ or other dirs/  reusable packages
```

El directorio `internal/` es especial — sus paquetes solo se pueden importar dentro del mismo módulo, aplicando encapsulación a nivel de módulo.

## Por qué es importante

Los paquetes y módulos son cómo se estructuran los proyectos Go y cómo se administran las dependencias — esencial para cualquier proyecto real.

Comprender los paquetes (un directorio de archivos, visibilidad controlada por mayúsculas exportada/no exportada, el paquete especial `main`) es fundamental para organizar el código y controlar su API pública.

Los módulos (`go mod`, `go.mod`/`go.sum`) proporcionan gestión de dependencias reproducible, versionada y verificada por integridad — el estándar moderno que reemplazó el antiguo enfoque GOPATH.

Conocer el sistema de importación, la convención `internal/` para código privado de módulo y las herramientas (`go mod init/tidy`, `go get`) es necesario para construir, compartir y mantener proyectos Go, y refleja soltura práctica con el ecosistema Go.