golang-normas / proyecto-diseño

Traducciones:

  • 한국어 문서
  • 简体中文
  • 正體中文
  • 简体中文 – ???
  • Francés
  • completo
  • portugués
  • Español

Descripción

Este es un diseño básico para Ir proyectos de aplicación. No es un estándar oficial definido por el equipo principal de desarrollo de Go; sin embargo, es un conjunto de patrones de diseño de proyectos históricos y emergentes comunes en el ecosistema de Go. Algunos de estos patrones son más populares que otros. También tiene una serie de pequeñas mejoras junto con varios directorios de soporte comunes a cualquier aplicación del mundo real lo suficientemente grande.

Si estás tratando de aprender Go o si estás construyendo un PoC o un proyecto de juguete para ti, este diseño del proyecto es excesivo. Comience con algo realmente simple (un solo archivo main.go es más que suficiente). A medida que su proyecto crezca, tenga en cuenta que será importante asegurarse de que su código esté bien estructurado, de lo contrario, terminará con un código desordenado con muchas dependencias ocultas y estado global. Cuando haya más personas trabajando en el proyecto, necesitará aún más estructura. Es entonces cuando es importante introducir una forma común de administrar paquetes/bibliotecas. Cuando tiene un proyecto de código abierto o cuando conoce otros proyectos, importe el código de su repositorio de proyectos, es cuando es importante tener paquetes y código privados (también conocido como internal). Clona el repositorio, conserva lo que necesitas y elimina todo lo demás. El hecho de que esté ahí no significa que tengas que usarlo todo. Ninguno de estos patrones se utiliza en cada proyecto. Incluso el patrón vendor no es universal.

Con Go 1.14 Go Modules finalmente están listos para la producción. Use Go Modules a menos que tenga una razón específica para no usarlos y si lo hace, no necesita preocuparse por $GOPATH y dónde coloca su proyecto. El archivo básico go.mod en el repositorio asume que tu proyecto está alojado en GitHub, pero no es un requisito. La ruta de acceso del módulo puede ser cualquier cosa, aunque el primer componente de ruta del módulo debe tener un punto en su nombre (la versión actual de Go ya no lo hace cumplir, pero si está utilizando versiones un poco más antiguas, no se sorprenda si sus compilaciones fallan sin él). Consulte Problemas 37554 y 32819 si desea obtener más información al respecto.

Este diseño de proyecto es intencionalmente genérico y no intenta imponer una estructura de paquete Go específica.

Este es un esfuerzo comunitario. Abra un problema si ve un patrón nuevo o si cree que es necesario actualizar uno de los patrones existentes.

Si necesita ayuda con el nombre, el formato y el estilo, comience ejecutando gofmty golint. También asegúrese de leer estas pautas y recomendaciones de estilo de código Go:

  • https://talks.golang.org/2014/names.slide
  • https://golang.org/doc/effective_go.html#names
  • https://blog.golang.org/package-names
  • https://github.com/golang/go/wiki/CodeReviewComments
  • Estilo de directriz para Ir paquetes (rakyll/JBD)

Go Project Layout para información adicional.

Más información sobre nombres y organización de paquetes, así como otras recomendaciones de estructura de código:

  • GopherCon EU 2018: Peter Bourgon – Mejores prácticas para la Programación Industrial
  • GopherCon Rusia 2018: Ashley McNamara + Brian Ketelsen – Mejores prácticas de Go.
  • GopherCon 2017: Edward Muller-Go Anti-Patrones
  • GopherCon 2018: Kat Zien-Cómo Estructurar sus Aplicaciones Go

Una publicación en chino sobre pautas de Diseño Orientadas a paquetes y Capa de arquitectura

  • 的的和和

Directorios Go

/cmd

Aplicaciones principales para este proyecto.

El nombre de directorio para cada aplicación debe coincidir con el nombre del ejecutable que desea tener (por ejemplo, /cmd/myapp).

No ponga mucho código en el directorio de la aplicación. Si cree que el código se puede importar y usar en otros proyectos, debería estar en el directorio /pkg. Si el código no es reutilizable o si no desea que otros lo reutilicen, coloque ese código en el directorio /internal. Te sorprenderás de lo que otros harán, ¡así que sé explícito sobre tus intenciones!

Es común tener una pequeña función main que importa e invoca el código de los directorios /internal y /pkg y nada más.

Vea el directorio /cmd para ver ejemplos.

/interno

