chore: sync local latest state and repository cleanup
This commit is contained in:
Your Name
230
docs/reports/architecture/MODULARIZATION_GUIDE.md
Normal file
230
docs/reports/architecture/MODULARIZATION_GUIDE.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# 🦟 蚊子项目模块化改造指南
|
||||
|
||||
## 当前架构
|
||||
|
||||
```
|
||||
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自动配置
|
||||
|
||||
建议在下一版本进行完整的多模块改造。
|
||||
Reference in New Issue
Block a user