golang-standards/project-layout

Traductions:

  • 어어어
  • 体体中文
  • 中中文
  • 体体中文
  • 体体中文-???
  • Français
  • 日本語
  • Portugais
  • Español

Aperçu

Ceci est une disposition de base pour les projets d’application Go. Ce n’est pas une norme officielle définie par l’équipe de développement Go de base; cependant, il s’agit d’un ensemble de modèles de mise en page de projets historiques et émergents communs dans l’écosystème Go. Certains de ces modèles sont plus populaires que d’autres. Il a également un certain nombre de petites améliorations ainsi que plusieurs répertoires de support communs à toute application du monde réel assez grande.

Si vous essayez d’apprendre Go ou si vous construisez un projet de PoC ou de jouet pour vous-même, cette disposition de projet est exagérée. Commencez par quelque chose de vraiment simple (un seul fichier main.go est plus que suffisant). Au fur et à mesure que votre projet se développe, gardez à l’esprit qu’il sera important de vous assurer que votre code est bien structuré, sinon vous vous retrouverez avec un code désordonné avec beaucoup de dépendances cachées et un état global. Lorsque vous aurez plus de personnes travaillant sur le projet, vous aurez besoin d’encore plus de structure. C’est alors qu’il est important d’introduire un moyen commun de gérer les paquets / bibliothèques. Lorsque vous avez un projet open source ou que vous connaissez d’autres projets, importez le code à partir de votre référentiel de projet, c’est alors qu’il est important d’avoir des packages et du code privés (alias internal). Clonez le référentiel, conservez ce dont vous avez besoin et supprimez tout le reste! Ce n’est pas parce qu’il est là que vous devez tout utiliser. Aucun de ces modèles n’est utilisé dans chaque projet. Même le motif vendor n’est pas universel.

Avec Go 1.14 Go Modules sont enfin prêts pour la production. Utilisez Go Modules sauf si vous avez une raison spécifique de ne pas les utiliser et si vous le faites, vous n’avez pas à vous soucier deGOPGOPATH et de l’endroit où vous placez votre projet. Le fichier go.mod de base dans le dépôt suppose que votre projet est hébergé sur GitHub, mais ce n’est pas une exigence. Le chemin du module peut être n’importe quoi bien que le premier composant de chemin de module devrait avoir un point dans son nom (la version actuelle de Go ne l’applique plus, mais si vous utilisez des versions légèrement plus anciennes, ne soyez pas surpris si vos versions échouent sans elle). Voir les problèmes 37554 et 32819 si vous voulez en savoir plus à ce sujet.

Cette disposition de projet est intentionnellement générique et n’essaie pas d’imposer une structure de package Go spécifique.

Il s’agit d’un effort communautaire. Ouvrez un problème si vous voyez un nouveau modèle ou si vous pensez que l’un des modèles existants doit être mis à jour.

Si vous avez besoin d’aide pour nommer, formater et styliser, commencez par exécuter gofmt et golint. Assurez-vous également de lire ces directives et recommandations de style Go code:

  • 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
  • Guide de style pour les paquets Go (rakyll/JBD)

Voir Go Project Layout pour des informations de fond supplémentaires.

En savoir plus sur le nommage et l’organisation des paquets ainsi que sur d’autres recommandations de structure de code :

  • GopherCon EU 2018: Peter Bourgon – Meilleures pratiques pour la programmation industrielle
  • GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen – Bonnes pratiques Go.
  • GopherCon 2017: Edward Muller – Go Anti-Patterns
  • GopherCon 2018: Kat Zien – Comment Structurez-Vous vos Applications Go

Un Article chinois sur les directives de Conception orientées Paquet et la couche d’architecture

  • 的的的

Répertoires Go

/cmd

Principales applications de ce projet.

Le nom du répertoire de chaque application doit correspondre au nom de l’exécutable que vous souhaitez avoir (par exemple, /cmd/myapp).

Ne mettez pas beaucoup de code dans le répertoire de l’application. Si vous pensez que le code peut être importé et utilisé dans d’autres projets, alors il devrait vivre dans le répertoire /pkg. Si le code n’est pas réutilisable ou si vous ne voulez pas que d’autres le réutilisent, placez ce code dans le répertoire /internal. Vous serez surpris de ce que les autres feront, alors soyez explicite sur vos intentions!

Il est courant d’avoir une petite fonction main qui importe et appelle le code des répertoires /internal et /pkg et rien d’autre.

Voir le répertoire /cmd pour des exemples.

