wenzi/docs/reports/architecture/MODULARIZATION_GUIDE.md

🦟 蚊子项目模块化改造指南

当前架构

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

<!-- 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 模块

<!-- 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 模块

<!-- 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>

自动配置类:

// src/main/resources/META-INF/spring.factories
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.mosquito.config.MosquitoAutoConfiguration

4. mosquito-sdk 模块

<!-- 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依赖集成

<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自动配置

建议在下一版本进行完整的多模块改造。