# platform-common

**Repository Path**: microservice-framework-org/platform-common

## Basic Information

- **Project Name**: platform-common
- **Description**: 平台公共基础模块，提供通用工具、异常处理、统一响应、AOP 切面等基础设施
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-04-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Platform Common 模块

平台公共基础模块，提供通用工具、异常处理、统一响应等功能。

## 项目结构

```
platform-common/
├── pom.xml                                    # Maven 配置文件
└── src/main/java/com/platform/common/
    ├── annotation/                            # 自定义注解
    │   ├── ApiIdempotent.java                # 幂等性注解
    │   ├── ApiLimit.java                     # 限流注解
    │   └── LogRecord.java                    # 日志记录注解
    │
    ├── aspect/                                # AOP 切面
    │   ├── IdempotentAspect.java             # 幂等切面
    │   ├── RateLimitAspect.java              # 限流切面
    │   └── LogAspect.java                    # 日志切面
    │
    ├── constant/                              # 常量定义
    │   ├── Constants.java                    # 全局常量
    │   ├── RedisKeyConstants.java            # Redis Key 常量
    │   └── ErrorCodeConstants.java           # 错误码常量
    │
    ├── exception/                             # 异常处理
    │   ├── BusinessException.java            # 业务异常
    │   ├── SystemException.java              # 系统异常
    │   ├── GlobalExceptionHandler.java       # 全局异常处理器
    │   └── ErrorCode.java                    # 错误码接口
    │
    ├── response/                              # 统一响应
    │   ├── Result.java                       # 统一返回对象
    │   ├── PageResult.java                   # 分页返回对象
    │   └── ResultUtil.java                   # 返回工具类
    │
    ├── utils/                                 # 工具类
    │   ├── JsonUtils.java                    # JSON 工具
    │   ├── DateUtils.java                    # 日期工具
    │   ├── IdGenerator.java                  # ID 生成器（雪花算法）
    │   ├── IpUtils.java                      # IP 工具
    │   └── BeanCopyUtils.java                # Bean 拷贝工具
    │
    ├── context/                               # 上下文
    │   ├── UserContext.java                  # 用户上下文
    │   └── TraceContext.java                 # 链路追踪上下文
    │
    ├── interceptor/                           # 拦截器
    │   └── RequestInterceptor.java           # 请求拦截器
    │
    └── config/                                # 配置类
        ├── CommonAutoConfiguration.java      # 通用自动配置
        ├── WebMvcConfig.java                 # Web MVC 配置
        ├── JacksonConfig.java                # Jackson 配置
        ├── RestTemplateConfig.java           # RestTemplate 配置
        └── ThreadPoolConfig.java             # 线程池配置
```

## 核心功能

### 1. 注解支持

- **@ApiIdempotent**: 接口幂等性保证，基于 Redis 实现
- **@ApiLimit**: 接口限流，基于 Redis 滑动窗口算法
- **@LogRecord**: 操作日志记录，支持 SpEL 表达式

### 2. AOP 切面

- **IdempotentAspect**: 幂等性切面，防止重复提交
- **RateLimitAspect**: 限流切面，保护系统不被过度访问
- **LogAspect**: 日志切面，自动记录操作日志

### 3. 异常处理

- **BusinessException**: 业务异常基类
- **SystemException**: 系统异常基类
- **GlobalExceptionHandler**: 全局异常处理器，统一返回错误信息

### 4. 统一响应

- **Result<T>**: 统一成功/失败响应格式
- **PageResult<T>**: 分页查询响应格式
- **ResultUtil**: 快速构建响应对象的工具类

### 5. 工具类

- **JsonUtils**: JSON 序列化和反序列化
- **DateUtils**: 日期时间处理（支持 Java8 新特性）
- **IdGenerator**: 分布式唯一 ID 生成器（雪花算法）
- **IpUtils**: IP 地址解析工具
- **BeanCopyUtils**: 对象属性拷贝工具

### 6. 上下文管理

- **UserContext**: 线程安全的用户上下文（ThreadLocal）
- **TraceContext**: 链路追踪上下文，支持分布式追踪

### 7. 自动配置

通过 `spring.factories` 实现自动装配，引入即可使用：

- 自动注册 AOP 切面（需要 Redis）
- 自动注册请求拦截器
- 自动配置 Jackson 序列化行为
- 自动配置 RestTemplate
- 自动配置线程池

## 使用方式

### 1. 在项目中添加依赖

```xml
<dependency>
    <groupId>com.platform</groupId>
    <artifactId>platform-common</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 2. 配置示例（application.yml）

```yaml
platform:
  idempotent:
    enabled: true          # 启用幂等性检查
  ratelimit:
    enabled: true          # 启用限流
  log:
    enabled: true          # 启用日志记录
  interceptor:
    enabled: true          # 启用拦截器
```

### 3. 使用示例

#### 3.1 幂等性接口

```java
@PostMapping("/order")
@ApiIdempotent(prefix = "order:create:", expireTime = 5000)
public Result<OrderVO> createOrder(@RequestBody OrderDTO orderDTO) {
    // 业务逻辑
    return Result.success(orderService.create(orderDTO));
}
```

#### 3.2 限流接口

```java
@GetMapping("/search")
@ApiLimit(key = "#keyword", time = 1, maxCount = 10)
public Result<List<ProductVO>> search(@RequestParam String keyword) {
    // 业务逻辑
    return Result.success(productService.search(keyword));
}
```

#### 3.3 日志记录

```java
@LogRecord(
    description = "创建订单",
    type = "ORDER",
    subType = "CREATE",
    bizNo = "#orderDTO.orderNo",
    operator = "#user.username"
)
@PostMapping("/order")
public Result<OrderVO> createOrder(@RequestBody OrderDTO orderDTO) {
    // 业务逻辑
    return Result.success(orderService.create(orderDTO));
}
```

#### 3.4 获取当前用户信息

```java
@Service
public class OrderServiceImpl implements OrderService {
    
    @Override
    public OrderVO create(OrderDTO dto) {
        // 获取当前登录用户 ID
        Long userId = UserContext.getUserId();
        String username = UserContext.getUsername();
        
        // 业务逻辑...
    }
}
```

#### 3.5 统一异常处理

```java
// 框架会自动捕获并处理所有异常
// 业务代码只需抛出异常即可
if (order == null) {
    throw new BusinessException(ErrorCodeConstants.DATA_NOT_FOUND, "订单不存在");
}
```

## 注意事项

1. **Redis 依赖**: 幂等性和限流功能需要 Redis 支持，确保项目中引入了 Redis 依赖
2. **上下文清理**: UserContext 和 TraceContext 使用 ThreadLocal，已在拦截器中自动清理
3. **配置覆盖**: 所有自动配置都可以通过 `@ConditionalOnMissingBean` 进行覆盖
4. **性能考虑**: 生产环境建议根据实际场景调整线程池参数和限流阈值

## 后续计划

- [ ] 添加数据权限注解
- [ ] 集成 Sentinel 实现更强大的限流
- [ ] 添加分布式锁工具类
- [ ] 支持更多的序列化协议
- [ ] 添加操作日志存储实现

## 许可证

Internal Use Only - 仅供内部使用