311 lines
23 KiB
Markdown
311 lines
23 KiB
Markdown
# 扩展开发
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [引言](#引言)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 引言
|
||
本指南面向AIOT平台云项目的扩展开发者，系统讲解框架的扩展机制与最佳实践。内容覆盖插件系统的设计与实现原理（以Spring Boot自动装配为核心）、自定义组件开发（Starter创建与配置）、第三方集成方案（外部系统对接与数据交换）、框架扩展点（钩子、拦截器、过滤器）、性能优化（缓存、异步、并发）、故障排查以及贡献与最佳实践。
|
||
|
||
## 项目结构
|
||
AIOT平台采用多模块聚合工程，核心扩展能力集中在viewsh-framework中，按功能拆分为多个Spring Boot Starter模块，每个Starter负责特定领域的自动装配与能力封装。模块间通过Maven聚合管理，遵循“框架组件”和“业务组件”的双重分类。
|
||
|
||
```mermaid
|
||
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"]
|
||
```
|
||
|
||
图表来源
|
||
- [pom.xml](file://viewsh-framework/pom.xml#L12-L34)
|
||
|
||
章节来源
|
||
- [pom.xml](file://viewsh-framework/pom.xml#L1-L50)
|
||
|
||
## 核心组件
|
||
- 自动装配入口：各Starter通过META-INF下的自动装配清单或spring.factories声明，由Spring Boot在启动时扫描并加载。
|
||
- 环境标签传播：env Starter提供环境标签（tag）在Web请求、Feign调用、负载均衡中的传递，确保跨服务链路的一致性。
|
||
- Web过滤器与拦截器：通过Web自动配置注入过滤器，实现统一的环境上下文处理。
|
||
- RPC与网关：通过Feign拦截器与负载均衡客户端工厂，将环境信息透传至下游服务。
|
||
|
||
章节来源
|
||
- [spring.factories](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/resources/META-INF/spring.factories#L1-L3)
|
||
- [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-redis/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-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-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)
|
||
|
||
## 架构总览
|
||
下图展示了env Starter在启动阶段与运行阶段的关键交互：EnvironmentPostProcessor在启动早期设置环境标签；Web层通过过滤器建立上下文；RPC层通过Feign拦截器与负载均衡器传播标签。
|
||
|
||
```mermaid
|
||
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](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/config/EnvEnvironmentPostProcessor.java#L27-L48)
|
||
- [EnvUtils.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/core/util/EnvUtils.java#L24-L44)
|
||
- [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)
|
||
|
||
## 详细组件分析
|
||
|
||
### 环境标签传播组件（env Starter）
|
||
- 启动期环境处理：通过EnvironmentPostProcessor在应用启动早期读取环境变量，将tag写入注册中心等目标配置项，避免重复覆盖。
|
||
- 运行期上下文：Web过滤器从HTTP请求头提取tag，设置到线程上下文；Feign拦截器在RPC调用中将tag附加到请求头；负载均衡器根据tag选择实例。
|
||
- 工具类：EnvUtils提供tag获取、主机名解析等通用方法。
|
||
|
||
```mermaid
|
||
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](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/config/EnvEnvironmentPostProcessor.java#L1-L51)
|
||
- [EnvUtils.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/core/util/EnvUtils.java#L1-L57)
|
||
- [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)
|
||
|
||
章节来源
|
||
- [EnvEnvironmentPostProcessor.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/config/EnvEnvironmentPostProcessor.java#L1-L51)
|
||
- [EnvUtils.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/core/util/EnvUtils.java#L1-L57)
|
||
- [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)
|
||
|
||
### Web自动配置与安全扩展
|
||
- Web自动配置：通过AutoConfiguration.imports声明Web相关自动配置，注入WebMvc/WebFlux扩展点。
|
||
- 安全扩展：通过AutoConfiguration.imports声明安全相关自动配置，结合过滤器/拦截器实现统一鉴权与审计。
|
||
- WebSocket扩展：通过AutoConfiguration.imports声明WebSocket自动配置，提供消息通道与会话管理。
|
||
|
||
章节来源
|
||
- [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声明RabbitMQ/Kafka/RocketMQ等自动配置，提供统一的消息发送/接收抽象。
|
||
- 定时任务扩展：通过AutoConfiguration.imports声明Quartz自动配置，提供分布式调度与作业管理。
|
||
- 监控扩展：通过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-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)
|
||
|
||
### 数据访问与Excel扩展
|
||
- MyBatis扩展：通过AutoConfiguration.imports声明MyBatis自动配置，提供多数据源、分页、动态SQL等能力。
|
||
- Excel扩展：通过AutoConfiguration.imports声明Excel自动配置，提供导入导出工具与模板引擎。
|
||
|
||
章节来源
|
||
- [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)
|
||
|
||
### 业务能力扩展（租户、数据权限、IP）
|
||
- 租户隔离：通过AutoConfiguration.imports声明租户自动配置，提供全局租户上下文与路由。
|
||
- 数据权限：通过AutoConfiguration.imports声明数据权限自动配置，提供字段级与记录级权限控制。
|
||
- IP能力：通过AutoConfiguration.imports声明IP自动配置，提供地理位置与反欺诈能力。
|
||
|
||
章节来源
|
||
- [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)
|
||
|
||
## 依赖关系分析
|
||
- 组件耦合：env Starter对Web、RPC、负载均衡存在直接依赖，形成“环境标签传播”的闭环；其他Starter通过AutoConfiguration.imports间接依赖Spring Boot自动装配机制。
|
||
- 外部依赖：各Starter通过AutoConfiguration.imports声明第三方组件（如Redis、MQ、Quartz、MyBatis等），避免硬编码依赖。
|
||
- 可能的循环依赖：env Starter内部通过工具类与上下文解耦，避免在过滤器、拦截器、负载均衡器之间形成环状依赖。
|
||
|
||
```mermaid
|
||
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"]
|
||
```
|
||
|
||
图表来源
|
||
- [pom.xml](file://viewsh-framework/pom.xml#L12-L34)
|
||
|
||
章节来源
|
||
- [pom.xml](file://viewsh-framework/pom.xml#L1-L50)
|
||
|
||
## 性能考虑
|
||
- 缓存策略
|
||
- 使用Redis Starter提供的自动配置，结合注解与编程式缓存，减少数据库压力。
|
||
- 对热点数据设置合理的过期时间与并发控制，避免缓存击穿与雪崩。
|
||
- 异步处理
|
||
- 使用消息队列Starter进行削峰填谷，将耗时操作异步化。
|
||
- 对批量操作使用流式处理与分页，降低内存占用。
|
||
- 并发优化
|
||
- 在RPC层通过负载均衡器按tag选择实例，提升可用性与分区容灾能力。
|
||
- 在Web层合理配置过滤器顺序与线程池大小，避免阻塞。
|
||
|
||
## 故障排查指南
|
||
- 启动阶段无环境标签
|
||
- 检查EnvironmentPostProcessor是否生效，确认目标配置项未被其他配置覆盖。
|
||
- 章节来源
|
||
- [EnvEnvironmentPostProcessor.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/config/EnvEnvironmentPostProcessor.java#L27-L48)
|
||
- 请求无tag上下文
|
||
- 检查Web过滤器是否正确注入，确认请求头中tag值是否符合预期。
|
||
- 章节来源
|
||
- [EnvWebFilter.java](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/java/com/viewsh/framework/env/core/web/EnvWebFilter.java)
|
||
- RPC调用丢失tag
|
||
- 检查Feign拦截器是否生效，确认负载均衡器是否正确读取上下文。
|
||
- 章节来源
|
||
- [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)
|
||
- 自动装配未生效
|
||
- 检查AutoConfiguration.imports或spring.factories是否存在拼写错误或路径问题。
|
||
- 章节来源
|
||
- [AutoConfiguration.imports](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/resources/META-INF/org.springframework.boot.autoconfigure.AutoConfiguration.imports)
|
||
- [spring.factories](file://viewsh-framework/viewsh-spring-boot-starter-env/src/main/resources/META-INF/spring.factories#L1-L3)
|
||
|
||
## 结论
|
||
AIOT平台通过Starter体系实现了高度可扩展的插件化架构：启动期通过EnvironmentPostProcessor与spring.factories完成环境初始化，运行期通过Web过滤器、Feign拦截器与负载均衡器实现环境标签的全链路传播。开发者可据此快速扩展新能力，并遵循统一的自动装配规范与最佳实践。
|
||
|
||
## 附录
|
||
- 开发自定义Starter步骤
|
||
- 创建模块并引入必要的依赖坐标。
|
||
- 在src/main/resources/META-INF目录下创建AutoConfiguration.imports或spring.factories。
|
||
- 在config包中编写自动装配类，在core包中实现核心能力。
|
||
- 在模块根pom中声明模块名称与描述，确保与框架分类一致。
|
||
- 第三方集成要点
|
||
- 使用统一的环境标签（tag）贯穿请求链路，便于定位与排障。
|
||
- 对外数据交换采用标准化的JSON格式，必要时增加签名与加密。
|
||
- 贡献与社区
|
||
- 提交PR前确保通过单元测试与集成测试。
|
||
- 在README中补充模块说明与使用示例。 |