Ce starter vous permet de facilement démarrer le développement d'une application Expressjs basée sur le générateur d'applicatopn express-generator.
- Installation
- Structure de fichiers
- Liste des modules preconiser
- Externalisation de la configuration
Obligatoire
- Presentation of the application and delivery
Obligatoire
- Integration continue
- Developper une nouvelle API
- Cross origin
- Tests unitaires
- Swagger
- Logger
- Visual Studio Code
Vous devez modifier la registry de votre configuration npm pour pointer sur le repository npm proto
npm config set registry http://nexus3.dev.fr.proto.com/repository/npm_all/
Télécharger les sources du starter-express au format zip que vous décompresserez dans votre répertoire applicatif. Puis installez les packages node:
Remarque
Si vous allez utiliser la dépendance couchbase
, installez d'abord cette dépendance
npm install couchbase --save
puis installez les dépendances du Starter en tapant la commande ci-dessous:
# Installer les packages avec npm
npm install
starter-expressjs/
├──app/ * Répertoire des fichiers sources de l'application
│ ├──database/ * Répertoire des fichiers de connexion a la base de données
│ │ └──connection.js * Fichier de connexion à la base de données
│ │
│ ├──routes/ * répertoire pour la definition des services
│ │ ├──sample-api * Exemple d'api(le découpage se fait par entité)
│ | | ├──sample-apiRouter.js * La route de notre api qui utilise le service
| │ | ├──sample-apiService.js * La partie service de l'api (partie métier)
| | | └──sample-apiSpec.js * Exemple d'implémentation des tests avec jasmine
| | |
| | └──swagger.js * Génération de la documenation swagger en utilisant soit:(swagger-jsdoc || swagger.json)
| |
| |
│ ├──utils/ * Répertoire des modules utiles
│ │ ├──swagger * Dossier de configuration du swagger
│ | ├──constantsError.js * Définition des constantes pour les erreur hors router
│ | ├──httpResponse.js * définition des message de réponse
│ │ ├──logger.js * Fichier de configuration du logger
│ │ └──validator.js * Utilisation d'express-validator pour valider les champs
│ │
│ └──config.js * Fichier de configuration principale de l'application
│
├──bin/
│ ├──httpServer.js * Création d'un serveur HTTP
│ ├──httpsServer.js * Création d'un serveur HTTPS
│ └──www * Fichier de configuration des serveurs de l'application
│
├──public/
│ └──swaggerui * répertoire pour la configuration du swagger
│
├──app.js * fichier de configuration de l'application(point d'entrée)
├──jasmine.json * configuration jasmine pour les tests unitaires
├──make-package.xml * fichier de configuration du maven-assembly
├──package.json * configuration des dépendances utilisée par npm
├──pom.xml * configuration du frontend-maven-plugin
└──synchro_version.sh * Synchronise les versions du pom.xml avec celle du package.json
Cliquer ici pour voir la liste des modules node préconier
Pour externaliser la configuration d'une application on va utiliser dotenv
, dans le starter-kit la configuration du dotenv
est dans le fichier
app/config.js
:
/**
* config.js
*/
var dotenv = require('dotenv');
var logger = require('./utils/logger');
//load configuration
dotenv.config({ path: process.env.NODEJS_CONF_PATH_APPNAME + '/config.properties' }); //"CONF_PATH=C:/Users/xfr61950010Deskto/pexpress/config.properties"
-
Le fichier
config.properties
nous permet de renseigner la configuration de l'application(endev
on le met a la racine du projet). -
Chaque application doit avoir un fichier de configuration par environnement
(qualif, prod)
stocké dans legit
de conf gitops, (bien regarder le groupe d'appartenance).
Exemple: le starter-kit appartient au groupeingenierie-dev
: (ingenierie-dev/starters/starter-express
) équivalent à (nom-du-groupe/nom-du-projet/nom-application
). -
Avant de démarrer l'application veuillez renommer, puis setter le chemin de cette configuration, en le passant à la variable d'environnement
NODEJS_CONF_PATH_APPNAME
(Exemple: pour le projet MOSS on auraNODEJS_CONF_PATH_MOSS
) -
Ne jamais livrer le fichier
config.properties
dans les sources de l'application.
Vous pouvez démarrer le serveur local.
# Démarrer le serveur
NODEJS_CONF_PATH_APPNAME=path-to-load-configuration npm start
Et accéder à l'application avec l'url http://localhost:3000/
Pour créer vos jobs, deux templates Jenkins sont à votre disposition sur http://jenkins.dev.fr.proto.com/view/Template/:
Build_NodeJS
(prend en paramètre l'url git du projet et la branche à construire)ReleaseNodeJS
(prend en paramètre l'url git du projet et la branche à construire)
Les modifications à réaliser pour adapter pom.xml
et package.json
à votre projet:
pom.xml
: Les champs à modifier sont les suivants:
<groupId>com.proto.[GROUP_ID]</groupId> <!-- Remplacer [[GROUP_ID]] par le nom de votre projet -->
<artifactId>[ARTIFACT_ID]</artifactId> <!-- Remplacer [ARTIFACT_ID] par le nom de votre projet suffixé par -front par exemple -->
<version>[VERSION]-SNAPSHOT</version> <!-- Initialiser la version à la valeur souhaitée, par exemple 0.0.1 -->
<name>[APP_NAME]</name> <!-- Indiquer le nom de votre application -->
<scm>
<connection>scm:git:git@git@gitlab.dev.fr.proto.com:XXXXXX/XXXXXX.git</connection> <!--Spécifier l'url git de votre projet-->
<developerConnection>scm:git:git@gitlab.dev.fr.proto.com:XXXXXX/XXXXXX.git</developerConnection> <!--Spécifier l'url git de votre projet-->
</scm>
package.json
: On utilise le module sync-pom-version pour synchroniser la version du pom.xml avec celle du package.json.
-
Le
README.md
de votre application doit contenir toutes les informations nécessaires de votre application.
Exemple de README.md à fournir dans les sources de votre application -
Créer une
issue
sur gitlab qui comporte les informations sur la livraison ainsi que le contenu du fichierconfig.properties
. Exemple issue à créer -
Pour plus d'information veuillez consulter cette documentation
Choisir la base de données à utiliser.Puis installer la dépendances adéquate:
npm install oracledb --save //DB Oracle
npm install pg --save //DB Postgres
npm install couchbase --save //DB Couchbase installer cette dépendance avant de faire `npm install`
npm install jdbc --save //DB Teradata
Dans la fichier config.js
on va renseigner la configuration de la base de données
├──app/
│ ├──database/
│ ├──routes/
│ ├──utils/
│ │
│ └──config.js
- Exemple de configuration pour une base Oracle:
module.exports = {
//Information to connecte to the oracle db
"database": {
"user": "NomUtilisatuer",
"password": "MotDePasse",
"connectString": "NomHote/NomDeService"
}
}
- Exemple de configuration pour une base Postgres:
module.exports = {
database: {
user: "NonUtilisateur",
database: "database",
password: "MotDePasse",
host: "host",
port: 5432
}
}
Maintenant dans le fichier app/database/connection
, on fait un import du fichier de config
├──app/
│ ├──database/
│ │ └──connection.js
│ │
│ ├──routes/
│ ├──utils/
│ └──config.js
- Exemple de fichier de connexion pour une base
Postgres
var pg = require('pg');
const config = require('./../config')
// create a config to configure both pooling behavior
// and client options
// note: all config is optional and the environment variables
// will be read if the config is not present
var pg = {
user: config.database.user, //env var: PGUSER
database: config.database.database, //env var: PGDATABASE
password: config.database.password, //env var: PGPASSWORD
host: config.database.host, // Server hosting the postgres database
port: config.database.port, //env var: PGPORT
//number of connections to use in connection pool
//0 will disable connection pooling
max: 18
//max milliseconds a client can go unused before it is removed
//from the pool and destroyed
};
module.exports = pg;
-
Ci-dessous les liens pour les autres bases
- Dans le dossier
app/routes
, on va créer les apis qui seront regroupés par entité. - Respecter la régle un service par table (ou bien par context).
- Une api peut avoir plusieurs endpoints
- Dans
app/routes/sample-api/sample-apiRouter.js
on trouve un exemple d'api qui nous renvoie le{"Hello Nodejs": "with fwk Experssjs"}
"use strict";
const express = require('express'),
HttpStatus = require('http-status-codes'),
router = express.Router();
const logger = require('./../../utils/logger'),
sample_apiService = require('./sample-apiService');
/**
* @swagger
* /:
* get:
* tags:
* - index
* description: welcome to the starter express
* produces:
* - application/json
* responses:
* 200:
* description: welcome page
* schema:
* $ref: '#/definitions/index'
*/
router.get('/sample/v1/hello', (req, res) => {
sample_apiService.message()
.then((result) => {
logger.debug(result);
res.status(HttpStatus.OK).send(result);
});
});
module.exports = router;
Pour plus d'exemple regarder le proto-express
La fonctionnalité HTTP access control (CORS) est activée.
La configuration est dans le fichier ./app.js
//CORS middleware
var allowCrossDomain = function (req, res, next) {
res.header('Access-Control-Allow-Origin', '*');
res.header('Access-Control-Allow-Methods', 'GET,PUT,POST,DELETE,PATCH,OPTIONS');
res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization, Content-Length, X-Requested-With');
next();
}
...
app.use(allowCrossDomain);
- Dans chaque entité on aura un fichier de test unitaires
app/routes/sample-api/sample-apiSpec.js
Exemple d'une spec de test:
const endpoint = 'http://localhost:3000/api/sample/v1/hello';
describe("sample-api", () => {
describe('/ GET', () => {
it('returns status code 200', (done) => {
request.get(endpoint, (error, response) => {
expect(response.statusCode).toEqual(HttpStatus.OK);
done();
});
});
});
});
- La configuration des tests est dans le fichier
jasmine.json
- Pour executer les tests
npm test
-
Dans le fichier
app/routes/swagger.js
en choisie une configuration pour générer la documentation de nos apis (en utilisant swagger-jsDoc ou bien l'editeur de swagger). -
Le dossier de configuration de swagger se trouve dans:
app/utils/swagger
-
Si on utilise pas la bibliothèque swagger-jsDoc, on pourra rédiger la documentation des APIs on utilisant l'éditeur de swagger
-
la configuration de swagger-ui se trouve dans:
public/swaggerui
. -
Pour plus d'informations consultez la documentation swagger
- Le fichier de configuration du logger se trouve dans :
app/utils/logger.js
- Pour surveiller les logs de l'application on fait un import de la configuration du logger dans le fichier
app.js
(Point d'entrée) - Setter la variable d'environnement
NODEJS_PATH_LOGS
dans le fichierconfig.properties
pour spécifier le chemin ou sauvegarder les LOGS
- Editeur de code développé par Microsoft, peut être installé sur Windows, Linux et macOS
- Téléchargement sur https://code.visualstudio.com/
Liste des plugins à rajouter:
- eslint.
- exports autocomplete, JavaScript (ES6) snippets.
- express, ExpressSnippet et Express-Lines.
- Git History, Git Project Manager et gitignore.
- jasmine code snippets.
- Node.js Assertion Snippets, Node.js Modules Intellisense, View Node Package et npm.
- JS-CSS-HTML Formatter
En suivant la Documentation officielle, une fois que vous aurez gégérer le fichier launch.json
, veuillez remplacer son sontenu par le suivant:
{
// Utilisez IntelliSense pour découvrir les attributs de débogage Node.js possibles.
// Pointez pour afficher la description des attributs existants.
// Pour plus d'informations, visitez : https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Lancer le programme",
"program": "${workspaceRoot}/bin/www",
"envFile": "${workspaceRoot}/config.properties",
"env": {
"NODE_ENV": "development",
"NODEJS_CONF_PATH_APPNAME":"."
}
}
]
}
Le envFile
nous permet de déclarer le fichier de configuration de l'application(dans cet exemple le fichier config.properties
est à la racine du projet).
Le env
nous permet de déclarer les variables d'environnement.