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 25 de 36 · Un proyecto real ✦ WebMCP implementado

Go para la web: net/http, JSON y SQL

10 min de lectura 3 retos

Llega lo que más se parece a tu día a día: una API web. En Go no hace falta framework, ni Apache, ni php-fpm: la biblioteca estándar trae servidor, router, JSON y acceso a bases de datos. En esta lección montas la API de tareas y la pruebas sin abrir ningún puerto.

¿De dónde vienen los nombres?

mux = multiplexer (multiplexor)
Aparato que reparte muchas señales por un solo cable. En la web, el que mira cada petición y la manda a su función: tu router.
ServeMux = Serve (servir) + mux
El router de la biblioteca estándar de Go: el que sirve cada ruta con su handler.
w y r = writer y request
Los dos parámetros de todo handler: w (un http.ResponseWriter) es donde escribes la respuesta y r (un *http.Request) es la petición que llega.
Marshal = to marshal (poner en orden, formar)
Convertir un valor de Go en bytes de un formato, aquí JSON: tu json_encode(). Unmarshal es lo contrario: tu json_decode().
httptest = HTTP + test
Paquete para probar handlers sin red: finge la petición y guarda la respuesta para que la mires.
En 4 ideas
1/4

Un handler es una función func(w http.ResponseWriter, r *http.Request): lees la petición de r y escribes la respuesta en w. En PHP: $_GET, $_POST y $_SERVER por un lado, y echo y header() por otro.

1 · Un servidor en diez líneas

En PHP, nginx recibe la visita, se la pasa a php-fpm y php-fpm ejecuta tu index.php desde cero. En Go, tu programa es el servidor: abre un puerto y se queda escuchando. Es la diferencia entre llamar a un taxi cada vez (PHP) y tener tu propio coche aparcado en la puerta (Go).

Gomain.go
package main

import (
    "fmt"
    "log"
    "net/http"
)

func hola(w http.ResponseWriter, r *http.Request) {
    // En PHP: echo "Hola, tienes tareas pendientes";
    fmt.Fprintln(w, "Hola, tienes tareas pendientes")
}

func main() {
    http.HandleFunc("GET /", hola)
    log.Println("Escuchando en http://localhost:8080")
    // Se queda aquí, atendiendo peticiones, hasta que lo pares.
    log.Fatal(http.ListenAndServe(":8080", nil))
}

Lo ejecutas con go run . y abres http://localhost:8080 en el navegador. Cada visita llama a hola con dos cosas: w para escribir la respuesta y r con todo lo que trae la petición. Así se traducen tus superglobales:

PHPGoPara qué
$_SERVER['REQUEST_METHOD']r.MethodGET, POST…
$_GET['q']r.URL.Query().Get("q")Parámetro de la URL
$_POST['titulo']r.FormValue("titulo")Campo de un formulario
file_get_contents('php://input')r.BodyEl cuerpo crudo (por ejemplo, JSON)
header('Content-Type: …')w.Header().Set("Content-Type", "…")Una cabecera de la respuesta
http_response_code(201)w.WriteHeader(http.StatusCreated)El código de estado
echo $html;fmt.Fprint(w, html)El cuerpo de la respuesta

2 · Rutas: GET /tareas/{id}

Desde Go 1.22, el router de serie entiende método y parámetros en la ruta. Ya no hace falta una librería para lo básico:

PHP 8.5index.php
<?php
declare(strict_types=1);

// nginx + php-fpm ejecutan este fichero en CADA petición.
$tareas = [
    1 => ["id" => 1, "titulo" => "Comprar pan", "hecha" => false],
];

$metodo = $_SERVER["REQUEST_METHOD"];
$ruta = (string) parse_url($_SERVER["REQUEST_URI"], PHP_URL_PATH);

