Le but de cet article est de montrer une application réelle que j’ai développée récemment utilisant Go, Vue.js, et Docker, et qui est en production aujourd’hui. Les tutoriels sont parfois décevants dans la mesure où ils ne traitent pas de situations réelles. J’ai donc essayé de présenter les choses un peu différemment ici. Je ne vais pas commenter l’intégralité du code car cela prendrait une éternité mais je vais expliquer la structure générale du projet, quels choix critiques j’ai fait, et pourquoi. Je vais aussi essayer de mettre en avant certains bouts de codes qui valent le coup d’être commentés.
L’intégralité du code de l’application se trouve sur mon GitHub, peut-être que vous pourriez l’ouvrir en parallèle de la lecture de cet article.
But de l’application
Cette application est dédiée à la présentation de données issues de différentes bases de données de façon user friendly. En voici les principales fonctionnalités :
- l’utilisateur doit s’identifier pour pouvoir utiliser la Single Page Application (SPA)
- l’utilisateur peut sélectionner différentes interfaces via un panneau à gauche dans le but de récupérer des données issues de plusieurs tables de bdd
- l’utilisateur peut décider de seulement compter les résultats retournés par la bdd, ou d’obtenir les résultats complets
- si les résultats retournés par la bdd sont suffisamment légers, alors ils sont retournés par l’API et affichés au sein de la SPA à l’intérieur d’un tableau de données. L’utilisateur peut aussi décider de les exporter comme CSV.
- si les résultats sont trop lourds, alors ils sont envoyés à l’utilisateur par email au sein d’une archive zippée de façon asynchrone
- comme critères de recherche, l’utilisateur peut entrer du texte ou des fichiers CSV contenant un grand nombre de critères
- certains inputs utilisateur sont des listes select dont les valeurs sont chargées dynamiquement depuis la bdd
Structure du projet et outils
Le projet est constitué de 2 conteneurs Docker:
- un conteneur pour une API backend écrite en Go. Pas besoin ici d’un serveur HTTP puisque Go possède déjà un serveur HTTP très efficace natif (net/http). Cette application expose une API RESTful afin de recueillir des requêtes depuis le frontend et de retourner les résultats renvoyés par plusieurs bdd.
- un conteneur pour une interface frontend utilisant une SPA Vue.js. Ici un serveur Nginx est nécessaire afin de servir les fichiers statiques.
Voici le Dockerfile de mon application Go :
FROM golang
VOLUME /var/log/backend
COPY src /go/src
RUN go install go_project
CMD /go/bin/go_project
EXPOSE 8000
Terriblement simple comme vous pouvez le voir. J’utilise une image Docker Golang déjà construite basée sur Debian.
Le Dockerfile de mon frontend est légèrement plus gros car j’ai besoin d’installer Nginx, mais il reste très simple malgré tout :
FROM ubuntu:xenial
RUN apt-get update && apt-get install -y \
nginx \
&& rm -rf /var/lib/apt/lists/*
COPY site.conf /etc/nginx/sites-available
RUN ln -s /etc/nginx/sites-available/site.conf /etc/nginx/sites-enabled
COPY .htpasswd /etc/nginx
COPY startup.sh /home/
RUN chmod 777 /home/startup.sh
CMD ["bash","/home/startup.sh"]
EXPOSE 9000
COPY vue_project/dist /home/html/
Le fichier startup.sh se contente de démarrer le serveur Nginx. Voici ma configuration Nginx (site.conf):
server {
listen 9000;
server_name api.example.com;
# In order to avoid favicon errors on some navigators like IE
# which would pollute Nginx logs (do use the "=")
location = /favicon.ico { access_log off; log_not_found off; }
# Static folder that Nginx must serve
location / {
root /home/html;
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
}
# robots.txt file generated on the fly
location /robots.txt {
return 200 "User-agent: *\nDisallow: /";
}
}
Comme vous pouvez le voir, l’authentification est requise pour utiliser l’appli frontend. J’ai mis cela en place via un fichier .htpasswd.
En réalité, l’utilisation de Docker pour l’application Go n’apporte pas vraiment grand chose puisque Go n’a besoin d’aucune dépendance externe une fois compilé, ce qui rend le déploiement très facile. Parfois, intégrer Go à Docker peut être utile si vous avez des fichiers à charger en plus de votre binaire Go (comme un template HTML, ou des fichiers de configuration). Ce n’est pas le cas ici mais il n’empêche que j’ai préféré utiliser Docker pour des raisons de cohérence : tous mes services tournent sous Docker et je ne veux donc pas avoir à traiter de cas particuliers.
L’application Go est constituée de plusieurs fichiers. La raison est uniquement une question de lisibilité et tout aurait pu parfaitement être placé dans un seul et même fichier. Il faut garder à l’esprit que lorsque vous découpez l’application de cette façon, vous avez des éléments à exporter (variables, strucs, fonctions,…) si vous voulez les réutiliser à travers toute l’application (en passant la première lettre en majuscule). Durant le développement vous devrez aussi utiliser go run avec une wildcard comme cela:
go run src/go_project/*.go
J’utilise quelques bibliothèques Go externes (mais tellement peu grâce à l’excellente bibliothèque standard de Go !) :
- gorilla/mux pour le routing des requêtes de l’API, en particulier pour les points d’accès nécessitant des arguments positionnels
- rs/cors pour une gestion plus facile de CORS (qui peut vite devenir un cauchemar)
- gopkg.in/gomail.v2 pour la gestion des emails, en particulier pour les pièces jointes
La structure et les outils utilisés par le frontend est beaucoup plus complexe. Voici un article dédié au sujet. En réalité cette complexité n’affecte que la partie développement parce qu’au final, une fois que tout est compilé, vous obtenez seulement des fichiers HTML/CSS/JS classiques que vous copiez collez simplement dans votre conteneur Docker.
Dev vs Prod
La configuration n’est pas la même selon que l’on est en développement ou en production. Pour le développement j’utilise une base de données répliquée localement, je logue les erreurs en console et non pas au sein d’un fichier, j’utilise des serveurs locaux, … Comment gérer tout cela de façon intégrée ?
Dans l’application Vue.js j’ai besoin de me connecter soit à un serveur d’API local pour le développement (127.0.0.1), soit à un serveur d’API de production (api.example.com). J’ai donc créé un fichier http-constants.js qui retourne soit une adresse locale, soit une adresse de production, selon que l’on a lancé npm run dev ou npm run build. Pour plus de détails, consultez cet article où j’ai déjà tout expliqué.
Au sein de l’appli Go, plusieurs paramètres changent selon que l’on est en dev ou en prod. Afin de gérer cela, j’utilise des variables d’environnement transmises à l’appli Go par Docker. Configurer son appli via des variables d’environnement est censé être une bonne pratique d’après l’appli à 12 facteurs. Premièrement nous devons initialiser ces variables d’environnement au cours de la création du conteneur grâce à l’option -e:
docker run --net my_network \
--ip 172.50.0.10 \
-p 8000:8000 \
-e "CORS_ALLOWED_ORIGIN=http://api.example.com:9000" \
-e "REMOTE_DB_HOST=10.10.10.10" \
-e "LOCAL_DB_HOST=172.50.0.1" \
-e "LOG_FILE_PATH=/var/log/backend/errors.log" \
-e "USER_EMAIL=me@example.com" \
-v /var/log/backend:/var/log/backend \
-d --name backend_v1_container myaccount/myrepo:backend_v1
Par la suite ces variables sont récupérées par le programme Go grâce à la fonction os.getenv(). Voici comment j’ai géré le tout dans main.go:
// Initialize db parameters
var localHost string = getLocalHost()
var remoteHost string = getRemoteHost()
const (
// Local DB:
localPort = 5432
localUser = "my_local_user"
localPassword = "my_local_pass"
localDbname = "my_local_db"
// Remote DB:
remotePort = 5432
remoteUser = "my_remote_user"
remotePassword = "my_remote_pass"
remoteDbname = "my_remote_db"
)
// getLogFilePath gets log file path from env var set by Docker run
func getLogFilePath() string {
envContent := os.Getenv("LOG_FILE_PATH")
return envContent
}
// getLocalHost gets local db host from env var set by Docker run.
// If no env var set, set it to localhost.
func getLocalHost() string {
envContent := os.Getenv("LOCAL_DB_HOST")
if envContent == "" {
envContent = "127.0.0.1"
}
return envContent
}
// getRemoteHost gets remote db host from env var set by Docker run.
// If no env var set, set it to localhost.
func getRemoteHost() string {
envContent := os.Getenv("REMOTE_DB_HOST")
if envContent == "" {
envContent = "127.0.0.1"
}
return envContent
}
// getRemoteHost gets remote db host from env var set by Docker run.
// If no env var set, set it to localhost.
func getCorsAllowedOrigin() string {
envContent := os.Getenv("CORS_ALLOWED_ORIGIN")
if envContent == "" {
envContent = "http://localhost:8080"
}
return envContent
}
// getUserEmail gets user email of the person who will receive the results
// from env var set by Docker run.
// If no env var set, set it to admin.
func getUserEmail() string {
envContent := os.Getenv("USER_EMAIL")
if envContent == "" {
envContent = "admin@example.com"
}
return envContent
}
Comme vous pouvez le voir, si la variable d’environnement n’est pas déclarée, on la remplace par une valeur par défaut. On peut ensuite utiliser ces fonctions dédiées partout dans le programme. Voici par exemple comment je gère la fonctionnalité de logging (loguer en console pour le développement, et loguer dans un fichier en production):
log.SetFlags(log.LstdFlags | log.Lshortfile) // add line number to logger
if logFilePath := getLogFilePath(); logFilePath != "" { // write to log file only if logFilePath is set
f, err := os.OpenFile(logFilePath, os.O_RDWR|os.O_CREATE|os.O_APPEND, 0666)
if err != nil {
log.Fatal(err)
}
defer f.Close()
log.SetOutput(f)
}
Notez que le logging implique aussi l’utilisation d’un volume partagé. En effet je veux que mes fichiers de logs soient accessibles depuis l’hôte Docker directement. C’est pourquoi j’ai ajouté -v /var/log/backend:/var/log/backend à la commande docker run ci-dessus et mis une directive VOLUME spécifique dans le Dockerfile.
Design de l’application frontend avec Vuetify.js
Je n’ai jamais été un fan du design, surtout quand il faut y passer des jours pour des petites applications telles que celle-là. C’est pourquoi j’utilise Vuetify.js qui est un super framework à utiliser par dessus Vue.js et qui vous fournit de magnifiques composants prêts à l’emploi. Vuetify utilise le material design de Google, qui a beaucoup de style je trouve.
Utilisation mémoire
J’ai dû faire face à plusieurs défis liés à la mémoire lors de la création de ce programme en raison du fait que certaines requêtes SQL peuvent parfois retourner un très grand nombre de lignes.
Côté backend Go
Les lignes retournées par la bdd sont placées dans un array de structs. Lorsque des millions de lignes sont retournées, la manipulation de cet array devient très coûteuse en termes de mémoire. La solution est de déporter autant que faire se peut la logique côté SQL plutôt que de la laisser dans votre programme Go. PostgreSQL est très performant en ce qui concerne l’optimisation des performances et dans mon cas les bases de données tournent sous PostgreSQL 10 qui améliore considérablement les performances de certaines requêtes grâce aux opérations parallèles. En plus de cela, mes bases de données ont des ressources qui leur sont dédiées donc autant en profiter.
Concernant la génération de CSV, il vous faut aussi étudier si il est préférable de stocker le CSV en mémoire ou sur le disque. Personnellement je l’écris sur le disque afin de réduire l’utilisation mémoire.
Mais malgré tout cela, j’ai aussi été contraint d’augmenter la RAM de mon serveur.
Côté frontend Vue.js
Il est clair qu’un navigateur ne peut pas se permettre d’afficher trop de contenu. Si vous cherchez à afficher un trop grand nombre de lignes au sein du navigateur, ça va planter ou faire ramer le navigateur. La première solution (qui est celle que j’ai adoptée) est d’envoyer les résultats dans une archive .zip lorsqu’un trop grand nombre de résultats est retourné par la base de données. Une autre solution pourrait être de paginer les résultats dans le navigateur et que chaque nouvelle page déclenche en fait une nouvelle requête vers la base de données afin de charger plus de résultats (ce qui nécessiterait l’utilisation de LIMIT dans votre requête SQL).
Quelques bouts de code un peu délicats
Voici certaines parties qu’il me semble intéressant de commenter soit parce qu’elles sont particulièrement piégeuses, ou tout simplement originales.
Réaliser plusieurs requêtes asynchrones avec Axios
Mon frontend contient plusieurs selects HTML et je veux que les valeurs proposées par ces listes soient chargées dynamiquement depuis l’API. Pour ce faire j’ai besoin d’utiliser axios.all() et axios.spread() afin de réaliser plusieurs appels à l’API en parallèle avec Axios. La documentation d’Axios est quelque peu erratique sur le sujet. Il est important de comprendre que vous avez 2 options :
- attraper les erreurs pour chaque requête dans
axios.all:HTTP.get('/get-countries-list').catch(...) - attraper les erreurs de façon globale après
axios.spread:.then(axios.spread(...)).catch(...)
La première option vous permet d’afficher des messages d’erreur précis selon la requête qui a généré l’erreur, mais cette option est non bloquante donc on entre malgré tout dans axios.spread() en dépit de l’erreur et certains paramètres se retrouveront undefined dans axios.spread() ce qui vous oblige à gérer cela intelligemment. Dans la deuxième option, une erreur globale est générée dès qu’au moins une des requête échoue, et nous n’entrons jamais dans axios.spread().
J’ai choisi la seconde option : si au moins une des requêtes à l’API échoue, alors toutes les requêtes s’arrêtent :
created () {
axios.all([
HTTP.get('/get-countries-list'),
HTTP.get('/get-companies-industries-list'),
HTTP.get('/get-companies-sizes-list'),
HTTP.get('/get-companies-types-list'),
HTTP.get('/get-contacts-industries-list'),
HTTP.get('/get-contacts-functions-list'),
HTTP.get('/get-contacts-levels-list')
])
// If all requests succeed
.then(axios.spread(function (
// Each response comes from the get query above
countriesResp,
companyIndustriesResp,
companySizesResp,
companyTypesResp,
contactIndustriesResp,
contactFunctionsResp,
contactLevelsResp
) {
// Put countries retrieved from API into an array available to Vue.js
this.countriesAreLoading = false
this.countries = []
for (let i = countriesResp.data.length - 1; i >= 0; i--) {
this.countries.push(countriesResp.data[i].countryName)
}
// Remove France and put it at the top for convenience
let indexOfFrance = this.countries.indexOf('France')
this.countries.splice(indexOfFrance, 1)
// Sort the data alphabetically for convenience
this.countries.sort()
this.countries.unshift('France')
// Put company industries retrieved from API into an array available to Vue.js
this.companyIndustriesAreLoading = false
this.companyIndustries = []
for (let i = companyIndustriesResp.data.length - 1; i >= 0; i--) {
this.companyIndustries.push(companyIndustriesResp.data[i].industryName)
}
this.companyIndustries.sort()
[...]
}
// bind(this) is needed in order to inject this of Vue.js (otherwise
// this would be the axios instance)
.bind(this)))
// In case one of the get request failed, stop everything and tell the user
.catch(e => {
alert('Could not load the full input lists in form.')
this.countriesAreLoading = false
this.companyIndustriesAreLoading = false
this.companySizesAreLoading = false
this.companyTypesAreLoading = false
this.contactIndustriesAreLoading = false
this.contactFunctionsAreLoading = false
this.contactLevelsAreLoading = false
})
},
Générer un CSV en javascript
Je regrette qu’il n’y ait pas de solution plus simple. Voici comment j’ai dû m’y prendre pour créer un CSV en javascript et le servir à l’utilisateur sous forme de téléchargement :
generateCSV: function () {
let csvArray = [
'data:text/csv;charset=utf-8,' +
'Company Id;' +
'Company Name;' +
'Company Domain;' +
'Company Website;' +
[...]
'Contact Update Date'
]
this.resultsRows.forEach(function (row) {
let csvRow = row['compId'] + ';' +
row['compName'] + ';' +
row['compDomain'] + ';' +
row['compWebsite'] + ';' +
[...]
row['contUpdatedOn']
csvArray.push(csvRow)
})
let csvContent = csvArray.join('\r\n')
let encodedUri = encodeURI(csvContent)
let link = document.createElement('a')
link.setAttribute('href', encodedUri)
link.setAttribute('download', 'companies_and_contacts_extracted.csv')
document.body.appendChild(link)
link.click()
}
}
Récupérer les données envoyées par Axios en Go
Les données POST envoyées par Axios sont nécessairement encodées en JSON. Malheureusement il n’y a actuellement aucun moyen de modifier ce comportement. Go possède une fonction très utile appelée PostFormValue qui se charge de récupérer facilement les données POST encodées en “form data”, mais malheureusement il ne gère pas les données encodées en JSON. J’ai donc dû faire un unmarshal JSON vers une struct afin de récupérer les données POST :
body, err := ioutil.ReadAll(r.Body)
if err != nil {
err = CustErr(err, "Cannot read request body.\nStopping here.")
log.Println(err)
http.Error(w, "Internal server error", http.StatusInternalServerError)
return
}
// Store JSON data in a userInput struct
var userInput UserInput
err = json.Unmarshal(body, &userInput)
if err != nil {
err = CustErr(err, "Cannot unmarshall json.\nStopping here.")
log.Println(err)
http.Error(w, "Internal server error", http.StatusInternalServerError)
return
}
Les fonctions “variadique” en Go
L’utilisateur peut entrer un nombre variable de critères qui seront par la suite utilisés dans une seule et même requête SQL. En gros, chaque nouveau critère est une nouvelle clause SQL WHERE. Comme nous ne connaissons pas à l’avance le nombre de paramètres qui seront passés à la fonction database/sql query(), nous devons utiliser la propriété “variadique” de la fonction query() ici. Une fonction variadique est une fonction qui accepte un nombre variable de paramètres. En Python vous utiliseriez *args or *kwargs. Ici on utilise la notation .... Le premier argument de query() est une requête SQL sous forme de texte, et le second argument est un array d’interfaces vides qui contient tous les paramètres :
rows, err := db.Query(sqlStmtStr, sqlArgs...)
if err != nil {
err = CustErr(err, "SQL query failed.\nStopping here.")
log.Println(err)
http.Error(w, "Internal server error", http.StatusInternalServerError)
return compAndContRows, err
}
defer rows.Close()
Gérer CORS
En deux mots, CORS est une mesure de sécurité qui empêche le frontend de récupérer des informations depuis un backend qui n’est pas situé à la même URL. Voici une explication bien faîte de l’importance de CORS. Afin de vous conformer à ces règles, vous devez gérer CORS comme il se doit du côté de l’API serveur. La propriété la plus importante de CORS à gérer est la propriété Allowed Origins. Il n’est pas si facile de gérer cela en Go parce que cela implique en premier lieu une requête “preflight” (utilisant l’OPTION HTTP) et en second lieu de paramétrer les headers HTTP correctement.
La meilleure solution en Go selon moi est d’utiliser la bibliothèque rs/cors nous permettant de gérer CORS comme suit :
router := mux.NewRouter()
c := cors.New(cors.Options{
AllowedOrigins: []string{"http://localhost:8080"},
})
handler := c.Handler(router)
Les valeurs NULL en Go
Lorsque vous requêtez la bdd, vous avez de grandes chances d’obtenir des valeurs NULL. Ces valeurs NULL doivent être explicitement gérées en Go, en particulier si vous voulez convertir ces résultats en JSON. Vous avez pour cela 2 solutions :
- utiliser les pointeurs pour les valeurs pouvant être NULL dans la struct qui va recevoir les valeurs. Cela fonctionne mais les valeurs NULL ne sont pas détectées par le mot-clé
'omitempty'durant le marshalling JSON ce qui fait qu’une chaîne vide sera quand même affichée dans votre JSON - utiliser les types NULL de la bibliothèque sql : remplacer
stringparsql.NullString,intparsql.NullInt64,boolparsql.NullBool, ettimeparsql.NullTime, mais alors vous obtenez quelque chose comme{"Valid":true,"String":"Smith"}, ce qui n’est pas immédiatement valide en JSON. Il faut donc ajouter quelques étapes avant de faire du marshaling JSON.
J’ai mis en place la seconde option et créé un type et une méthode custom qui implémentent le json.Marshaler. Notez que, en utilisant cette méthode, j’aurais pu transformer NULL en une chaîne vide afin qu’elle ne soit pas incluse dans le JSON final, mais ici je veux justement que les valeurs NULL soient gardées et envoyées au frontend en JSON comme null :
type JsonNullString struct {
sql.NullString
}
func (v JsonNullString) MarshalJSON() ([]byte, error) {
if v.Valid {
return json.Marshal(v.String)
} else {
return json.Marshal(nil)
}
}
type CompAndContRow struct {
CompId string `json:"compId"`
CompName JsonNullString `json:"compName"`
CompDomain JsonNullString `json:"compDomain"`
CompWebsite JsonNullString `json:"compWebsite"`
[...]
}
La concaténation de plusieurs lignes en SQL
Le SQL est un langage très vieux mais toujours très puissant aujourd’hui. Par ailleurs, PostgreSQL nous fournit des fonctions très utiles qui nous permettent de faire des tas de choses en SQL au lieu d’appliquer des scripts aux résultats (ce qui n’est pas efficace d’un point de vue mémoire/CPU). Ici j’ai un grand nombre de LEFT JOIN SQL cumulés qui retournent de nombreuses lignes similaires. Le problème est que je veux que certaines de ces lignes soient concaténées entre elles au sein d’une seule ligne. Par exemple, une entreprise peut avoir plusieurs emails et je veux que tous ces emails apparaissent au sein de la même ligne séparés par le symbole ¤. Faire cela en Go impliquerait de parcourir l’array contenant les résultats un grand nombre de fois. Dans le cas de millions de lignes ce serait fort long au point même peut-être de crasher si le serveur ne dispose pas d’assez de mémoire. Heureusement, accomplir cela avec PostgreSQL est très facile en utilisant la fonction string_agg() combinée à GROUP BY et DISTINCT :
SELECT comp.id, string_agg(DISTINCT companyemail.email,'¤')
FROM company AS comp
LEFT JOIN companyemail ON companyemail.company_id = comp.id
WHERE comp.id = $1
GROUP BY comp.id
Conclusion
J’essaye de couvrir ici un large panel de sujets au sein d’un seul et même article : Go, Vue.js, Javascript, SQL, Docker, Nginx… J’espère que vous y avez trouvez des éléments utiles que vous pourrez réutiliser dans votre propre application.
Si vous avez des question à propos de l’appli, n’hésitez pas. Et si vous pensez que certaines parties de mon code auraient pu être mieux optimisées j’adorerais avoir votre avis. Cet article est aussi une façon pour moi de recevoir des feedbacks critiques sur mon propre travail !
