Paquetes, Módulos y Mejores Prácticas de Diseño de Proyectos

Higiene de módulos, convenciones de etiquetado y publicación.

Estos hábitos mantienen los grafos de importación pequeños, los lanzamientos predecibles y los monorepos mantenibles a medida que los equipos crecen.

Cómo Usar Esta Lista

• Aplica durante la creación del módulo, antes de etiquetar v1.0.0, y en la revisión de lanzamientos.
• Automatiza con go mod tidy, go test ./..., go vet ./..., y golangci-lint en CI.
• Trata los cambios de ruta de importación que rompen la compatibilidad como eventos semver (/v2 para bibliotecas).
• Revisa al añadir un segundo binario, dividir módulos o incorporar consumidores externos.

A - Identidad y versionado del módulo

• Elige una ruta de módulo que coincida con el dominio de alojamiento. Usa github.com/org/repo o tu dominio real para que go get se resuelva para siempre.
• Confirma go.mod y go.sum juntos. Las compilaciones reproducibles y la verificación de checksum dependen de ambos archivos.
• Ejecuta go mod tidy antes de cada fusión y etiqueta de lanzamiento. Los huérfanos y los indirectos faltantes nunca deberían sorprender a CI.
• Etiqueta los lanzamientos con semver que coincida con las líneas principales del módulo. Los módulos v2+ necesitan /v2 en la ruta del módulo y en las rutas de importación.
• Retrae etiquetas incorrectas en lugar de pretender que nunca existieron. Documenta la migración en las notas de lanzamiento al retractar.

B - Dependencias y actualizaciones

• Fija las dependencias directas con go get module@version intencional. Evita @latest a ciegas en la rama principal de producción sin revisar el changelog.
• Comprende MVS antes de luchar contra el grafo. Incrementa la versión mínima que satisface el grafo; no edites manualmente las versiones transitivas sin motivo.
• Usa go mod why -m para justificar nuevos módulos transitivos. Elimina peso no utilizado antes de que se arraigue.
• Establece GOPRIVATE para módulos privados y deshabilita sumdb donde sea apropiado. Documenta la autenticación de VCS para CI y portátiles.
• Prefiere go.work sobre rutas replace específicas de la máquina en ramas compartidas. Las anulaciones locales pertenecen a los archivos de espacio de trabajo o a la configuración de desarrollo documentada.

C - Diseño y disposición de paquetes

• Mantén cmd/ delgado; inyecta la orquestación en main, la lógica en otro lugar. Un paquete main por binario bajo cmd/<nombre>/.
• Coloca los detalles de implementación en internal/. Deja que el compilador imponga los límites en lugar de solo las advertencias de README.
• Nombra los paquetes según lo que hacen, no util o common. Nombres cortos en minúsculas; evita el tartamudeo de importación en los sitios de llamada.
• Exporta la superficie de API más pequeña que satisfaga las necesidades del consumidor. Los identificadores en mayúsculas son promesas de compatibilidad.
• Rompe ciclos de importación con paquetes de contrato compartidos, no con importaciones de punto. Las interfaces y los DTO viven debajo de ambos lados.

D - Publicación y consumo

• Documenta qué paquetes son estables para importadores externos. README más paquetes opcionales pkg/ o de biblioteca de nivel superior.
• Añade un archivo LICENSE compatible con tu proxy de módulo. Los consumidores y la revisión legal lo esperan en la raíz del módulo.
• Ejecuta go test ./... y go vet ./... en cada candidato a etiqueta. Los consumidores de módulos heredan tu barra de calidad.
• Publica entradas de changelog para cambios en la API y en la ruta del módulo. Incluye pasos de actualización para migraciones /v2.
• Haz vendor solo con una política de actualización documentada. go mod vendor ayuda a CI sin conexión; no dejes que el vendor se pudra en silencio.

E - Monorepo y repositorios multi-módulo

• Por defecto, usa un solo módulo hasta que las líneas de lanzamiento diverjan realmente. Archivos go.mod adicionales añaden coste operativo.
• Confirma el go.work raíz cuando los equipos co-desarrollan módulos diariamente. Documenta las comprobaciones de GOWORK=off para la validación de la publicación.
• Etiqueta cada módulo de forma independiente en repositorios multi-módulo. CI no debería asumir que una etiqueta Git versiona cada submódulo.
• Evita suposiciones de internal/ entre módulos. internal no abarca límites de módulos, incluso en un solo repositorio Git.
• Divide módulos cuando el semver, la propiedad o los conjuntos de consumidores difieran. No cuando las carpetas simplemente parezcan abarrotadas.

Preguntas Frecuentes

Relacionados

• Paquetes y Módulos: La Unidad de Distribución de Go - Descripción general conceptual
• go.mod, go.sum y Selección de Versión Mínima - Archivos y MVS
• Diseño Estándar de Proyectos para Servicios y Bibliotecas - cmd, internal, pkg
• Conceptos Básicos de Paquetes y Módulos - Puntos de partida ejecutables

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