Nomenclatura de Paquetes y Directorios internal/

Los nombres de los paquetes de Go y la disposición de los directorios comunican la intención antes de que un lector abra un archivo.

Nombres cortos consistentes más los directorios internal/ mantienen honestas las APIs públicas y permiten que el compilador aplique los límites.

Resumen

Los nombres de los paquetes deben ser en minúsculas, concisos y descriptivos sin repeticiones redundantes.

Las rutas de importación llevan el prefijo del módulo; las cláusulas de paquete nombran la unidad compilada.

El nombre especial internal restringe las importaciones a los directorios ancestros dentro del mismo árbol de módulos.

Esa combinación reduce el acoplamiento accidental y hace que las refactorizaciones sean más seguras para los autores de bibliotecas.

Receta

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

// example.com/widget/internal/parser/parser.go
package parser // no es package widgetparser
 
import "strings"
 
func Parse(raw string) (string, error) {
    return strings.TrimSpace(raw), nil
}

// example.com/widget/api/handler.go
package api
 
import "example.com/widget/internal/parser"
 
func Handle(raw string) (string, error) {
    return parser.Parse(raw)
}

Cuándo usar esto:

• Al nombrar un nuevo paquete según su función (auth, store, parser), no el nombre del repositorio.
• Al colocar detalles de implementación bajo internal/ cuando los módulos externos no deben importarlos.
• Al separar binarios de cmd/ de paquetes reutilizables en el mismo módulo.
• Al revisar importaciones en CI con go list o linters que marcan rutas repetitivas.

Ejemplo de Trabajo

example.com/checkout/
  go.mod
  cmd/checkoutd/main.go
  checkout/          // tipos de dominio - la ruta de importación termina en /checkout
    checkout.go
  internal/
    tax/
      tax.go
    payment/
      payment.go
  api/
    http.go

// checkout/checkout.go
package checkout
 
type Cart struct {
    Items []string
}

// internal/tax/tax.go
package tax
 
func Rate(region string) float64 {
    if region == "CA" {
        return 0.0725
    }
    return 0
}

// api/http.go
package api
 
import (
    "example.com/checkout/checkout"
    "example.com/checkout/internal/tax"
)
 
func Quote(c checkout.Cart, region string) float64 {
    return tax.Rate(region) * float64(len(c.Items))
}

Lo que esto demuestra:

• Los tipos de dominio públicos viven en un paquete de nivel superior con un nombre claro.
• internal/tax puede ser llamado desde api/ porque api está bajo el padre internal example.com/checkout.
• Los módulos externos pueden importar checkout y api pero no internal/tax.

Profundización

Cómo Funciona

• Los nombres de los paquetes aparecen en identificadores calificados (tax.Rate).

Los nombres cortos se leen bien en los sitios de llamada porque la ruta de importación ya proporciona contexto.

• El compilador permite internal solo cuando el paquete importador está debajo del directorio que contiene la carpeta internal.

Para .../checkout/internal/tax, los importadores deben vivir debajo de .../checkout/.

• Múltiples paquetes en un módulo obtienen su propio subdirectorio; no puedes mezclar package foo y package bar en la misma carpeta.

Reglas de Nomenclatura de un Vistazo

internal/ vs pkg/

pkg/ no oculta símbolos.

Si necesitas garantías sólidas, usa internal/.

Notas de Go

// Malo: repetición en el sitio de llamada cuando la importación se renombra mal
import checkoutinternal "example.com/checkout/internal/checkout"
 
// Bueno: detalle interno con nombre de paquete corto
import "example.com/checkout/internal/tax"

// internal/ anidado aún más profundo funciona - la regla es por directorio internal
// example.com/checkout/internal/payment/gateway/gateway.go
package gateway

Errores Comunes

• La discrepancia entre la ruta de importación y el nombre del paquete confunde a los lectores. Mantenlos alineados excepto para main y casos bien conocidos de la biblioteca estándar.
• internal se basa en la ruta, no en la visibilidad. Los identificadores en minúsculas ya son privados del paquete; internal/ bloquea las importaciones entre módulos por completo.
• Mover código de público a internal/ es un cambio que rompe la compatibilidad para cualquiera que haya importado la ruta antigua.
• Nombres de carpetas genéricos (utils) se convierten en cajones de sastre. Divídalos por responsabilidad en su lugar.
• Los paquetes de prueba package foo_test viven junto a foo y son un paquete separado para pruebas de caja negra.

Alternativas

• Múltiples módulos - Límites de lanzamiento más fuertes que internal/ cuando los equipos necesitan semver separados.
• Espacios de trabajo de Go - Desarrollo local a través de módulos sin exponer paquetes privados.
• Paquetes públicos solo de interfaz - Superficie exportada pequeña con implementación en tipos no exportados (aún no es un sustituto para internal/ entre módulos).

Preguntas Frecuentes

Relacionado

• Paquetes y Módulos: La Unidad de Distribución de Go - Rutas de módulos y rutas de importación
• Diseño de Proyecto Estándar para Servicios y Bibliotecas - Ubicación de cmd, internal, pkg
• Ciclos de Importación, Importaciones Vacías y Importaciones Punto - Patrones de importación y ciclos
• Conceptos Básicos de Paquetes y Módulos - Ejemplos ejecutables de nomenclatura e internal

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, 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).