if ($metodo === "GET" && preg_match('#^/tareas/(\d+)$#', $ruta, $m)) {
    $tarea = $tareas[(int) $m[1]] ?? null;
    if ($tarea === null) {
        http_response_code(404);
        exit;
    }
    header("Content-Type: application/json");
    echo json_encode($tarea);
    exit;
}

http_response_code(404);
Gohandlers.go
package main

import (
    "encoding/json"
    "net/http"
    "strconv"
)

type Tarea struct {
    ID     int    `json:"id"`
    Titulo string `json:"titulo"`
    Hecha  bool   `json:"hecha"`
}

// Vive mientras viva el programa, no solo una petición.
var tareas = map[int]Tarea{
    1: {ID: 1, Titulo: "Comprar pan"},
}

// Se registra con: mux.HandleFunc("GET /tareas/{id}", verTarea)
func verTarea(w http.ResponseWriter, r *http.Request) {
    // En PHP: (int) $m[1]
    id, err := strconv.Atoi(r.PathValue("id"))
    if err != nil {
        http.Error(w, "id no válido", http.StatusBadRequest)
        return
    }
    tarea, ok := tareas[id]
    if !ok {
        http.NotFound(w, r)
        return
    }
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(tarea)
}

Para probar un handler no necesitas abrir un puerto. httptest.NewRequest fabrica una petición y httptest.NewRecorder es una respuesta de mentira que lo apunta todo. Así funciona este ejemplo en el navegador, y así harás los tests de tu API:

Gomain.go
package main

import (
    "fmt"
    "net/http"
    "net/http/httptest"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /tareas/{id}", func(w http.ResponseWriter, r *http.Request) {
        // En PHP: $id = $matches[1];
        fmt.Fprint(w, "tarea ", r.PathValue("id"))
    })

    pruebas := []struct{ metodo, ruta string }{
        {"GET", "/tareas/7"},
        {"POST", "/tareas/7"},
        {"GET", "/proyectos/7"},
    }
    for _, p := range pruebas {
        rec := httptest.NewRecorder()
        mux.ServeHTTP(rec, httptest.NewRequest(p.metodo, p.ruta, nil))
        fmt.Printf("%-4s %-12s -> %d %q\n", p.metodo, p.ruta, rec.Code, rec.Body.String())
    }
}

Fíjate en el POST: la ruta existe, pero solo para GET, así que el router contesta él solo 405 Method Not Allowed. Y una ruta que no existe da 404. Nada de eso lo has escrito tú.

¿Por qué? · En PHP no existe

¿Por qué el programa no se olvida de todo tras cada petición? En PHP sí lo hace

PHP sigue el modelo «no compartas nada»: cada petición arranca un script limpio y, al terminar, todo se borra. Si una petición deja una variable rota, la siguiente ni se entera. Lo que quieres conservar va a la sesión, a Redis o a la base de datos.

En Go el programa sigue vivo entre peticiones. Eso trae dos cosas:

  • Lo bueno: abres la conexión a la base de datos una vez al arrancar y la reutilizas siempre. Nada de reconectar ni de recargar la configuración en cada visita.
  • Lo que hay que vigilar: una variable global (como el map de tareas) la comparten todas las peticiones. Si una la cambia, las demás lo ven.

Además, Go atiende varias peticiones a la vez. Si dos tocan el mismo map al mismo tiempo, el programa puede romperse. Por eso la API de más abajo lleva un candado (sync.Mutex), que entenderás a fondo en el módulo 08.

3 · JSON con encoding/json

El JSON se hace con el paquete encoding/json. A cada campo le pones una etiqueta (struct tag): un texto entre comillas invertidas después del tipo, que le dice a json con qué nombre sacarlo.

Gomain.go
package main

import (
    "encoding/json"
    "fmt"
)

type Tarea struct {
    ID        int      `json:"id"`
    Titulo    string   `json:"titulo"`
    Hecha     bool     `json:"hecha"`
    Etiquetas []string `json:"etiquetas,omitempty"`
    // En minúscula: json no lo ve y no sale en la respuesta.
    notas string
}

