跳到主要内容

开发工作流

引用文件

本文引用的文件

目录​

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

引言​

本文件面向 yudao-cloud 项目的开发团队，系统化梳理 Git 工作流、Pull Request（PR）流程与代码审查标准；介绍基于 GitHub Actions 与 Jenkins 的 CI/CD 流程、自动化构建与测试、容器化部署策略；明确版本管理与发布规范；给出开发协作与问题变更流程建议；并提供开发工具链使用与常见问题排查方法，帮助团队高效、稳定地交付高质量版本。

项目结构​

yudao-cloud 采用多模块 Maven 聚合工程，顶层 POM 定义版本与构建配置，各业务模块与框架模块独立构建与打包。项目包含网关模块、系统与基础设施模块、业务模块（设备、运营、黑名单、任务、规则引擎等），以及丰富的部署与运维脚本。

Mermaid Diagram Code:

graph TB
Root["yudao-cloud 根 POM<br/>版本: 2.4.1-SNAPSHOT<br/>Java: 17+"] --> GW["yudao-gateway<br/>网关"]
Root --> SYS["yudao-module-system<br/>系统模块"]
Root --> INFRA["yudao-module-infra<br/>基础设施模块"]
Root --> DEV["yudao-module-device<br/>设备模块"]
Root --> LAUNCH["yudao-module-launcher<br/>运营模块"]
Root --> BLACK["yudao-module-blacklist<br/>黑名单模块"]
Root --> TASK["yudao-module-task<br/>任务与OTA模块"]
Root --> RULE["yudao-module-rule<br/>规则引擎模块"]
Root --> BPM["yudao-module-bpm<br/>工作流模块"]
Root --> REPORT["yudao-module-report<br/>报表模块"]

图示来源

章节来源

核心组件​

  • 网关与灰度发布：基于 Spring Cloud Gateway 的灰度负载均衡，支持按请求头版本号路由到指定实例，保障平滑发布与 A/B 测试。
  • 规则引擎（LiteFlow）：提供规则定义、缓存、业务绑定与审批流程，支持复杂条件匹配与高性能执行。
  • 数据存储与多数据源：MySQL 与 TDengine 混合存储，分别承载 OLTP 与时序/日志数据；Redis 用于缓存与消息中间件。
  • 监控与可观测性：SkyWalking Agent 注入与 Prometheus 暴露端点，结合 Nacos 配置中心与注册中心。
  • CI/CD：GitHub Actions Maven 构建矩阵（JDK 8/11/17），Jenkins 多模块构建与生产部署脚本。

章节来源

架构总览​

系统采用微服务架构，统一通过网关接入，后端服务通过 Nacos 注册与配置中心管理，流量可基于灰度发布策略进行分流。数据层采用 MySQL + TDengine 混合架构，配合 Redis 缓存与 Kafka 消息队列，实现高吞吐与低延迟。

Mermaid Diagram Code:

graph TB
User["Web/App 用户"] --> Gateway["yudao-gateway 网关"]
Device["智能终端设备"] --> Gateway
subgraph "微服务集群 (Spring Cloud Alibaba)"
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

图示来源

详细组件分析​

网关灰度发布机制​

  • 灰度负载均衡：根据请求头中的版本号筛选匹配实例，若无匹配则回退至全量实例。
  • 请求处理时序：过滤器检查 URL Scheme，调用负载均衡器选择实例，最终转发请求。

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)
Filter->>Filter : 检查 URL Scheme 是否为 grayLb
Filter->>LB : 调用 choose() 选择实例
LB->>Nacos : 获取所有可用服务实例列表 (含 metadata)
Nacos-->>LB : 返回实例列表
LB->>LB : 筛选 metadata[version] == 1.0.1 的实例
alt 存在匹配版本的实例
LB->>LB : 基于权重随机选择一个实例
else 无匹配或无版本头
LB->>LB : 在所有实例中基于权重选择
end
LB-->>Filter : 返回目标 ServiceInstance
Filter->>Instance : 转发请求
Instance-->>Client : 返回响应

图示来源

章节来源

规则引擎（LiteFlow）与业务绑定​

  • 核心实体：RuleLiteflowChainDO 定义规则链、EL 表达式、业务类型与生效状态。
  • 缓存与执行：RuleRunUtil 提供 Redis 缓存 + 分布式锁 + 数据库兜底的获取策略；DeviceTrueCmp/DeviceFalseCmp 作为匹配结果组件。
  • 业务绑定：RuleBusinessApiServiceImpl 支持绑定/解绑规则与变更详情构建，结合 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"]

图示来源

章节来源

数据存储与多数据源​

  • 多数据源常量：System 与 Task 模块通过 DataSourceConstants 定义不同数据源（默认/时序/归档等）。
  • 存储架构：业务数据走 MySQL，时序/日志走 TDengine，缓存走 Redis。

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

图示来源

章节来源

监控与可观测性​

  • SkyWalking：通过 JAVA_TOOL_OPTIONS 注入 Agent，忽略特定路径。
  • Prometheus：Infra 模块提供控制器暴露服务发现 Target 列表。

章节来源

消息队列集成​

  • Kafka：用于日志上报缓冲与业务异步解耦。黑名单模块提供 Kafka 生产者示例接口。

章节来源

依赖分析​

  • 构建与测试：Maven Surefire 插件版本管理，支持 JUnit 5；编译插件配置 Lombok 与 MapStruct 注解处理器。
  • 仓库源：配置华为云与阿里云 Maven 源，提升依赖下载速度。
  • 环境配置：Maven Profile 定义 dev/prod 环境，包含 Nacos 服务地址、命名空间、日志收集地址等。

Mermaid Diagram Code:

