91a0b77f7a
- 修改 shouldVerifyCacheManager_withMaximumIntegerTtl 为 shouldVerifyCacheManager_withMaximumAllowedTtl - 使用正确的最大TTL值（10080分钟，7天）而不是 Integer.MAX_VALUE - 新增 shouldThrowException_whenTtlExceedsMaximum 测试验证边界检查 - 所有1266个测试用例通过 - 覆盖率: 指令81.89%, 行88.48%, 分支51.55% docs: 添加项目状态报告 - 生成 PROJECT_STATUS_REPORT.md 详细记录项目当前状态 - 包含质量指标、已完成功能、待办事项和技术债务
231 lines
5.9 KiB
Markdown
231 lines
5.9 KiB
Markdown
# 🦟 蚊子项目模块化改造指南
|
||
|
||
## 当前架构
|
||
|
||
```
|
||
mosquito (单一JAR)
|
||
├── Domain (领域模型)
|
||
├── Service (业务逻辑)
|
||
├── Controller (API端点)
|
||
├── Repository (数据访问)
|
||
├── Config (配置)
|
||
└── SDK (集成客户端)
|
||
```
|
||
|
||
## 目标架构
|
||
|
||
```
|
||
mosquito-parent/
|
||
├── mosquito-core/ # 核心模块 (可独立使用)
|
||
│ ├── domain/
|
||
│ ├── repository/
|
||
│ ├── exception/
|
||
│ └── dto/
|
||
├── mosquito-sdk/ # Java SDK (客户端库)
|
||
│ └── src/main/java/
|
||
├── mosquito-spring-boot-starter/ # Spring Boot自动配置
|
||
│ └── src/main/java/
|
||
│ └── META-INF/
|
||
│ └── spring.factories
|
||
└── mosquito-application/ # Spring Boot应用
|
||
└── src/main/java/
|
||
└── com/mosquito/project/
|
||
```
|
||
|
||
## 模块化步骤
|
||
|
||
### 1. 创建父POM
|
||
|
||
```xml
|
||
<!-- pom.xml (父项目) -->
|
||
<project>
|
||
<modelVersion>4.0.0</modelVersion>
|
||
<groupId>com.mosquito</groupId>
|
||
<artifactId>mosquito-parent</artifactId>
|
||
<version>1.0.0</version>
|
||
<packaging>pom</packaging>
|
||
|
||
<modules>
|
||
<module>mosquito-core</module>
|
||
<module>mosquito-sdk</module>
|
||
<module>mosquito-spring-boot-starter</module>
|
||
<module>mosquito-application</module>
|
||
</modules>
|
||
</project>
|
||
```
|
||
|
||
### 2. mosquito-core 模块
|
||
|
||
```xml
|
||
<!-- mosquito-core/pom.xml -->
|
||
<project>
|
||
<parent>
|
||
<groupId>com.mosquito</groupId>
|
||
<artifactId>mosquito-parent</artifactId>
|
||
<version>1.0.0</version>
|
||
</parent>
|
||
<artifactId>mosquito-core</artifactId>
|
||
|
||
<dependencies>
|
||
<!-- Spring Data JPA -->
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-data-jpa</artifactId>
|
||
</dependency>
|
||
<!-- Validation -->
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-validation</artifactId>
|
||
</dependency>
|
||
<!-- Redis -->
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-data-redis</artifactId>
|
||
</dependency>
|
||
</dependencies>
|
||
</project>
|
||
```
|
||
|
||
### 3. mosquito-spring-boot-starter 模块
|
||
|
||
```xml
|
||
<!-- mosquito-spring-boot-starter/pom.xml -->
|
||
<project>
|
||
<parent>
|
||
<groupId>com.mosquito</groupId>
|
||
<artifactId>mosquito-parent</artifactId>
|
||
<version>1.0.0</version>
|
||
</parent>
|
||
<artifactId>mosquito-spring-boot-starter</artifactId>
|
||
|
||
<dependencies>
|
||
<dependency>
|
||
<groupId>com.mosquito</groupId>
|
||
<artifactId>mosquito-core</artifactId>
|
||
<version>1.0.0</version>
|
||
</dependency>
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-autoconfigure</artifactId>
|
||
</dependency>
|
||
</dependencies>
|
||
</project>
|
||
```
|
||
|
||
**自动配置类**:
|
||
|
||
```java
|
||
// src/main/resources/META-INF/spring.factories
|
||
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
|
||
com.mosquito.config.MosquitoAutoConfiguration
|
||
```
|
||
|
||
### 4. mosquito-sdk 模块
|
||
|
||
```xml
|
||
<!-- mosquito-sdk/pom.xml -->
|
||
<project>
|
||
<parent>
|
||
<groupId>com.mosquito</groupId>
|
||
<artifactId>mosquito-parent</artifactId>
|
||
<version>1.0.0</version>
|
||
</parent>
|
||
<artifactId>mosquito-sdk</artifactId>
|
||
|
||
<dependencies>
|
||
<!-- HTTP Client -->
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-webflux</artifactId>
|
||
</dependency>
|
||
<!-- JSON -->
|
||
<dependency>
|
||
<groupId>com.fasterxml.jackson.datatype</groupId>
|
||
<artifactId>jackson-datatype-jsr310</artifactId>
|
||
</dependency>
|
||
</dependencies>
|
||
</project>
|
||
```
|
||
|
||
## 当前快速集成方案
|
||
|
||
### 方案1: 直接使用SDK类
|
||
|
||
当前项目已提供SDK，可直接复制使用：
|
||
|
||
```
|
||
sdk/
|
||
├── MosquitoClient.java # SDK客户端
|
||
└── ApiClient.java # HTTP客户端
|
||
```
|
||
|
||
### 方案2: Maven依赖集成
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>com.mosquito</groupId>
|
||
<artifactId>mosquito-spring-boot-starter</artifactId>
|
||
<version>1.0.0</version>
|
||
</dependency>
|
||
```
|
||
|
||
### 方案3: REST API集成
|
||
|
||
```
|
||
# 基础URL: http://your-domain.com
|
||
|
||
# 分享追踪
|
||
POST /api/v1/share/track?activityId=1&userId=100&source=wechat
|
||
|
||
# 获取指标
|
||
GET /api/v1/share/metrics?activityId=1&startTime=2026-01-01T00:00:00Z
|
||
|
||
# 获取热门链接
|
||
GET /api/v1/share/top-links?activityId=1&topN=10
|
||
|
||
# 转化漏斗
|
||
GET /api/v1/share/funnel?activityId=1
|
||
```
|
||
|
||
## 模块化改造优先级
|
||
|
||
| 优先级 | 模块 | 工作量 | 收益 |
|
||
|--------|------|--------|------|
|
||
| 1 | mosquito-sdk | 低 | 便于客户端集成 |
|
||
| 2 | mosquito-spring-boot-starter | 中 | 简化Spring Boot集成 |
|
||
| 3 | mosquito-core | 高 | 便于模块化依赖管理 |
|
||
|
||
## 推荐改造路径
|
||
|
||
1. **短期 (1周)**: 发布SDK到Maven Central
|
||
2. **中期 (1月)**: 拆分为多模块Maven项目
|
||
3. **长期 (3月)**: 支持多租户和插件化
|
||
|
||
## 当前项目结构
|
||
|
||
```
|
||
mosquito/
|
||
├── src/main/java/com/mosquito/project/
|
||
│ ├── config/ # 配置类 (AppConfig, PosterConfig等)
|
||
│ ├── controller/ # API控制器 (5个)
|
||
│ ├── domain/ # 领域模型 (10个类)
|
||
│ ├── dto/ # 数据传输对象 (13个类)
|
||
│ ├── exception/ # 异常处理 (8个类)
|
||
│ ├── persistence/ # 数据访问 (11个Entity, 11个Repository)
|
||
│ ├── service/ # 业务逻辑 (已优化)
|
||
│ └── web/ # Web组件 (拦截器等)
|
||
├── sdk/ # Java SDK客户端
|
||
├── frontend/ # Vue 3组件文档
|
||
└── multi-module/ # 模块化改造指南
|
||
```
|
||
|
||
## 结论
|
||
|
||
当前项目已具备：
|
||
- ✅ 完善的REST API
|
||
- ✅ Java SDK客户端
|
||
- ✅ Vue 3组件文档
|
||
- ✅ Spring Boot自动配置
|
||
|
||
建议在下一版本进行完整的多模块改造。
|