# dict-translator
**Repository Path**: huyaoying/dict-translator
## Basic Information
- **Project Name**: dict-translator
- **Description**: Java项目,基于Jackson实现字典自动翻译
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-08-05
- **Last Updated**: 2025-08-05
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 🚀 Java字典自动翻译项目
🎯 基于Spring Boot + Jackson序列化器实现的高性能字典自动翻译解决方案
支持数据库字典和枚举字典的自动翻译,提供灵活的缓存策略和完善的监控体系
---
## 📋 目录
- [功能特性](#-功能特性)
- [技术栈](#-技术栈)
- [快速开始](#-快速开始)
- [使用说明](#-使用说明)
- [项目结构](#-项目结构)
- [测试API](#-测试api)
- [核心特性](#-核心特性)
- [扩展功能](#-扩展功能)
- [注意事项](#-注意事项)
- [贡献指南](#-贡献指南)
- [许可证](#-许可证)
## ✨ 功能特性
### 🎯 核心功能
- 🔄 **字典自动翻译** - 通过`@DictField`注解标记字段,自动进行字典翻译
- 📚 **多种字典类型** - 支持数据库字典和枚举字典
- ⚡ **高性能缓存** - 使用Redis缓存提高翻译性能
- 🏷️ **自动字段生成** - 自动生成原字段名+Name的展示字段
- 🔗 **嵌套对象支持** - 支持嵌套对象内的字典字段翻译
- 🔧 **Jackson深度集成** - 完全集成Jackson序列化器
|
### 🚀 高级特性
- 💾 **动态缓存配置** - 字段级别的缓存策略控制
- 📊 **缓存监控** - 完善的缓存统计和管理API
- 🔄 **缓存预热** - 应用启动时预加载热点数据
- 🛡️ **降级处理** - Redis异常时自动降级到数据库
- 📈 **性能优化** - RedisTemplate直接操作,性能更优
- 🔍 **详细日志** - 完整的操作日志便于问题排查
|
## 🛠️ 技术栈
| 技术 | 版本 | 描述 |
|------|------|------|
|  | 2.7.14 | 🌱 核心框架,提供自动配置和依赖注入 |
|  | 2.15.2 | 🔄 JSON序列化框架,实现字典翻译核心逻辑 |
|  | 3.5.3.1 | 🗄️ 数据库ORM框架,简化数据库操作 |
|  | Latest | ⚡ 缓存数据库,提供高性能缓存支持 |
|  | 8.0+ | 🐬 关系型数据库,存储字典数据 |
|  | Latest | 🔧 代码生成工具,减少样板代码 |
## 🚀 快速开始
### 🎯 只需5步,快速体验字典翻译功能!
---
### 📋 步骤 1: 环境准备
> 🔧 **系统要求**
**☕ Java**

JDK 8 或更高版本
|
**🐬 MySQL**

MySQL 8.0 或更高版本
|
**⚡ Redis**

Redis 服务器
|
### 📋 步骤 2: 数据库初始化
```sql
-- 创建数据库
CREATE DATABASE dict_translator
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
```
### 📋 步骤 3: 配置文件
编辑 `src/main/resources/application.yml`:
```yaml
spring:
# 数据库配置
datasource:
url: jdbc:mysql://localhost:3306/dict_translator?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
username: your_username
password: your_password
# Redis配置
redis:
host: localhost
port: 6379
password: your_redis_password # 如果没有密码可以删除此行
```
### 📋 步骤 4: 启动项目
```bash
# 使用Maven启动
mvn spring-boot:run
# 或者先编译再运行
mvn clean package
java -jar target/dict-translator-1.0.0.jar
```
### 📋 步骤 5: 验证功能
🎉 **测试API接口**
```bash
# 基础功能测试
curl http://localhost:8080/api/users/test
# 缓存配置测试
curl http://localhost:8080/api/cache/test
```
**✅ 看到JSON响应数据说明部署成功!**
预期返回结果:
```json
{
"id": 1,
"name": "张三",
"status": 1,
"statusName": "启用",
"gender": "M",
"genderName": "男",
"deptId": "001",
"deptIdText": "技术部",
"detail": {
"email": "zhangsan@example.com",
"phone": "13800138000",
"education": "bachelor",
"educationName": "本科",
"maritalStatus": "single",
"maritalStatusName": "单身"
},
"roles": [
{
"roleId": 1,
"roleType": "admin",
"roleTypeName": "管理员",
"roleName": "系统管理员"
},
{
"roleId": 2,
"roleType": "user",
"roleTypeName": "普通用户",
"roleName": "普通用户"
}
]
}
```
## 📖 使用说明
### 🏷️ 1. 字典字段注解
> 💡 **核心概念**:通过 `@DictField` 注解标记需要翻译的字段,系统会自动生成对应的显示字段。
**📚 数据库字典示例**
```java
// 性别字段翻译
@DictField(
dictType = DictType.DATABASE,
dictCode = "gender"
)
@JsonSerialize(using = DictFieldSerializer.class)
private String gender;
// 自动生成: genderName
// 部门字段翻译(自定义后缀)
@DictField(
dictType = DictType.DATABASE,
dictCode = "department",
nameSuffix = "Text"
)
@JsonSerialize(using = DictFieldSerializer.class)
private String deptId;
// 自动生成: deptIdText
```
|
**🔢 枚举字典示例**
```java
// 状态字段翻译
@DictField(
dictType = DictType.ENUM,
dictCode = "com.lau.dicttranslator.enums.StatusEnum"
)
@JsonSerialize(using = DictFieldSerializer.class)
private Integer status;
// 自动生成: statusName
// 优先级字段翻译
@DictField(
dictType = DictType.ENUM,
dictCode = "com.lau.dicttranslator.enums.PriorityEnum",
enableCache = true,
cacheExpire = 86400
)
@JsonSerialize(using = DictFieldSerializer.class)
private Integer priority;
// 自动生成: priorityName
```
|
### ⚙️ 2. 注解参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `dictType` | `DictType` | ✅ | - | 🔧 字典类型:`DATABASE` 或 `ENUM` |
| `dictCode` | `String` | ✅ | - | 📝 数据库字典代码 或 枚举类全名 |
| `nameSuffix` | `String` | ❌ | `"Name"` | 🏷️ 生成显示字段的后缀名 |
| `enableCache` | `boolean` | ❌ | `true` | ⚡ 是否启用缓存功能 |
| `cacheExpire` | `int` | ❌ | `3600` | ⏰ 缓存过期时间(秒) |
> 📌 **提示**:合理配置缓存参数可以显著提升系统性能!
### 3. 动态缓存配置
支持为每个字段单独配置缓存策略:
```java
/**
* 高频访问字段:长期缓存
*/
@DictField(
dictType = DictType.DATABASE,
dictCode = "gender",
enableCache = true,
cacheExpire = 7200 // 2小时
)
@JsonSerialize(using = DictFieldSerializer.class)
private String gender;
/**
* 实时性要求高的字段:禁用缓存
*/
@DictField(
dictType = DictType.DATABASE,
dictCode = "status",
enableCache = false // 每次都查询最新数据
)
@JsonSerialize(using = DictFieldSerializer.class)
private String status;
/**
* 枚举字段:超长期缓存
*/
@DictField(
dictType = DictType.ENUM,
dictCode = "com.lau.dicttranslator.enums.StatusEnum",
enableCache = true,
cacheExpire = 86400 // 24小时
)
@JsonSerialize(using = DictFieldSerializer.class)
private Integer priority;
```
### 4. 缓存策略建议
| 字段类型 | 建议配置 | 说明 |
|---------|---------|------|
| 基础数据字典 | `enableCache=true, cacheExpire=7200` | 性别、地区等基础数据,变化频率低 |
| 组织架构 | `enableCache=true, cacheExpire=3600` | 部门、岗位等,中等变化频率 |
| 业务状态 | `enableCache=false` | 订单状态、审批状态等,需要实时性 |
| 枚举常量 | `enableCache=true, cacheExpire=86400` | 代码中定义的枚举,基本不变 |
### 5. 枚举字典实现
枚举类需要实现`getNameByCode`静态方法:
```java
public enum StatusEnum {
ACTIVE(1, "启用"),
INACTIVE(0, "禁用");
private final Integer code;
private final String name;
// 构造方法和getter省略...
public static String getNameByCode(Integer code) {
if (code == null) return null;
for (StatusEnum status : values()) {
if (status.getCode().equals(code)) {
return status.getName();
}
}
return null;
}
}
```
### 6. 数据库字典表结构
```sql
CREATE TABLE IF NOT EXISTS dict_data (
id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID',
dict_type VARCHAR(100) NOT NULL COMMENT '字典类型',
dict_key VARCHAR(100) NOT NULL COMMENT '字典键值',
dict_label VARCHAR(200) NOT NULL COMMENT '字典标签',
sort_order INT DEFAULT 0 COMMENT '排序',
status INT DEFAULT 1 COMMENT '状态 0=禁用 1=启用',
UNIQUE KEY uk_dict_type_key (dict_type, dict_key)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='字典数据表';
```
## 🏗️ 项目结构
### 📁 清晰的分层架构设计
```
📦 src/main/java/com/lau/dicttranslator/
├── 📄 DictTranslatorApplication.java # 🚀 主启动类
│
├── 📂 annotation/ # 🏷️ 注解定义
│ └── 📄 DictField.java # 字典字段注解
│
├── 📂 config/ # ⚙️ 配置类
│ ├── 📄 CacheConfig.java # 缓存配置
│ ├── 📄 JacksonConfig.java # Jackson配置
│ ├── 📄 MybatisPlusConfig.java # MyBatis Plus配置
│ └── 📄 RedisConfig.java # Redis配置
│
├── 📂 controller/ # 🎮 控制器层
│ ├── 📄 CacheManagementController.java # 缓存管理API
│ ├── 📄 CacheTestController.java # 缓存测试API
│ └── 📄 UserController.java # 用户测试API
│
├── 📂 entity/ # 🗃️ 数据实体
│ └── 📄 DictData.java # 字典数据实体
│
├── 📂 enums/ # 🔢 枚举定义
│ ├── 📄 DictType.java # 字典类型枚举
│ └── 📄 StatusEnum.java # 状态枚举示例
│
├── 📂 model/ # 📋 业务模型
│ ├── 📄 CacheExampleModel.java # 缓存配置示例
│ ├── 📄 User.java # 用户实体示例
│ ├── 📄 UserDetail.java # 用户详情实体
│ └── 📄 UserRole.java # 用户角色实体
│
├── 📂 repository/ # 🗄️ 数据访问层
│ └── 📄 DictDataMapper.java # 字典数据Mapper
│
├── 📂 serializer/ # 🔄 序列化器
│ ├── 📄 DictFieldSerializer.java # 字典字段序列化器
│ └── 📄 DictObjectSerializer.java # 对象序列化器
│
├── 📂 service/ # 🔧 业务服务层
│ ├── 📄 DictService.java # 字典服务接口
│ └── 📂 impl/
│ └── 📄 DictServiceImpl.java # 字典服务实现
│
└── 📂 util/ # 🛠️ 工具类
├── 📄 CacheUtil.java # 缓存工具类
└── 📄 SpringContextHolder.java # Spring上下文工具
```
### 🎯 架构特点
**🏷️ 注解驱动**
简单注解即可实现
字典翻译功能
|
**🔄 序列化集成**
Jackson深度集成
透明化翻译过程
|
**⚡ 高性能缓存**
Redis缓存支持
灵活的缓存策略
|
**🔧 易于扩展**
清晰的分层架构
便于功能扩展
|
## 🧪 测试API
### 🎯 完整的API测试套件
---
### 🔍 1. 基础功能测试
**📋 接口信息**
- **方法**: `GET`
- **路径**: `/api/users/test`
- **描述**: 测试字典翻译基础功能
|
**🚀 快速测试**
```bash
curl -X GET http://localhost:8080/api/users/test
```
|
### ⚡ 2. 缓存配置测试
**📋 接口信息**
- **方法**: `GET`
- **路径**: `/api/cache/test`
- **描述**: 测试不同缓存策略效果
|
**🚀 快速测试**
```bash
curl -X GET http://localhost:8080/api/cache/test
```
|
### 3. 缓存管理API
#### 3.1 缓存统计信息
```
GET http://localhost:8080/api/cache-management/stats
```
#### 3.2 清除缓存
```
# 清除指定字典类型缓存
DELETE http://localhost:8080/api/cache-management/dict/{dictType}
# 清除指定枚举类缓存
DELETE http://localhost:8080/api/cache-management/enum/{enumClassName}
# 清除所有缓存
DELETE http://localhost:8080/api/cache-management/all
```
#### 3.3 缓存监控
```
# 获取缓存键列表
GET http://localhost:8080/api/cache-management/keys?pattern=dict:cache:*
# 获取指定键详情
GET http://localhost:8080/api/cache-management/key/{key}
```
#### 3.4 缓存操作
```
# 手动设置缓存
POST http://localhost:8080/api/cache-management/set
Content-Type: application/x-www-form-urlencoded
key=test:key&value=test:value&expireSeconds=300
# 删除指定缓存
DELETE http://localhost:8080/api/cache-management/key/{key}
# 测试过期时间
POST http://localhost:8080/api/cache-management/test-expire
# 缓存预热
POST http://localhost:8080/api/cache-management/warmup
```
预期返回结果(显示不同的缓存策略):
```json
{
"id": 1,
"name": "缓存测试示例",
"gender": "M",
"genderName": "男", // 2小时缓存
"deptId": "001",
"deptIdName": "技术部", // 1小时缓存
"education": "bachelor",
"educationName": "本科", // 30分钟缓存
"status": "active",
"statusName": "激活", // 禁用缓存,实时查询
"priority": 1,
"priorityName": "启用" // 24小时缓存
}
```
## 核心特性
### 1. **动态缓存配置(RedisTemplate实现)**
- ✅ 支持字段级别的缓存开关
- ✅ 支持自定义缓存过期时间(秒级精度)
- ✅ 支持多种缓存策略在同一对象中并存
- ✅ 使用RedisTemplate直接操作Redis,性能更优
- ✅ 支持缓存降级机制,确保服务可用性
- ✅ 提供详细的缓存操作日志
### 2. **自动依赖注入修复**
- 使用SpringContextHolder解决Jackson序列化器依赖注入问题
- 支持多种获取Service实例的方式
- 提供降级处理机制
### 3. **完整的字典翻译体系**
- 支持数据库字典和枚举字典
- 支持嵌套对象翻译
- 支持集合对象翻译
### 4. **缓存管理与监控**
- ✅ 提供RESTful缓存管理API
- ✅ 支持缓存统计和监控
- ✅ 支持缓存预热功能
- ✅ 支持按模式清除缓存
- ✅ 提供缓存键的生命周期管理
## 扩展功能
1. **自定义缓存策略**:可以根据业务需求调整缓存时间和策略
2. **多数据源支持**:可以扩展支持多个数据源的字典数据
3. **国际化支持**:可以扩展支持多语言字典翻译
4. **异步翻译**:对于大量数据可以考虑异步翻译提高性能
5. **缓存预热**:可以在应用启动时预加载常用字典数据
## 注意事项
1. 确保枚举类实现了`getNameByCode`方法
2. 数据库字典数据需要预先配置
3. Redis服务需要正常运行以支持缓存功能
4. 嵌套对象内的字典字段需要正确配置`@DictField`注解和`@JsonSerialize`注解
5. 合理设置缓存过期时间,避免内存占用过多
6. 对于高并发场景,建议启用Redis连接池
## RedisTemplate实现优势
### 🚀 **性能优势**
- **直接操作Redis**:绕过Spring Cache抽象层,减少额外开销
- **精确控制过期时间**:支持秒级精度的TTL设置
- **批量操作支持**:支持批量删除和模式匹配操作
- **连接池优化**:使用Lettuce连接池,支持高并发场景
### 🎯 **功能优势**
- **字段级缓存配置**:每个字段可以独立设置缓存策略
- **动态缓存管理**:运行时可以动态调整缓存策略
- **丰富的监控API**:提供完整的缓存监控和管理接口
- **缓存预热机制**:支持应用启动时预加载热点数据
### 🛡️ **可靠性优势**
- **降级处理**:Redis异常时自动降级到数据库查询
- **异常隔离**:缓存操作异常不影响业务主流程
- **详细日志**:提供完整的缓存操作日志便于排查问题
- **统计监控**:实时统计缓存命中率和性能指标
### 💡 **使用场景建议**
| 场景 | 缓存策略 | 示例配置 |
|------|---------|---------|
| 基础配置数据 | 长期缓存 | `enableCache=true, cacheExpire=7200` |
| 业务数据 | 中期缓存 | `enableCache=true, cacheExpire=1800` |
| 实时状态 | 禁用缓存 | `enableCache=false` |
| 静态枚举 | 超长缓存 | `enableCache=true, cacheExpire=86400` |
通过RedisTemplate实现,您的字典翻译系统将拥有更好的性能、更强的控制能力和更完善的监控体系!🎉
---
## 🤝 贡献指南
我们欢迎所有形式的贡献!无论是报告bug、提出新功能建议,还是提交代码改进。
### 🌟 如果这个项目对您有帮助,请给我们一个 Star!
### 🎉 感谢使用 Java字典自动翻译项目!
**如果您觉得这个项目有用,请考虑给我们一个 ⭐ Star!**