Entorno de desarrollo con Go: herramientas y estructura de proyectos

Configurar el entorno de trabajo de Go

Para trabajar con Go de forma productiva necesitas: (1) el compilador y herramientas oficiales, (2) un editor con soporte para Go, y (3) una estructura de proyecto basada en módulos. En esta sección configurarás lo mínimo para compilar, ejecutar y mantener proyectos reales.

Instalación

• Windows/macOS/Linux: instala Go desde el sitio oficial (paquete/instalador). Esto incluye el comando go, el compilador y herramientas como gofmt.
• Editor recomendado: VS Code con la extensión “Go” (usa gopls para autocompletado, navegación y diagnósticos). También funcionan GoLand, Vim/Neovim o Emacs con LSP.

Variables de entorno clave

Go funciona bien con su configuración por defecto, pero conviene conocer estas variables:

• PATH: debe incluir la ruta donde quedó instalado Go para poder ejecutar go desde la terminal.
• GOPATH: espacio de trabajo tradicional. Hoy es opcional para proyectos con módulos, pero sigue existiendo (por defecto suele ser $HOME/go).
• GOMODCACHE: caché de módulos descargados (normalmente dentro de GOPATH).
• GOBIN: destino de binarios instalados con go install (si no se define, usa $GOPATH/bin).
• GO111MODULE: histórico; en versiones modernas los módulos están activados por defecto. No suele ser necesario tocarlo.

Verificación por terminal

Abre una terminal y ejecuta:

go version

Luego inspecciona el entorno efectivo:

go env

Comandos útiles para comprobar rutas específicas:

Continúa en nuestra aplicación.

• Escuche el audio con la pantalla apagada.
• Obtenga un certificado al finalizar.
• ¡Más de 5000 cursos para que explores!

O continúa leyendo más abajo...

Descargar la aplicación

go env GOPATH GOMODCACHE GOBIN

Si go no se encuentra, revisa el PATH y reinicia la terminal (o el sistema) tras la instalación.

Flujo de trabajo con la herramienta go

El comando go es el centro del flujo de trabajo: compila, ejecuta, prueba, formatea, valida y gestiona dependencias.

go run: ejecutar rápido

Compila en un binario temporal y lo ejecuta. Ideal para prototipos o herramientas pequeñas.

go run .

Cuando usas módulos, ejecutar go run . desde la raíz del módulo es una práctica común.

go build: compilar

Genera un binario (o verifica que compila) sin ejecutarlo.

go build ./...

./... significa “este paquete y todos los subpaquetes”. Es útil en CI para asegurar que todo compila.

go test: pruebas

Ejecuta pruebas y también compila los paquetes. Es habitual correrlo antes de subir cambios.

go test ./...

Con cobertura:

go test ./... -cover

gofmt y go fmt: formateo

gofmt es el formateador estándar de Go. Mantener el formato consistente reduce discusiones de estilo y mejora la legibilidad.

• gofmt formatea archivos directamente.
• go fmt aplica gofmt a paquetes (es un wrapper).

gofmt -w .

En editores, configura “format on save” para que sea automático.

go vet: análisis estático

go vet detecta patrones sospechosos (errores sutiles) que compilan pero pueden fallar en runtime.

go vet ./...

Una rutina recomendada antes de integrar cambios:

gofmt -w . && go test ./... && go vet ./...

Estructura de un módulo con go mod

Los módulos son la forma moderna de organizar proyectos y dependencias. Un módulo se define por un archivo go.mod en la raíz del proyecto.

Crear un módulo

En una carpeta vacía:

mkdir hola-go && cd hola-go
go mod init example.com/hola-go

Esto crea go.mod con el nombre del módulo. En proyectos reales, el nombre suele coincidir con el repositorio (por ejemplo, github.com/usuario/proyecto).

Archivos del módulo

• go.mod: declara el módulo, versión de Go y dependencias requeridas.
• go.sum: checksums para asegurar integridad de dependencias descargadas.

Buenas prácticas:

• Versiona go.mod y go.sum en Git.
• No edites go.sum manualmente.
• Evita “copiar” dependencias al repo; Go las descarga al caché de módulos.

Gestión de dependencias

Cuando importas un paquete externo por primera vez y compilas/pruebas, Go resuelve y descarga la dependencia automáticamente. También puedes hacerlo explícito:

go get example.com/algun/modulo@latest

Para limpiar y normalizar dependencias (muy útil tras borrar imports o mover código):

go mod tidy

Para ver por qué una dependencia está presente:

go mod why -m example.com/algun/modulo

Organización de paquetes, archivos y convenciones de nombres

