Aperçu

Il s'agit d'une mise en page de base pour les projets d'application Go. Il ne s'agit pas d'une norme officielle définie par l'équipe de développement principale de Go; c'est une mise en page de répertoire couramment utilisée pour les projets communautaires Go.

Si vous apprenez Go ou construisez une preuve de concept (PoC) ou un projet personnel simple, cette mise en page de projet est trop compliquée. Au lieu de cela, commencez avec une mise en page vraiment simple (juste un fichier main.go et go.mod suffisent). À mesure que votre projet évolue, assurez-vous que votre structure de code est bonne, sinon vous vous retrouverez avec un code désordonné contenant beaucoup de dépendances cachées et d'état global. Lorsque davantage de personnes s'impliquent dans le projet, vous avez besoin d'une approche plus structurée. Dans ce cas, il est important d'introduire une façon commune de gérer les packages/bibliothèques. Lorsque vous avez un projet open-source ou que vous savez que d'autres projets importent du code à partir de votre dépôt de projet, il est important d'avoir des packages et du code privés (également appelés internes). Clônez le dépôt, gardez les parties dont vous avez besoin et supprimez tout le reste ! Juste parce que cela existe ne signifie pas que vous devez tout utiliser. Aucun de ces modèles n'est utilisé dans chaque projet. Même le modèle vendeur n'est pas universel.

Cette mise en page de projet est intentionnellement conçue pour être très générale et ne tente pas d'imposer une structure spécifique de package Go.

Spécification du répertoire de projet Go

Ci-dessous se trouve la spécification recommandée du répertoire de projet Go.

.
├── go.mod
├── api
├── assets
├── build
├── cmd
├── configs
├── deployments
├── docs
├── examples
├── githooks
├── go.mod
├── init
├── internal
├── pkg
├── scripts
├── test
├── third_party
├── tools
├── vendor
├── web
└── website

Les significations de chaque répertoire sont présentées ci-dessous.

/cmd

Les applications principales du projet, c'est-à-dire, le point d'entrée des programmes. Les fichiers Go dans ce répertoire génèrent généralement des fichiers exécutables. Dans un projet simple, un fichier comme /test/main.go peut servir de point d'entrée.

Le nom du répertoire pour chaque application devrait correspondre au nom du fichier exécutable souhaité (par exemple, /cmd/myapp).

Ne mettez pas trop de code dans le répertoire de l'application. Si vous pensez que le code peut être importé et utilisé dans d'autres projets, placez-le 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 le code dans le répertoire /internal. Vous serez surpris du comportement des autres, alors exprimez clairement vos intentions !

Il y a généralement une petite fonction main qui importe et appelle le code des répertoires /internal et /pkg, et rien d'autre.

/internal

Code d'application et de bibliothèque privé. Il s'agit du code que vous ne voulez pas que d'autres importent dans leurs applications ou bibliothèques. Notez que ce schéma de mise en page est imposé par le compilateur Go lui-même. Pour plus d'informations détaillées, veuillez vous référer aux notes de publication de Go 1.4. À noter qu'il n'est pas limité au répertoire internal de niveau supérieur. Vous pouvez avoir de multiples répertoires internal à n'importe quel niveau de l'arborescence du projet.

Vous pouvez choisir d'ajouter une structure supplémentaire pour les packages internes afin de distinguer entre le code interne partagé et non partagé. Ce n'est pas obligatoire (surtout pour les projets plus petits), mais montrer visuellement l'utilisation prévue des packages est une bonne pratique. Votre code d'application réel peut être placé dans le répertoire /internal/app (par exemple, /internal/app/myapp), et le code partagé pour ces applications peut être placé dans le répertoire /internal/pkg (par exemple, /internal/pkg/myprivlib).

/pkg

Code de bibliothèque pouvant être utilisé par des applications externes (par exemple, /pkg/mypubliclib). D'autres projets importeront ces bibliothèques et s'attendront à ce qu'elles fonctionnent correctement, alors réfléchissez bien avant de mettre du contenu ici :-) Notez que le répertoire internal est un meilleur moyen de garantir que les packages privés ne peuvent pas être importés, car cela est imposé par Go lui-même. Le répertoire /pkg reste tout de même un bon moyen d'indiquer explicitement que le code dans ce répertoire est sûr pour les autres à utiliser.

