360 lines
16 KiB
Markdown
360 lines
16 KiB
Markdown
# 开发指南
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本开发指南面向AIOT平台云项目的开发与维护团队，目标是帮助新成员快速完成本地开发环境搭建、理解并遵循统一的代码规范与最佳实践、掌握CI/CD流水线与测试策略、以及高效地进行调试与问题排查。同时提供扩展框架组件与自定义功能的指导，确保团队协作的一致性与开发效率。
|
||
|
||
## 项目结构
|
||
项目采用多模块Maven聚合工程组织，顶层POM负责统一版本与插件管理；核心模块包括网关、系统服务、基础设施服务、物联网服务、作业调度、消息队列、监控与安全等。框架层提供通用starter与测试组件，便于各业务模块复用。
|
||
|
||
```mermaid
|
||
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/>定时任务封装"]
|
||
```
|
||
|
||
图表来源
|
||
- [pom.xml](file://pom.xml#L10-L30)
|
||
- [viewsh-framework/pom.xml](file://viewsh-framework/pom.xml#L12-L34)
|
||
|
||
章节来源
|
||
- [pom.xml](file://pom.xml#L1-L176)
|
||
- [viewsh-framework/pom.xml](file://viewsh-framework/pom.xml#L1-L50)
|
||
|
||
## 核心组件
|
||
- 依赖管理与版本控制：通过BOM集中管理第三方依赖版本，确保模块间一致性。
|
||
- 代码生成与编译插件：统一配置Lombok、MapStruct、参数名发现等，减少编译问题。
|
||
- 测试组件：提供H2、Jedis Mock、Podam等测试依赖，支撑单元与集成测试。
|
||
- 网关路由：集中管理各服务的路由与Swagger聚合，简化前端接入。
|
||
- 中间件与容器编排：通过docker-compose一键启动MySQL、Redis、Nacos、RocketMQ、TDengine等。
|
||
|
||
章节来源
|
||
- [viewsh-dependencies/pom.xml](file://viewsh-dependencies/pom.xml#L88-L706)
|
||
- [pom.xml](file://pom.xml#L63-L142)
|
||
- [viewsh-framework/viewsh-spring-boot-starter-test/pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-test/pom.xml#L18-L59)
|
||
- [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml#L28-L271)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L1-L266)
|
||
|
||
## 架构总览
|
||
整体采用微服务与容器化部署，网关统一入口，服务间通过注册与配置中心、消息队列与定时任务协同工作。CI/CD通过Jenkins流水线实现自动化构建、镜像推送、部署与健康检查，并具备自动回滚能力。
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
图表来源
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L12-L266)
|
||
- [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml#L34-L213)
|
||
|
||
## 详细组件分析
|
||
|
||
### 网关组件（Gateway）
|
||
- 路由配置：集中定义各服务的路径前缀与灰度负载均衡URI，支持Swagger文档聚合。
|
||
- 健康检查：通过Actuator健康端点进行容器健康探测。
|
||
- 配置加载：优先加载本地配置，再加载Nacos远程配置。
|
||
|
||
```mermaid
|
||
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](file://viewsh-gateway/src/main/resources/application.yaml#L28-L271)
|
||
|
||
章节来源
|
||
- [viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml#L1-L276)
|
||
|
||
### 物联网服务（IoT Server）
|
||
- 配置要点：启用Swagger、MyBatis-Plus、Redis缓存、Kafka/RocketMQ配置、XXL-Job执行器等。
|
||
- 多租户与消息总线：支持多租户忽略表与缓存，消息总线类型可选Redis。
|
||
- 启动参数：通过环境变量注入数据库、缓存、消息队列与调度中心地址。
|
||
|
||
```mermaid
|
||
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](file://viewsh-module-iot-server/src/main/resources/application.yaml#L12-L163)
|
||
|
||
章节来源
|
||
- [viewsh-module-iot-server/src/main/resources/application.yaml](file://viewsh-module-iot-server/src/main/resources/application.yaml#L1-L163)
|
||
|
||
### CI/CD流水线（Jenkins）
|
||
- 分阶段：初始化、检出、变更检测、预构建检查、依赖镜像构建、服务并行构建、部署、最终健康检查。
|
||
- 并行度：根据CPU与内存动态计算最大并行构建数。
|
||
- 回滚：部署失败或健康检查失败时自动回滚至上一个镜像标签。
|
||
- 指标：记录阶段耗时与总耗时，生成性能报告并归档指标。
|
||
|
||
```mermaid
|
||
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](file://Jenkinsfile#L47-L358)
|
||
|
||
章节来源
|
||
- [Jenkinsfile](file://Jenkinsfile#L1-L1041)
|
||
|
||
### 测试策略
|
||
- 单元测试：使用JUnit 5与Mockito，推荐继承通用测试基类，Mock Mapper与外部RPC，聚焦Service状态转换。
|
||
- 集成测试：混合队列验证（Redis+MySQL双写），关注分数与优先级一致性及补偿逻辑。
|
||
- 常用工具：H2内存数据库、Jedis Mock、Podam随机对象生成。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
TStart(["开始测试"]) --> Unit["单元测试<br/>Mock外部依赖"]
|
||
Unit --> Integ["集成测试<br/>Redis+MySQL一致性"]
|
||
Integ --> Tools["使用测试工具<br/>H2/Jedis Mock/Podam"]
|
||
Tools --> TEnd(["测试完成"])
|
||
```
|
||
|
||
图表来源
|
||
- [part8-测试指南.md](file://docs/ops-architecture/part8-测试指南.md#L5-L27)
|
||
- [viewsh-framework/viewsh-spring-boot-starter-test/pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-test/pom.xml#L18-L59)
|
||
|
||
章节来源
|
||
- [part8-测试指南.md](file://docs/ops-architecture/part8-测试指南.md#L1-L30)
|
||
- [viewsh-framework/viewsh-spring-boot-starter-test/pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-test/pom.xml#L1-L61)
|
||
|
||
### 开发环境搭建与IDE配置
|
||
- 基础软件：JDK 17、Maven、IntelliJ IDEA、Git、Docker。
|
||
- 中间件：使用docker-compose.core.yml一键启动MySQL、Redis、Nacos、RocketMQ、TDengine。
|
||
- IDE插件：Lombok、MapStruct。
|
||
- 本地调试：通过application-local.yaml与Nacos配置中心加载本地配置。
|
||
|
||
章节来源
|
||
- [08-开发指南.md](file://docs/technical-overview/08-开发指南.md#L5-L25)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L1-L266)
|
||
|
||
### 代码规范与最佳实践
|
||
- 命名规范：类名UpperCamelCase、应用名lower-kebab-case、包名com.viewsh.module.{模块}.{层级}。
|
||
- 日志与异常：统一使用@Slf4j，INFO记录关键流程，ERROR记录异常并包含异常对象；业务异常抛出ServiceException(ErrorCode)，避免吞异常。
|
||
- 提交规范：feat/fix/docs/style等类型配合scope与描述，保持清晰可追溯。
|
||
|
||
章节来源
|
||
- [08-开发指南.md](file://docs/technical-overview/08-开发指南.md#L27-L59)
|
||
|
||
### 分支管理策略（Git Flow）
|
||
- master：生产环境，仅允许从release合并。
|
||
- release：预发布环境，进行集成测试。
|
||
- dev：开发环境，功能从dev切出并通过PR合并。
|
||
- feat/xxx：功能分支，开发完成后合并回dev。
|
||
|
||
章节来源
|
||
- [08-开发指南.md](file://docs/technical-overview/08-开发指南.md#L42-L59)
|
||
|
||
### 如何新增一个微服务
|
||
- 创建Module：在viewsh-module-xxx下创建Maven子模块。
|
||
- 依赖配置：引入viewsh-common及相关starter。
|
||
- 配置文件：resources下创建bootstrap.yaml，配置Nacos地址。
|
||
- 启动类：添加@SpringBootApplication与@EnableDiscoveryClient。
|
||
- 网关路由：在Nacos配置中心的viewsh-gateway路由配置中添加转发规则。
|
||
|
||
章节来源
|
||
- [08-开发指南.md](file://docs/technical-overview/08-开发指南.md#L61-L69)
|
||
|
||
### 常见问题排查（FAQ）
|
||
- 连接被拒绝：检查Nacos是否启动成功，8848端口未被防火墙拦截。
|
||
- 依赖下载失败：检查pom.xml中的Maven仓库配置与IDE settings.xml镜像设置。
|
||
- MapStruct转换对象属性为null：确保Lombok在MapStruct之前执行（参考父工程maven-compiler-plugin配置）。
|
||
|
||
章节来源
|
||
- [08-开发指南.md](file://docs/technical-overview/08-开发指南.md#L71-L81)
|
||
|
||
### 调试技巧与问题排查
|
||
- 日志分析：统一使用@Log4j2或@Slf4j，区分INFO/ERROR级别，结合Nacos配置中心调整日志级别。
|
||
- 性能分析：利用Spring Boot Admin与SkyWalking链路追踪，结合XXL-Job执行器日志定位瓶颈。
|
||
- 内存泄漏检测：通过JVM参数与容器健康检查（HeapDumpOnOutOfMemoryError）捕获堆转储，结合容器日志定位。
|
||
|
||
章节来源
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L24-L49)
|
||
- [viewsh-module-iot-server/src/main/resources/application.yaml](file://viewsh-module-iot-server/src/main/resources/application.yaml#L120-L128)
|
||
|
||
### 代码审查指南与质量保证流程
|
||
- 代码审查：PR需包含需求说明、变更清单、测试覆盖与风险评估；至少一名Reviewer同意后方可合并。
|
||
- 质量门禁：通过Jenkins流水线的单元测试、集成测试与健康检查；失败自动回滚。
|
||
- 规范检查：遵循命名、日志、异常与提交规范；IDE配置Lombok与MapStruct处理器顺序。
|
||
|
||
章节来源
|
||
- [Jenkinsfile](file://Jenkinsfile#L360-L432)
|
||
- [pom.xml](file://pom.xml#L73-L110)
|
||
- [08-开发指南.md](file://docs/technical-overview/08-开发指南.md#L27-L59)
|
||
|
||
### 扩展框架组件与自定义功能
|
||
- 扩展框架组件：在viewsh-framework中新增或完善starter，提供核心封装与Spring配置，遵循“core+config”结构。
|
||
- 自定义功能：在具体业务模块中复用viewsh-common与相关starter，按需引入MyBatis、Redis、MQ、定时任务等组件。
|
||
|
||
章节来源
|
||
- [viewsh-framework/pom.xml](file://viewsh-framework/pom.xml#L12-L34)
|
||
- [viewsh-dependencies/pom.xml](file://viewsh-dependencies/pom.xml#L88-L706)
|
||
|
||
### 开发流程与协作规范
|
||
- 开发流程：从dev切出feat分支，完成PR评审与测试，合并至dev后再进入release与master。
|
||
- 协作规范：统一IDE设置、提交信息格式、测试覆盖率要求与日志规范；通过Jenkins流水线保障交付质量。
|
||
|
||
章节来源
|
||
- [08-开发指南.md](file://docs/technical-overview/08-开发指南.md#L42-L59)
|
||
- [Jenkinsfile](file://Jenkinsfile#L47-L142)
|
||
|
||
## 依赖分析
|
||
- 版本统一：通过viewsh-dependencies集中管理Spring Boot、Cloud、Cloud Alibaba、MyBatis、Redisson、MapStruct、Lombok等版本。
|
||
- 插件统一：maven-compiler-plugin配置annotationProcessorPaths，确保Lombok与MapStruct顺序正确；启用参数名发现。
|
||
- 测试依赖：H2、Jedis Mock、Podam、Mockito Inline等，支撑单元与集成测试。
|
||
|
||
```mermaid
|
||
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"]
|
||
```
|
||
|
||
图表来源
|
||
- [pom.xml](file://pom.xml#L51-L61)
|
||
- [viewsh-dependencies/pom.xml](file://viewsh-dependencies/pom.xml#L88-L706)
|
||
- [pom.xml](file://pom.xml#L73-L110)
|
||
|
||
章节来源
|
||
- [pom.xml](file://pom.xml#L35-L49)
|
||
- [viewsh-dependencies/pom.xml](file://viewsh-dependencies/pom.xml#L16-L86)
|
||
|
||
## 性能考虑
|
||
- 构建性能：使用Maven缓存卷与BuildKit缓存，依赖镜像按需重建，动态并行度以充分利用硬件资源。
|
||
- 运行性能：容器限制内存与CPU，启用JVM参数与堆转储；通过SkyWalking与Spring Boot Admin观测性能。
|
||
- 数据一致性：Redis+MySQL双写架构需重点验证分数与优先级一致性及补偿逻辑。
|
||
|
||
章节来源
|
||
- [Jenkinsfile](file://Jenkinsfile#L203-L222)
|
||
- [Jenkinsfile](file://Jenkinsfile#L505-L541)
|
||
- [docker-compose.core.yml](file://docker-compose.core.yml#L42-L49)
|
||
- [part8-测试指南.md](file://docs/ops-architecture/part8-测试指南.md#L16-L27)
|
||
|
||
## 故障排查指南
|
||
- 启动失败：检查Nacos连通性与端口开放；核对Maven仓库镜像与网络代理。
|
||
- 依赖冲突：统一通过BOM管理版本，避免手动指定版本导致冲突。
|
||
- 编译错误：确保Lombok在MapStruct之前执行，避免No property named错误。
|
||
- 集成测试失败：验证Redis与MySQL一致性，检查补偿逻辑与队列处理。
|
||
|
||
章节来源
|
||
- [08-开发指南.md](file://docs/technical-overview/08-开发指南.md#L71-L81)
|
||
- [pom.xml](file://pom.xml#L73-L110)
|
||
- [part8-测试指南.md](file://docs/ops-architecture/part8-测试指南.md#L16-L27)
|
||
|
||
## 结论
|
||
本开发指南围绕环境搭建、代码规范、测试策略、调试与故障排查、CI/CD流水线、扩展与协作等方面，提供了系统性的实践指引。建议团队在日常开发中严格遵循规范与流程，持续优化构建与运行性能，确保AIOT平台云项目的高质量交付与稳定运营。
|
||
|
||
## 附录
|
||
- 中间件一键启动命令与配置参考：[08-开发指南.md](file://docs/technical-overview/08-开发指南.md#L16-L25)
|
||
- 网关路由与Swagger聚合配置：[viewsh-gateway/src/main/resources/application.yaml](file://viewsh-gateway/src/main/resources/application.yaml#L28-L271)
|
||
- 物联网服务配置要点：[viewsh-module-iot-server/src/main/resources/application.yaml](file://viewsh-module-iot-server/src/main/resources/application.yaml#L12-L163)
|
||
- CI/CD流水线关键阶段与回滚策略：[Jenkinsfile](file://Jenkinsfile#L47-L358) |