核心特性

引用文件

本文引用的文件

引言

本文件聚焦 yudao-cloud 的核心特性，围绕微服务架构设计、网关灰度发布机制、规则引擎（LiteFlow）、多数据源混合存储（MySQL + TDengine）、统一异常处理、代码生成器、日志监控体系等主题，系统阐述实现原理、使用场景与业务价值，并给出特性间的协作关系与最佳实践建议，帮助开发者高效落地与演进。

项目结构

yudao-cloud 采用模块化多模块聚合工程，顶层 POM 定义了核心模块与依赖管理；各业务模块（如 system、infra、device、launcher、blacklist、task、rule 等）独立构建与部署，网关模块统一对外提供路由与灰度能力。

Mermaid Diagram Code:

graph TB
Root["yudao-cloud 根工程<br/>聚合模块与依赖管理"]
GW["yudao-gateway<br/>网关服务"]
SYS["yudao-module-system<br/>系统基础模块"]
INFRA["yudao-module-infra<br/>基础设施模块"]
DEVICE["yudao-module-device<br/>设备管理模块"]
LAUNCHER["yudao-module-launcher<br/>Launcher运营模块"]
BLACKLIST["yudao-module-blacklist<br/>黑名单模块"]
TASK["yudao-module-task<br/>任务与OTA模块"]
RULE["yudao-module-rule<br/>规则引擎模块"]
Root --> GW
Root --> SYS
Root --> INFRA
Root --> DEVICE
Root --> LAUNCHER
Root --> BLACKLIST
Root --> TASK
Root --> RULE

图表来源

pom.xml

章节来源

核心组件

微服务架构与模块化：以 Spring Boot 3 + Spring Cloud Alibaba 为基础，模块间通过 Nacos 注册与配置中心协同。
网关灰度发布：基于 Header 版本与标签（tag）的灰度负载均衡，支持按版本/标签分流。
规则引擎（LiteFlow）：动态规则定义、缓存与业务绑定，支持审批流联动。
多数据源混合存储：MySQL 业务库 + TDengine 时序库，结合 Kafka 异步上报与归档。
统一异常处理：全局异常翻译与错误日志落库，增强可观测性。
代码生成器：一键生成后端 CRUD 与前端页面，加速研发。
日志监控体系：操作日志、API 访问日志、Prometheus 服务发现、SkyWalking 链路追踪。

章节来源

架构总览

整体采用“网关 + 微服务集群 + 中间件”的架构，网关负责路由、鉴权与灰度；服务间通过 Nacos 协同；数据层采用 MySQL 与 TDengine 双栈，Kafka 用于日志缓冲与异步解耦。

Mermaid Diagram Code:

graph TB
User["Web/App 用户"] --> Gateway["yudao-gateway 网关"]
Device["智能终端设备"] --> Gateway
subgraph "微服务集群"
Gateway --> System["yudao-system 系统服务"]
Gateway --> Infra["yudao-infra 基础服务"]
Gateway --> DeviceSvc["yudao-device 设备服务"]
Gateway --> Launcher["yudao-launcher 运营服务"]
Gateway --> Blacklist["yudao-blacklist 黑名单服务"]
Gateway --> Task["yudao-task 任务/OTA服务"]
Gateway --> Rule["yudao-rule 规则引擎"]
end
subgraph "中间件与存储"
Nacos["Nacos 注册/配置中心"]
Redis["Redis 缓存"]
MySQL["MySQL 业务库"]
TDengine["TDengine 时序库"]
Kafka["Kafka 消息队列"]
end
System -.-> Nacos
DeviceSvc -.-> TDengine
Task -.-> TDengine
Blacklist -.-> Kafka
Gateway -.-> Redis

图表来源

章节来源

详细组件分析

网关灰度发布机制

实现要点
- 自定义灰度负载均衡器：根据请求 Header 中的 version 与 tag，筛选满足条件的服务实例，再基于 Nacos 权重随机选择。
- 灰度过滤器：拦截 grayLb 协议的请求，注入自定义负载均衡器，完成实例选择与 URL 重建。
使用场景
- 新版本灰度放量、AB 实验、按区域/渠道分流。
业务价值
- 降低新版本风险，支持精细化流量治理。
配置与调用
- 客户端在请求头携带 version 与 tag，网关将请求 scheme 从 lb 切换为 grayLb 即可启用灰度。

