Files

lzh b71558ae07 feat(ops): update cleaner status and assignment logic

2026-01-19 14:56:31 +08:00

16 KiB

Raw Blame History

开发指南

**本文引用的文件** - [pom.xml](file://pom.xml) - [lombok.config](file://lombok.config) - [Jenkinsfile](file://Jenkinsfile) - [08-开发指南.md](file://docs/technical-overview/08-开发指南.md) - [part8-测试指南.md](file://docs/ops-architecture/part8-测试指南.md) - [viewsh-framework/pom.xml](file://viewsh-framework/pom.xml) - [viewsh-dependencies/pom.xml](file://viewsh-dependencies/pom.xml) - [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml) - [docker-compose.core.yml](file://docker-compose.core.yml) - [viewsh-module-iot-server/src/main/resources/application.yaml](file://viewsh-module-iot-server/src/main/resources/application.yaml) - [viewsh-framework/viewsh-spring-boot-starter-test/pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-test/pom.xml)

简介

本开发指南面向AIOT平台云项目的开发与维护团队，目标是帮助新成员快速完成本地开发环境搭建、理解并遵循统一的代码规范与最佳实践、掌握CI/CD流水线与测试策略、以及高效地进行调试与问题排查。同时提供扩展框架组件与自定义功能的指导，确保团队协作的一致性与开发效率。

项目结构

项目采用多模块Maven聚合工程组织，顶层POM负责统一版本与插件管理；核心模块包括网关、系统服务、基础设施服务、物联网服务、作业调度、消息队列、监控与安全等。框架层提供通用starter与测试组件，便于各业务模块复用。

graph TB
A["顶层POM<br/>统一版本与插件"] --> B["viewsh-dependencies<br/>BOM依赖管理"]
A --> C["viewsh-framework<br/>通用组件与starter"]
A --> D["viewsh-gateway<br/>Spring Cloud Gateway"]
A --> E["viewsh-module-system-server<br/>系统服务"]
A --> F["viewsh-module-infra-server<br/>基础设施服务"]
A --> G["viewsh-module-iot-server<br/>物联网服务"]
A --> H["viewsh-module-iot-gateway<br/>物联网网关"]
A --> I["viewsh-module-ops-server<br/>运维服务"]
C --> C1["viewsh-spring-boot-starter-test<br/>测试组件"]
C --> C2["viewsh-spring-boot-starter-mybatis<br/>MyBatis封装"]
C --> C3["viewsh-spring-boot-starter-redis<br/>Redis封装"]
C --> C4["viewsh-spring-boot-starter-web<br/>Web封装"]
C --> C5["viewsh-spring-boot-starter-security<br/>安全封装"]
C --> C6["viewsh-spring-boot-starter-monitor<br/>监控封装"]
C --> C7["viewsh-spring-boot-starter-mq<br/>消息队列封装"]
C --> C8["viewsh-spring-boot-starter-job<br/>定时任务封装"]

图表来源

章节来源

核心组件

依赖管理与版本控制：通过BOM集中管理第三方依赖版本，确保模块间一致性。
代码生成与编译插件：统一配置Lombok、MapStruct、参数名发现等，减少编译问题。
测试组件：提供H2、Jedis Mock、Podam等测试依赖，支撑单元与集成测试。
网关路由：集中管理各服务的路由与Swagger聚合，简化前端接入。
中间件与容器编排：通过docker-compose一键启动MySQL、Redis、Nacos、RocketMQ、TDengine等。

章节来源

架构总览

整体采用微服务与容器化部署，网关统一入口，服务间通过注册与配置中心、消息队列与定时任务协同工作。CI/CD通过Jenkins流水线实现自动化构建、镜像推送、部署与健康检查，并具备自动回滚能力。

graph TB
subgraph "客户端"
U["浏览器/移动端/设备"]
end
subgraph "边缘与入口"
GW["Spring Cloud Gateway"]
end
subgraph "服务层"
SYS["system-server"]
INF["infra-server"]
IOT["iot-server"]
IOTG["iot-gateway"]
OPS["ops-server"]
end
subgraph "基础设施"
NACOS["Nacos 配置/注册中心"]
MQ["RocketMQ 消息队列"]
REDIS["Redis 缓存"]
MYSQL["MySQL 数据库"]
TD["TDengine 时序库"]
XXL["XXL-Job 调度中心"]
end
U --> GW
GW --> SYS
GW --> INF
GW --> IOT
GW --> OPS
SYS --- NACOS
INF --- NACOS
IOT --- NACOS
OPS --- NACOS
IOT --- MQ
IOT --- REDIS
IOT --- MYSQL
IOT --- TD
IOT --- XXL
IOTG --> IOT
IOTG --- MQ
IOTG --- REDIS

图表来源

详细组件分析

网关组件（Gateway）

路由配置：集中定义各服务的路径前缀与灰度负载均衡URI，支持Swagger文档聚合。
健康检查：通过Actuator健康端点进行容器健康探测。
配置加载：优先加载本地配置，再加载Nacos远程配置。

sequenceDiagram
participant C as "客户端"
participant GW as "Gateway"
participant SVC as "目标服务"
participant N as "Nacos"
C->>GW : 请求 /admin-api/system/...
GW->>N : 加载路由与配置
GW->>SVC : 转发请求灰度LB
SVC-->>GW : 返回响应
GW-->>C : 返回聚合后的Swagger或业务响应

图表来源

viewsh-gateway/src/main/resources/application.yaml

章节来源

viewsh-gateway/src/main/resources/application.yaml

物联网服务（IoT Server）

配置要点：启用Swagger、MyBatis-Plus、Redis缓存、Kafka/RocketMQ配置、XXL-Job执行器等。
多租户与消息总线：支持多租户忽略表与缓存，消息总线类型可选Redis。
启动参数：通过环境变量注入数据库、缓存、消息队列与调度中心地址。

flowchart TD
Start(["启动 IoT Server"]) --> LoadCfg["加载本地与Nacos配置"]
LoadCfg --> InitDB["初始化数据源与MyBatis-Plus"]
InitDB --> InitCache["初始化Redis缓存"]
InitCache --> InitMQ["初始化消息队列(Kafka/RocketMQ)"]
InitMQ --> InitJob["初始化XXL-Job执行器"]
InitJob --> Ready(["服务就绪"])

图表来源

viewsh-module-iot-server/src/main/resources/application.yaml

章节来源

viewsh-module-iot-server/src/main/resources/application.yaml

CI/CD流水线（Jenkins）

分阶段：初始化、检出、变更检测、预构建检查、依赖镜像构建、服务并行构建、部署、最终健康检查。
并行度：根据CPU与内存动态计算最大并行构建数。
回滚：部署失败或健康检查失败时自动回滚至上一个镜像标签。
指标：记录阶段耗时与总耗时，生成性能报告并归档指标。

sequenceDiagram
participant SCM as "Git 仓库"
participant J as "Jenkins"
participant D as "Docker Registry"
participant K as "部署主机"
SCM-->>J : 推送/合并触发
J->>J : 初始化与资源检测
J->>J : 变更检测与服务选择
J->>D : 构建依赖镜像可选
J->>D : 并行构建服务镜像
J->>K : 串行部署按依赖顺序
J->>K : 健康检查并行
alt 失败
J->>K : 自动回滚
end

图表来源

Jenkinsfile

章节来源

Jenkinsfile

测试策略

单元测试：使用JUnit 5与Mockito，推荐继承通用测试基类，Mock Mapper与外部RPC，聚焦Service状态转换。
集成测试：混合队列验证（Redis+MySQL双写），关注分数与优先级一致性及补偿逻辑。
常用工具：H2内存数据库、Jedis Mock、Podam随机对象生成。

flowchart TD
TStart(["开始测试"]) --> Unit["单元测试<br/>Mock外部依赖"]
Unit --> Integ["集成测试<br/>Redis+MySQL一致性"]
Integ --> Tools["使用测试工具<br/>H2/Jedis Mock/Podam"]
Tools --> TEnd(["测试完成"])

图表来源

章节来源

开发环境搭建与IDE配置

基础软件：JDK 17、Maven、IntelliJ IDEA、Git、Docker。
中间件：使用docker-compose.core.yml一键启动MySQL、Redis、Nacos、RocketMQ、TDengine。
IDE插件：Lombok、MapStruct。
本地调试：通过application-local.yaml与Nacos配置中心加载本地配置。

章节来源

代码规范与最佳实践

命名规范：类名UpperCamelCase、应用名lower-kebab-case、包名com.viewsh.module.{模块}.{层级}。
日志与异常：统一使用@Slf4j，INFO记录关键流程，ERROR记录异常并包含异常对象；业务异常抛出ServiceException(ErrorCode)，避免吞异常。
提交规范：feat/fix/docs/style等类型配合scope与描述，保持清晰可追溯。

章节来源

08-开发指南.md

分支管理策略（Git Flow）

master：生产环境，仅允许从release合并。
release：预发布环境，进行集成测试。
dev：开发环境，功能从dev切出并通过PR合并。
feat/xxx：功能分支，开发完成后合并回dev。

章节来源

08-开发指南.md

如何新增一个微服务

创建Module：在viewsh-module-xxx下创建Maven子模块。
依赖配置：引入viewsh-common及相关starter。
配置文件：resources下创建bootstrap.yaml，配置Nacos地址。
启动类：添加@SpringBootApplication与@EnableDiscoveryClient。
网关路由：在Nacos配置中心的viewsh-gateway路由配置中添加转发规则。

章节来源

08-开发指南.md

常见问题排查（FAQ）

连接被拒绝：检查Nacos是否启动成功，8848端口未被防火墙拦截。
依赖下载失败：检查pom.xml中的Maven仓库配置与IDE settings.xml镜像设置。
MapStruct转换对象属性为null：确保Lombok在MapStruct之前执行（参考父工程maven-compiler-plugin配置）。

章节来源

08-开发指南.md

调试技巧与问题排查

日志分析：统一使用@Log4j2或@Slf4j，区分INFO/ERROR级别，结合Nacos配置中心调整日志级别。
性能分析：利用Spring Boot Admin与SkyWalking链路追踪，结合XXL-Job执行器日志定位瓶颈。
内存泄漏检测：通过JVM参数与容器健康检查（HeapDumpOnOutOfMemoryError）捕获堆转储，结合容器日志定位。

章节来源

代码审查指南与质量保证流程

代码审查：PR需包含需求说明、变更清单、测试覆盖与风险评估；至少一名Reviewer同意后方可合并。
质量门禁：通过Jenkins流水线的单元测试、集成测试与健康检查；失败自动回滚。
规范检查：遵循命名、日志、异常与提交规范；IDE配置Lombok与MapStruct处理器顺序。

章节来源

扩展框架组件与自定义功能

扩展框架组件：在viewsh-framework中新增或完善starter，提供核心封装与Spring配置，遵循“core+config”结构。
自定义功能：在具体业务模块中复用viewsh-common与相关starter，按需引入MyBatis、Redis、MQ、定时任务等组件。

章节来源

开发流程与协作规范

开发流程：从dev切出feat分支，完成PR评审与测试，合并至dev后再进入release与master。
协作规范：统一IDE设置、提交信息格式、测试覆盖率要求与日志规范；通过Jenkins流水线保障交付质量。

章节来源

依赖分析

版本统一：通过viewsh-dependencies集中管理Spring Boot、Cloud、Cloud Alibaba、MyBatis、Redisson、MapStruct、Lombok等版本。
插件统一：maven-compiler-plugin配置annotationProcessorPaths，确保Lombok与MapStruct顺序正确；启用参数名发现。
测试依赖：H2、Jedis Mock、Podam、Mockito Inline等，支撑单元与集成测试。

graph LR
P["父POM"] --> D["viewsh-dependencies<br/>BOM"]
P --> F["viewsh-framework<br/>通用组件"]
P --> S["各业务模块"]
D --> SB["Spring Boot/Cloud/Alibaba"]
D --> MB["MyBatis/Plus/Join"]
D --> RS["Redisson/Lettuce"]
D --> MS["MapStruct/Lombok"]
D --> TK["测试工具/H2/Jedis Mock/Podam/Mockito"]

图表来源

章节来源

性能考虑

构建性能：使用Maven缓存卷与BuildKit缓存，依赖镜像按需重建，动态并行度以充分利用硬件资源。
运行性能：容器限制内存与CPU，启用JVM参数与堆转储；通过SkyWalking与Spring Boot Admin观测性能。
数据一致性：Redis+MySQL双写架构需重点验证分数与优先级一致性及补偿逻辑。

章节来源

故障排查指南

启动失败：检查Nacos连通性与端口开放；核对Maven仓库镜像与网络代理。
依赖冲突：统一通过BOM管理版本，避免手动指定版本导致冲突。
编译错误：确保Lombok在MapStruct之前执行，避免No property named错误。
集成测试失败：验证Redis与MySQL一致性，检查补偿逻辑与队列处理。

章节来源

结论

本开发指南围绕环境搭建、代码规范、测试策略、调试与故障排查、CI/CD流水线、扩展与协作等方面，提供了系统性的实践指引。建议团队在日常开发中严格遵循规范与流程，持续优化构建与运行性能，确保AIOT平台云项目的高质量交付与稳定运营。

附录

中间件一键启动命令与配置参考：08-开发指南.md
网关路由与Swagger聚合配置：viewsh-gateway/src/main/resources/application.yaml
物联网服务配置要点：viewsh-module-iot-server/src/main/resources/application.yaml
CI/CD流水线关键阶段与回滚策略：Jenkinsfile

16 KiB Raw Blame History Unescape Escape

开发指南

目录

简介

项目结构

核心组件

架构总览

详细组件分析

网关组件（Gateway）

物联网服务（IoT Server）

CI/CD流水线（Jenkins）

测试策略

开发环境搭建与IDE配置

代码规范与最佳实践

分支管理策略（Git Flow）

如何新增一个微服务

常见问题排查（FAQ）

调试技巧与问题排查

代码审查指南与质量保证流程

扩展框架组件与自定义功能

开发流程与协作规范

依赖分析

性能考虑

故障排查指南

结论

附录

16 KiB

Raw Blame History