easy-trans 技术文档

easy-trans 技术文档

【免费下载链接】easy-trans easy-trans是一个数据翻译组件，开发者可以通过一个注解将vo中的id翻译为title、name；可以将字典码sex 1翻译为男/女。支持缓存、微服务等各种各样的有趣玩法。 项目地址: https://gitcode.com/dromara/easy-trans

1. 安装指南

1.1 环境要求

• JDK 1.8+
• Spring Boot 2.x 或 3.x
• 支持的ORM框架：MyBatis Plus/JPA/Beetl SQL/TK MyBatis/MyBatis Flex/easy-query

1.2 Maven依赖配置

必须引入的核心Starter：

<dependency>
    <groupId>com.fhs-opensource</groupId>
    <artifactId>easy-trans-spring-boot-starter</artifactId>
    <version>2.2.9</version>
</dependency>

按需选择ORM扩展包（只需引入一个）：

<!-- MyBatis Plus扩展 -->
<dependency>
    <groupId>com.fhs-opensource</groupId>
    <artifactId>easy-trans-mybatis-plus-extend</artifactId>
    <version>2.2.9</version>
</dependency>

<!-- JPA扩展（Spring Boot 2.x） -->
<dependency>
    <groupId>com.fhs-opensource</groupId>
    <artifactId>easy-trans-jpa-extend</artifactId>
    <version>2.2.9</version>
</dependency>

<!-- Redis支持（若启用缓存） -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

2. 项目使用说明

2.1 基础配置

在application.yml中添加以下配置：

easy-trans:
  is-enable-redis: true      # 是否启用Redis缓存
  is-enable-global: true     # 是否启用全局自动翻译
  is-enable-tile: true       # 是否启用平铺模式
  dict-use-redis: true       # 字典数据是否存Redis（微服务必开）
  mp-new: false              # MyBatis Plus 3.5.3.2+版本需设为true

2.2 禁用Redis（可选）

若无需Redis，在启动类排除自动配置：

@SpringBootApplication(exclude = { RedisAutoConfiguration.class })

2.3 字典初始化

若项目包含字典表，需初始化数据：

@Autowired
private DictionaryTransService dictionaryTransService;

// 示例：刷新性别字典
Map<String,String> sexMap = new HashMap<>();
sexMap.put("0", "男");
sexMap.put("1", "女");
dictionaryTransService.refreshCache("sex", sexMap);

3. API使用文档

3.1 实体类注解说明

在需要翻译的字段上添加@Trans注解：

@Data
public class Student implements TransPojo {
    // 字典翻译
    @Trans(type = TransType.DICTIONARY, key = "sex", ref = "sexName")
    private Integer sex;
    
    // 简单翻译（关联其他表）
    @Trans(type = TransType.SIMPLE, target = School.class, fields = "schoolName")
    private String schoolId;
    
    // 远程翻译（跨微服务）
    @Trans(type = TransType.RPC, targetClassName = "com.fhs.test.pojo.School", 
           fields = "schoolName", serviceName = "userService")
    private String remoteSchoolId;
    
    // 枚举翻译
    @Trans(type = TransType.ENUM, key = "desc")
    private StudentType studentType;
    
    public enum StudentType {
        ARTS("文科"), SCIENCES("理科");
        private String desc;
        StudentType(String desc) { this.desc = desc; }
    }
}

3.2 翻译类型详解

类型	说明	适用场景
DICTIONARY	字典翻译	性别、状态等字典值转换
SIMPLE	简单关联翻译	同库表关联查询（如user_id→user_name）
RPC	跨微服务翻译	跨服务数据关联（如订单查用户信息）
AUTO	自定义方法翻译	需手动实现数据查询逻辑
ENUM	枚举翻译	将枚举值转换为描述文本

4. 项目安装方式

4.1 本地开发环境

1. 引入上述Maven依赖
2. 配置application.yml
3. 在实体类中添加@Trans注解
4. 启动服务后，返回的JSON数据将自动包含翻译结果

4.2 微服务场景

1. 确保各服务间API网关放行/easyTrans/proxy/**路径
2. 通过Filter/Interceptor实现服务间认证
3. 自定义RestTemplate以携带认证参数

4.3 注意事项

• 若启用全局翻译（is-enable-global:true），所有实现TransPojo的返回对象会自动翻译
• 翻译结果默认存储在transMap字段中，前端可直接读取
• 建议生产环境开启Redis缓存以提高性能

【免费下载链接】easy-trans easy-trans是一个数据翻译组件，开发者可以通过一个注解将vo中的id翻译为title、name；可以将字典码sex 1翻译为男/女。支持缓存、微服务等各种各样的有趣玩法。 项目地址: https://gitcode.com/dromara/easy-trans