# easy-dict

**Repository Path**: wrxfxdd/easy-dict

## Basic Information

- **Project Name**: easy-dict
- **Description**: 数据字典翻译，数据字典转换，数据字典映射 
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 10
- **Forks**: 1
- **Created**: 2025-08-27
- **Last Updated**: 2025-11-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EasyDict 1.0.7

## 开源、免费、轻量级 Java 字典翻译组件，让代码变得简单、优雅！

## 关联 数据字典转换、数据字典翻译、数据字典组件、数据字典工具

## 📖 EasyDict 介绍

EasyDict 是一款轻量级、零侵入设计 Java 数据字典转换框架，目前拥有两种数据源获取方式：实现接口、指定枚举类。四大核心功能：注解转换、缓存机制、工具类手动转换、自定义字段转义后缀等！

## ✨ 核心特性
- 🔧 **使用简单** - 只需加一个注解，无需任何配置
- 🎯 **零侵入设计** - 基于注解驱动，无需修改现有业务逻辑
- 📊 **缓存管理** - 内置缓存统计和管理功能
- 🛡️ **支持枚举数据源** - 支持项目中已有的枚举进行翻译


## 🚀 快速开始

### 1. 添加Maven依赖
#### jdk8
```xml  
<dependency>  
    <groupId>io.gitee.wrxfxdd</groupId>    
    <artifactId>easy-dict</artifactId>    
    <version>1.0.7</version>
</dependency>  
```  
#### jdk17
```xml  
<dependency>  
    <groupId>io.gitee.wrxfxdd</groupId>    
    <artifactId>easy-dict</artifactId>    
    <version>2.0.7</version>
</dependency>  
```  

### 2. 获取数据源

#### 选择数据源采用模式
| 系统字典架构  | 采用模式   | 简介                   |
|---------|--------|----------------------|
| 字典存储在数据库 | 模式一    | 只需实现获取数据源接口 、无需配置    |
| 字典使用的枚举 | 模式二    | 加注解直接使用，无需实现方法、无需配置、 |
| 两者同时存在  | 模式一+模式二 | 同时使用                 |

#### 模式一：创建一个类实现 DictProvider 接口
```java  
@Component  
public class EasyDictProvider implements DictProvider {  
    @Autowired  
    private DictionaryService dictionaryService;  
    @Override  
    public String getDictName(String typeCode, String value) {  
        // 根据typeCode和value查询字典表或缓存  
        // 示例：从数据库查询  
        return dictionaryService.getDictLabel(typeCode, value);  
    }}  
```  

#### 模式二：创建一个枚举

默认字段是 `code` 和 `label`，如果字段不一样，也无所谓，在使用注解的时候指定下即可
```java  
public enum GameTypeEnum {
    WZRY("1", "王者荣耀"),
    LOL("2", "英雄联盟");
    private final String code;
    private final String label;
    GameTypeEnum(String code, String label) {
        this.code = code;
        this.label = label;
    }
    public String getCode() {
        return code;
    }
    public String getLabel() {
        return label;
    }
}

```  
### 3. 在实体类中使用注解 
```java  
public class User {  
    private Long id;

    // 模式一：也可以自定义翻译字段后缀 @@EasyDict(dictType = "user_type", suffix = "Label")
    @@EasyDict(typeCode = "user_status")  
    private String status;
    
    // 模式二
    @@EasyDict(enumClass = GameTypeEnum.class) 
    private String gameType;
    
    // 模式二：如果枚举 code 和 label 字段不一样需要指定，通过注解属性enumCodeMethod，enumLabelMethod指定你的枚举定义的字段get方法名
    @@EasyDict( enumClass = GameTypeEnum.class,enumCodeMethod = "getCode",enumLabelMethod = "getLabel")
    private String orderType;
}  
```  

### 4. 使用效果

当对象被序列化为 JSON 时（如后端返回前端数据时），会自动添加字典字段。如果有其他场景需要翻译字典可以手动调用工具类转换
```json  
{  
    "id": 1,    
    "status": "1",   
    "statusDict": "启用",  
    "gameType": "A",    
    "gameTypeDict": "管理员"  
}  
```  

## 手动转换工具

自动序列化没有触发或是有其他场景需要转换时，可以使用手动转换工具：
```java  
@Service  
public class UserService {  
    @Autowired  
    private EasyDictUtil dictUtil; 
    
    public List<User> getUsersWithDict() {  
        List<User> users = userRepository.findAll();        // 手动转换字典  
        return dictUtil.listConverter(users);  
    }    
    
    public User getUserWithDict(Long id) {  
        User user = userRepository.findById(id);        // 转换单个对象  
        return dictUtil.convertSingleObject(user);  
    }
}  
```  


## 基础配置说明
（整段都无需配置，主要是提供修改统一翻译后缀的功能）
```yaml  
easydict:  
  # 是否启用EasyDict功能  
  enabled: true  # 字典翻译（全局配置）  
  dict-suffix: Dict  # 缓存配置  
  cache:    # 是否启用字典值缓存  
    enabled: true    # 缓存最大条目数  
    max-size: 1000    # 写入后过期时间（秒）  
    expire-after-write: 3600  # 调试配置  
```