/interne

Code d’application privée et de bibliothèque. C’est le code que vous ne voulez pas que les autres importent dans leurs applications ou bibliothèques. Notez que ce modèle de mise en page est appliqué par le compilateur Go lui-même. Voir Go 1.4 release notes pour plus de détails. Notez que vous n’êtes pas limité au répertoire internal de niveau supérieur. Vous pouvez avoir plus d’un répertoire internal à n’importe quel niveau de l’arborescence de votre projet.

Vous pouvez éventuellement ajouter un peu de structure supplémentaire à vos paquets internes pour séparer votre code interne partagé et non partagé. Ce n’est pas nécessaire (en particulier pour les petits projets), mais il est agréable d’avoir des indices visuels montrant l’utilisation prévue du package. Votre code d’application réel peut aller dans le répertoire /internal/app (par exemple, /internal/app/myapp) et le code partagé par ces applications dans le répertoire /internal/pkg (par exemple, /internal/pkg/myprivlib).

/pkg

Code de bibliothèque qui peut être utilisé par des applications externes (par ex., /pkg/mypubliclib). D’autres projets importeront ces bibliothèques en s’attendant à ce qu’elles fonctionnent, alors réfléchissez à deux fois avant de mettre quelque chose ici:-) Notez que le répertoire internal est un meilleur moyen de s’assurer que vos paquets privés ne sont pas importables car il est appliqué par Go. Le répertoire /pkg est toujours un bon moyen de communiquer explicitement que le code de ce répertoire est sûr pour une utilisation par d’autres. Le billet de blog I'll take pkg over internal de Travis Jeffery donne un bon aperçu des répertoires pkg et internal et du moment où il pourrait être judicieux de les utiliser.

C’est aussi un moyen de regrouper le code Go en un seul endroit lorsque votre répertoire racine contient de nombreux composants et répertoires non Go, ce qui facilite l’exécution de divers outils Go (comme mentionné dans ces discussions: Best Practices for Industrial Programming de GopherCon EU 2018, GopherCon 2018: Kat Zien – Comment Structurez-vous vos Applications Go et GoLab 2018 – Massimiliano Pippi – Modèles de mise en page de projets dans Go).

Consultez le répertoire /pkg si vous voulez voir quels dépôts Go populaires utilisent ce modèle de disposition de projet. C’est un modèle de mise en page commun, mais il n’est pas universellement accepté et certains membres de la communauté Go ne le recommandent pas.

Il est ok de ne pas l’utiliser si votre projet d’application est vraiment petit et où un niveau d’imbrication supplémentaire n’ajoute pas beaucoup de valeur (sauf si vous voulez vraiment :-)). Pensez-y quand il devient assez grand et que votre répertoire racine est assez occupé (surtout si vous avez beaucoup de composants d’applications non Go).

/vendor

Dépendances d’application (gérées manuellement ou par votre outil de gestion des dépendances préféré comme la nouvelle fonctionnalité Go Modules intégrée). La commande go mod vendor créera le répertoire /vendor pour vous. Notez que vous devrez peut-être ajouter l’indicateur -mod=vendor à votre commande go build si vous n’utilisez pas Go 1.14 où il est activé par défaut.

Ne validez pas les dépendances de votre application si vous construisez une bibliothèque.