Código de biblioteca y aplicación privada. Este es el código que no desea que otros importen en sus aplicaciones o bibliotecas. Tenga en cuenta que este patrón de diseño es impuesto por el propio compilador de Go. Consulte Go 1.4 release notes para obtener más detalles. Tenga en cuenta que no está limitado al directorio de nivel superior internal. Puede tener más de un directorio internal en cualquier nivel del árbol de su proyecto.

Opcionalmente, puede agregar un poco de estructura adicional a sus paquetes internos para separar su código interno compartido y no compartido. No es necesario (especialmente para proyectos más pequeños), pero es bueno tener pistas visuales que muestren el uso previsto del paquete. El código de aplicación real puede ir en el directorio /internal/app(por ejemplo, /internal/app/myapp) y el código compartido por esas aplicaciones en el directorio /internal/pkg (por ejemplo, /internal/pkg/myprivlib).

/pkg

Código de biblioteca que se puede usar en aplicaciones externas (p. ej., /pkg/mypubliclib). Otros proyectos importarán estas bibliotecas esperando que funcionen, así que piénselo dos veces antes de poner algo aquí 🙂 Tenga en cuenta que el directorio internal es una mejor manera de asegurarse de que sus paquetes privados no sean importables porque Go lo hace cumplir. El directorio /pkg sigue siendo una buena manera de comunicar explícitamente que el código de ese directorio es seguro para su uso por otros. La entrada de blog I'll take pkg over internal de Travis Jeffery proporciona una buena visión general de los directorios pkg y internal y cuándo podría tener sentido usarlos.

También es una forma de agrupar el código Go en un solo lugar cuando su directorio raíz contiene muchos componentes y directorios que no son Go, lo que facilita la ejecución de varias herramientas Go (como se mencionó en estas charlas: Best Practices for Industrial Programming de GopherCon EU 2018, GopherCon 2018: Kat Zien-Cómo Estructurar sus Aplicaciones Go y GoLab 2018 – Massimiliano Pippi – Patrones de diseño de proyectos en Go).

Consulte el directorio /pkg si desea ver qué repositorios populares de Go utilizan este patrón de diseño de proyecto. Este es un patrón de diseño común, pero no es universalmente aceptado y algunos en la comunidad Go no lo recomiendan.

Está bien no usarlo si su proyecto de aplicación es realmente pequeño y donde un nivel adicional de anidamiento no agrega mucho valor (a menos que realmente desee :-)). Piénsalo cuando se esté haciendo lo suficientemente grande y tu directorio raíz esté bastante ocupado (especialmente si tienes muchos componentes de aplicaciones no móviles).Dependencias de aplicaciones

/proveedor

(administradas manualmente o mediante su herramienta de administración de dependencias favorita, como la nueva función incorporada Go Modules). El comando go mod vendor creará el directorio /vendor para usted. Tenga en cuenta que es posible que deba agregar el indicador -mod=vendor a su comando go build si no está utilizando Go 1.14 donde está activado de forma predeterminada.

No confirme las dependencias de la aplicación si está creando una biblioteca.