## @@EasyDict 注解属性说明
```java  
@@EasyDict(
        typeCode = "user_status",    // 必填：字典类型代码  
        suffix = "Label",            // 可选：自定义字段后缀  
        cache = true,                // 可选：是否启用缓存  
        cacheExpire = 1800,          // 可选：缓存过期时间（秒）  
        fallback = "未知",            // 可选：解析失败时的回退值  
        priority = 1000,             // 可选：解析器优先级  
        group = "default",           // 可选：字典数据源分组（暂未实现）
        enumClass = "YourEnum.class", // 指定用于字典翻译的枚举类
        enumCodeMethod = "getCode", // 从枚举实例读取"代码"的方法名
        enumLabelMethod = "getLabel" // 从枚举实例读取"显示值"的方法名
)
```  

## 🔧 扩展功能

### 缓存管理
```java  
@RestController  
public class DictController {  
    @Autowired  
    private EasyDictManager easyDictManager;  
    // 查看缓存统计  
    @GetMapping("/dict/cache-stats")  
    public String getCacheStats() {  
        return easyDictManager.getCacheStats();  
        // 输出示例：Cache[size=156, expired=12, maxSize=1000]  
    }
    
    // 清理缓存  
    @PostMapping("/dict/cache/clear")  
    public String clearCache() {  
        easyDictManager.clearCache();  
        return "缓存已清理";  
    }
    
    // 检查组件状态  
    @GetMapping("/dict/status")  
    public EasyDictManager.ComponentStatus getStatus() {  
        return easyDictManager.getComponentStatus();  
    }
}  
```  

### 静态工具方法
```java  
// 直接转换单个值  
String dictValue = EasyDictUtil.convertDictValue(  
    "user_status", "1", dictProvider);  
```  

## 🔍 功能实现状态
### ✅ 已实现功能

| 功能模块        | 实现状态 | 说明             |  
|-------------|----------|----------------|  
| **核心转换**    | ✅ 完全实现 | 基于Jackson的字典转换 |  
| **注解支持**    | ✅ 完全实现 | @@EasyDict |  
| **自动配置**    | ✅ 完全实现 | Spring Boot自动配置 |  
| **缓存机制**    | ✅ 完全实现 | LRU缓存 + 过期时间   |  
| **缓存管理**    | ✅ 完全实现 | 统计信息 + 手动清理    |  
| **配置支持**    | ✅ 完全实现 | 丰富的配置选项        |  
| **手动转换**    | ✅ 完全实现 | 工具类支持          |  
| **异常处理**    | ✅ 完全实现 | 完善的回退机制        |  
| **自定义后缀**   | ✅ 完全实现 | 支持全局和字段级配置     |  
| **枚举数据源翻译** | ✅ 完全实现 | 指定项目中已有的枚举进行翻译 |  

### ⚠️ 部分实现功能

| 功能模块 | 实现状态 | 说明 |  
|----------|----------|------|  
| **字段级缓存控制** | ⚠️ 部分实现 | 注解中的cache属性已定义但未完全生效 |  
| **自定义回退值** | ⚠️ 部分实现 | fallback属性已定义但未完全生效 |  

### ❌ 未实现功能

| 功能模块       | 实现状态  | 说明                |     |
| ---------- | ----- | ----------------- | --- |
| **字典分组**   | ❌ 未实现 | group属性预留，暂未实现    |     |
| **多数据源**   | ❌ 未实现 | 多DictProvider路由机制 |     |
| **解析器优先级** | ❌ 未实现 | priority属性预留，暂未实现 |     |


### 下版本升级功能

暂无


## 升级日志

- **1.0.5**: 第一版发布，通过实现接口获取数据源。四大核心功能：注解转换、缓存机制、工具类手动转换、自定义字段转义后缀等
- **1.0.6**: 新增支持项目中的枚举类获取数据源 `@@EasyDict(enumClass = GameTypeEnum.class)` 


## 🚨 注意事项

### 必要条件

1. **Spring Boot 环境** - 需要 Spring Boot 2.0+
2. **DictProvider 实现** - DictProvider 需要注册为 Bean

### 常见问题

1. **字典字段不显示** - 检查 DictProvider 是否正确注册为 Bean
2. **缓存不生效** - 检查缓存配置是否正确
3. **数据一致性** - 字典数据变更时及时清理缓存

## ⭐ 支持项目

如果 EasyDict 对你有帮助，欢迎：

- ⭐ **给个 Star** - 让更多人发现这个项目
- 🐛 **报告问题** - 帮助我们改进和完善
- 💡 **提出建议** - 分享你的想法和需求
- 📢 **分享推荐** - 推荐给更多开发者使用

你的支持是我们持续改进的动力！

## ⭐ 新项目预告

后续推出注解自动转换外键字段需要映射的字段


## 🔗 相关链接

- [GitHub 仓库](https://github.com/your-org/easy-dict)
- [API 文档](https://your-org.github.io/easy-dict/javadoc/)
- [更新日志](CHANGELOG.md)
- [问题反馈](https://github.com/your-org/easy-dict/issues)