filepath vs path: cuándo usar cada uno en Go

Si estás lidiando con rutas de archivos, no puedes permitirte confundir path con filepath. La diferencia es fundamental: path trabaja exclusivamente con rutas separadas por barras diagonales (/), independientemente de tu sistema operativo. Es una especificación lógica para rutas virtuales, como las de una URL, un path dentro de un archivo ZIP o un identificador de un objeto en un bucket de S3. En cambio, filepath es el que interactúa con el sistema de archivos real, adaptándose al os.PathSeparator de tu máquina; esto significa que en Linux/macOS usará / y en Windows usará \.

Esta distinción existe por una razón de diseño: la portabilidad. El paquete path garantiza que la lógica de rutas sea la misma en cualquier plataforma, lo cual es vital cuando procesas datos que no dependen del hardware local. filepath, por su parte, le dice al sistema operativo exactamente dónde encontrar un recurso. Si usas path para manipular rutas de archivos en Windows, vas a tener problemas graves. path no reconocerá la barra invertida \ como un separador, sino como parte del nombre de un archivo, lo que romperá toda tu lógica de navegación. Por el contrario, si intentas usar filepath para construir una URL, terminarás con barras invertidas que harán que el servidor web te devuelva un error 400.

Para recorrer directorios, evita la función filepath.Walk (que está algo obsoleta por su ineficiencia) y utiliza filepath.WalkDir [disponible desde Go 1.16]. WalkDir es mucho más rápida porque no llama a os.Lstat por cada archivo, sino que utiliza la información que ya viene en la entrada del directorio (DirEntry), reduciendo drásticamente las llamadas al sistema.

package main

import (
	"fmt"
	"io/fs"
	"os"
	"path"
	"path/filepath"
	"runtime"
)

func main() {
	// 1. La diferencia en el separador
	// En Windows, filepath usará \, pero path siempre usará /
	fmt.Printf("SO Actual: %s\n", runtime.GOOS)

	// filepath.Join es para el filesystem local
	localPath := filepath.Join("usuarios", "admin", "config.yaml")
	fmt.Printf("Local (filepath.Join): %s\n", localPath)

	// path.Join es para rutas lógicas (URLs, ZIPs, etc.)
	virtualPath := path.Join("api", "v1", "user")
	fmt.Printf("Virtual (path.Join):    %s\n", virtualPath)

	// 2. Manipulación de elementos
	// fíjate cómo filepath identifica la extensión y el directorio
	fullPath := filepath.Join("tmp", "datos", "reporte.pdf")
	fmt.Printf("Base: %s | Dir: %s | Ext: %s\n",
		filepath.Base(fullPath),
		filepath.Dir(fullPath),
		filepath.Ext(fullPath))

	// 3. Limpieza de rutas (Clean)
	// filepath.Clean resuelve ".." y "." según las reglas del SO
	dirtyPath := filepath.Join("a", "b", "..", "c", "./d")
	fmt.Printf("Ruta limpia: %s\n", filepath.Clean(dirtyPath))

	// 4. Walker eficiente: filepath.WalkDir
	// Creamos un directorio temporal para la demostración
	tmpDir, err := os.MkdirTemp("", "demo-walk-*")
	if err != nil {
		panic(err)
	}
	defer os.RemoveAll(tmpDir)

	// Creamos algunos archivos de prueba
	os.WriteFile(filepath.Join(tmpDir, "archivo1.txt"), []byte("hola"), 0644)
	os.WriteFile(filepath.Join(tmpDir, "foto.png"), []byte("mundo"), 0644)

	fmt.Println("--- Iniciando WalkDir ---")
	err = filepath.WalkDir(tmpDir, func(pathActual string, d fs.DirEntry, err error) error {
		if err != nil {
			return err
		}
		// d.IsDir() nos permite saber si es un directorio sin hacer un stat extra
		tipo := "archivo"
		if d.IsDir() {
			tipo = "directorio"
		}
		fmt.Printf("[%s] %s\n", tipo, pathActual)
		return nil
	})

	if err != nil {
		fmt.Printf("Error en WalkDir: %v\n", err)
	}
}

Análisis del código

En el ejemplo anterior, observa cómo filepath.Join adapta el resultado al sistema operativo actual. Si corres esto en Windows, verás usuarios\admin\config.yaml, mientras que en Linux será usuarios/admin/config.yaml. Esto es lo que permite que tu código sea multiplataforma.

Cuando usamos filepath.Base, filepath.Dir y filepath.Ext, estamos extrayendo información basándonos en las reglas de la plataforma. Si le pasas a filepath.Base una ruta de Windows que use \, funcionará correctamente. Si intentas hacer lo mismo con path.Base y una ruta de Windows, fallará porque path buscará / y tratará todo lo anterior a la última barra como el nombre del archivo.

En la sección de WalkDir, notarás que la función anónima recibe fs.DirEntry. La clave de la eficiencia aquí es que d.IsDir() o d.Name() se ejecutan sin necesidad de realizar una llamada adicional al kernel para obtener los metadatos del archivo, a diferencia de filepath.Walk, que es mucho más pesada en términos de I/O.

El error frecuente

El error más común ocurre cuando intentas construir rutas de archivos usando path.Join en lugar de filepath.Join.

// ERROR: Esto fallará en Windows
p := path.Join("C:", "Users", "Documentos")
// En Windows, p será "C:/Users/Documentos"
// Aunque parece una ruta, Go y el SO podrían no tratarla correctamente 
// en llamadas de bajo nivel que esperen el separador nativo,
// o peor aún, si intentas concatenar manualmente:
p2 := path.Join("dir", "sub\\dir") 
// path.Join tratará la "\" como un carácter literal, no como separador.

Si tu aplicación necesita leer archivos del disco, usa siempre filepath. Si tu aplicación procesa rutas de una base de datos que representan URLs o la estructura interna de un archivo comprimido, usa path.

N° 117