easy-trans 技术文档

2026-02-04 04:05:52作者：冯爽妲Honey

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`	枚举翻译	将枚举值转换为描述文本