Mermaid Diagram Code:

sequenceDiagram
participant Client as 客户端
participant Filter as GrayReactiveLoadBalancerClientFilter
participant LB as GrayLoadBalancer
participant Nacos as Nacos注册中心
participant Instance as 服务实例
Client->>Filter : 发起请求 (Header : version=1.0.1, tag=dev)
Filter->>Filter : 检查 URL Scheme 是否为 grayLb
Filter->>LB : 调用 choose() 选择实例
LB->>Nacos : 获取所有可用服务实例列表
Nacos-->>LB : 返回实例列表 (含 metadata)
LB->>LB : 筛选 metadata[version] == 1.0.1 与 tag
alt 存在匹配版本/标签的实例
LB->>LB : 基于权重随机选择一个实例
else 无匹配或无版本头
LB->>LB : 在所有实例中基于权重选择
end
LB-->>Filter : 返回目标 ServiceInstance
Filter->>Instance : 转发请求
Instance-->>Client : 返回响应

图表来源

章节来源

规则引擎（LiteFlow）

核心模型
- 规则链实体：包含规则链名称、作用域、EL 表达式、JSON 数据、业务类型、路由、命名空间、生效与审批状态等。
- 缓存传输对象：将规则详情序列化后写入 Redis，提升匹配性能。
执行组件
- 成功/失败组件：分别代表匹配成功与失败，失败时抛出运行时异常。
规则获取与缓存
- 多级策略：Redis 命中直接返回；未命中则加分布式锁，双检 Redis，再查询数据库并写入缓存或空占位，防止击穿与穿透。
业务绑定与审批
- 绑定/解绑接口接收业务类型、业务 ID、规则链 ID 与操作类型，构建变更详情并联动 BPM 审批状态。

Mermaid Diagram Code:

flowchart TD
Start["开始: getRuleDetail(ruleId)"] --> CheckParam{"ruleId 是否为空?"}
CheckParam -- 是 --> Error["抛出异常"]
CheckParam -- 否 --> QueryRedis["查询 Redis 缓存"]
QueryRedis --> CacheHit{"缓存命中?"}
CacheHit -- 是 --> CheckEmpty{"是否为空占位符?"}
CheckEmpty -- 是 --> ReturnNull["返回 null"]
CheckEmpty -- 否 --> ReturnResult["返回规则 DTO"]
CacheHit -- 否 --> AcquireLock["尝试获取分布式锁"]
AcquireLock --> LockSuccess{"获取成功?"}
LockSuccess -- 否 --> ReturnNullLock["返回 null"]
LockSuccess -- 是 --> DoubleCheckRedis["再次查询 Redis"]
DoubleCheckRedis --> DoubleHit{"缓存命中?"}
DoubleHit -- 是 --> ReturnResult
DoubleHit -- 否 --> QueryDB["查询数据库 RuleBusinessApi"]
QueryDB --> DBHit{"数据库存在?"}
DBHit -- 是 --> SetCache["写入 Redis 缓存"]
SetCache --> ReturnDBResult["返回 DB 数据"]
DBHit -- 否 --> SetEmptyCache["写入防穿透空值"]
SetEmptyCache --> ReturnNullDB["返回 null"]

图表来源

RuleRunUtil.java

Mermaid Diagram Code:

classDiagram
class RuleLiteflowChainDO {
+Long id
+String applicationName
+String name
+String chainName
+Integer scope
+String elData
+String jsonData
+Integer businessType
+String route
+String namespace
+Integer enable
+Integer valid
}
class RuleLiteflowChainCacheDTO {
+Long id
+String chainName
+String elData
+String jsonData
+Integer businessType
+String route
+Integer enable
+Integer valid
}
class DeviceTrueCmp {
+execute() void
}
class DeviceFalseCmp {
+execute() void
}
RuleLiteflowChainDO --> RuleLiteflowChainCacheDTO : "缓存序列化"
RuleLiteflowChainCacheDTO --> DeviceTrueCmp : "匹配成功"
RuleLiteflowChainCacheDTO --> DeviceFalseCmp : "匹配失败"

