# webcommon

**Repository Path**: goddesszz/webcommon

## Basic Information

- **Project Name**: webcommon
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-12-04
- **Last Updated**: 2026-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Webcommon

### 介绍
Webcommon 是一个基于 Spring Boot 3.x 的通用工具组件库，专为 Java 17+ 环境设计。
该组件库封装了 Web 开发中常用的工具类和功能模块，旨在提高开发效率，减少重复代码，提供统一的解决方案。
具体主要依赖现成的第三方组件，而非自己造轮子。

### 主要特性
- 🚀 **开箱即用**：基于 Spring Boot 自动配置，零配置启动
- 🔧 **功能丰富**：涵盖权限控制、日志记录、异常处理、文件上传等核心功能
- 🛡️ **安全可靠**：内置幂等性校验、参数签名验证等安全机制
- 🌍 **国际化支持**：完善的多语言消息处理
- 📦 **模块化设计**：各功能模块独立可选，按需引入

### 功能模块

#### 🔐 权限认证模块
- 用户登录信息自动填充
- 请求权限白名单管理
- Feign 请求头用户信息透传

#### 📝 日志记录模块
- 访问日志自动记录
- 操作日志切面处理
- 访问监控过滤器

#### 🌐 Web请求处理模块
- 接口响应数据封装
- 全局异常处理器
- 统一错误码管理
- 查询参数处理
- 请求参数校验

#### 🔒 安全防护模块
- 幂等性校验
- 参数签名验证
- 数据隐私脱敏

#### 📤 文件处理模块
- MinIO 对象存储集成
- 文件上传下载
- 头像生成工具

#### 🔄 数据处理模块
- 数据观察者模式
- Redis 缓存工具
- 实体审计功能

#### 🛠️ 工具组件
- 参数校验约束
- 数据拷贝工具
- ZIP 压缩工具
- I18n消息工具类
- Redis缓存封装工具

### 环境要求
- Java 17+
- Spring Boot 3.4.6+
- Maven 3.9+

### Maven 依赖

在您的 `pom.xml` 中添加以下依赖：

```xml
<dependency>
    <groupId>io.gitee.goddesszz</groupId>
    <artifactId>webcommon</artifactId>
    <version>1.0.7</version>
</dependency>
```

### 使用方式

#### 1. 基础配置
在您的 Spring Boot 启动类上添加 `@SpringBootApplication` 注解：

```java
@SpringBootApplication
public class YourApplication {
    public static void main(String[] args) {
        SpringApplication.run(YourApplication.class, args);
        System.err.printf("application startup success... [server.port=%s, spring.profiles.active=%s]%n", SpringContextHolder.getProperty("server.port"), SpringContextHolder.getProperty("spring.profiles.active"));
    }
}
```

#### 2. 启用特定功能

##### 启用 MinIO 文件上传功能
```java
@SpringBootApplication
@EnableMinioClient
public class YourApplication {
    // ...
}
```

##### 启用 MyBatis 审计功能
```java
@SpringBootApplication
@EnableMybatisAudit
public class YourApplication {
    // ...
}
```

#### 3. 核心功能使用示例

##### 异常处理
```java
@RestController
public class DemoController {
    
    @GetMapping("/test")
    public ApiResult<String> test() {
        throw new ServiceException(BizError.DEFAULT_ERROR);
    }
}
```

##### 访问日志记录
```java
@RestController
public class DemoController {
    
    @AccessLog("用户查询操作")
    @GetMapping("/users")
    public ApiResult<List<User>> getUsers() {
        // 业务逻辑
        return success(userService.findAll());
    }
}
```

##### 幂等性校验
```java
@RestController
public class DemoController {
    
    @PostMapping("/order")
    @EnsureIdempotent(expireSeconds = 300)
    public ApiResult<Order> createOrder(@RequestBody OrderDto orderDto) {
        // 创建订单逻辑
        return success(orderService.create(orderDto));
    }
}
```

##### 参数签名验证
```java
@RestController
public class DemoController {
    
    @PostMapping("/secure/api")
    @EnsureSafeSign
    public ApiResult<String> secureApi(@RequestBody SecureRequest request) {
        // 安全接口逻辑
        return success("处理成功");
    }
}
```

##### 权限白名单配置
```java
@RestController
@RequestMapping("/api/public")
public class PublicController {
    
    @NonePermission
    @GetMapping("/health")
    public ApiResult<String> healthCheck() {
        return success("OK");
    }
}
```

### 配置选项

在 `application.yml` 中可配置以下选项：

```yaml
# 访问监控日志
access-monitor:
  log:
    enabled: true

# 缓存配置
cache:
  expire-time: 60

# 客户端配置
client:
  appSecret: your-app-secret

# 权限白名单扫描包
none-permission:
  url-scanner-package: com.yourcompany.yourapp
```

### 版本更新记录

#### v1.0.7
- 升级 Spring Boot 至 3.4.6
- 优化自动配置逻辑
- 修复已知问题

#### v1.0.6
- 添加数据观察者模式
- 增强 Redis 缓存工具
- 改进异常处理机制

### 贡献指南
欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。

### 开源协议
本项目采用 MIT 协议开源。

### 联系方式
- 作者：goddesszz
- 邮箱：1406103364@qq.com
- Gitee：https://gitee.com/goddesszz/webcommon