func main() {
    t := Tarea{ID: 1, Titulo: "Comprar pan", notas: "en la panadería de abajo"}

    // En PHP: $json = json_encode($tarea);
    datos, err := json.Marshal(t)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println(string(datos))

    // En PHP: $datos = json_decode($json, true);
    var nueva Tarea
    err = json.Unmarshal([]byte(`{"titulo":"Repasar Go","hecha":true,"prioridad":3}`), &nueva)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Printf("%+v\n", nueva)
}
  • json:"titulo": el nombre del campo en el JSON.
  • ,omitempty: si el campo está vacío (0, "", nil…), no lo saques.
  • json:"-": no lo saques nunca, aunque tenga mayúscula (por ejemplo, una contraseña).
  • Al leer, los campos que no conoces (como prioridad) se ignoran sin error, y los que faltan se quedan con su valor cero.

¿Por qué? · En PHP no existe

¿Por qué hacen falta etiquetas? En PHP json_encode() no las pide

json_encode() usa el nombre de la propiedad tal cual: $titulo sale como "titulo". En Go no se puede, porque un campo en minúscula es privado y json (que es otro paquete) no lo ve. Para que salga tiene que llamarse Titulo, y el JSON de toda la vida va en minúscula.

La etiqueta separa los dos nombres: Titulo para Go y "titulo" para el JSON. Y de regalo, decides campo a campo qué sale y qué no, sin implementar JsonSerializable.

4 · El orden de la respuesta: cabeceras, código y cuerpo

Una respuesta HTTP viaja en este orden: primero el código (200, 404…), después las cabeceras y al final el cuerpo. En cuanto escribes la primera letra del cuerpo, Go envía lo anterior tal como esté. Es como cerrar un sobre: lo que no metiste antes, ya no entra.

  1. w.Header().Set(...): prepara las cabeceras.
  2. w.WriteHeader(código): envía el código y las cabeceras. Si no lo llamas, se envía un 200 en la primera escritura.
  3. w.Write(...), fmt.Fprint(w, ...) o json.NewEncoder(w).Encode(...): el cuerpo.
Gomain.go
package main

import (
    "fmt"
    "net/http"
    "net/http/httptest"
)

func mal(w http.ResponseWriter, r *http.Request) {
    fmt.Fprint(w, `{"id":1}`)
    // Tarde: el cuerpo ya salió con 200 y su tipo adivinado.
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusCreated)
}

func bien(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusCreated)
    fmt.Fprint(w, `{"id":1}`)
}

func main() {
    handlers := []struct {
        nombre  string
        handler http.HandlerFunc
    }{
        {"mal", mal},
        {"bien", bien},
    }
    for _, h := range handlers {
        rec := httptest.NewRecorder()
        h.handler(rec, httptest.NewRequest("POST", "/tareas", nil))
        respuesta := rec.Result()
        fmt.Printf("%-4s -> %d %s\n", h.nombre, respuesta.StatusCode, respuesta.Header.Get("Content-Type"))
    }
}

5 · La API de tareas completa (en memoria)

Juntamos todo: un repositorio en memoria, tres rutas y JSON de entrada y de salida. Al final del módulo 09 cambiarás el repositorio en memoria por SQLite sin tocar los handlers, gracias a la interfaz RepositorioTareas del módulo 05.

Gomain.go
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/http/httptest"
    "strconv"
    "strings"
    "sync"
)

type Tarea struct {
    ID     int    `json:"id"`
    Titulo string `json:"titulo"`
    Hecha  bool   `json:"hecha"`
}

// API guarda las tareas en memoria mientras vive el programa.
type API struct {
    // El candado evita que dos peticiones a la vez rompan el slice (módulo 08).
    mu     sync.Mutex
    tareas []Tarea
}

func responderJSON(w http.ResponseWriter, codigo int, v any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(codigo)
    json.NewEncoder(w).Encode(v)
}

