Mis apuntes · Aprende Go desde PHP

Se guardan solos en este navegador mientras escribes. Puedes usar Markdown. Al descargarlos, la primera línea es tu enlace personal al curso.

Lección 23 de 36 · Un proyecto real ✦ WebMCP implementado

Paquetes y módulos: Composer y PSR-4 en Go

8 min de lectura 3 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.

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.

GoQué esEn PHP
MóduloTu proyecto entero, con nombre y versión de GoEl proyecto de composer.json
PaqueteUna carpeta con ficheros .goUn namespace (y su carpeta PSR-4)
go.modNombre del módulo y dependenciascomposer.json
go.sumHuella (hash) de cada dependenciaLos shasum de composer.lock
Ruta de importNombre del módulo + carpetaApp\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
Quiero…GoComposer
Empezar un proyectogo mod init <nombre>composer init
Añadir una libreríago get <ruta>@latestcomposer require <paquete>
Fijar una versión concretago get <ruta>@v5.4.0composer require <paquete>:5.4.0
Quitar lo que no uso y añadir lo que faltego mod tidycomposer remove (a mano) + composer install
Descargar todoLo hace solo go buildcomposer install
Buscar libreríaspkg.go.devpackagist.org

Dos diferencias importantes con Composer:

  1. 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.
  2. 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
<?php
declare(strict_types=1);

// PSR-4: App\Tareas\ vive en src/Tareas/
// y cada clase en su propio fichero.
namespace App\Tareas;

final class Tarea
{
    public function __construct(
        public readonly int $id,
        public readonly string $titulo,
        private bool $hecha = false,
    ) {}

    public function completar(): void
    {
        $this->hecha = true;
    }

    public function estaHecha(): 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.
type Tarea struct {
    ID     int
    Titulo string
    // 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/.

PHPGoQuién lo ve
namespace App\Tareas;package tareasNombre corto del paquete; la ruta completa la da la carpeta
use App\Tareas\Tarea;import ".../tareas" y luego tareas.TareaSe usa siempre con el prefijo del paquete
public (clase, método, propiedad)Nombre con mayúscula: Tarea, CompletarCualquier paquete que lo importe
private / protectedNombre con minúscula: hecha, validarTodo 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 ComposerNo existeEl 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"

type Tarea struct {
    ID     int
    Titulo string
    hecha  bool
}

// En PHP: public function completar(): void
func (t *Tarea) Completar() {
    t.hecha = true
}

// En PHP: public function estaHecha(): bool
func (t Tarea) EstaHecha() bool {
    return t.hecha
}

func main() {
    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';
func init() {
    tareas = append(tareas, "Comprar pan", "Repasar Go")
    fmt.Println("init: repositorio cargado")
}

func main() {
    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"
)

func abrir() (*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.

Hora de practicar

Retos · 0/3 resueltos

Reto 1 de 3

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

Resumen

Lo que te llevas de esta lección

  1. Módulo = proyecto con su go.mod (en PHP, composer.json).
  2. Paquete = carpeta; todos sus ficheros comparten package y se ven entre sí (en PHP, un namespace sin autoload).
  3. Mayúscula = sale del paquete; minúscula = se queda en el paquete (en PHP, public frente a private).
  4. internal/ = solo para tu proyecto, y lo comprueba el compilador (en PHP, un @internal que nadie vigila).
  5. go get + go.sum + binario: sin vendor/ ni composer install en producción.
  6. 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.