Si votre projet d'application est très petit et que l'imbrication à plusieurs niveaux n'ajoute pas beaucoup de valeur, il n'est pas non plus obligatoire de l'utiliser (à moins que vous ne le vouliez vraiment :-)). Lorsque le projet devient assez large et que le répertoire racine devient très chargé, envisagez de l'utiliser (surtout si vous avez de nombreux composants d'application non-Go).

/vendor

Dépendances de l'application (gérées manuellement ou en utilisant votre outil de gestion de dépendances préféré, tel que la fonctionnalité intégrée Go Modules). La commande go mod vendor créera le répertoire /vendor pour vous. Notez que si vous n'utilisez pas la version par défaut activée de Go 1.14, vous devrez peut-être ajouter le drapeau -mod=vendor à la commande go build.

Si vous construisez une bibliothèque, veuillez ne pas inclure vos dépendances d'application.

Répertoires de l'Application de Service

/api

Spécifications OpenAPI/Swagger, fichiers de schéma JSON, fichiers de définition de protocole et répertoires de protocoles API.

Répertoires de l'Application Web

/web

Composants spécifiques pour les applications web : actifs de site web statiques, modèles côté serveur et applications monopage (SPA).

Répertoires Généraux de l'Application

/configs

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

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

/init

Initialisation système (systemd, upstart, sysv) et configurations de gestionnaire/processus (runit, supervisord).

/scripts

Scripts pour diverses opérations de construction, d'installation, d'analyse et autres.

/build

Emballage et intégration continue.

Placez les configurations et scripts de paquetage cloud (AMI), conteneur (Docker), système d'exploitation (deb, rpm, pkg) dans le répertoire /build/package.

Placez les configurations et scripts d'intégration continue (travis, circle, drone) dans le répertoire /build/ci. Veuillez noter que certains outils d'intégration continue (comme Travis CI) sont très spécifiques quant à l'emplacement de leurs fichiers de configuration. Essayez de placer les fichiers de configuration dans le répertoire /build/ci et utilisez des liens pour les connecter à l'emplacement attendu par les outils d'intégration continue (si possible).

/deployments

Configurations de déploiement et modèles pour IaaS, PaaS, systèmes et orchestration de conteneurs (docker-compose, kubernetes/helm, terraform). Veuillez noter que dans certains dépôts (surtout pour les applications déployées en utilisant Kubernetes), ce répertoire est appelé /deploy.

/test

Autres applications de test externes et données de test. Organisez le répertoire /test de la manière qui vous convient. Pour les projets plus importants, organiser les données en sous-répertoires a du sens. Par exemple, vous pouvez créer des répertoires /test/data ou /test/testdata dans /test pour que Go ignore leur contenu. Veuillez noter que Go ignore également les répertoires ou fichiers commençant par "." ou "_", offrant une plus grande flexibilité lors de la désignation de répertoires de données de test.

Autres Répertoires

/docs

Conception et documentation utilisateur (autre que les documents godoc que vous générez).

/tools

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

/examples

Exemples d'applications et/ou de bibliothèques publiques.

/third_party

Outils auxiliaires externes, code forké et autres outils utilitaires tiers (par ex. Swagger UI).

/githooks

Hooks Git.

/assets

Actifs supplémentaires (images, logos, etc.) fournis avec le dépôt.

/website

Emplacement pour stocker les données du site web du projet si vous n'utilisez pas GitHub Pages.

/src

Certains projets Go peuvent avoir un répertoire src, mais cela est généralement dû au fait que les développeurs viennent du monde Java, où c'est un modèle courant. Si possible, essayez d'éviter d'adopter ce modèle similaire à Java. Vous ne voulez vraiment pas que votre code ou projet Go ressemble à du Java :-)

Ne confondez pas le répertoire /src au niveau du projet avec le répertoire /src utilisé pour l'espace de travail Go, décrit dans How to Write Go Code. La variable d'environnement $GOPATH pointe vers votre espace de travail (actuel) (par défaut, sur les systèmes non-Windows, elle pointe vers le répertoire $HOME/go). Cet espace de travail inclut les répertoires de premier niveau /pkg, /bin, et /src. Votre projet réel sera un sous-répertoire du répertoire /src, donc si votre projet a un répertoire /src, le chemin du projet ressemblera à ceci : /some/path/to/workspace/src/your_project/src/your_code.go. Veuillez noter que depuis Go 1.11, votre projet peut être situé en dehors du GOPATH, mais cela ne signifie pas que l'adoption de ce modèle de layout est une bonne idée.