func (a *API) listar(w http.ResponseWriter, r *http.Request) {
    a.mu.Lock()
    defer a.mu.Unlock()
    responderJSON(w, http.StatusOK, a.tareas)
}

func (a *API) ver(w http.ResponseWriter, r *http.Request) {
    id, err := strconv.Atoi(r.PathValue("id"))
    if err != nil {
        http.Error(w, "id no válido", http.StatusBadRequest)
        return
    }
    a.mu.Lock()
    defer a.mu.Unlock()
    for _, t := range a.tareas {
        if t.ID == id {
            responderJSON(w, http.StatusOK, t)
            return
        }
    }
    http.NotFound(w, r)
}

func (a *API) crear(w http.ResponseWriter, r *http.Request) {
    var t Tarea
    // En PHP: json_decode(file_get_contents('php://input'), true)
    if err := json.NewDecoder(r.Body).Decode(&t); err != nil || strings.TrimSpace(t.Titulo) == "" {
        http.Error(w, "tarea no válida", http.StatusBadRequest)
        return
    }
    a.mu.Lock()
    defer a.mu.Unlock()
    t.ID = len(a.tareas) + 1
    a.tareas = append(a.tareas, t)
    responderJSON(w, http.StatusCreated, t)
}

func NuevoMux(a *API) *http.ServeMux {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /tareas", a.listar)
    mux.HandleFunc("GET /tareas/{id}", a.ver)
    mux.HandleFunc("POST /tareas", a.crear)
    return mux
}

func main() {
    mux := NuevoMux(&API{})
    pedir := func(metodo, ruta, cuerpo string) {
        rec := httptest.NewRecorder()
        mux.ServeHTTP(rec, httptest.NewRequest(metodo, ruta, strings.NewReader(cuerpo)))
        fmt.Printf("%s %s -> %d %s", metodo, ruta, rec.Code, rec.Body.String())
    }
    pedir("POST", "/tareas", `{"titulo":"Comprar pan"}`)
    pedir("POST", "/tareas", `{"titulo":"Repasar Go"}`)
    pedir("POST", "/tareas", `{"titulo":"   "}`)
    pedir("GET", "/tareas", "")
    pedir("GET", "/tareas/2", "")
    pedir("GET", "/tareas/9", "")
}

En tu máquina, para servirla de verdad, basta con añadir en main() la línea http.ListenAndServe(":8080", NuevoMux(&API{})). Y para probarla, los pedir(...) de arriba son casi un test: muévelos a un api_test.go con t.Errorf y tendrás los tests de tu API.

6 · SQL con database/sql

Para la base de datos, Go trae database/sql: una interfaz común, como PDO, y un driver por motor que se importa aparte. En el proyecto final usarás SQLite con modernc.org/sqlite, escrito en Go puro. Este código no se puede ejecutar en el navegador (no hay disco), así que es de solo lectura:

Gomain.go
import (
    "database/sql"
    "errors"

    // Solo por su init(): registra el driver «sqlite».
    _ "modernc.org/sqlite"
)

type RepositorioSQLite struct {
    db *sql.DB
}

func NuevoRepositorioSQLite(ruta string) (*RepositorioSQLite, error) {
    // En PHP: $pdo = new PDO('sqlite:tareas.db');
    db, err := sql.Open("sqlite", ruta)
    if err != nil {
        return nil, err
    }
    return &RepositorioSQLite{db: db}, nil
}

func (r *RepositorioSQLite) BuscarPorID(id int) (Tarea, error) {
    var t Tarea
    // En PHP: $stmt = $pdo->prepare('SELECT … WHERE id = ?'); $stmt->execute([$id]);
    err := r.db.QueryRow(
        "SELECT id, titulo, prioridad, hecha FROM tareas WHERE id = ?", id,
    ).Scan(&t.ID, &t.Titulo, &t.Prioridad, &t.Hecha)
    if errors.Is(err, sql.ErrNoRows) {
        return Tarea{}, ErrTareaNoEncontrada
    }
    return t, err
}

