DM-ROW 接口文档

Appearance

微服务架构设计 ​

**本文引用的文件** - [lemes-cloud/pom.xml](file://lemes-cloud/pom.xml) - [lemes-business-devicemate/pom.xml](file://lemes-cloud/lemes-business-devicemate/pom.xml) - [lemes-framework/pom.xml](file://lemes-cloud/lemes-framework/pom.xml) - [lemes-framework-core/pom.xml](file://lemes-cloud/lemes-framework/lemes-framework-core/pom.xml) - [lemes-gateway/src/main/resources/bootstrap.yml](file://lemes-cloud/lemes-gateway/src/main/resources/bootstrap.yml) - [lemes-auth/src/main/resources/bootstrap.yml](file://lemes-cloud/lemes-auth/src/main/resources/bootstrap.yml) - [lemes-business-dm-common/pom.xml](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/pom.xml) - [lemes-business-dm-device/pom.xml](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/pom.xml) - [lemes-business-dm-store/pom.xml](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/pom.xml) - [lemes-business-dm-workflow/pom.xml](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/pom.xml) - [docker-compose.yml](file://lemes-cloud/src/devops/docker-compose/docker-compose.yml) - [install.sh](file://lemes-cloud/src/devops/k8s/install.sh)

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

引言 ​

本文件面向架构师与系统设计人员，系统性阐述 DeviceMate 项目的微服务架构设计，重点围绕 lemes-cloud 聚合工程的模块化组织与职责划分，包括网关、认证、框架层、公共服务以及业务服务等。文档同时解释服务拆分策略（dm-common、dm-device、dm-store、dm-workflow），并梳理 Spring Cloud 生态中的关键组件作用与集成方式，如 Nacos 服务发现与配置中心、Gateway API 网关、Sentinel 流控与熔断、Redis 缓存、OpenFeign 声明式调用等。最后提供部署拓扑、服务注册发现流程与数据流向图示，帮助读者快速理解并落地实施。

项目结构 ​

lemes-cloud 采用 Maven 多模块聚合工程，顶层 POM 定义了统一的依赖版本与构建策略，并通过 profiles 支持多环境（Nacos 地址、命名空间、组）切换。核心模块包括：

  • lemes-gateway：API 网关，负责路由、鉴权白名单、限流等
  • lemes-auth：认证服务，提供令牌签发与刷新、客户端配置等
  • lemes-framework：框架层，封装通用能力（OpenFeign、LoadBalancer、Nacos、Sentinel、Redis、Actuator 等）
  • lemes-service-common：通用公共服务
  • lemes-business-devicemate：DeviceMate 业务域，进一步细分为 dm-common、dm-device、dm-store、dm-workflow 四个子域服务

图表来源

章节来源

核心组件 ​

  • 网关（lemes-gateway）
    • 通过 Nacos 发现下游服务，配置忽略路径白名单，支持限流策略占位
    • 提供统一入口，承载鉴权前置校验与路由转发
  • 认证（lemes-auth）
    • 以 Nacos 作为注册与配置中心，暴露管理端点，提供客户端令牌有效期配置
  • 框架层（lemes-framework）
    • 封装 OpenFeign、LoadBalancer、Nacos Discovery/Config、Sentinel、Redis、Actuator、Micrometer-Prometheus 等
    • 为业务服务提供跨模块调用、服务治理与可观测性基础能力
  • 公共服务（lemes-service-common）
    • 作为通用能力下沉，被网关与业务服务复用
  • 业务服务（lemes-business-devicemate）
    • dm-common：公共业务能力（如字典、通用枚举、通用模型等）
    • dm-device：设备全生命周期管理
    • dm-store：仓储出入库、库存管理
    • dm-workflow：基于 Flowable 的工作流编排与执行

章节来源

架构总览 ​

DeviceMate 微服务架构以 Spring Cloud Alibaba 为核心，结合 Nacos、Gateway、OpenFeign、Sentinel、Redis、MyBatis-Plus 等技术栈，形成“网关 + 认证 + 框架 + 公共 + 业务”的分层设计。服务间通信以 REST 为主，配合 OpenFeign 实现声明式调用；服务治理通过 Nacos 完成注册与配置；流量治理由 Sentinel 提供限流与熔断；缓存层使用 Redis 提升读性能；数据库访问采用 MyBatis-Plus。

图表来源

详细组件分析 ​

网关（lemes-gateway）组件 ​

  • 职责
    • 统一入口、路由转发、鉴权白名单放行、限流策略（配置占位）
  • 关键配置
    • Nacos 注册与配置中心地址、命名空间、组
    • 忽略路径白名单（登录、公钥获取、OAuth、静态资源等）
    • 日志与管理端点暴露
  • 交互关系
    • 下游依赖认证服务与公共服务，以及 DeviceMate 业务域各子服务

图表来源

章节来源

认证（lemes-auth）组件 ​

  • 职责
    • 客户端令牌签发与刷新、令牌有效期配置、客户端类型管理
  • 关键配置
    • Nacos 注册信息、命名空间、组
    • 客户端 Web 与 Client 的访问令牌与刷新令牌有效期
  • 交互关系
    • 网关在鉴权阶段调用认证服务完成令牌校验

图表来源

章节来源

框架层（lemes-framework-core）组件 ​

  • 职责
    • 提供跨模块调用（OpenFeign）、负载均衡（LoadBalancer）、服务注册与配置（Nacos）、流量治理（Sentinel）、缓存（Redis/Cache）、监控（Actuator/Micrometer-Prometheus）、日志（Log4j2）等通用能力
  • 关键依赖
    • OpenFeign、LoadBalancer、Nacos Discovery/Config、Sentinel、Redis、Actuator、Prometheus、MyBatis-Plus、POI、EasyExcel、Jasypt 等

图表来源

章节来源

业务服务拆分策略 ​

  • dm-common（公共业务服务）
    • 职责：沉淀通用领域模型、枚举、工具类、通用查询与字典等
    • 边界：不包含具体业务逻辑，仅提供可复用能力
  • dm-device（设备管理服务）
    • 职责：设备档案、变更、状态流转、关联附件与文档
    • 边界：围绕设备实体的全生命周期管理
  • dm-store（仓储管理服务）
    • 职责：出入库单据、库存盘点、库位管理、批次与序列号追踪
    • 边界：仓储作业与库存准确性保障
  • dm-workflow（工作流服务）
    • 职责：流程建模、任务分配、审批与回退、流程监控
    • 边界：以 Flowable 为核心的流程编排与执行

图表来源

章节来源

服务间通信机制与治理 ​

  • 通信机制
    • RESTful API：服务间主要通信方式
    • OpenFeign：声明式 HTTP 客户端，简化远程调用
  • 负载均衡
    • Spring Cloud LoadBalancer：客户端负载均衡，结合 Nacos 服务发现
  • 熔断与限流
    • Sentinel：提供流量控制、熔断降级、系统负载保护
  • 分布式事务
    • 当前框架层未显式引入分布式事务组件，建议在跨服务一致性要求高的场景采用 Saga 或 TCC 模式，并结合事件驱动与幂等设计

图表来源

章节来源

依赖分析 ​

  • 版本与依赖管理
    • 顶层 POM 使用 dependencyManagement 统一管理 Spring Cloud、Spring Boot、Spring Cloud Alibaba、MyBatis-Plus、Hutool、FastJSON、Guava、POI、EasyExcel、Jasypt、Nacos 等版本
    • 业务与框架模块继承父 POM，避免版本冲突
  • 环境与配置
    • 通过 Maven Profiles 切换不同 Nacos 环境（地址、命名空间、组），便于多环境部署与运维

图表来源

章节来源

性能考虑 ​

  • 缓存策略
    • 使用 Redis 作为缓存层，优先缓存热点数据与只读列表，结合 Spring Cache 简化使用
  • 数据库优化
    • MyBatis-Plus 提供高效 ORM 能力，建议对高频查询建立合适索引，避免 N+1 查询
  • 网关与限流
    • Gateway 可结合 Sentinel 对热点接口与全局请求进行限流，防止雪崩
  • 负载均衡
    • 使用 LoadBalancer 均衡流量，结合健康检查与权重配置提升可用性
  • 监控与可观测性
    • Actuator + Micrometer + Prometheus 提供指标采集，结合 Grafana/Alertmanager 实现告警与可视化

故障排查指南 ​

  • 网关问题
    • 检查忽略路径配置是否正确，确认白名单路径是否被错误拦截
    • 查看网关日志与管理端点输出，定位路由与鉴权异常
  • 认证问题
    • 核对 Nacos 配置中心中的客户端令牌有效期与命名空间
    • 确认网关调用认证服务的连通性与超时设置
  • 服务发现与配置
    • 确认 Nacos 地址、命名空间、组配置正确，服务实例健康状态正常
  • 框架层问题
    • 检查 OpenFeign、Sentinel、Redis、Actuator 等依赖是否启用且版本兼容
  • 日志与监控
    • 通过日志文件与管理端点收集上下文信息，结合 Prometheus 指标定位性能瓶颈

章节来源

结论 ​

DeviceMate 的微服务架构以 lemes-cloud 为聚合核心，通过清晰的分层与模块化设计实现了高内聚、低耦合的服务组织。借助 Spring Cloud Alibaba 技术栈，系统具备完善的注册与配置、流量治理、缓存与监控能力。业务域内的 dm-common、dm-device、dm-store、dm-workflow 明确分工，既保证了通用能力的复用，也确保了各子域的独立演进。建议在后续实践中完善分布式事务与事件驱动机制，持续优化缓存与数据库性能，并加强灰度发布与自动化运维能力。

附录 ​

部署拓扑图（Docker Compose） ​

图表来源

章节来源

Kubernetes 安装脚本要点 ​

  • 系统初始化：关闭防火墙、SELinux、交换分区，配置 yum 源与内核参数
  • 安装 Docker 与 kubelet、kubeadm、kubectl，并拉取所需镜像
  • 该脚本用于本地或测试环境快速搭建 K8s 集群，便于后续部署微服务

章节来源