Vue d’ensemble de l’architecture - nbacheng/nbcio-boot

Fichiers source

Cette page est générée à partir des fichiers source suivants :

Structure modulaire du projet

Le projet nbcio-boot adopte une architecture Maven multi-modules structurée en trois couches principales : le module de base (base), les modules métier (module) et les starters techniques. Cette organisation permet une séparation claire des responsabilités tout en facilitant la réutilisation des composants transverses.

Le module parent pom.xml:1-65 définit la configuration globale incluant Spring Boot 2.3.5.RELEASE, Spring Cloud Hoxton.SR8 et Spring Cloud Alibaba 2.2.3.RELEASE. Les six modules principaux déclarés sont : nbcio-boot-base (infrastructure), nbcio-boot-module-system (système), nbcio-boot-module-flowable (workflow), nbcio-boot-module-im (messagerie), nbcio-boot-module-demo (démonstration) et nbcio-module-estar (métier spécifique).

Le module de base nbcio-boot-base/pom.xml:1-22 se subdivise en trois sous-modules complémentaires : nbcio-boot-base-api (interfaces et contrats), nbcio-boot-base-core (implémentation centrale avec Web, WebSocket, sécurité) et nbcio-boot-base-tools (utilitaires Redis, Hutool, Commons). Cette séparation permet aux modules métier de dépendre uniquement des couches nécessaires.

Les starters techniques nbcio-boot-starter/pom.xml:1-40 fournissent des configurations prêtes à l'emploi pour les préoccupations transverses : nbcio-boot-starter-job (XXL-Job pour les tâches planifiées), nbcio-boot-starter-lock (Redisson pour les verrous distribués) et nbcio-boot-starter-rabbitmq (messagerie asynchrone). Ces starters encapsulent la complexité de configuration et exposent des abstractions simplifiées.

正在加载图表渲染器...

Points clés de l'architecture modulaire :

Isolation des couches : Le module base-core dépend de base-tools, mais les modules métier dépendent directement de base-core sans couche intermédiaire
Microservices optionnels : Les starters sont commentés par défaut dans le POM parent, indiquant une architecture monolithique prioritaire avec possibilité d'évolution microservices
Version centralisée : Toutes les versions critiques (Mybatis-Plus 3.4.3.1, Druid 1.1.22, Flowable 6.7.2) sont gérées dans les propriétés du parent

Pile technologique et dépendances

La stack technique repose sur l'écosystème Spring avec des extensions soigneusement sélectionnées pour les besoins d'une plateforme d'entreprise. Le fichier pom.xml:8-53 définit les versions de tous les composants majeurs avec une attention particulière à la compatibilité et à la sécurité.

Framework principal :

Spring Boot 2.3.5.RELEASE avec Spring Cloud Hoxton.SR8 et Spring Cloud Alibaba 2.2.3.RELEASE
Java 1.8 comme version cible, garantissant une large compatibilité d'environnement
Mybatis-Plus 3.4.3.1 pour l'ORM avec support multi-datasources via dynamic-datasource-spring-boot-starter 3.2.0

Sécurité et authentification :

Apache Shiro 1.7.1 combiné à java-jwt 3.11.0 pour l'authentification stateless
shiro-redis 3.1.0 pour la gestion distribuée des sessions
Intégration JustAuth 1.3.4 pour les connexions OAuth2 (WeChat, DingTalk)

Le module core nbcio-boot-base/nbcio-boot-base-core/pom.xml:42-98 ajoute les dépendances fondamentales : spring-boot-starter-web pour l'API REST, spring-boot-starter-websocket pour les communications temps réel, spring-boot-starter-validation pour la validation des entrées, et Quartz pour l'ordonnancement des tâches. Les pilotes de base de données supportés incluent MySQL 8.0.27, PostgreSQL 42.2.6, Oracle 11.2.0.3 et SQLServer 4.0.

Les utilitaires nbcio-boot-base/nbcio-boot-base-tools/pom.xml:22-52 fournissent Redis via spring-boot-starter-data-redis avec commons-pool2 pour le pooling des connexions, Hutool 5.3.8 pour les opérations courantes (crypto, core), et commons-beanutils 1.9.4 pour la manipulation réflexive des beans.

Technologie	Version	Usage	Justification
Spring Boot	2.3.5	Framework principal	Stabilité éprouvée, support étendu
Mybatis-Plus	3.4.3.1	ORM	Simplification SQL, pagination intégrée
Druid	1.1.22	Pool de connexions	Monitoring, protection SQL injection
Flowable	6.7.2	Moteur workflow	BPMN 2.0, intégration Spring native
Shiro + JWT	1.7.1 / 3.11.0	Sécurité	Stateless, distribuable
Redisson	3.16.1	Verrous distribués	Haute disponibilité, primitives riches
XXL-Job	2.2.0	Ordonnancement	Console d'administration, clustering
Knife4j	2.0.9	Documentation API	UI Swagger améliorée

Décisions techniques notables :

Log4j2 2.15.0 : Version mise à jour suite à la vulnérabilité critique CVE-2021-44228, démontrant une politique de sécurité proactive
Fastjson 1.2.78 : Version antérieure aux vulnérabilités récentes, nécessiterait une mise à jour vers 1.2.83+ pour une sécurité optimale
Multi-SGBD : Les quatre pilotes de base de données permettent un déploiement flexible selon l'infrastructure client

Architecture des modules métier

Module Système

Le module système nbcio-boot-module-system/pom.xml:41-127 constitue le point d'entrée principal de l'application monolithique. Il agrège toutes les dépendances métier et expose les APIs REST via spring-boot-maven-plugin configuré en mode non-microservices (skip=false).

Responsabilités principales :

Gestion des utilisateurs, rôles et permissions
Intégration des modules métier (demo, estar, im) en mode monolithique
Exposition des endpoints REST et documentation Swagger via Knife4j
Connexion aux services tiers : DingTalk SDK (taobao-sdk-java-auto), WeChat (jeewx-api 1.4.6), rapports (jimureport 1.4.0)

Entrées API et intégrations : Le module déclare des dépendances system scope vers les JARs DingTalk dans le répertoire lib/ : taobao-sdk-java-auto_1479188381469-20220210.jar et lippi-oapi-encrpt.jar. Ces bibliothèques propriétaires nécessitent une inclusion manuelle via includeSystemScope=true dans la configuration du plugin Maven.

Module Workflow (Flowable)

Le module workflow nbcio-boot-module-flowable/pom.xml:21-66 implémente le moteur de processus métier avec Flowable 6.7.2. Il maintient une indépendance stricte vis-à-vis des autres modules métier, ne dépendant que de nbcio-boot-base-core.

Architecture technique :

flowable-engine 6.7.2 avec exclusion de Mybatis natif (conflit avec Mybatis-Plus)
flowable-spring-boot-starter-basic pour l'auto-configuration Spring
fel 0.8 (Expression Language) pour l'évaluation des expressions dans les processus BPMN
xercesImpl 2.12.0 pour le parsing XML des définitions de processus

Contraintes d'intégration : Le module déclare explicitement dans les commentaires que les starters cloud et job doivent être commentés en mode monolithique. Cette architecture permet au module d'être utilisé indifféremment dans une application monolithique (via nbcio-boot-module-system) ou potentiellement en microservice.

Module Messagerie Instantanée (IM)

Le module IM nbcio-boot-module-im/pom.xml:24-53 fournit les fonctionnalités de chat en temps réel basées sur une architecture WebSocket haute performance.

Stack technique :

tio-websocket-server 3.7.0.v20201010-RELEASE : Serveur WebSocket haute performance maintenu par le projet t-io
jedis 4.1.1 : Client Redis pour la distribution des messages et le stockage des sessions
hutool-all 5.7.22 : Utilitaires pour la sérialisation et le traitement des messages
spring-data-redis 2.6.1 : Intégration Spring pour les opérations Redis

Modèle de communication : L'architecture repose sur t-io pour la gestion des connexions WebSocket persistantes avec Redis comme couche de distribution pour supporter le clustering horizontal. Les messages sont sérialisés et persistés dans Redis pour permettre la récupération d'historique et la synchronisation multi-instances.

正在加载图表渲染器...

Points d'interaction critiques :

Authentification WebSocket : Les connexions WebSocket doivent être authentifiées via le même mécanisme JWT que les APIs REST
Synchronisation Redis : Les messages de chat sont distribués via pub/sub Redis pour supporter plusieurs instances du serveur
Isolation Flowable : Le moteur de workflow utilise son propre schéma de base de données pour éviter les conflits avec les tables métier

Modèle de données et entités

Gestion des rôles départementaux

L'entité SysDepartRole implémente un modèle de rôles spécifiques par département, permettant une délégation fine des autorisations au sein de la structure organisationnelle.

Structure de données :

java
1public class SysDepartRole {
2    @TableId(type = IdType.ASSIGN_ID)
3    private String id;              // Identifiant unique distribué
4    
5    @Dict(dictTable="sys_depart", dicText="depart_name", dicCode="id")
6    private String departId;        // Référence au département
7    
8    private String roleName;        // Nom du rôle départemental
9    private String roleCode;        // Code unique pour les vérifications programmatiques
10    private String description;     // Description fonctionnelle
11    
12    @JsonFormat(timezone = "GMT+8", pattern = "yyyy-MM-dd HH:mm:ss")
13    private Date createTime;        // Horodatage de création
14    private String createBy;        // Créateur
15    private Date updateTime;        // Dernière modification
16    private String updateBy;        // Modificateur
17}

Points de conception :

L'annotation @Dict permet la traduction automatique des IDs en noms lisibles dans les interfaces
IdType.ASSIGN_ID génère des identifiants compatibles avec les systèmes distribués (algorithme snowflake)
Le format de date GMT+8 indique un déploiement cible en zone horaire chinoise

Relations utilisateurs-départements

L'entité de liaison SysUserDepart implémente une relation plusieurs-à-plusieurs entre utilisateurs et départements avec support de l'appartenance multiple.

Constructeurs surchargés :

java
1public class SysUserDepart {
2    @TableId(type = IdType.ASSIGN_ID)
3    private String id;
4    private String userId;    // Référence utilisateur
5    private String depId;     // Référence département
6    
7    // Constructeur complet pour création avec ID prédéfini
8    public SysUserDepart(String id, String userId, String depId) {
9        this.id = id;
10        this.userId = userId;
11        this.depId = depId;
12    }
13    
14    // Constructeur simplifié pour association rapide
15    public SysUserDepart(String id, String departId) {
16        this.userId = id;
17        this.depId = departId;
18    }
19}

Cas d'usage supportés :

Utilisateur appartenant à plusieurs départements (matrice projet/fonction)
Transfert inter-départements avec conservation d'historique
Requêtes optimisées via index composites sur (userId, depId)

Permissions départementales

L'entité SysDepartPermission gère les permissions spécifiques au niveau départemental, permettant d'outrepasser ou restreindre les permissions globales des rôles.

Modèle de données :

java
1public class SysDepartPermission {
2    @TableId(type = IdType.ASSIGN_ID)
3    private String id;
4    
5    private String departId;      // Département cible
6    private String permissionId;  // Permission accordée
7    private String dataRuleIds;   // Règles de filtrage des données
8    
9    public SysDepartPermission(String departId, String permissionId) {
10        this.departId = departId;
11        this.permissionId = permissionId;
12    }
13}

Mécanisme de règles de données : Le champ dataRuleIds stocke une liste d'identifiants de règles de filtrage (séparateurs à confirmer dans le code service). Ces règles permettent de restreindre l'accès aux données selon des critères dynamiques (région, hiérarchie, propriété).

Association rôle-utilisateur départemental

L'entité SysDepartRoleUser établit la liaison ternaire entre utilisateurs, rôles départementaux et le contexte départemental.

正在加载图表渲染器...

Flux d'autorisation complet :

L'utilisateur authentifié possède des rôles globaux et des appartenances départementales
Les rôles départementaux héritent des permissions du département parent
Les permissions départementales peuvent restreindre ou étendre les permissions de base
Les règles de données filtrent dynamiquement les résultats selon le contexte départemental

Points d'extension identifiés :

La hiérarchie des départements (parent_id) nécessite une propagation en cascade des permissions
Le champ data_rule_ids requiert un parser pour interpréter les règles de filtrage
L'absence de champ d'activation/suspension suggère une gestion par suppression logique (à confirmer dans les DAOs)

Flux de données et chaînes dappel critiques

Séquence d'authentification et autorisation

Le processus d'authentification combine Shiro pour la validation des credentials et JWT pour la gestion stateless des sessions. Cette architecture permet une distribution horizontale sans affinité de session.

正在加载图表渲染器...

Points critiques de la séquence :

Double validation : Le token JWT est validé cryptographiquement ET vérifié contre Redis pour supporter la révocation immédiate
Cache des rôles : Les rôles et permissions sont mis en cache Redis après la première requête pour réduire la charge base de données
Timeout session : La durée de vie du token JWT et l'expiration Redis doivent être synchronisées (configuration à confirmer dans application.yml)

Flux de création de processus workflow

L'intégration Flowable suit un pattern où le module système délègue l'exécution des processus au module flowable via des appels de service internes.

Étapes du flux :

L'utilisateur soumet un formulaire de demande via le module système
Le contrôleur valide les données et appelle le service workflow
Le service workflow démarre une instance de processus Flowable avec les variables métier
Flowable évalue les expressions BPMN (via FEL) pour déterminer le chemin d'exécution
Les tâches utilisateur sont créées et notifiées via le module IM ou les intégrations DingTalk/WeChat
Les callbacks de complétion mettent à jour les tables métier dans le module système

Gestion des erreurs :

Les erreurs Flowable sont encapsulées dans des exceptions métier personnalisées
Les transactions de base de données sont coordonnées via Spring @Transactional
Les timeouts de processus sont gérés par les timers Flowable avec escalation

Flux de messagerie temps réel

Le module IM utilise une architecture publish-subscribe avec Redis comme bus de messages pour supporter la distribution multi-instance.

Séquence d'envoi de message :

Client A envoie message via WebSocket au serveur t-io
Serveur publie le message sur le channel Redis chat:{conversationId}
Toutes les instances souscrivant au channel reçoivent le message
Chaque instance délivre le message aux clients WebSocket connectés localement
Le message est persisté dans la base de données pour l'historique

Optimisations identifiées :

Compression des messages pour réduire la bande passante Redis
Batch des acknowledgments pour réduire la charge réseau
Connection pooling t-io pour supporter des milliers de connexions simultanées

Décisions de conception et compromis

Architecture monolithique prioritaire

Le projet adopte une architecture modulaire monolithique avec une option microservices commentée dans le POM parent. Cette décision se justifie par :

Avantages :

Déploiement simplifié (un seul artifact JAR)
Transactions distribuées évitées
Latence inter-service éliminée
Debugging et tracing facilités

Compromis :

Scalabilité limitée au niveau de l'application entière
Déploiements nécessitant un redémarrage complet
Coupling fort entre modules métier

Migration microservices préparée : Les starters cloud et les APIs locales (nbcio-system-local-api) sont déjà structurés pour supporter une extraction en services indépendants. Le passage en microservices nécessiterait :

Activation des modules starter commentés
Configuration d'un registre de services (Nacos/Eureka)
Mise en place d'une API Gateway
Migration des appels locaux vers Feign/gRPC

Multi-datasource avec Druid

Le choix de dynamic-datasource-spring-boot-starter combiné à Druid répond aux besoins de :

Séparation lecture/écriture : Routage automatique vers les réplicas en lecture
Multi-tenancy : Isolation des données par client dans des schémas distincts
Monitoring : Interface Druid pour surveiller les performances SQL

Limitations connues :

Les transactions distribuées entre datasources ne sont pas supportées nativement
Le cache Mybatis doit être désactivé ou configuré par datasource
Les migrations de schéma (Flyway/Liquibase) nécessitent une configuration spéciale

Flowable vs Activiti

Le choix de Flowable 6.7.2 plutôt qu'Activiti (fork original) se justifie par :

Communauté active : Flowable maintient un rythme de release régulier
Correction de bugs : De nombreux bugs Activiti sont corrigés dans Flowable
Intégration Spring Boot : Starter officiel avec auto-configuration
Performance : Optimisations du moteur d'exécution

Risques identifiés :

Courbe d'apprentissage pour les équipes familières avec Activiti
Certains connecteurs propriétaires peuvent ne pas être compatibles
La version 6.7.2 nécessite Java 8+ (contrainte alignée avec le projet)

Sécurité Shiro + JWT

L'association Shiro pour l'authentification et JWT pour la gestion des sessions stateless offre :

Forces :

Pas de stockage de session côté serveur (scalabilité)
Tokens auto-contenus avec claims personnalisables
Shiro fournit une couche d'autorisation riche

Faiblesses atténuées :

Révocation de tokens : Résolu via validation Redis avant chaque requête
Renouvellement de token : Refresh tokens avec expiration courte
XSS/CSRF : Protection via headers HTTP-only et validation d'origine

Gestion des dépendances DingTalk

L'utilisation de JARs locaux (system scope) pour les SDK DingTalk présente des risques :

Problèmes identifiés :

Non-résolution automatique des dépendances transitives
Conflits potentiels avec les versions de bibliothèques communes
Maintenance manuelle des mises à jour de sécurité

Recommandations :

Migration vers les versions Maven Central si disponibles
Isolation dans un module dédié pour limiter l'impact
Tests de compatibilité à chaque mise à jour SDK

Configuration et démarrage

Propriétés système critiques

Le fichier pom.xml:15-53 définit les propriétés globales qui doivent être alignées avec la configuration runtime :

xml
1<properties>
2    <jeecgboot.version>3.0</jeecgboot.version>
3    <java.version>1.8</java.version>
4    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
5    <spring-cloud.version>Hoxton.SR8</spring-cloud.version>
6    <spring-cloud-alibaba.version>2.2.3.RELEASE</spring-cloud-alibaba.version>
7    <flowable.version>6.7.2</flowable.version>
8    <mysql-connector-java.version>8.0.27</mysql-connector-java.version>
9    <log4j2.version>2.15.0</log4j2.version>
10</properties>

Points d'attention :

L'encodage UTF-8 doit être respecté dans tous les fichiers de configuration
La version Java 1.8 limite l'utilisation des fonctionnalités Java 9+
La version Log4j2 2.15.0 corrige la vulnérabilité critique mais devrait être mise à jour vers 2.17.1+

Profil de build

Le module système nbcio-boot-module-system/pom.xml:129-142 configure le plugin Spring Boot Maven avec des options spécifiques :

xml
1<plugin>
2    <groupId>org.springframework.boot</groupId>
3    <artifactId>spring-boot-maven-plugin</artifactId>
4    <configuration>
5        <skip>false</skip>  <!-- Mode monolithique -->
6        <fork>true</fork>   <!-- Devtools activé -->
7        <includeSystemScope>true</includeSystemScope>  <!-- Inclusion JARs DingTalk -->
8    </configuration>
9</plugin>

Implications :

fork=true permet le rechargement à chaud en développement
includeSystemScope=true est requis pour les dépendances system scope
Le changement vers skip=true serait nécessaire pour une extraction microservices

Ordre de démarrage des modules

L'ordre de déclaration dans le POM parent pom.xml:55-65 détermine la séquence de build :

nbcio-boot-base : Infrastructure (doit être compilé en premier)
nbcio-boot-module-demo : Exemples (dépend de flowable)
nbcio-boot-module-system : Point d'entrée principal
nbcio-module-estar : Métier spécifique
nbcio-boot-module-flowable : Workflow
nbcio-boot-module-im : Messagerie

Note importante : Les starters (job, lock, rabbitmq) sont commentés et ne sont pas compilés par défaut. Leur activation nécessite de décommenter les lignes correspondantes et de gérer les dépendances transitives.

Variables d'environnement requises

Bien que non visibles dans les POMs, l'architecture suggère les variables suivantes (à confirmer dans application.yml) :

SPRING_PROFILES_ACTIVE : Profil de déploiement (dev/test/prod)
MYSQL_HOST, MYSQL_PORT, MYSQL_DATABASE : Connexion base de données
REDIS_HOST, REDIS_PORT : Cache distribué
DINGTALK_APPKEY, DINGTALK_APPSECRET : Intégration DingTalk
JWT_SECRET : Clé de signature des tokens
FLOWABLE_DATABASE_SCHEMA : Schéma dédié pour Flowable

Health checks et monitoring

Le module core inclut spring-boot-starter-actuator, suggérant les endpoints de santé suivants :

/actuator/health : État des connexions DB, Redis
/actuator/metrics : Métriques de performance
/actuator/info : Version de l'application

Ces endpoints doivent être sécurisés et exposés de manière contrôlée en production.