func (r *RepositorioSQLite) Listar() ([]Tarea, error) {
    filas, err := r.db.Query("SELECT id, titulo, prioridad, hecha FROM tareas ORDER BY id")
    if err != nil {
        return nil, err
    }
    // Sin esto, la conexión se queda ocupada.
    defer filas.Close()

    var tareas []Tarea
    // En PHP: while ($fila = $stmt->fetch()) { ... }
    for filas.Next() {
        var t Tarea
        if err := filas.Scan(&t.ID, &t.Titulo, &t.Prioridad, &t.Hecha); err != nil {
            return nil, err
        }
        tareas = append(tareas, t)
    }
    return tareas, filas.Err()
}
PDOdatabase/sqlOjo
new PDO($dsn)sql.Open("sqlite", ruta)No conecta todavía: prepara un pool de conexiones
prepare + execute + fetchdb.QueryRow(sql, args...).Scan(&a, &b)Una fila; si no hay, sql.ErrNoRows
query + while (fetch)db.Query(...) + for filas.Next()Siempre defer filas.Close()
exec + lastInsertId()res, err := db.Exec(...) + res.LastInsertId()Para INSERT, UPDATE y DELETE
beginTransaction()tx, err := db.Begin()Luego tx.Commit() o tx.Rollback()

Y para publicarlo: compilas para el sistema del servidor y subes un único fichero. Go compila para otro sistema cambiando dos variables de entorno:

$ GOOS=linux GOARCH=amd64 go build -o tareas ./cmd/tareas
$ scp tareas usuario@mi-servidor:/srv/tareas/
$ ssh usuario@mi-servidor /srv/tareas/tareas
2026/11/17 10:00:00 Escuchando en http://localhost:8080

La pregunta que te vas a hacer

«Vale, pero… ¿y cómo lo despliego en mi servidor de verdad?»

No necesitas PHP, ni php-fpm, ni extensiones, ni composer install en el servidor: solo el binario. Lo habitual es una de estas dos formas:

  1. Binario + systemd: copias el fichero, creas un servicio de systemd para que arranque solo y se reinicie si cae, y pones Caddy o nginx delante para el HTTPS y el dominio (como proxy_pass, no como fastcgi_pass).
  2. Docker: una imagen en dos pasos (compilas en una imagen con Go y copias solo el binario a una imagen mínima). Suele pesar unos pocos MB, frente a los cientos de una imagen de PHP con sus extensiones.

Para seguir:

Hora de practicar

Retos · 0/3 resueltos

Reto 1 de 3

Tu primer endpoint JSON

Completa el handler Salud(w http.ResponseWriter, r *http.Request) para que responda con código 200, la cabecera Content-Type: application/json y el cuerpo {"estado":"ok"}. Los tests lo llaman con httptest, sin red. Es tu header('Content-Type: application/json'); echo json_encode(['estado' => 'ok']);.

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. Handler = func(w http.ResponseWriter, r *http.Request) (en PHP, superglobales + echo + header()).
  2. GET /tareas/{id} + r.PathValue("id") es el router de serie (en PHP, Slim o el router de Laravel).
  3. JSON con etiquetas json:"titulo"; los campos en minúscula no salen (en PHP, json_encode() de las propiedades públicas).
  4. Cabeceras, código y cuerpo, en ese orden (en PHP, output_buffering lo disimula).
  5. El programa vive entre peticiones: lo global se comparte (en PHP, cada petición empieza de cero).
  6. database/sql + driver es tu PDO; los tests de la API, con httptest y sin red.

Para recordarlo: «Cierra el sobre al final»

Una respuesta es una carta: primero escribes la dirección y el sello (cabeceras y código) y lo último que metes es la carta (el cuerpo). En cuanto empiezas a escribir el cuerpo, el sobre se cierra y lo que no pusiste antes ya no entra.