framework-web - Web 应用模块

1. 模块概述

framework-web 是 epoch-framework 的 Web 应用开发支持模块，提供了 Web 应用开发所需的基础功能和组件，包括全局异常处理、消息队列支持等。该模块旨在简化 Web 应用的开发，提供统一的 Web 开发体验。

2. 模块结构

framework-web/
├── exception/       # 异常处理
└── mq/              # 消息队列支持
    ├── base/        # 基础接口定义
    ├── config/      # 配置类
    ├── result/      # 结果模型
    └── rocketmq/    # RocketMQ 实现

3. 核心功能

3.1 exception - 异常处理

提供全局异常处理功能，统一拦截和处理各种异常，转换为标准响应格式。

主要类：

• GlobalExceptionHandler：全局异常处理器，处理各种类型的异常

处理的异常类型：

• BusinessException：业务异常，包含错误码和错误信息
• MethodArgumentNotValidException：参数校验异常
• ConstraintViolationException：参数约束违反异常
• HttpRequestMethodNotSupportedException：HTTP 请求方法不支持异常
• Exception：其他未捕获的异常

响应格式：

{
  "code": "ERROR_CODE",
  "message": "错误信息",
  "data": null
}

使用方式：

// 自动生效，无需额外配置
@RestControllerAdvice
public class GlobalExceptionHandler {
    // 异常处理方法
}

3.2 mq - 消息队列支持

提供消息队列功能支持，基于 RocketMQ 实现，包含消息发送和消费的完整功能。

3.2.1 base - 基础接口定义

定义消息队列的基础接口，为不同的消息队列实现提供统一的抽象。

主要接口：

• BaseMessage：基础消息模型，定义消息的基本属性
• MessageCallbackHandler：消息回调处理器，处理消息发送结果
• MessageHandler：消息处理器，处理消息消费逻辑
• MessageSender：消息发送器，发送消息到消息队列

BaseMessage 核心字段：

private String messageId;         // 消息ID
private String topic;             // 主题
private String tags;              // 标签
private String keys;              // 键
private String body;              // 消息体
private Map<String, String> properties; // 消息属性
private Date sendTime;            // 发送时间

3.2.2 config - 配置类

提供消息队列的配置类，用于配置消息队列的各种参数。

主要类：

• MQAutoConfiguration：消息队列自动配置类，自动配置消息队列组件
• MQConfigProperties：消息队列配置属性，包含消息队列的基本配置
• MQThreadPoolConfig：消息队列线程池配置，配置消息消费的线程池
• RocketConfig：RocketMQ 配置类，配置 RocketMQ 特定参数

配置示例：

epoch:
  mq:
    rocketmq:
      name-server: 127.0.0.1:9876
      producer-group: epoch-producer-group
      consumer-group: epoch-consumer-group
      retry-times-when-send-failed: 3
      retry-times-when-send-async-failed: 3
    thread-pool:
      core-pool-size: 10
      max-pool-size: 50
      queue-capacity: 100
      keep-alive-seconds: 60

3.2.3 result - 结果模型

定义消息消费结果模型，用于表示消息消费的结果。

主要类：

• ConsumeResult：消息消费结果模型，包含消费状态和错误信息

消费状态：

• SUCCESS：消费成功
• FAILURE：消费失败
• RETRY_LATER：稍后重试

3.2.4 rocketmq - RocketMQ 实现

基于 RocketMQ 实现消息队列的发送和消费功能。

主要类：

• EpochMQAutoConfiguration：RocketMQ 自动配置类，配置 RocketMQ 组件
• RocketMessageSender：RocketMQ 消息发送器，实现 MessageSender 接口

消息发送示例：

@Autowired
private MessageSender messageSender;

// 同步发送消息
BaseMessage message = new BaseMessage();
message.setTopic("test-topic");
message.setTags("test-tags");
message.setBody("test-body");
messageSender.send(message);

// 异步发送消息
messageSender.sendAsync(message, new MessageCallbackHandler() {
    @Override
    public void onSuccess(BaseMessage message) {
        // 消息发送成功处理
    }
    
    @Override
    public void onFailure(BaseMessage message, Throwable throwable) {
        // 消息发送失败处理
    }
});

