Diseño de Proyecto Estándar para Servicios y Bibliotecas

Go no tiene una estructura jerárquica oficial obligatoria, pero las convenciones de la comunidad hacen que los repositorios sean predecibles: cmd/ para binarios, internal/ para código privado y pkg/ opcional para APIs públicas soportadas.

Adaptarse a esa estructura acelera la incorporación y mantiene claros los límites de los módulos.

Resumen

Coloca un paquete main por comando bajo cmd/<nombre>/.

Mantén los detalles de implementación en internal/ para que otros módulos no puedan importarlos.

Las bibliotecas destinadas a la reutilización externa viven en paquetes de nivel superior con nombres claros o bajo pkg/ cuando deseas una zona pública obvia.

Un módulo puede alojar múltiples comandos y paquetes compartidos; divide los módulos solo cuando las líneas de lanzamiento diverjan.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

example.com/shop/
  go.mod
  cmd/
    shopd/main.go
    migrate/main.go
  internal/
    api/
    store/
  pkg/client/   # SDK estable opcional

// cmd/shopd/main.go
package main
 
import "example.com/shop/internal/api"
 
func main() {
    api.ListenAndServe()
}

Cuándo usar esto:

• Al iniciar un nuevo servicio HTTP o un worker con más de un binario.
• Al publicar una biblioteca consumida por otras empresas o repositorios.
• Al refactorizar un repositorio plano donde main y SQL se mezclaban en un solo paquete.

Ejemplo de Trabajo

example.com/notify/
  go.mod
  README.md
  cmd/
    notifyd/main.go
  internal/
    config/config.go
    server/http.go
    queue/worker.go
  pkg/client/client.go

// internal/config/config.go
package config
 
import "os"
 
func Port() string {
    if p := os.Getenv("PORT"); p != "" {
        return p
    }
    return "8080"
}

// internal/server/http.go
package server
 
import (
    "net/http"
    "example.com/notify/internal/config"
)
 
func ListenAndServe() error {
    return http.ListenAndServe(":"+config.Port(), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("ok"))
    }))
}

// pkg/client/client.go - SDK delgado para otros servicios
package client
 
import "net/http"
 
type Client struct{ Base string }
 
func (c Client) Ping() (*http.Response, error) {
    return http.Get(c.Base + "/healthz")
}

// cmd/notifyd/main.go
package main
 
import (
    "log"
    "example.com/notify/internal/server"
)
 
func main() {
    if err := server.ListenAndServe(); err != nil {
        log.Fatal(err)
    }
}

Lo que esto demuestra:

• cmd/notifyd es la única entrada ejecutable; la lógica permanece testeable en internal/server.
• pkg/client es opcional pero señala una API soportada para otros módulos.
• La configuración y el cableado HTTP son detalles de implementación privados.

Análisis Profundo

Cómo Funciona

cmd/ - Cada subdirectorio es package main que compila un binario.

Los nombres coinciden con el artefacto (shopd, migrate, ctl).

CI mapea go build -o bin/shopd ./cmd/shopd.

internal/ - El compilador bloquea importaciones desde fuera del subárbol del módulo padre.

Úsalo para capas de almacenamiento, adaptadores y cualquier cosa no cubierta por promesas semver.

pkg/ - Convención de repositorios de la era Kubernetes; no está impuesta.

Los importadores externos pueden depender de él, así que trátalo como cualquier paquete público con disciplina de compatibilidad.

Paquetes de dominio de nivel superior - Muchos módulos usan example.com/widget/widget o example.com/widget con paquetes en la raíz en lugar de pkg/.

Elige una estrategia y documéntala en README.

Comparación de Estructuras

Notas de Go

# Compilar todos los comandos
go build -o bin/ ./cmd/...
 
# Probar paquetes internos sin exportarlos
go test ./internal/...

// Evita la lógica de negocio en main - mantiene las pruebas rápidas
func main() {
    if err := run(); err != nil {
        log.Fatal(err)
    }
}

Trampas Comunes

• Tratar pkg/ como mágicamente estable - Es solo una convención; semver y la documentación hacen que la estabilidad sea real.
• Todo en internal/ - Hace imposibles las pruebas de integración en otros repositorios; exporta superficies de cliente mínimas.
• Múltiples main en un solo directorio - Inválido; divide los binarios bajo cmd/.
• Repositorios planos que crecen indefinidamente - Sin internal/, los ayudantes privados se filtran en las rutas de importación públicas.
• Copiar la estructura de Kubernetes ciegamente - Tu servicio puede necesitar un binario, no operadores y CRDs.

Alternativas

• Módulos separados por servicio - Aislamiento fuerte en organizaciones grandes.
• Paquetes de nivel superior orientados al dominio (billing/, shipping/) sin pkg/ - Claro para bibliotecas medianas.
• Plantillas (kubebuilder, cobra) - Generan la estructura cmd/ para dominios de problemas específicos.

Preguntas Frecuentes

Relacionado

• Nomenclatura de Paquetes y Directorios internal/ - Reglas de nomenclatura e internal/
• Paquetes y Módulos: La Unidad de Distribución de Go - Módulo vs paquete
• go work: Modo de Espacio de Trabajo para Repositorios Multi-Módulo - Monorepos multi-módulo
• Conceptos Básicos de Paquetes y Módulos - Ejemplo de esquema de estructura

Versiones de Stack: Esta página fue escrita para Go 1.26.x (Green Tea GC por defecto, go fix modernizadores - verificar parche en la compilación), chi (última versión - verificar en la compilación), gin (última versión - verificar en la compilación), echo (última versión - verificar en la compilación), google.golang.org/grpc (última versión - verificar en la compilación), sigs.k8s.io/controller-runtime (última versión - verificar en la compilación), kubebuilder (última versión - verificar en la compilación), tinygo (última versión - verificar objetivos de placa en la compilación), wazero (última versión - verificar en la compilación), y golangci-lint (última versión - verificar conjunto de linters en la compilación).

Y29kZWd1aWRlcy5pb3xjZ2lvNTE0fDIwMjYwNw==