graph LR
POM["根 POM"] --> DepMgmt["依赖管理<br/>yudao-dependencies"]
POM --> Plugins["插件管理<br/>Surefire/Compiler/Flatten"]
POM --> Profiles["环境 Profile<br/>dev/prod"]
POM --> Repos["仓库源<br/>Huawei/Aliyun/Spring"]

图示来源

章节来源

性能考虑​

  • 规则引擎缓存策略：Redis 缓存 + 分布式锁 + 数据库兜底，降低热点规则的数据库压力。
  • 灰度发布：基于版本头的实例筛选与权重选择，避免全量切换带来的风险与抖动。
  • 多数据源：将高频写入的设备日志与运行记录下沉至 TDengine，减轻 MySQL 压力。
  • 监控与日志：SkyWalking 与 Prometheus 结合，便于定位性能瓶颈与异常。

[本节为通用指导，无需列出具体文件来源]

故障排查指南​

  • 网关灰度不生效：确认请求头是否携带版本号，检查 GrayLoadBalancer 的实例筛选逻辑与 Nacos 元数据配置。
  • 规则引擎匹配异常：核对 RuleLiteflowChainDO 的 EL 表达式与业务绑定状态，检查 Redis 缓存是否命中或存在空值占位。
  • Kafka 消息堆积：检查消费者消费速率与分区数，确认 Kafdrop UI 的主题状态与消费者组偏移。
  • 定时任务执行异常：参考 deploy/readme.md 中的任务计划，核对 Quartz/XXL-Job 配置与日志输出。

章节来源

结论​

yudao-cloud 项目通过清晰的模块化设计、灰度发布与规则引擎能力、混合存储架构与可观测性体系，构建了可扩展、可演进的微服务开发框架。结合 GitHub Actions 与 Jenkins 的 CI/CD 流水线，能够稳定地支持多 JDK 版本构建与多模块部署。建议团队在日常开发中严格遵循 Git 工作流与 PR 审查规范，确保代码质量与发布节奏可控。

[本节为总结性内容，无需列出具体文件来源]

附录​

Git 工作流与分支管理​

  • 主分支保护：master 作为受保护分支，禁止直接推送，所有改动通过 Pull Request 合并。
  • 功能分支：feature/<issue-id>-短横线命名，合并后清理。
  • 热修复分支：hotfix/<issue-id>-短横线命名，从 release 或 master 派生，修复后回并至 master 与 develop。
  • 发布分支：release/<版本号>，冻结发布内容，执行回归测试与最终修复。

[本节为通用规范说明，无需列出具体文件来源]

Pull Request 流程与代码审查标准​

  • PR 描述：包含需求背景、变更内容、影响范围、测试要点与风险评估。
  • 审查清单：代码风格、单元测试覆盖率、安全与性能影响、兼容性与回归测试。
  • 合并策略：至少一名审查者批准，冲突解决后方可合并。

[本节为通用规范说明，无需列出具体文件来源]

持续集成/持续部署（CI/CD）​

  • GitHub Actions：使用 Maven 构建矩阵，覆盖 JDK 8/11/17，跳过测试加速构建。
  • Jenkins：多模块构建脚本支持框架组件、模块 API、模块 Biz 与网关的分阶段构建与 Docker 镜像构建、推送与回滚；生产部署脚本支持远程拉取镜像、容器重启与参数注入。

Mermaid Diagram Code:

sequenceDiagram
participant Dev as 开发者
participant GH as GitHub Actions
participant JTB as Jenkins 构建
participant JPD as Jenkins 生产部署
participant Registry as Docker 镜像仓库
Dev->>GH : 推送代码触发 Maven 构建
GH-->>Dev : 构建报告
Dev->>JTB : 触发多模块构建
JTB->>Registry : 构建并推送镜像
JTB-->>Dev : 构建完成
Dev->>JPD : 触发生产部署
JPD->>JPD : 远程停止/删除容器
JPD->>Registry : 拉取最新镜像
JPD->>JPD : 启动新容器并注入参数
JPD-->>Dev : 部署完成

图示来源

章节来源

版本管理与发布流程​

  • 语义化版本：遵循主.次.修订，里程碑版本打 Tag 推送。
  • 标签管理：发布前在 master 上创建 vX.Y.Z 标签，确保构建产物与标签一致。
  • 发布流程：完成 PR 合并、CI 构建、镜像推送与生产部署，最后在 Issue/变更日志中标注版本与链接。

[本节为通用规范说明，无需列出具体文件来源]

开发协作规范​

  • 任务分配：通过 Issue 指派给责任人，明确截止时间与验收标准。
  • 进度跟踪：使用项目看板（白板/看板工具）可视化任务状态。
  • 沟通机制：日常站会、评审会与复盘会，重大决策形成会议纪要。

[本节为通用规范说明，无需列出具体文件来源]

问题管理与需求变更流程​

  • 问题登记：Issue 模板标准化，包含重现步骤、期望结果、实际结果与日志。
  • 变更评审：需求变更提交变更请求，评估影响与成本，经评审通过后纳入迭代。
  • 回归验证：修复完成后在测试环境验证，通过后合并至主分支。

[本节为通用规范说明，无需列出具体文件来源]

开发工具链与环境​

  • 环境准备：JDK 17+、MySQL 8.0+、Redis 5.0+、Nacos 2.x、TDengine、Kafka。
  • 启动方式：根目录 Maven 构建后，分别启动网关与各业务模块；或使用 Docker Compose 一键启动。
  • 端口与文档：各模块默认端口与接口文档地址见项目说明。

章节来源

任务与 OTA 数据模型示例​

  • UotaDetailDO：展示 OTA 升级包元数据设计，体现审批流与业务数据结合。

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答