【SpringBoot3】使用Easy-Trans做字典翻译

最新推荐文章于 2025-08-08 09:36:55 发布

原创

最新推荐文章于 2025-08-08 09:36:55 发布 · 3.8k 阅读

22 ·

CC 4.0 BY-SA版权

文章标签：

#springboot #java #编程 #数据字典

在项目中经常会有一些根据id从某个表中查name或者从数据字典表中根据code查name的场景。

Easy-Trans 可以非常优雅的实现以上需求，可以有效减少字段冗余。

Easy-Trans介绍

适用场景

有userId/idCardNo(身份证号码-唯一键场景) 需要 userName，无需联表查询。
有gender code 0 需要男。
枚举指定属性给前端
反向翻译

亮点

缓存支持
跨微服务翻译支持(User和Order 是2个不同微服务，order里面有userId 需要userName)
国际化支持
多种ORM框架适配
多数据源支持
集合支持(userIds [1,2,3] 翻译为张三,李四,王五)
反向翻译支持男->gender 0 张三->user_id 1 陕西分公司财务部 -> org_id 1

一、配置参数说明

在yaml中添加如下配置：

easy-trans:
   #启用redis缓存 如果不用redis请设置为false
   is-enable-redis: true
   #启用全局翻译(拦截所有responseBody进行自动翻译)，如果对于性能要求很高可关闭此配置在方法上使用注解翻译
   is-enable-global: true 
   #启用平铺模式 手动翻译无效
   is-enable-tile: true
   #字典缓存放到redis 微服务模式请开启
   dict-use-redis: true 
   #使用@RpcTrans来标记哪些类可以进行RPC翻译，默认为关闭，多团队协作推荐开启
   is-enable-custom-rpc: true
   # ruoyi相关的框架请开启
   is-enable-map-result: true
   # 反向翻译数据库类型 mysql
   db-type: mysql 
   # Mybatis-plus 为 3.5.3.2版本以上的3.x 版本请设置为true
   mp-new: true

二、核心注解`@Trans`说明

1、参数说明

1、type
指定翻译的数据源
easy trans支持多种数据源，所以要手动指定。
可选值：

TransType.AUTO_TRANS 自动自定义数据源翻译，左侧有单独的章节讲解如何自定义数据源。
TransType.DICTIONARY 字典缓存为数据源
TransType.SIMPLE 本微服务/单体项目系统自动查表作为数据源
TransType.RPC 自动调用其他微服务接口进行自动查表作为数据源

2、key
指定具体数据源(type为TransType.AUTO_TRANS或者TransType.DICTIONARY才需要配置)

type为TransType.DICTIONARY 传入字典分组编码比如orderStatus

3、ref
将翻译出来的数据映射到本pojo的某个属性上
比如根据userId翻译userName，vo中已经有userName了（必须手动在vo定义username属性，否则翻译失败），可以通过ref对vo的username进行赋值。

4、refs
类似ref，不过支持多个，是数组格式不是字符串逗号分隔哦

----推荐使用平铺模式来代替ref和refs(详情见左侧平铺模式)----

5、target
TransType.SIMPLE的时候指定对方的po类
比如是userId那么就指定UserPo.class

6、targetClassName
TransType.RPC的时候指定对方的po类全名 @since 2.2.12 TransType.SIMPLE类型也支持
com.ucenter.po.User

7、fields
用来指定我需要对方类的要哪个字段(TransType.SIMPLE和TransType.RPC可用)
支持指定多个，数组格式，不是字符串分隔哦

8、alias
别名，解决翻译结果字段名重名问题
一个vo有createUserId和updateUserId 他们的结果都叫userName 就可以通过别名来区分，比如updateUserId配置了update 那么结果就为updateUserName。

9、serviceName
微服务名称(TransType.RPC 有效)
TransType.RPC的时候组件自动调用其他微服务的接口获取数据，所以要指定服务名称，easyTrans会自动去注册中心获取对应的服务实例URL进行调用。

10、serviceContextPath
服务的context-path
如果远程微服务配置了context-path 可以通过此属性来配置，保证RPC调用不会404