图表来源

章节来源

多数据源混合存储（MySQL + TDengine）

设计思路
- 业务主库：MySQL，承载核心业务数据。
- 时序/日志库：TDengine，承载设备心跳、运行记录、访问量等高吞吐写入场景。
- Kafka：异步缓冲与解耦，承接设备侧上报。
数据源常量
- System 模块：DEFAULT/master、TD_API_VISIT（API 访问量分钟级）。
- Task 模块：DEFAULT/master、APP_ACTIVITY、TD_ENGINE_*（日活/运行记录/归档）。
- Device 模块：DEFAULT/master、APP_INSTALL。
数据流
- 设备侧上报经网关进入 Task/Device 服务，写入 TDengine 或 MySQL，部分数据归档至 TDengine 归档库。

Mermaid Diagram Code:

graph TD
subgraph "业务数据 (OLTP)"
App["业务应用"] --> |CRUD| MySQL["MySQL 8.0+"]
end
subgraph "时序/日志数据 (OLAP)"
Device["设备端"] --> |心跳/日志| Gateway["网关"]
Gateway --> |转发| TaskSvc["Task/Device 服务"]
TaskSvc --> |写入| TDengine["TDengine 时序库"]
TaskSvc --> |归档| TDArchive["TDengine 归档库"]
end
subgraph "缓存层"
Service --> |Cache| Redis["Redis 5.0+"]
end

图表来源

章节来源

统一异常处理

能力概述
- 全局异常翻译：将各类异常转换为统一的 CommonResult 返回码与消息。
- 特殊场景处理：针对“表不存在”等特定异常，自动提示对应模块的开启指引与文档地址。
- 异常日志落库：异步记录 API 错误日志，便于定位问题。
使用场景
- 参数缺失/类型错误、权限不足、业务异常、未知异常等。
业务价值
- 规范错误输出、降低前后端沟通成本、提升可观测性。

Mermaid Diagram Code:

sequenceDiagram
participant User as 用户/前端
participant Handler as GlobalExceptionHandler
participant Logger as Slf4j Logger
participant ErrorLog as 错误日志API
User->>Handler : 发起请求 (访问未开启模块)
Handler->>Handler : 捕获异常 (Check Message)
alt 模块未开启 (如 : message contains "ai_")
Handler->>Logger : Log Error (AI 大模型...表结构未导入)
Handler->>ErrorLog : 异步记录错误日志
Handler-->>User : Return CommonResult.error (501 NOT_IMPLEMENTED)
else 其他异常
Handler->>ErrorLog : 异步记录错误日志
Handler-->>User : Return Standard Error
end

图表来源

GlobalExceptionHandler.java

章节来源

代码生成器

能力概述
- 自动生成后端 CRUD 代码（Controller/Service/Mapper/DO/VO）与前端页面（Vue2/Vue3），配套菜单与 SQL。
使用场景
- 快速搭建 CRUD 页面与接口，减少重复劳动。
业务价值
- 提升研发效率，保证代码风格与规范一致。

章节来源

README.md

日志监控体系

操作日志（Operate Log）
- 记录用户关键业务操作，字段覆盖 traceId、用户类型、模块类型、子类型、业务编号、动作明细与拓展字段。
API 访问日志（Api Access Log）
- 记录 HTTP 请求详情，字段覆盖 traceId、用户信息、应用名、请求方法/URL/参数、响应体、耗时、结果码等。
监控与可观测性
- Prometheus：通过服务发现接口暴露目标列表，供 Prometheus 抓取。
- SkyWalking：容器内注入 Agent，忽略特定路径，统一链路追踪。
Kafka：黑名单模块等场景用于异步回调事件发送。

Mermaid Diagram Code:

classDiagram
class OperateLogDO {
+String traceId
+Long userId
+Integer userType
+String type
+String subType
+Long bizId
+String action
+String extra
}
class ApiAccessLogDO {
+Long id
+String traceId
+Long userId
+Integer userType
+String applicationName
+String requestMethod
+String requestUrl
+String requestParams
+String responseBody
+LocalDateTime beginTime
+Integer duration
+Integer resultCode
}

图表来源

章节来源

任务与 OTA（数据模型示例）