消息消费示例：

@Component
public class TestMessageHandler implements MessageHandler {
    
    @Override
    public String getTopic() {
        return "test-topic";
    }
    
    @Override
    public String getTags() {
        return "test-tags";
    }
    
    @Override
    public ConsumeResult handle(BaseMessage message) {
        try {
            // 处理消息
            return ConsumeResult.success();
        } catch (Exception e) {
            // 处理失败
            return ConsumeResult.failure("处理失败：" + e.getMessage());
        }
    }
}

4. 设计理念

4.1 统一处理

提供统一的异常处理和响应格式，减少重复代码，提高代码一致性。

4.2 可扩展

消息队列模块采用接口抽象设计，支持扩展不同的消息队列实现（如 Kafka、RabbitMQ 等）。

4.3 高性能

消息消费采用线程池处理，提高消息处理效率；消息发送支持同步和异步两种方式，满足不同场景需求。

4.4 易用性

提供简洁的 API 和自动配置，减少使用成本；异常处理自动生效，无需额外配置。

5. 使用指南

5.1 引入依赖

<dependency>
    <groupId>com.epoch</groupId>
    <artifactId>framework-web</artifactId>
    <version>${epoch.version}</version>
</dependency>

<!-- 如果需要使用消息队列功能 -->
<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-spring-boot-starter</artifactId>
    <version>2.3.1</version>
</dependency>

5.2 配置说明

5.2.1 异常处理

无需额外配置，自动生效。

5.2.2 消息队列

在 application.yml 中配置消息队列参数：

epoch:
  mq:
    rocketmq:
      name-server: 127.0.0.1:9876
      producer-group: epoch-producer-group
      consumer-group: epoch-consumer-group

5.3 最佳实践

1. 使用统一响应格式：所有 API 都应使用 ResponseResult 包装响应结果
2. 使用业务异常：在业务逻辑中使用 BusinessException 表示业务错误
3. 合理使用消息队列：将耗时操作、异步处理等场景使用消息队列
4. 处理消息消费失败：实现消息消费的重试机制，避免消息丢失
5. 监控消息队列：监控消息的发送和消费情况，及时发现问题

6. 版本变更

6.1 主要变更

• 3.4.0：

  • 优化异常处理，增加更多异常类型支持
  • 完善消息队列功能，支持更多 RocketMQ 特性

• 3.3.0：

  • 重构全局异常处理器，提高可扩展性
  • 新增消息队列功能，基于 RocketMQ 实现

• 3.2.0：

  • 初始版本，提供全局异常处理功能

7. 常见问题

7.1 如何自定义异常处理？

可以继承 GlobalExceptionHandler 或实现自己的异常处理器：

@RestControllerAdvice
public class CustomExceptionHandler extends GlobalExceptionHandler {
    // 自定义异常处理方法
    @ExceptionHandler(CustomException.class)
    public ResponseResult handleCustomException(CustomException e) {
        return ResponseResult.error("CUSTOM_ERROR", e.getMessage());
    }
}

7.2 如何发送消息？

注入 MessageSender 并使用：

@Autowired
private MessageSender messageSender;

baseMessage message = new BaseMessage();
message.setTopic("test-topic");
message.setTags("test-tags");
message.setBody("test-body");
messageSender.send(message);

7.3 如何消费消息？

实现 MessageHandler 接口并注册为 Spring Bean：

@Component
public class TestMessageHandler implements MessageHandler {
    
    @Override
    public String getTopic() {
        return "test-topic";
    }
    
    @Override
    public String getTags() {
        return "test-tags";
    }
    
    @Override
    public ConsumeResult handle(BaseMessage message) {
        // 处理消息
        return ConsumeResult.success();
    }
}

7.4 如何配置消息队列线程池？

在 application.yml 中配置：

epoch:
  mq:
    thread-pool:
      core-pool-size: 10
      max-pool-size: 50
      queue-capacity: 100
      keep-alive-seconds: 60