# common-dict **Repository Path**: creekmoon/common-dict ## Basic Information - **Project Name**: common-dict - **Description**: 通用字典组件 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-05-08 - **Last Updated**: 2025-11-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Common-Dict 通用字典工具 一个简洁优雅的 Java 字典翻译工具,帮助开发者轻松实现业务对象中编码字段的自动翻译功能。 ## 🚀 核心特性 - **零侵入性设计** - 仅需实现接口和添加注解,无需修改现有业务逻辑 - **自动递归翻译** - 支持嵌套对象和集合的深度翻译 - **灵活的翻译策略** - 支持自定义翻译器,满足复杂业务场景 - **高性能缓存** - 内置字典缓存机制,避免重复查询 - **反向查找支持** - 支持通过字典值反向查找字典键 ## 📦 快速开始 ### Maven 依赖 ```xml cn.creekmoon common-dict 0.0.3 ``` ### 基础使用 **1. 定义字典数据** ```java // 初始化字典数据 Map> dictMap = new HashMap<>(); dictMap.put("status", Map.of("1", "已启用", "0", "已禁用")); dictMap.put("level", Map.of("1", "初级", "2", "中级", "3", "高级")); Dict.setDictMap(dictMap); // 设置业务包路径(用于递归翻译) Dict.setGlobalBusinessPackageNames("com.yourcompany.domain"); ``` **2. 定义业务对象** ```java @Data public class User implements Dict { private String name; @DictMapping private String status = "1"; // 将翻译为: "已启用" @DictMapping(suffix = "用户") private String level = "2"; // 将翻译为: "中级用户" } ``` **3. 获取翻译结果** ```java User user = new User(); user.setName("张三"); // 方式1: 获取翻译结果(不影响原对象) JSONObject dictResult = user.getDict(); System.out.println(dictResult.getString("status")); // 输出: "已启用" System.out.println(dictResult.getString("level")); // 输出: "中级用户" // 方式2: 填充到原对象 user.fillSelf(); System.out.println(user.getStatus()); // 输出: "已启用" System.out.println(user.getLevel()); // 输出: "中级用户" ``` ## 🎯 实际应用场景 ### 场景一:用户管理系统 在用户管理系统中,经常需要将状态码、角色编码等转换为可读的文字。 ```java @Data public class UserInfo implements Dict { private String userName; @DictMapping // 使用字段名 'userStatus' 作为字典类型 private String userStatus = "ACTIVE"; @DictMapping(dictCode = "role", suffix = "权限") private String roleCode = "ADMIN"; @DictMapping private String departmentCode = "TECH"; } // 字典配置 Map> dictMap = new HashMap<>(); dictMap.put("userStatus", Map.of( "ACTIVE", "活跃", "INACTIVE", "停用", "PENDING", "待审核" )); dictMap.put("role", Map.of( "ADMIN", "管理员", "USER", "普通用户" )); dictMap.put("departmentCode", Map.of( "TECH", "技术部", "SALES", "销售部" )); Dict.setDictMap(dictMap); // 使用示例 UserInfo user = new UserInfo(); JSONObject result = user.getDict(); // 结果: {"userStatus": "活跃", "roleCode": "管理员权限", "departmentCode": "技术部"} ``` ### 场景二:订单系统 处理订单状态、支付方式等多种编码字段的翻译。 ```java @Data public class Order implements Dict { private String orderId; @DictMapping private String orderStatus = "PAID"; @DictMapping private String paymentMethod = "ALIPAY"; @DictMapping(dictCode = "logistics", suffix = "配送") private String logisticsType = "EXPRESS"; // 嵌套对象也会自动翻译 private OrderItem orderItem = new OrderItem(); } @Data public class OrderItem implements Dict { @DictMapping private String itemStatus = "IN_STOCK"; } // 字典配置 dictMap.put("orderStatus", Map.of( "PENDING", "待支付", "PAID", "已支付", "SHIPPED", "已发货", "DELIVERED", "已送达" )); dictMap.put("paymentMethod", Map.of( "ALIPAY", "支付宝", "WECHAT", "微信支付", "BANK", "银行卡" )); dictMap.put("logistics", Map.of( "EXPRESS", "快递", "PICKUP", "自提" )); dictMap.put("itemStatus", Map.of( "IN_STOCK", "有库存", "OUT_OF_STOCK", "缺货" )); // 使用 - 自动处理嵌套对象 Order order = new Order(); JSONObject result = order.getDict(); /* 结果: { "orderStatus": "已支付", "paymentMethod": "支付宝", "logisticsType": "快递配送", "orderItem": { "itemStatus": "有库存" } } */ ``` ### 场景三:集合数据翻译 处理列表数据的批量翻译。 ```java @Data public class Department implements Dict { private String deptName; @DictMapping private String deptType = "TECH"; private List employees = Arrays.asList( new Employee("MANAGER"), new Employee("DEVELOPER") ); } @Data public class Employee implements Dict { private String name; @DictMapping private String position; public Employee(String position) { this.position = position; } } // 字典配置 dictMap.put("deptType", Map.of( "TECH", "技术部门", "SALES", "销售部门" )); dictMap.put("position", Map.of( "MANAGER", "经理", "DEVELOPER", "开发工程师", "TESTER", "测试工程师" )); // 使用 - 自动处理集合中的所有对象 Department dept = new Department(); JSONObject result = dept.getDict(); /* 结果: { "deptType": "技术部门", "employees": [ {"position": "经理"}, {"position": "开发工程师"} ] } */ ``` ### 场景四:自定义翻译器 当默认翻译逻辑无法满足需求时,可以实现自定义翻译器。 ```java // 自定义翻译器 - 将数字评分转换为星级显示 public class StarRatingTranslator implements DictFieldTranslator { @Override public String searchDictValue(Object dictObject, Field sourceField, Object fieldValue, DictMapping annotation) { if (fieldValue == null) return null; int score = Integer.parseInt(fieldValue.toString()); return "★".repeat(Math.max(0, Math.min(5, score))) + annotation.suffix(); } } @Data public class ProductReview implements Dict { private String reviewText; @DictMapping(suffix = " 星好评", fieldTranslator = StarRatingTranslator.class) private String rating = "4"; // 将翻译为: "★★★★ 星好评" } ``` ### 场景五:多值字典翻译器 当字段包含多个逗号分隔的值需要分别翻译时,可以使用内置的多值字典翻译器。 ```java @Data public class TaskInfo implements Dict { // 多值字段翻译:1,2,3 -> 未开始,进行中,已完成 @DictMapping(fieldTranslator = MultiValueDictFieldTranslator.class) private String taskStatus = "1,2,3"; // 部分匹配:1,2,3,4 -> 未开始,进行中,已完成,4 @DictMapping(dictCode = "taskStatus", fieldTranslator = MultiValueDictFieldTranslator.class) private String mixedStatus = "1,2,3,4"; // 带后缀:HIGH,LOW -> 高优先级任务,低优先级任务 @DictMapping(dictCode = "priority", suffix = "任务", fieldTranslator = MultiValueDictFieldTranslator.class) private String priorityWithSuffix = "HIGH,LOW"; // 标签系统:TAG1,TAG2,TAG3 -> 重要,紧急,优先 @DictMapping(dictCode = "tags", fieldTranslator = MultiValueDictFieldTranslator.class) private String taskTags = "TAG1,TAG2,TAG3"; } // 字典配置 dictMap.put("taskStatus", Map.of( "1", "未开始", "2", "进行中", "3", "已完成" )); dictMap.put("priority", Map.of( "HIGH", "高优先级", "MEDIUM", "中优先级", "LOW", "低优先级" )); dictMap.put("tags", Map.of( "TAG1", "重要", "TAG2", "紧急", "TAG3", "优先" )); // 使用示例 TaskInfo task = new TaskInfo(); JSONObject result = task.getDict(); /* 结果: { "taskStatus": "未开始,进行中,已完成", "mixedStatus": "未开始,进行中,已完成,4", "priorityWithSuffix": "高优先级任务,低优先级任务", "taskTags": "重要,紧急,优先" } */ ``` **多值翻译器特性:** - ✅ **自动分割**: 按逗号分隔多个值 - ✅ **逐个翻译**: 对每个值单独进行字典查找 - ✅ **容错处理**: 没找到翻译的值保持原样 - ✅ **自动拼接**: 翻译后用逗号重新组合 - ✅ **后缀支持**: 支持添加统一后缀 **翻译效果对照表:** | 输入值 | 字典配置 | 翻译结果 | |-------|---------|---------| | `"1,2,3"` | `{"1":"未开始", "2":"进行中", "3":"已完成"}` | `"未开始,进行中,已完成"` | | `"1,2,3,4"` | `{"1":"未开始", "2":"进行中", "3":"已完成"}` | `"未开始,进行中,已完成,4"` | | `"HIGH,LOW"` + 后缀`"任务"` | `{"HIGH":"高优先级", "LOW":"低优先级"}` | `"高优先级任务,低优先级任务"` | | `"X,Y,Z"` | 无匹配 | `"X,Y,Z"` | **适用场景:** - 任务状态组合(多个并行状态) - 标签系统(对象的多个标签翻译) - 权限组合(用户的多个角色权限) - 分类系统(商品的多个分类) ``` ## 🔧 高级功能 ### 反向查找 通过字典值查找对应的字典键: ```java // 通过字典值获取字典键 String dictKey = Dict.searchDictKey("orderStatus", "已支付"); // 返回: "PAID" ``` ### 获取字典数据 ```java // 获取指定字典类型的所有键值对 Map statusDict = Dict.getKeysMap("orderStatus"); // 获取所有字典数据 Map> allDict = Dict.getAll(); ``` ### 静态方法翻译 无需实现 Dict 接口也可以进行翻译: ```java // 直接翻译指定字段 String result = Dict.searchDictValue("orderStatus", "PAID"); // 返回: "已支付" // 翻译对象(对象无需实现 Dict 接口) JSONObject result = Dict.getDict(anyObject); // 填充对象 Dict.fillSelf(anyObject); ``` ## 📝 注解配置说明 ### @DictMapping 注解参数 | 参数 | 说明 | 默认值 | 示例 | |------|------|--------|------| | `dictCode` | 字典类型编码 | 使用字段名 | `@DictMapping(dictCode = "status")` | | `suffix` | 翻译结果后缀 | 空字符串 | `@DictMapping(suffix = "权限")` | | `fieldTranslator` | 自定义翻译器 | DefaultDictFieldTranslator | `@DictMapping(fieldTranslator = CustomTranslator.class)` | ### 字段类型支持 - ✅ String 类型字段 - ✅ 基本数据类型(int, long 等) - ✅ 包装类型(Integer, Long 等) - ✅ null 值处理 - ✅ 嵌套对象 - ✅ 集合类型 ## ⚡ 性能优化建议 1. **字典数据缓存**: 字典数据会自动缓存在内存中,避免重复设置 2. **翻译器实例复用**: 自定义翻译器全局只创建一个实例,确保线程安全 3. **批量翻译**: 对于集合数据,使用 `Dict.getDict()` 比逐个翻译更高效 ## 🔍 技术细节 ### 核心架构 本工具基于反射和注解技术实现,核心组件包括: 1. **Dict 接口**: 提供字典翻译的主要功能入口 2. **@DictMapping 注解**: 标记需要翻译的字段及翻译配置 3. **DictFieldTranslator 接口**: 定义字段翻译逻辑的扩展点 4. **DefaultDictFieldTranslator**: 默认的字典翻译实现 5. **MultiValueDictFieldTranslator**: 内置的多值字典翻译器,处理逗号分隔的多值翻译 ### 翻译流程 ```mermaid graph TD A["开始翻译"] --> B["扫描对象字段"] B --> C{"字段是否有
@DictMapping注解?"} C -->|否| D["跳过字段"] C -->|是| E{"字段类型判断"} E -->|集合类型| F["递归翻译集合元素"] E -->|业务对象类型| G["递归翻译嵌套对象"] E -->|基本类型| H["获取翻译器实例"] H --> I["执行字典翻译"] I --> J["应用后缀"] J --> K["存储翻译结果"] F --> L["合并翻译结果"] G --> L D --> L K --> L L --> M{"是否还有字段?"} M -->|是| B M -->|否| N["返回完整翻译结果"] ``` ### 核心实现原理 #### 1. 字典缓存机制 ```java // 正向字典缓存:字典类型 -> 字典键 -> 字典值 static Map> DICT_MAP = new ConcurrentHashMap<>(512); // 反向字典缓存:字典类型 -> 字典值 -> 字典键列表 static Map>> DICT_MAP_REVERSE = new ConcurrentHashMap<>(512); ``` #### 2. 翻译器缓存机制 ```java // 翻译器实例缓存,避免重复创建 Map translators = new ConcurrentHashMap<>(); ``` #### 3. 递归翻译判断 工具通过以下策略判断对象是否需要递归翻译: - 实现了 `Dict` 接口的对象 - 属于配置的业务包路径下的类 - 集合类型(会遍历集合中的每个元素) #### 4. 线程安全保证 - 字典缓存使用 `ConcurrentHashMap` 确保并发安全 - 翻译器实例全局唯一,要求实现必须线程安全 - 反射操作通过 `setAccessible()` 临时开放访问权限后立即恢复 ### 扩展点 #### 自定义翻译器接口 ```java public interface DictFieldTranslator { /** * 获取翻译结果 * @param dictObject 来源翻译的整个对象 * @param sourcefield 来源字段本身 * @param fieldValue 来源字段本身的值 * @param annotationValue 来源字段携带的注解值 * @return 翻译结果 */ String searchDictValue(Object dictObject, Field sourcefield, Object fieldValue, DictMapping annotationValue); } ``` 通过实现此接口,可以完全自定义字段的翻译逻辑,支持复杂的业务场景需求。 --- ## 📄 License Apache License 2.0 ## 👨‍💻 作者 - **creekmoon** - *项目创建者* - [GitHub](https://github.com/creekmoon) --- *让字典翻译变得简单优雅 ✨*