Tenga en cuenta que desde 1.13 Go también habilitó la función de proxy de módulo (utilizando https://proxy.golang.org como su servidor proxy de módulo de forma predeterminada). Lea más sobre él here para ver si se ajusta a todos sus requisitos y restricciones. Si lo hace, entonces no necesitará el directorio vendor en absoluto.

Directorios de aplicaciones de servicio

/api

Especificaciones OpenAPI / Swagger, archivos de esquema JSON, archivos de definición de protocolo.

Consulte el directorio /api para ver ejemplos.

Directorios de aplicaciones web

/web

Componentes específicos de aplicaciones web: activos web estáticos, plantillas del lado del servidor y SPAs.

Directorios de aplicaciones comunes

/configs

Plantillas de archivos de configuración o configuraciones predeterminadas.

Ponga su confd o consul-template archivos de plantilla aquí.

/init

Configuraciones de inicio del sistema (systemd, upstart, sysv) y administrador / supervisor de procesos (runit, supervisord).

/scripts

Scripts para realizar varias operaciones de compilación, instalación,análisis, etc.

Estos scripts mantienen el Makefile de nivel raíz pequeño y simple (por ejemplo, https://github.com/hashicorp/terraform/blob/master/Makefile).

Consulte el directorio /scripts para ver ejemplos.

/build

Embalaje e Integración Continua.

Ponga sus configuraciones de paquetes de nube (AMI), contenedor (Docker), sistema operativo (deb, rpm, pkg) y scripts en el directorio /build/package.

Ponga sus configuraciones y scripts de CI (travis, circle, drone) en el directorio /build/ci. Tenga en cuenta que algunas de las herramientas de CI (p. ej., Travis CI) son muy exigentes con la ubicación de sus archivos de configuración. Intente colocar los archivos de configuración en el directorio /build/ci enlazándolos a la ubicación donde las herramientas de CI los esperan (cuando sea posible).

/ implementaciones

Configuraciones y plantillas de implementación de IaaS, PaaS, orquestación de sistemas y contenedores (docker-compose, kubernetes/helm, mesos, terraform, bosh). Tenga en cuenta que en algunos repositorios (especialmente aplicaciones implementadas con kubernetes) este directorio se llama /deploy.

/ test

Aplicaciones de prueba externas adicionales y datos de prueba. Siéntase libre de estructurar el directorio /test de la forma que desee. Para proyectos más grandes, tiene sentido tener un subdirectorio de datos. Por ejemplo, puede tener /test/data o /test/testdata si necesita ignorar lo que hay en ese directorio. Tenga en cuenta que Go también ignorará los directorios o archivos que comiencen con “.”o”_”, para que tenga más flexibilidad en términos de cómo nombrar su directorio de datos de prueba.

Vea el directorio /test para ver ejemplos.

Otros directorios

/ docs

Documentos de diseño y de usuario (además de la documentación generada por godoc).

Vea el directorio /docs para ver ejemplos.

/tools

herramientas de Apoyo para este proyecto. Tenga en cuenta que estas herramientas pueden importar código de los directorios /pkg y /internal.

Vea el directorio /tools para ver ejemplos.

ejemplos

Ejemplos de sus aplicaciones y/o bibliotecas públicas.

Consulte el directorio /examples para ver ejemplos.

/ third_party

Herramientas de ayuda externas, código bifurcado y otras utilidades de terceros (por ejemplo, interfaz de usuario Swagger).

/githooks

Git ganchos.

/ assets

Otros assets para acompañar su repositorio (imágenes, logotipos, etc.).

/ sitio web

Este es el lugar para colocar los datos del sitio web de tu proyecto si no estás usando páginas de GitHub.

Consulte el directorio /website para ver ejemplos.Directorios

No deberías Tener

/src

Algunos proyectos de Go tienen una carpeta src, pero generalmente sucede cuando los desarrolladores provienen del mundo Java, donde es un patrón común. Si puede ayudarse a sí mismo, intente no adoptar este patrón Java. Realmente no quieres que tu código Go o tus proyectos Go se parezcan a Java 🙂

No confundas el directorio de nivel de proyecto /src con el directorio /src que usa Go para sus espacios de trabajo como se describe en How to Write Go Code. La variable de entorno $GOPATH apunta a su espacio de trabajo (actual) (de forma predeterminada, apunta a $HOME/go en sistemas que no son Windows). Esta área de trabajo incluye el nivel superior /pkg/bin y /src directorios. Su proyecto real termina siendo un subdirectorio bajo /src, por lo que si tiene el directorio /src en su proyecto, la ruta del proyecto se verá así: /some/path/to/workspace/src/your_project/src/your_code.go. Tenga en cuenta que con Go 1.11 es posible tener su proyecto fuera de su GOPATH, pero aún así no significa que sea una buena idea usar este patrón de diseño.

Insignias

  • Ir a la Tarjeta de Informe – Que se va a escanear tu código con la etiqueta gofmtgo vetgocyclogolintineffassignlicense y misspell. Reemplace github.com/golang-standards/project-layout con la referencia de su proyecto.

    Boleta de calificaciones Go

  • GoDoc: Proporcionará una versión en línea de su documentación generada por GoDoc. Cambia el enlace para que apunte a tu proyecto.

    Go Doc

  • Pkg.Ve.dev-Pkg.Ve.dev es un nuevo destino para los documentos de Go discovery &. Puede crear una insignia con la herramienta de generación de insignias.

    PkgGoDev

  • Release-Mostrará el último número de versión de su proyecto. Cambia el enlace de github para que apunte a tu proyecto.

    Release

Notas

Una plantilla de proyecto más obstinada con configuraciones, scripts y código de muestra/reutilizables es un WIP.

Deja una respuesta

Tu dirección de correo electrónico no será publicada.