Lección 23 de 36 · Un proyecto real✦ WebMCP implementado
Paquetes y módulos: Composer y PSR-4 en Go
8 min de lectura3 retos
Hasta ahora todo cabía en un main.go. Un proyecto de verdad tiene carpetas, dependencias y código que no quieres que nadie toque desde fuera. En esta lección traduces lo que ya sabes de Composer y PSR-4 a módulos y paquetes de Go.
¿De dónde vienen los nombres?
go.mod = module (módulo)
El fichero que dice cómo se llama tu proyecto y de qué depende: tu composer.json.
go.sum = checksum (suma de comprobación)
Guarda la huella de cada dependencia descargada para detectar si alguien la cambia. Hace parte del trabajo de tu composer.lock.
internal = internal (interno)
Nombre de carpeta especial: lo que hay dentro solo lo puede importar el código de la carpeta padre. Es el @internal de PHPDoc, pero obligatorio.
init = initialize (inicializar)
Función que Go ejecuta sola, antes de main(), para preparar un paquete. Como el código suelto de un fichero PHP que se ejecuta al hacer require.
En 4 ideas
1/4
Un módulo es tu proyecto entero y se describe en go.mod. En PHP es el composer.json: nombre del proyecto y dependencias.
Un paquete es una carpeta: todos sus .go comparten el mismo package. En PHP sería un namespace donde el autoload PSR-4 ya no hace falta, porque Go sabe dónde está cada carpeta.
La mayúscula decide qué sale del paquete y la carpeta internal/ decide qué sale del módulo. En PHP serían public/private y un @internal que el compilador sí respeta.
go get añade una dependencia y go mod tidy limpia las que sobran. Es composer require y composer update, pero sin carpeta vendor/ en producción: todo va dentro del binario.
1 · Módulo y paquete: proyecto y carpeta
En PHP hay dos ideas que casi siempre van juntas: el proyecto (lo que describe composer.json) y el namespace (cómo se llaman tus clases). Go tiene las mismas dos ideas con otro nombre.
Go
Qué es
En PHP
Módulo
Tu proyecto entero, con nombre y versión de Go
El proyecto de composer.json
Paquete
Una carpeta con ficheros .go
Un namespace (y su carpeta PSR-4)
go.mod
Nombre del módulo y dependencias
composer.json
go.sum
Huella (hash) de cada dependencia
Los shasum de composer.lock
Ruta de import
Nombre del módulo + carpeta
App\Tareas\Tarea
Piensa en un armario. El módulo es el armario entero, con su etiqueta en la puerta (go.mod). Cada cajón es un paquete: una carpeta. Lo que metes en un cajón se ve desde los demás solo si lo dejas a la vista, con mayúscula.
Para crear el armario, una sola orden. El nombre suele ser la dirección del repositorio, aunque no lo hayas subido todavía:
$ mkdir tareas && cd tareas
$ go mod init github.com/tuusuario/tareas
go: creating new go.mod: module github.com/tuusuario/tareas
$ cat go.mod
module github.com/tuusuario/tareas
go 1.26
Con ese nombre, la carpeta tareas/internal/almacen se importa como github.com/tuusuario/tareas/internal/almacen. No hay mapa de autoload que mantener: la ruta del import es la ruta de la carpeta.
2 · go get, go.mod y go.sum: tu Composer
Añadir una librería es como en Composer: una orden y se apunta sola en go.mod. Vamos a traer chi, un router web ligero:
$ go get github.com/go-chi/chi/v5@latest
go: added github.com/go-chi/chi/v5 v5.5.0
$ cat go.mod
module github.com/tuusuario/tareas
go 1.26
require github.com/go-chi/chi/v5 v5.5.0
En go.mod van versiones exactas, no rangos como ^5.2. Si dos librerías piden v5.1.0 y v5.2.1 de la misma dependencia, Go elige la más alta de las pedidas, nunca una más nueva que nadie ha pedido. Así dos compilaciones con el mismo go.mod usan siempre las mismas versiones.
go.sum no elige versiones: guarda la huella (hash) del contenido de cada una. Si mañana alguien cambia el código de v5.5.0 en GitHub, la huella no cuadra y go build se niega a seguir.
¿Por qué? · En PHP no existe
¿Por qué no hay vendor/ ni composer install en producción?
En PHP, las librerías se leen cada vez que alguien visita tu web, así que la carpeta vendor/ tiene que estar en el servidor. Si se te olvida el composer install al desplegar, la web cae con Class not found.
Go compila las librerías dentro de tu ejecutable. Las descarga una vez a una caché de tu ordenador y, tras go build, el binario ya lo lleva todo. Al servidor subes un solo fichero.
Sin vendor/ que subir ni olvidar.
Sin «en mi máquina funciona» por una versión distinta: go.mod y go.sum lo fijan.
Si una librería se manipula después de publicarse, la huella de go.sum lo detecta.
3 · Una carpeta, un paquete (adiós PSR-4)
En PHP con PSR-4, un fichero = una clase, y el autoload busca el fichero por el nombre de la clase. En Go la regla es más sencilla: una carpeta = un paquete. Dentro puedes tener uno o diez ficheros; todos empiezan con el mismo package tareas y todos se ven entre sí, como si fueran uno solo.
PHP 8.5tarea.php
<?phpdeclare(strict_types=1);
// PSR-4: App\Tareas\ vive en src/Tareas/// y cada clase en su propio fichero.namespace App\Tareas;
finalclass Tarea
{
publicfunction__construct(
publicreadonly int $id,
publicreadonly string $titulo,
private bool $hecha = false,
) {}
publicfunctioncompletar(): void
{
$this->hecha = true;
}
publicfunctionestaHecha(): bool
{
return$this->hecha;
}
}
// En otro fichero:// use App\Tareas\Tarea;// $t = new Tarea(1, "Comprar pan");
Gotarea.go
// Fichero tareas/tarea.go: la carpeta tareas/ ES el paquete.// En PHP: namespace App\Tareas;package tareas
// Tarea empieza por mayúscula: se ve desde otros paquetes.typeTareastruct {
IDintTitulostring// hecha, en minúscula: solo la ve el paquete tareas.
hecha bool
}
func (t *Tarea) Completar() {
t.hecha = true
}
func (t Tarea) EstaHecha() bool {
return t.hecha
}
// En otro paquete:// import "github.com/tuusuario/tareas/tareas"// t := tareas.Tarea{ID: 1, Titulo: "Comprar pan"}
Equivalencia POO · PHP → Go
La frontera de la visibilidad en Go no es la clase, es el paquete (la carpeta). Y por encima está el módulo, con internal/.
PHP
Go
Quién lo ve
namespace App\Tareas;
package tareas
Nombre corto del paquete; la ruta completa la da la carpeta
use App\Tareas\Tarea;
import ".../tareas" y luego tareas.Tarea
Se usa siempre con el prefijo del paquete
public (clase, método, propiedad)
Nombre con mayúscula: Tarea, Completar
Cualquier paquete que lo importe
private / protected
Nombre con minúscula: hecha, validar
Todo el paquete (todos los ficheros de la carpeta)
/** @internal */
Carpeta internal/
Solo el código que cuelga de la carpeta padre de internal/
Autoload de Composer
No existe
El compilador sabe la carpeta de cada import
Este programa cabe en un fichero, pero imagina que Tarea vive en su paquete. Desde fuera solo puedes usar lo que empieza por mayúscula:
Gomain.go
package main
import"fmt"typeTareastruct {
IDintTitulostring
hecha bool
}
// En PHP: public function completar(): voidfunc (t *Tarea) Completar() {
t.hecha = true
}
// En PHP: public function estaHecha(): boolfunc (t Tarea) EstaHecha() bool {
return t.hecha
}
funcmain() {
t := Tarea{ID: 1, Titulo: "Comprar pan"}
t.Completar()
// Desde otro paquete, t.hecha NO compilaría:// t.hecha undefined (cannot refer to unexported field hecha)
fmt.Println(t.Titulo, "hecha:", t.EstaHecha())
}
Una regla más que PHP no tiene: los paquetes no se pueden importar en círculo. Si tareas importa almacen, almacen no puede importar tareas; el compilador para con import cycle not allowed. Te obliga a que las dependencias vayan en una sola dirección, justo lo que pide una arquitectura por capas.
4 · La carpeta internal/: privado de verdad
Con la mayúscula decides qué sale de un paquete. Pero a veces tienes un paquete entero que no quieres que nadie use desde otro proyecto: tu acceso a la base de datos, tus utilidades. Para eso Go tiene una carpeta con nombre especial: internal/.
tareas/ <- el módulo (go.mod)
├── go.mod
├── go.sum
├── cmd/
│ └── tareas/
│ └── main.go <- el programa: package main
├── internal/
│ └── almacen/
│ └── almacen.go <- solo lo importa código de tareas/
└── tareas/
├── tarea.go <- package tareas
└── tarea_test.go <- sus tests (lección siguiente)
cmd/tareas/main.go puede importar internal/almacen porque cuelga de la misma carpeta padre. Si otro proyecto (aquí, github.com/otro/app) lo intenta, no compila. Este es el mensaje real:
$ go build .
package github.com/otro/app
main.go:6:5: use of internal package github.com/tuusuario/tareas/internal/almacen not allowed
¿Por qué? · En PHP no existe
¿Por qué una carpeta que el compilador vigila? En PHP no existe
En PHP, todo lo que hay en vendor/ se puede usar. Puedes marcar una clase con /** @internal */, pero es un comentario: nadie te impide hacer new \Vendor\Lib\Internal\Helper(). Cuando el autor la cambia en una versión menor, tu código se rompe y la culpa es tuya.
En Go esa promesa la cumple el compilador. Lo que pongas en internal/ lo puedes cambiar cuando quieras sin romper a nadie, porque nadie de fuera lo ha podido usar.
5 · init(): preparar el paquete antes de main
Un paquete puede tener una o varias funciones init(). No las llamas tú: Go las ejecuta solas, una vez, después de dar valor a las variables del paquete y antes de main(). Es como el código suelto que hay al principio de un fichero PHP y que se ejecuta en cuanto haces require.
Gomain.go
package main
import"fmt"var tareas []string// Se ejecuta sola, antes de main.// En PHP: código suelto al hacer require 'bootstrap.php';funcinit() {
tareas = append(tareas, "Comprar pan", "Repasar Go")
fmt.Println("init: repositorio cargado")
}
funcmain() {
fmt.Println("main: hay", len(tareas), "tareas")
}
Su uso más típico lo verás en el proyecto final. Un driver de base de datos se registra en su init(), y tú lo importas con _ (guion bajo), que significa «importa este paquete solo por su init(), no voy a llamar a nada suyo»:
Gomain.go
import (
"database/sql"// Solo por su init(): registra el driver «sqlite».
_ "modernc.org/sqlite"
)
funcabrir() (*sql.DB, error) {
// En PHP: new PDO('sqlite:tareas.db')return sql.Open("sqlite", "tareas.db")
}
La pregunta que te vas a hacer
«Vale, pero… ¿y dónde está mi Packagist?»
No hay un registro central donde subir paquetes. La ruta del import es la dirección del repositorio: publicas tu código en GitHub (o donde sea), le pones una etiqueta de git como v1.0.0 y ya se puede hacer go get. Un proxy público de Google guarda una copia para que no desaparezca si borran el repositorio.
pkg.go.dev: el buscador de paquetes y su documentación, lo más parecido a Packagist.
Referencia de go.mod: todo lo que puede llevar el fichero, para cuando lo necesites.
Hora de practicar
Retos · 0/3 resueltos
Reto 1 de 3 · ✓ Resuelto
init se escribe en minúscula
Este programa debería cargar dos tareas antes de arrancar, pero dice que hay 0. La función de carga se llama Init() con mayúscula y Go solo ejecuta sola la que se llama exactamente init(). Arréglalo para que imprima init: repositorio cargado y luego main: 2 tareas. Es el código suelto de tu bootstrap.php.
Al pulsar Comprobar, unos tests ocultos prueban tu código con el compilador oficial de Go.
Gomain.go · editable
Pista. Cambia Init por init. No hace falta llamarla desde main(): Go lo hace por ti (y de hecho no te deja llamarla a mano).
Reto 2 de 3 · ✓ Resuelto
Decide qué se exporta
Imagina que Tarea vive en el paquete tareas y la usa el paquete web. Haz públicos los campos ID, Titulo y Hecha y el método Completar(), y deja privado el campo notaInterna. Los tests miran con reflect qué se ve desde fuera. Es elegir entre public y private en una clase de PHP.
Al pulsar Comprobar, unos tests ocultos prueban tu código con el compilador oficial de Go.
Gomain.go · editable
Pista. Basta con poner en mayúscula la primera letra. Cuando cambies titulo por Titulo, cambia también donde se usa dentro de main() y del método.
Reto 3 de 3 · ✓ Resuelto
Un constructor que protege la tarea
El campo titulo es privado, así que desde otro paquete la única forma de crear una Tarea válida es tu constructor. Completa NuevaTarea(titulo string) (Tarea, error): quita los espacios de los lados y, si el título queda vacío, devuelve ErrTituloVacio. El método Titulo() deja leerlo desde fuera. Ejemplo: NuevaTarea(" Comprar pan ") da una tarea cuyo Titulo() es Comprar pan. Es tu __construct con validación y un private readonly string $titulo.
Al pulsar Comprobar, unos tests ocultos prueban tu código con el compilador oficial de Go.
Gomain.go · editable
Pista. Importa strings y usa strings.TrimSpace (el trim() de PHP). Después, si el título es "", devuelve Tarea{} y ErrTituloVacio.
Resumen
Lo que te llevas de esta lección
Módulo = proyecto con su go.mod (en PHP, composer.json).
Paquete = carpeta; todos sus ficheros comparten package y se ven entre sí (en PHP, un namespace sin autoload).
Mayúscula = sale del paquete; minúscula = se queda en el paquete (en PHP, public frente a private).
internal/ = solo para tu proyecto, y lo comprueba el compilador (en PHP, un @internal que nadie vigila).
go get + go.sum + binario: sin vendor/ ni composer install en producción.
init() se ejecuta sola antes de main(); el import con _ la usa para registrar drivers.
Para recordarlo: «Mi Casa, Mis Cajones»
MMódulo go.mod
CCarpeta package tareas
MMayúscula Tarea / hecha
CCerrado internal/
El Módulo es la casa; cada Carpeta, un cajón (un paquete); la Mayúscula deja algo a la vista de las visitas; y internal/ es el cajón Cerrado que solo abre la familia.