23 KiB
23 KiB
扩展开发
**本文引用的文件** - [pom.xml](file://viewsh-framework/pom.xml) - [EnvEnvironmentPostProcessor.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/config/EnvEnvironmentPostProcessor.java) - [EnvUtils.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/core/util/EnvUtils.java) - [EnvWebFilter.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/core/web/EnvWebFilter.java) - [EnvRequestInterceptor.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/core/fegin/EnvRequestInterceptor.java) - [EnvLoadBalancerClient.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/core/fegin/EnvLoadBalancerClient.java) - [EnvLoadBalancerClientFactory.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/core/fegin/EnvLoadBalancerClientFactory.java) - [EnvContextHolder.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/core/context/EnvContextHolder.java) - [spring.factories](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/resources/META-INF/spring.factories) - [AutoConfiguration.imports](file://viewsh-framework/viewsh-spring-boot-starter-job/src/main/resources/META-INF/org.springframework.boot.autoconfigure.AutoConfiguration.imports) - [AutoConfiguration.imports](file://viewsh-framework/viewsh-spring-boot-starter-monitor/src/main/resources/META-INF/org.springframework.boot.autoconfigure.AutoConfiguration.imports) - [AutoConfiguration.imports](file://viewsh-framework/viewsh-spring-boot-starter-mq/src/main/resources/META-INF/org.springframework.boot.autoconfigure.AutoConfiguration.imports) - [AutoConfiguration.imports](file://viewsh-framework/viewsh-spring-boot-starter-redis/src/main/resources/META-INF/org.springframework.boot.autoconfigure.AutoConfiguration.imports) - [AutoConfiguration.imports](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/resources/META-INF/org.springframework.boot.autoconfigure.AutoConfiguration.imports) - [AutoConfiguration.imports](file://viewsh-framework/viewsh-spring-boot-starter-security/src/main/resources/META-INF/org.springframework.boot.autoconfigure.AutoConfiguration.imports) - [AutoConfiguration.imports](file://viewsh-framework/viewsh-spring-boot-starter-websocket/src/main/resources/META-INF/org.springframework.boot.autoconfigure.AutoConfiguration.imports) - [AutoConfiguration.imports](file://viewsh-framework/viewsh-spring-boot-starter-mybatis/src/main/resources/META-INF/org.springframework.boot.autoconfigure.AutoConfiguration.imports) - [AutoConfiguration.imports](file://viewsh-framework/viewsh-spring-boot-starter-excel/src/main/resources/META-INF/org.springframework.boot.autoconfigure.AutoConfiguration.imports) - [AutoConfiguration.imports](file://viewsh-framework/viewsh-spring-boot-starter-test/src/main/resources/META-INF/org.springframework.boot.autoconfigure.AutoConfiguration.imports) - [AutoConfiguration.imports](file://viewsh-framework/viewsh-spring-boot-starter-biz-tenant/src/main/resources/META-INF/org.springframework.boot.autoconfigure.AutoConfiguration.imports) - [AutoConfiguration.imports](file://viewsh-framework/viewsh-spring-boot-starter-biz-data-permission/src/main/resources/META-INF/org.springframework.boot.autoconfigure.AutoConfiguration.imports) - [AutoConfiguration.imports](file://viewsh-framework/viewsh-spring-boot-starter-biz-ip/src/main/resources/META-INF/org.springframework.boot.autoconfigure.AutoConfiguration.imports) - [ViewshEnvWebAutoConfiguration.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/config/ViewshEnvWebAutoConfiguration.java) - [ViewshEnvRpcAutoConfiguration.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/config/ViewshEnvRpcAutoConfiguration.java) - [EnvProperties.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/config/EnvProperties.java) - [pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-env/pom.xml) - [pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-web/pom.xml) - [pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-security/pom.xml) - [pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-websocket/pom.xml) - [pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-redis/pom.xml) - [pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-mq/pom.xml) - [pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-job/pom.xml) - [pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-monitor/pom.xml) - [pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-mybatis/pom.xml) - [pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-excel/pom.xml) - [pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-test/pom.xml) - [pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-biz-tenant/pom.xml) - [pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-biz-data-permission/pom.xml) - [pom.xml](file://viewsh-framework/viewsh-spring-boot-starter-biz-ip/pom.xml)目录
引言
本指南面向AIOT平台云项目的扩展开发者，系统讲解框架的扩展机制与最佳实践。内容覆盖插件系统的设计与实现原理（以Spring Boot自动装配为核心）、自定义组件开发（Starter创建与配置）、第三方集成方案（外部系统对接与数据交换）、框架扩展点（钩子、拦截器、过滤器）、性能优化（缓存、异步、并发）、故障排查以及贡献与最佳实践。
项目结构
AIOT平台采用多模块聚合工程，核心扩展能力集中在viewsh-framework中，按功能拆分为多个Spring Boot Starter模块，每个Starter负责特定领域的自动装配与能力封装。模块间通过Maven聚合管理，遵循“框架组件”和“业务组件”的双重分类。
graph TB
A["viewsh-framework(pom.xml)"] --> B["viewsh-spring-boot-starter-env"]
A --> C["viewsh-spring-boot-starter-web"]
A --> D["viewsh-spring-boot-starter-security"]
A --> E["viewsh-spring-boot-starter-websocket"]
A --> F["viewsh-spring-boot-starter-redis"]
A --> G["viewsh-spring-boot-starter-mq"]
A --> H["viewsh-spring-boot-starter-job"]
A --> I["viewsh-spring-boot-starter-monitor"]
A --> J["viewsh-spring-boot-starter-mybatis"]
A --> K["viewsh-spring-boot-starter-excel"]
A --> L["viewsh-spring-boot-starter-test"]
A --> M["viewsh-spring-boot-starter-biz-tenant"]
A --> N["viewsh-spring-boot-starter-biz-data-permission"]
A --> O["viewsh-spring-boot-starter-biz-ip"]
图表来源
章节来源
核心组件
- 自动装配入口：各Starter通过META-INF下的自动装配清单或spring.factories声明，由Spring Boot在启动时扫描并加载。
- 环境标签传播：env Starter提供环境标签（tag）在Web请求、Feign调用、负载均衡中的传递，确保跨服务链路的一致性。
- Web过滤器与拦截器：通过Web自动配置注入过滤器，实现统一的环境上下文处理。
- RPC与网关：通过Feign拦截器与负载均衡客户端工厂，将环境信息透传至下游服务。
章节来源
- spring.factories
- AutoConfiguration.imports
- AutoConfiguration.imports
- AutoConfiguration.imports
- AutoConfiguration.imports
- AutoConfiguration.imports
- AutoConfiguration.imports
- AutoConfiguration.imports
- AutoConfiguration.imports
- AutoConfiguration.imports
- AutoConfiguration.imports
- AutoConfiguration.imports
- AutoConfiguration.imports
- AutoConfiguration.imports
架构总览
下图展示了env Starter在启动阶段与运行阶段的关键交互：EnvironmentPostProcessor在启动早期设置环境标签；Web层通过过滤器建立上下文；RPC层通过Feign拦截器与负载均衡器传播标签。
sequenceDiagram
participant Boot as "Spring Boot"
participant EnvPP as "EnvEnvironmentPostProcessor"
participant EnvU as "EnvUtils"
participant WebF as "EnvWebFilter"
participant FeignI as "EnvRequestInterceptor"
participant LB as "EnvLoadBalancerClient"
Boot->>EnvPP : "postProcessEnvironment()"
EnvPP->>EnvU : "getTag()/getHostName()"
EnvPP-->>Boot : "设置目标配置项(tag)"
Boot->>WebF : "过滤器初始化"
WebF->>EnvU : "从请求头获取tag"
WebF-->>Boot : "设置线程上下文"
Boot->>FeignI : "拦截器初始化"
FeignI->>EnvU : "从上下文获取tag"
FeignI-->>LB : "在请求模板中添加tag"
LB-->>Boot : "选择实例时携带tag"
图表来源
- EnvEnvironmentPostProcessor.java
- EnvUtils.java
- EnvWebFilter.java
- EnvRequestInterceptor.java
- EnvLoadBalancerClient.java
- EnvLoadBalancerClientFactory.java
详细组件分析
环境标签传播组件（env Starter）
- 启动期环境处理：通过EnvironmentPostProcessor在应用启动早期读取环境变量，将tag写入注册中心等目标配置项，避免重复覆盖。
- 运行期上下文：Web过滤器从HTTP请求头提取tag，设置到线程上下文；Feign拦截器在RPC调用中将tag附加到请求头；负载均衡器根据tag选择实例。
- 工具类：EnvUtils提供tag获取、主机名解析等通用方法。
classDiagram
class EnvEnvironmentPostProcessor {
+postProcessEnvironment(environment, application)
}
class EnvUtils {
+getTag(request)
+getTag(instance)
+getTag(environment)
+setTag(template, tag)
+getHostName()
}
class EnvWebFilter {
+doFilterInternal(request, response, chain)
}
class EnvRequestInterceptor {
+apply(template)
}
class EnvLoadBalancerClient {
+choose(...)
}
class EnvLoadBalancerClientFactory {
+create(...)
}
class EnvContextHolder {
+setTag(tag)
+getTag()
+clear()
}
EnvEnvironmentPostProcessor --> EnvUtils : "使用"
EnvWebFilter --> EnvUtils : "使用"
EnvRequestInterceptor --> EnvUtils : "使用"
EnvLoadBalancerClient --> EnvContextHolder : "读取tag"
EnvLoadBalancerClientFactory --> EnvLoadBalancerClient : "创建"
图表来源
- EnvEnvironmentPostProcessor.java
- EnvUtils.java
- EnvWebFilter.java
- EnvRequestInterceptor.java
- EnvLoadBalancerClient.java
- EnvLoadBalancerClientFactory.java
- EnvContextHolder.java
章节来源
- EnvEnvironmentPostProcessor.java
- EnvUtils.java
- EnvWebFilter.java
- EnvRequestInterceptor.java
- EnvLoadBalancerClient.java
- EnvLoadBalancerClientFactory.java
- EnvContextHolder.java
Web自动配置与安全扩展
- Web自动配置：通过AutoConfiguration.imports声明Web相关自动配置，注入WebMvc/WebFlux扩展点。
- 安全扩展：通过AutoConfiguration.imports声明安全相关自动配置，结合过滤器/拦截器实现统一鉴权与审计。
- WebSocket扩展：通过AutoConfiguration.imports声明WebSocket自动配置，提供消息通道与会话管理。
章节来源
中间件与定时任务扩展
- 消息队列扩展：通过AutoConfiguration.imports声明RabbitMQ/Kafka/RocketMQ等自动配置，提供统一的消息发送/接收抽象。
- 定时任务扩展：通过AutoConfiguration.imports声明Quartz自动配置，提供分布式调度与作业管理。
- 监控扩展：通过AutoConfiguration.imports声明监控自动配置，提供链路追踪与指标采集。
章节来源
数据访问与Excel扩展
- MyBatis扩展：通过AutoConfiguration.imports声明MyBatis自动配置，提供多数据源、分页、动态SQL等能力。
- Excel扩展：通过AutoConfiguration.imports声明Excel自动配置，提供导入导出工具与模板引擎。
章节来源
业务能力扩展（租户、数据权限、IP）
- 租户隔离：通过AutoConfiguration.imports声明租户自动配置，提供全局租户上下文与路由。
- 数据权限：通过AutoConfiguration.imports声明数据权限自动配置，提供字段级与记录级权限控制。
- IP能力：通过AutoConfiguration.imports声明IP自动配置，提供地理位置与反欺诈能力。
章节来源
依赖关系分析
- 组件耦合：env Starter对Web、RPC、负载均衡存在直接依赖，形成“环境标签传播”的闭环；其他Starter通过AutoConfiguration.imports间接依赖Spring Boot自动装配机制。
- 外部依赖：各Starter通过AutoConfiguration.imports声明第三方组件（如Redis、MQ、Quartz、MyBatis等），避免硬编码依赖。
- 可能的循环依赖：env Starter内部通过工具类与上下文解耦，避免在过滤器、拦截器、负载均衡器之间形成环状依赖。
graph LR
Env["env Starter"] --> Web["Web Starter"]
Env --> Sec["Security Starter"]
Env --> WS["WebSocket Starter"]
Env --> MQ["MQ Starter"]
Env --> Job["Job Starter"]
Env --> Mon["Monitor Starter"]
Env --> MyB["MyBatis Starter"]
Env --> Red["Redis Starter"]
Env --> BizT["biz-tenant Starter"]
Env --> BizDP["biz-data-permission Starter"]
Env --> BizIP["biz-ip Starter"]
图表来源
章节来源
性能考虑
- 缓存策略
- 使用Redis Starter提供的自动配置，结合注解与编程式缓存，减少数据库压力。
- 对热点数据设置合理的过期时间与并发控制，避免缓存击穿与雪崩。
- 异步处理
- 使用消息队列Starter进行削峰填谷，将耗时操作异步化。
- 对批量操作使用流式处理与分页，降低内存占用。
- 并发优化
- 在RPC层通过负载均衡器按tag选择实例，提升可用性与分区容灾能力。
- 在Web层合理配置过滤器顺序与线程池大小，避免阻塞。
故障排查指南
- 启动阶段无环境标签
- 检查EnvironmentPostProcessor是否生效，确认目标配置项未被其他配置覆盖。
- 章节来源
- 请求无tag上下文
- 检查Web过滤器是否正确注入，确认请求头中tag值是否符合预期。
- 章节来源
- RPC调用丢失tag
- 检查Feign拦截器是否生效，确认负载均衡器是否正确读取上下文。
- 章节来源
- 自动装配未生效
- 检查AutoConfiguration.imports或spring.factories是否存在拼写错误或路径问题。
- 章节来源
结论
AIOT平台通过Starter体系实现了高度可扩展的插件化架构：启动期通过EnvironmentPostProcessor与spring.factories完成环境初始化，运行期通过Web过滤器、Feign拦截器与负载均衡器实现环境标签的全链路传播。开发者可据此快速扩展新能力，并遵循统一的自动装配规范与最佳实践。
附录
- 开发自定义Starter步骤
- 创建模块并引入必要的依赖坐标。
- 在src/main/resources/META-INF目录下创建AutoConfiguration.imports或spring.factories。
- 在config包中编写自动装配类，在core包中实现核心能力。
- 在模块根pom中声明模块名称与描述，确保与框架分类一致。
- 第三方集成要点
- 使用统一的环境标签（tag）贯穿请求链路，便于定位与排障。
- 对外数据交换采用标准化的JSON格式，必要时增加签名与加密。
- 贡献与社区
- 提交PR前确保通过单元测试与集成测试。
- 在README中补充模块说明与使用示例。