示例实体：UotaDetailDO，体现升级包元数据、文件关联、有效性与草稿数据等字段，配合 BPM 审批流使用。
业务价值：统一管理升级包生命周期，支持审批与灰度发布联动。

章节来源

UotaDetailDO.java

依赖分析

模块依赖
- 网关依赖各业务模块；业务模块之间低耦合，通过 Nacos 与配置中心协同。
外部依赖
- 中间件：Nacos、Redis、MySQL、TDengine、Kafka。
- 监控：Prometheus、SkyWalking。
配置管理
- 加载顺序：公共配置 → 数据源 → 环境配置 → 应用级 Nacos 配置；命名空间 dev_v2。

Mermaid Diagram Code:

graph TB
GW["yudao-gateway"] --> SYS["yudao-module-system"]
GW --> INFRA["yudao-module-infra"]
GW --> DEVICE["yudao-module-device"]
GW --> LAUNCHER["yudao-module-launcher"]
GW --> BLACKLIST["yudao-module-blacklist"]
GW --> TASK["yudao-module-task"]
GW --> RULE["yudao-module-rule"]
SYS --> Nacos["Nacos"]
INFRA --> Nacos
DEVICE --> Nacos
LAUNCHER --> Nacos
BLACKLIST --> Nacos
TASK --> Nacos
RULE --> Nacos
SYS --> MySQL["MySQL"]
DEVICE --> TDengine["TDengine"]
TASK --> TDengine
BLACKLIST --> Kafka["Kafka"]
GW --> Redis["Redis"]

图表来源

章节来源

性能考虑

灰度发布
- 基于 Header 的版本/标签筛选与 Nacos 权重选择，避免全量切换风险；建议合理设置权重与标签，结合监控指标评估。
规则引擎
- Redis 缓存 + 分布式锁 + 双检策略，降低数据库压力；建议对热点规则设置合理的 TTL 与预热。
多数据源
- MySQL 用于事务一致性，TDengine 用于高吞吐写入；建议按业务场景选择合适的数据源，避免跨库事务。
异常处理
- 异步记录错误日志，避免阻塞主线程；建议对高频异常进行采样与降噪。
监控
- Prometheus + SkyWalking 结合，建议设置关键指标阈值与告警；对网关与核心服务增加熔断与限流策略。

故障排查指南

网关灰度不生效
- 检查请求头是否包含 version 与 tag；确认网关过滤器是否启用 grayLb 协议；核对 Nacos 实例 metadata 中的版本/标签配置。
规则不匹配
- 检查规则链 enable/valid 状态；确认 Redis 缓存是否命中；查看失败组件是否触发异常。
数据写入异常
- 检查 TDengine/Kafka 连通性与权限；核对数据源配置与表结构；关注归档任务状态。
异常提示“模块未开启”
- 根据异常提示导入对应模块的表结构或开启相应功能；参考文档地址进行配置。

章节来源

结论

yudao-cloud 通过网关灰度、规则引擎、多数据源混合存储、统一异常处理与日志监控等核心能力，构建了面向 IoT 场景的高可用、可观测、可演进的微服务体系。建议在实践中遵循模块化设计、数据源分层、灰度优先与可观测性优先的原则，持续优化性能与稳定性。

附录

端口与配置示例
- System/BPM/Device/Blacklist/Launcher 等模块默认端口可在对应模块的 application.yaml 中查看。
文档与资源
- 系统设计、对接文档、数据分析、黑名单机制、设备接入等文档资源详见 README 中的文档索引。

章节来源

目录​

引言​

项目结构​

核心组件​

架构总览​

详细组件分析​

网关灰度发布机制​

规则引擎（LiteFlow）​

多数据源混合存储（MySQL + TDengine）​

统一异常处理​

代码生成器​

日志监控体系​

任务与 OTA（数据模型示例）​

依赖分析​

性能考虑​

故障排查指南​

结论​

附录​

目录

引言

项目结构

核心组件

架构总览

详细组件分析

网关灰度发布机制

规则引擎（LiteFlow）

多数据源混合存储（MySQL + TDengine）

统一异常处理

代码生成器

日志监控体系

任务与 OTA（数据模型示例）

依赖分析

性能考虑

故障排查指南

结论

附录