Notez que depuis 1.13 Go a également activé la fonctionnalité de proxy de module (en utilisant https://proxy.golang.org comme serveur proxy de module par défaut). En savoir plus à ce sujet here pour voir s’il répond à toutes vos exigences et contraintes. Si c’est le cas, vous n’aurez pas du tout besoin du répertoire vendor.

Répertoires d’applications de service

/api

Spécifications OpenAPI/Swagger, fichiers de schéma JSON, fichiers de définition de protocole.

Voir le répertoire /api pour des exemples.

Répertoires d’applications Web

/web

Composants spécifiques aux applications Web : ressources Web statiques, modèles côté serveur et SPAS.

Répertoires d’applications communs

/configs

Modèles de fichiers de configuration ou configurations par défaut.

Mettez vos fichiers de modèle confd ou consul-template ici.

/initialisation

Configuration de l’initialisation du système (systemd, arriviste, sysv) et du gestionnaire/superviseur de processus (runit, supervisord).

/scripts

Scripts pour effectuer diverses opérations de génération, d’installation, d’analyse, etc.

Ces scripts gardent le Makefile de niveau racine petit et simple (par exemple, https://github.com/hashicorp/terraform/blob/master/Makefile).

Voir le répertoire /scripts pour des exemples.

/build

Empaquetage et intégration continue.

Placez vos configurations et scripts de paquets cloud (AMI), container (Docker), OS (deb, rpm, pkg) dans le répertoire /build/package.

Placez vos configurations et scripts CI (travis, circle, drone) dans le répertoire /build/ci. Notez que certains des outils CI (p. ex., Travis CI) sont très pointilleux sur l’emplacement de leurs fichiers de configuration. Essayez de placer les fichiers de configuration dans le répertoire /build/ci les reliant à l’emplacement où les outils CI les attendent (lorsque cela est possible).

/déploiements

Configurations et modèles de déploiement d’orchestration IaaS, PaaS, système et conteneur (docker-compose, kubernetes/helm, mesos, terraform, bosh). Notez que dans certains dépôts (en particulier les applications déployées avec kubernetes), ce répertoire est appelé /deploy.

/test

Applications de test externes supplémentaires et données de test. N’hésitez pas à structurer le répertoire /test comme vous le souhaitez. Pour les projets plus importants, il est logique d’avoir un sous-répertoire de données. Par exemple, vous pouvez avoir /test/data ou /test/testdata si vous devez ignorer ce qui se trouve dans ce répertoire. Notez que Go ignorera également les répertoires ou les fichiers qui commencent par “.” ou “_”, vous avez donc plus de flexibilité dans la façon dont vous nommez votre répertoire de données de test.

Voir le répertoire /test pour des exemples.

Autres répertoires

/docs

Documents de conception et d’utilisateur (en plus de votre documentation générée par godoc).

Voir le répertoire /docs pour des exemples.

/tools

Outils de support pour ce projet. Notez que ces outils peuvent importer du code à partir des répertoires /pkg et /internal.

Voir le répertoire /tools pour des exemples.

/exemples

Exemples pour vos applications et/ou bibliothèques publiques.

Voir le répertoire /examples pour des exemples.

/third_party

Outils d’aide externes, code fourchu et autres utilitaires tiers (par exemple, interface utilisateur Swagger).

/githooks

Crochets Git.

/assets

Autres assets pour accompagner votre dépôt (images, logos, etc.).

/website

C’est l’endroit où mettre les données du site Web de votre projet si vous n’utilisez pas les pages GitHub.

Voir le répertoire /website pour des exemples.

Répertoires Que vous ne devriez pas avoir

/src

Certains projets Go ont un dossier src, mais cela arrive généralement lorsque les développeurs viennent du monde Java où c’est un modèle commun. Si vous pouvez vous aider, essayez de ne pas adopter ce modèle Java. Vous ne voulez vraiment pas que votre code Go ou vos projets Go ressemblent à Java:-)

Ne confondez pas le répertoire /src au niveau du projet avec le répertoire /src que Go utilise pour ses espaces de travail comme décrit dans How to Write Go Code. La variable d’environnement $GOPATH pointe vers votre espace de travail (actuel) (par défaut, elle pointe vers $HOME/go sur les systèmes non windows). Cet espace de travail inclut les répertoires de niveau supérieur /pkg/bin et /src. Votre projet réel finit par être un sous-répertoire sous /src, donc si vous avez le répertoire /src dans votre projet, le chemin du projet ressemblera à ceci: /some/path/to/workspace/src/your_project/src/your_code.go. Notez qu’avec Go 1.11 il est possible d’avoir votre projet en dehors de votre GOPATH, mais cela ne signifie toujours pas que c’est une bonne idée d’utiliser ce modèle de mise en page.

Badges

  • Carte de rapport Go – Il scannera votre code avec gofmtgo vetgocyclogolintgolintineffassignlicense et misspell. Remplacez github.com/golang-standards/project-layout par la référence de votre projet.

    Carte de rapport Go

  • GoDoc – Il fournira une version en ligne de votre documentation générée par GoDoc. Modifiez le lien pour qu’il pointe vers votre projet.

    Aller Doc

  • Pkg.aller.dev-Pkg.aller.dev est une nouvelle destination pour les documents Go discovery &. Vous pouvez créer un badge à l’aide de l’outil de génération de badge.

    PkgGoDev

  • Release – Il affichera le dernier numéro de version pour votre projet. Modifiez le lien github pour qu’il pointe vers votre projet.

    Release

Notes

Un modèle de projet plus abouti avec des exemples de configurations, des scripts et du code réutilisables est un WIP.

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée.