# macrozheng/mall-swarm architecture

> Architecture diagram of the GitHub repository macrozheng/mall-swarm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/macrozheng/mall-swarm
- Repository: https://github.com/macrozheng/mall-swarm

## Overview

##### 识别项目类型和目的
- 这是一个基于 Spring Cloud 2023 + Alibaba 微服务架构的电商平台（mall-swarm），包含注册中心、配置中心、API 网关、监控中心、认证中心和若干业务微服务（admin、portal、search、auth、monitor、demo）。
- 主要面向“前台商城 + 后台管理 + 搜索 + 认证 + 监控”全链路电商场景。

##### 文件结构分析
- 顶层 pom.xml：父工程聚合模块。
- config：Nacos 配置中心存储。
- mall-common：通用工具/公共 DTO、异常、Redis 服务等。
- mall-mbg：MyBatis Generator 生成的模型 & DAO。
- mall-auth：统一认证中心（Spring Security/OAuth2 + Sa-Token）。
- mall-gateway：Spring Cloud Gateway 实现的 API 网关。
- mall-monitor：基于 Spring Boot Admin 的监控中心。
- mall-admin：后台管理系统业务服务。
- mall-search：Elasticsearch 搜索服务。
- mall-portal：移动端/PC 端商城服务，包含 RabbitMQ、定时任务、支付、购物车、订单等。
- mall-demo：用于远程调用测试的示例服务。

##### README 中的架构洞察
- 系统架构图（document/resource/mall_micro_service_arch.jpg）展示了服务注册、配置、网关、各业务微服务、数据库、缓存、MQ、对象存储、ES、Logstash/Kibana 日志系统、容器编排等全景。
- 业务架构图（document/resource/re_mall_business_arch.jpg）展示了电商各业务边界。

##### 画系统设计图的步骤
a. 划分主要组件
- 基础设施层：Nacos 注册 & 配置中心、Docker/Kubernetes、监控（Prometheus + Spring Boot Admin）、日志收集（Logstash + Kibana）。
- 网关层：API Gateway（mall-gateway），统一鉴权、路由、限流、CORS 等。
- 认证层：认证中心（mall-auth）。
- 公共模块：mall-common、mall-mbg（代码生成 & 公共 DTO/Mapper）。
- 业务微服务：mall-admin、mall-portal、mall-search、mall-demo。
- 监控层：mall-monitor。
- 外部依赖：MySQL、Redis、MongoDB、Elasticsearch、RabbitMQ、OSS/MinIO、Seata（分布式事务）、外部支付（支付宝）。

b. 组件之间的关系和交互
- 客户端（后台 Vue 管理系统 & 前台 uni-app/vue APP）→ API Gateway → 各业务微服务。
- Gateway 调用前先向 mall-auth 验证 Token（Sa-Token + OAuth2）。
- 业务微服务内部通过 Feign/Ribbon 调用、或通过 MQ（RabbitMQ）异步通信（如订单超时取消）。
- 微服务直接读写自己的数据库（MySQL）和缓存（Redis），mall-search 同步商品数据到 ES。
- 对象存储：mall-admin 和 mall-portal 使用 MinIO/OSS 上传与下载文件。
- 监控：所有微服务注册到 Spring Boot Admin（mall-monitor），日志通过 Logstash 发送到 ES/Kibana。

c. 重要架构模式与设计原则
- 微服务分层：注册中心 → 配置中心 → 网关 → 认证 → 业务服务 → 数据存储。
- API Gateway 模式 + 认证/授权聚合。
- 业务解耦：各服务独立部署，内部使用 Feign + Ribbon 调用。
- 异步消息驱动：RabbitMQ 处理订单回滚、超时取消等。
- 分布式事务（Seata，仅在必要场景）。
- 日志与监控：集中式日志收集 + 统一监控面板。

d. 关键技术栈标注
- Spring Cloud Alibaba（Nacos、Gateway、Sentinel 可选）、Spring Boot 3.2
- Sa-Token + OAuth2
- MyBatis + MBG + PageHelper
- Elasticsearch + Spring Data ES
- RabbitMQ
- Redis
- MongoDB
- Docker + Kubernetes
- Logstash + Kibana + Spring Boot Admin

##### 针对全栈微服务电商的图表定制建议
- 强调各业务服务的依赖：搜索服务同步 ES，Portal 服务发送/接收 MQ，Admin 服务依赖公共模块和 MBG 模块。
- 将配置中心、注册中心、监控、日志等基础设施放在图的上方，共同指向所有微服务。
- 在 Kubernetes 部署视图中，可用 Pods/Services/Ingress 图示，或简化为容器图标 + 服务名称。

##### 图示元素要求
- 每个组件都要有清晰标签（服务名 + 技术框架）。
- 使用有向箭头表示调用/依赖方向。
- 用颜色或形状区分：
- 灰色箱子：基础设施（Nacos、Docker/K8s、日志、监控）
- 蓝色：网关 & 认证
- 绿色：业务微服务
- 橙色：外部系统（DB、Cache、ES、MQ、OSS、第三方支付）
- 在组件旁标注交互协议（HTTP/REST、gRPC、Feign、AMQP）。

##### 细节与深度
- 在网关与业务服务之间注明鉴权流程（网关 → auth → 返回 token 验证）。
- 在 Portal 服务框里，画出 RabbitMQ 交换机、队列、消费者（CancelOrderSender → CancelOrderReceiver）。
- 标注 Seata TC/AT 协议触发点（若使用分布式事务）。
- 在搜索管道中，画出“商品上架 → MySQL → 同步到 ES → 前端搜索”。

通过以上步骤和要点，即可产出一份涵盖注册中心、配置中心、网关、认证、业务服务、数据存储、消息队列、监控与日志等核心要素的详尽系统设计图。

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        Parent("Parent Aggregator\n(pom.xml)"):::infra
        Nacos("Configuration Center\n(Nacos)"):::infra
        Docker("Docker/Kubernetes"):::infra
        ELK("Logstash + Kibana\n(ELK Logging)"):::infra
    end

    %% Platform Services
    subgraph "Platform Services"
        direction TB
        Gateway("API Gateway\n(mall-gateway)"):::gateway
        Auth("Authentication Center\n(mall-auth)"):::gateway
        Monitor("Monitoring Center\n(mall-monitor)"):::infra
    end

    %% Common Modules
    subgraph "Common Modules"
        direction TB
        Common("Common Utilities & DTOs\n(mall-common)"):::common
        MBG("MyBatis Generator Module\n(mall-mbg)"):::common
    end

    %% Business Microservices
    subgraph "Business Microservices"
        direction TB
        Admin("Backend Management Service\n(mall-admin)"):::service
        Portal("Frontend Mall Service\n(mall-portal)"):::service
        Search("Search Service\n(mall-search)"):::service
        Demo("Demo Service\n(mall-demo)"):::service
    end

    %% Data & External Systems
    subgraph "Data & External Systems"
        direction TB
        MySQL("MySQL"):::external
        Redis("Redis"):::external
        Mongo("MongoDB"):::external
        ES("Elasticsearch"):::external
        MQ("RabbitMQ"):::external
        OSS("OSS/MinIO"):::external
        Pay("External Payment\n(Alipay)"):::external
        Seata("Seata\n(Distributed TX)"):::external
    end

    %% Interactions
    Parent --> Nacos
    Parent --> Docker
    Parent --> ELK

    Nacos --> Gateway
    Nacos --> Auth
    Nacos --> Monitor
    Nacos --> Admin
    Nacos --> Portal
    Nacos --> Search
    Nacos --> Demo

    Gateway -->|REST/HTTP| Auth
    Gateway -->|REST/HTTP| Admin
    Gateway -->|REST/HTTP| Portal
    Gateway -->|REST/HTTP| Search
    Gateway -->|REST/HTTP| Demo

    Auth -->|OAuth2 Token| Gateway

    Admin -->|uses| Common
    Admin -->|uses| MBG
    Portal -->|uses| Common
    Portal -->|uses| MBG

    Admin -->|JDBC| MySQL
    Admin -->|Redis| Redis
    Admin -->|OSS API| OSS

    Portal -->|JDBC| MySQL
    Portal -->|Redis| Redis
    Portal -->|OSS API| OSS
    Portal -->|AMQP| MQ
    Portal -->|Seata| Seata
    Portal -->|Payment API| Pay

    Search -->|JDBC| MySQL
    Search -->|Sync| ES

    Demo -->|Feign| Admin

    %% Monitoring & Logging
    Admin -->|metrics/logs| Monitor
    Portal -->|metrics/logs| Monitor
    Search -->|metrics/logs| Monitor
    Demo -->|metrics/logs| Monitor

    Admin -->|logs| ELK
    Portal -->|logs| ELK
    Search -->|logs| ELK
    Demo -->|logs| ELK

    %% Click Events
    click Parent "https://github.com/macrozheng/mall-swarm/blob/master/pom.xml"
    click Nacos "https://github.com/macrozheng/mall-swarm/tree/master/config/"
    click Gateway "https://github.com/macrozheng/mall-swarm/tree/master/mall-gateway/"
    click Auth "https://github.com/macrozheng/mall-swarm/tree/master/mall-auth/"
    click Monitor "https://github.com/macrozheng/mall-swarm/tree/master/mall-monitor/"
    click Common "https://github.com/macrozheng/mall-swarm/tree/master/mall-common/"
    click MBG "https://github.com/macrozheng/mall-swarm/tree/master/mall-mbg/"
    click Admin "https://github.com/macrozheng/mall-swarm/tree/master/mall-admin/"
    click Portal "https://github.com/macrozheng/mall-swarm/tree/master/mall-portal/"
    click Search "https://github.com/macrozheng/mall-swarm/tree/master/mall-search/"
    click Demo "https://github.com/macrozheng/mall-swarm/tree/master/mall-demo/"
    click Docker "https://github.com/macrozheng/mall-swarm/tree/master/document/docker/"
    click ELK "https://github.com/macrozheng/mall-swarm/tree/master/document/elk/"
    click Monitor "https://github.com/macrozheng/mall-swarm/tree/master/document/k8s/"
    click ELK "https://github.com/macrozheng/mall-swarm/tree/master/document/elk/"
    click ELK "https://github.com/macrozheng/mall-swarm/tree/master/document/sh/"

    %% Styles
    classDef infra fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef gateway fill:#87CEEB,stroke:#333,stroke-width:1px;
    classDef service fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef common fill:#98FB98,stroke:#333,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px;
```
