Cuando compilas un programa en Go, el resultado suele ser un archivo binario único. Sin embargo, en aplicaciones reales, ese binario suele necesitar “compañeros”: plantillas HTML, archivos CSS, imágenes o configuraciones. Normalmente, tendrías que preocuparte por asegurar que esos archivos estén presentes en la misma ruta relativa en el servidor de despliegue. La directiva //go:embed [disponible desde Go 1.16] resuelve este problema incorporando el contenido de los archivos directamente en el segmento de datos del ejecutable en tiempo de compilación.
Esto funciona porque el compilador de Go lee los archivos indicados y los escribe dentro del binario. Al ejecutar el programa, estos archivos no se buscan en el sistema de archivos del sistema operativo (OS), sino que ya residen en la memoria del proceso. El tipo embed.FS es el encargado de gestionar este acceso y, lo más importante, implementa la interfaz io/fs.FS. Esto te permite tratar a tu binario como si fuera un sistema de archivos real, permitiendo que cualquier función que acepte una interfaz fs.FS (como los parsers de templates o los servidores web) pueda leer tus archivos embebidos.
Deberías usarlo siempre que quieras entregar una aplicación “autocontenida”. Es el estándar para servir assets de un servidor web (HTML, JS, CSS), cargar plantillas de html/template o incluir certificados SSL por defecto. Sin embargo, hay una limitación crítica: los archivos son estáticos. Una vez compilado el binario, no puedes modificar el contenido de esos archivos; si necesitas cambiar un archivo CSS, tienes que volver a compilar el código. Si tu aplicación requiere que el usuario modifique archivos en tiempo de ejecución (como un config.yaml de usuario), usa os.Open de la forma tradicional. Si intentas usar embed para archivos que deben ser editables, terminarás con un error de “solo lectura” o, peor aún, con un binario que no refleja los cambios que el usuario espera.
package main
import (
"embed"
"fmt"
"html/template"
"net/http"
)
// La directiva //go:embed le indica al compilador que incluya
// todo el contenido de la carpeta "static" en la variable staticFiles.
//go:embed static
var staticFiles embed.FS
func main() {
// 1. Uso de templates con archivos embebidos.
// ParseFS permite leer directamente de nuestra variable embed.FS.
tmpl, err := template.ParseFS(staticFiles, "static/index.html")
if err != nil {
panic(fmt.Sprintf("Error cargando el template: %v", err))
}
// 2. Handler para la página principal.
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
data := map[string]string{"Title": "Go Embed Demo"}
if err := tmpl.Execute(w, data); err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
}
})
// 3. Servir archivos estáticos (CSS, JS, imágenes).
// Convertimos embed.FS a http.Handler usando http.FS.
// El contenido de "static/" se sirve en la ruta "/static/".
fs := http.FileServer(http.FS(staticFiles))
http.Handle("/static/", http.StripPrefix("/static/", http.Redirect("/static/index.html", http.StatusMovedPermanently))) // Ejemplo de redirección o manejo
// Una forma más limpia de servir el contenido de la subcarpeta:
// Si el archivo está en static/style.css, se accede vía /static/static/style.css
// debido a cómo funciona la jerarquía de archivos embebidos.
// Para simplificar, usaremos el contenido directamente:
http.Handle("/assets/", http.StripPrefix("/assets/", http.FileServer(http.FS(staticFiles))))
fmt.Println("Servidor escuchando en http://localhost:8080")
if err := http.ListenAndServe(":8080", nil); err != nil {
panic(err)
}
}
Análisis del ejemplo
En el código anterior, la directiva //go:embed static es la clave. Al aplicarla sobre la variable staticFiles de tipo embed.FS, el compilador no solo incluye los archivos, sino que mantiene la estructura de directorios dentro de la variable. Si tienes un archivo en static/style.css, para acceder a él desde la variable deberás usar la ruta static/style.css.
En la sección de template.ParseFS, vemos la potencia de la interfaz fs.FS. No estamos pasando una ruta de disco (como /home/user/app/static/index.html), sino que le pasamos staticFiles, que es una implementación de sistema de archivos que vive en la memoria del binario. Esto garantiza que, al desplegar el binario en un contenedor Docker minimalista (como uno de tipo scratch), el servidor HTML funcionará perfectamente aunque no existan archivos reales en el sistema de archivos del contenedor.
Finalmente, para el servidor de archivos estáticos, utilizamos http.FS(staticFiles). Esta función es un adaptador que convierte nuestro embed.FS (que es un tipo específico de embed) en un http.Handler. Al combinarlo con http.StripPrefix, estamos preparando el terreno para que las peticiones HTTP se mapeen correctamente a la estructura interna de nuestros archivos embebidos.
El error frecuente
Un error clásico ocurre cuando los desarrolladores confunden la ruta de archivos en su máquina local con la ruta dentro del binario.
// ERROR: Esto funcionará en tu PC, pero fallará en producción.
// Si despliegas un binario único, la carpeta "static" NO existirá en el disco.
data, err := os.ReadFile("static/index.html")
Si tu intención es usar archivos que fueron incluidos con //go:embed, nunca uses el paquete os. Debes usar siempre la variable que declaraste con la directiva //go:embed. El error más sutil es intentar usar os.Open pensando que el binario “lleva los archivos dentro”, cuando en realidad os.Open busca en el sistema de archivos del sistema operativo, no dentro del espacio de datos del ejecutable.
N° 116