11、 uniqueField
vo中的属性不是对方的id，而是唯一键，这里配置target类唯一键的字段名。
TransType.RPC 和TransType.SIMPLE 可用。
注意：不支持同一个类中混用id和唯一键，比如：Student类中有createUserId 和 updateUserMobile（用户的唯一键字段）

12、dataSource
数据源名称
在多数据源环境下指定此翻译使用哪个数据源 TransType.SIMPLE 有效。

13、sort
翻译顺序
比如文章表有createBy 字段对应用户表用户表有orgid字段对应组织表。
文章vo需要展示创建人以及创建人所在部门。就可以指定sort 先对createBy字段进行翻译，取orgid用ref设置到文章vo上，然后再用orgid翻译org的名称。

2、`@Trans`源码

@Retention(RetentionPolicy.RUNTIME)
@Target({
   
   ElementType.FIELD})
public @interface Trans {
   
   

    /**
     * 获取翻译类型，比如 wordbook 是字典
     *
     * @return 类型
     */
    String type();

    /**
     * 字段 比如  要翻译男女 上面的type写dictionary 此key写sex即可
     *
     * @return
     */
    String key() default "";

    /**
     * 设置到的target value  比如我有一个sex字段，有一个sexName 字段  sex是0 设置ref翻译服务可以自动把sexname设置为男
     * 目标类字段配置了多个 有teacherName,teacherage 两个字段   我想要teacherName  可以写 teacherName#name
     *
     * @return
     */
    String ref() default "";

    /**
     * ref 支持多个，为了保持兼容新加了一个字段
     * 作用同ref 只是支持多个
     *
     * @return
     */
    String[] refs() default {
   
   };

    /**
     * 目标class
     *
     * @return
     */
    Class<? extends VO> target() default TransPojo.class;

    /**
     * 需要目标class哪些字段
     *
     * @return
     */
    String[] fields() default {
   
   };

    /**
     * 别名
     *
     * @return
     */
    String alias() default "";

    /**
     * 远程服务名称
     *
     * @return
     */
    String serviceName() default "";

    /**
     * 远程服务 ContextPath
     *
     * @return
     */
    String serviceContextPath() default "";

    /**
     * @return
     */
    String targetClassName() default "";

    /**
     * 自定义的函数名(此名称需要被spring托管 并实现FuncGetter)
     * @return
     */
    String customeBeanFuncName() default "";

    /**
     * 数据源
     * @return
     */
    String dataSource() default "";

    /**
     *  唯一键字段
     * 部分的时候表里的code，身份证号码，手机号等也是唯一键
     * @return
     */
    String uniqueField() default "";

    /**
     *  排序字段,一般用于级联翻译
     * @return
     */
    int sort() default 0;
}

三、支持的转换类型

1、字典翻译(TransType.DICTIONARY)

需要使用者把字典信息刷新到DictionaryTransService 中进行缓存，使用字典翻译的时候取缓存数据源

2、简单翻译(TransType.SIMPLE)

比如有userId需要userName或者userPo给前端，原理是组件使用MybatisPlus/JPA的API自动进行查询，把结果放到transMap中。

3、跨微服务翻译(TransType.RPC)

比如订单和用户是2个微服务，但是我要在订单详情里展示订单的创建人的用户名，需要用到RPC翻译，原理是订单微服务使用restTemplate调用用户服务的一个统一的接口，把需要翻译的id传过去，然后用户微服务使用MybatisPlus/JPA的API自动进行查询把结果给订单微服务，然后订单微服务拿到数据后进行翻译，当然使用者只是需要一个注解，这些事情都是由组件自动完成的。

4、AutoTrans(TransType.AUTO)

还是id翻译name场景，但是使用者如果想组件调用自己写的方法而不通过Mybatis Plus/JPA 的API进行数据查询，就可以使用AutoTrans

5、枚举翻译(TransType.ENUM)

比如我要把SEX.BOY 翻译为男，可以用枚举翻译。

四、使用示例

1、引入依赖

<dependency>
    <groupId>com.fhs-opensource</groupId> <!-- VO 数据翻译 -->

最低0.47元/天解锁文章

200万优质内容无限畅学