Una estructura mantenible reduce acoplamiento, facilita pruebas y hace el proyecto navegable. En Go, la unidad principal de organización es el paquete (carpeta con archivos .go que comparten el mismo package).

Convenciones de nombres

• Paquetes: nombres cortos, en minúsculas, sin guiones ni underscores (ej. httpclient, store, auth).
• Archivos: descriptivos y en minúsculas (ej. server.go, handler.go, repository.go).
• Identificadores: CamelCase. Exportados empiezan con mayúscula (Client), no exportados con minúscula (client).
• Interfaces: a menudo terminan en -er cuando aplica (Reader, Store), pero evita forzar la convención.

Reglas prácticas para paquetes

• Un paquete debe tener una responsabilidad clara.
• Evita paquetes “util” genéricos; prefiere nombres que indiquen dominio o propósito.
• Minimiza dependencias entre paquetes; diseña APIs pequeñas.
• Coloca el main en un paquete main (normalmente bajo cmd/ en proyectos con múltiples binarios).

Estructura típica de proyecto

No existe una única estructura oficial, pero este esquema es común y escalable:

• cmd/: puntos de entrada (binarios). Cada subcarpeta suele ser un ejecutable.
• internal/: código privado del módulo (no importable desde otros módulos).
• pkg/: código pensado para ser importado por otros módulos (úsalo solo si realmente lo necesitas).
• api/: contratos (OpenAPI/Protobuf), si aplica.
• configs/: plantillas de configuración (si aplica).

Para proyectos pequeños, puedes empezar solo con main.go y uno o dos paquetes, y refactorizar hacia cmd/ e internal/ cuando crezca.

Proyecto mínimo: compilar y ejecutar

Crearás un módulo con un ejecutable simple y un paquete interno reutilizable.

Paso 1: inicializar el módulo

mkdir proyecto-minimo && cd proyecto-minimo
go mod init example.com/proyecto-minimo

Paso 2: crear estructura de carpetas

mkdir -p cmd/app internal/greeter

Paso 3: implementar un paquete interno

Crea internal/greeter/greeter.go:

package greeter

import "fmt"

// Hello construye un saludo a partir de un nombre.
//
// Ejemplo:
//  msg := greeter.Hello("Ada")
//  // "Hola, Ada"
func Hello(name string) string {
	if name == "" {
		name = "mundo"
	}
	return fmt.Sprintf("Hola, %s", name)
}

Paso 4: crear el ejecutable

Crea cmd/app/main.go:

package main

import (
	"fmt"
	"os"

	"example.com/proyecto-minimo/internal/greeter"
)

func main() {
	name := ""
	if len(os.Args) > 1 {
		name = os.Args[1]
	}
	fmt.Println(greeter.Hello(name))
}

Paso 5: ejecutar y compilar

Ejecutar:

go run ./cmd/app

Con argumento:

go run ./cmd/app Ada

Compilar binario:

go build -o app ./cmd/app

Ejecutar el binario:

./app Ada

Prácticas recomendadas: formateo, documentación y dependencias

Formateo automático

Antes de commitear:

gofmt -w .

Si usas VS Code, activa el formateo al guardar y selecciona gofmt como formateador por defecto.

Documentación con comentarios (GoDoc)

Go genera documentación a partir de comentarios. Reglas útiles:

• Comenta elementos exportados (funciones, tipos, constantes) con una frase que empiece por el nombre del elemento.
• Incluye ejemplos cortos cuando ayuden a evitar malentendidos.
• Mantén comentarios como documentación, no como “narración” del código.

Para ver documentación desde terminal:

go doc example.com/proyecto-minimo/internal/greeter

O de una función específica:

go doc example.com/proyecto-minimo/internal/greeter.Hello

Pruebas mínimas del paquete

Crea internal/greeter/greeter_test.go:

package greeter

import "testing"

func TestHello(t *testing.T) {
	got := Hello("Ada")
	want := "Hola, Ada"
	if got != want {
		t.Fatalf("Hello(\"Ada\") = %q; want %q", got, want)
	}
}

func TestHelloEmpty(t *testing.T) {
	got := Hello("")
	want := "Hola, mundo"
	if got != want {
		t.Fatalf("Hello(\"\") = %q; want %q", got, want)
	}
}

Ejecuta:

go test ./...

Validación adicional con go vet

go vet ./...

Manejo de dependencias en el día a día

• Después de agregar/eliminar imports o actualizar paquetes: go mod tidy.
• Para actualizar una dependencia a una versión específica: go get example.com/mod@v1.2.3.
• Para listar módulos directos e indirectos: go list -m all.

Checklist rápida para un proyecto mantenible