{"id":21089211,"url":"https://github.com/luo-zhan/transformer","last_synced_at":"2025-08-20T06:06:36.376Z","repository":{"id":178556776,"uuid":"215570263","full_name":"luo-zhan/Transformer","owner":"luo-zhan","description":"Transformer可能是最简单，但最强大的字段转换插件，一个注解搞定任意转换，让开发变得更加丝滑","archived":false,"fork":false,"pushed_at":"2024-06-18T03:06:48.000Z","size":183,"stargazers_count":53,"open_issues_count":2,"forks_count":9,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-04T01:11:22.249Z","etag":null,"topics":["annotation","spring","transform","translate"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luo-zhan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-16T14:35:16.000Z","updated_at":"2025-03-21T07:46:42.000Z","dependencies_parsed_at":"2024-11-19T21:39:01.725Z","dependency_job_id":null,"html_url":"https://github.com/luo-zhan/Transformer","commit_stats":null,"previous_names":["luo-zhan/transformer"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luo-zhan%2FTransformer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luo-zhan%2FTransformer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luo-zhan%2FTransformer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luo-zhan%2FTransformer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luo-zhan","download_url":"https://codeload.github.com/luo-zhan/Transformer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254522546,"owners_count":22085148,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotation","spring","transform","translate"],"created_at":"2024-11-19T21:24:24.045Z","updated_at":"2025-05-16T11:32:52.324Z","avatar_url":"https://github.com/luo-zhan.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Transformer\n\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=luo-zhan_Transformer\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=luo-zhan_Transformer)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=luo-zhan_Transformer\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=luo-zhan_Transformer)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=luo-zhan_Transformer\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=luo-zhan_Transformer)\u003cbr\u003e\n[![GitHub](https://img.shields.io/github/license/luo-zhan/Transformer)](http://opensource.org/licenses/apache-2-0)\n[![GitHub code size](https://img.shields.io/github/languages/code-size/Robot-L/transformer)]()\n[![GitHub last commit](https://img.shields.io/github/last-commit/Robot-L/translator?label=last%20commit)]()\n\n🎉🎉🎉\n\n全新的2.X版本来了，代码全部重构，拥抱spring体系，功能更全面，性能更强劲。\n\n## 简介 / Transformer\n\nTransformer是一款功能全面的字段转换工具，只需要几个简单的注解，即可实现各种姿势的字段转换，抛弃连表查询和累赘的转换逻辑，让开发更简单。\n\n\u003e 2.X 版已在生产环境稳定运行一年，功能更强大，性能更优越，JMH测试百万数据转换仅需0.15秒\n\u003e\n![image](https://msb-edu-dev.oss-cn-beijing.aliyuncs.com/test/Transform.png)\n\n## 场景 / Situation\n\n你在**查询数据对象返回给前端**时是否也有以下场景：\n\n1. 枚举值编码转换成文本（如性别Sex，“1”要转换成“男”）需要手动转换\n2. 数据字典值转换成文本（如订单状态order_status，“1”要转换成“已下单”）需要手动转换\n3. 数据对象中的外键id要转换成name，因使用连表查询从而不得已放弃了MybatisPlus的单表增强查询功能\n4. 自定义字段转换场景（如年龄介于10-17为少年，18-45为青年...），但代码缺少可复用性，想复用的时候不顺畅\n\n以上转换场景你会发现都是固定的逻辑，却要在各个不同的需求中重复编写，影响业务开发的效率，Transformer正是用来解决这些问题的。\n\n## 功能 / Features\n\n- [x] 多种类型的转换（数据字典转换、枚举转换、表外键转换、跨服务转换等其他自定义转换）\n- [x] 开箱即用，极简的API设计，对业务代码无侵入\n- [x] 支持处理包装类型（如返回值Page、ResultWrapper这种包装类拆包后才是真正的数据）\n- [x] 支持自定义转换注解，增强扩展性（支持redis、本地缓存）\n- [x] 支持嵌套字段的转换 【2.0.0已支持】\n- [x] 转换配置缓存，转换配置首次处理后不再重复处理，节省反射开销 【2.1.0已支持】\n- [x] 转换结果缓存，同一线程转换结果放入ThreadLocal，提高批量转换的性能 【2.1.0已支持】\n- [ ] 多线程转换，进一步提高批量转换的性能\n\n如果你有好的想法或建议，欢迎提issues或PR :)\n\n## 快速上手 / Quick Start\n\n### 1. 定义VO对象，增加转换注解\n\n例如学生信息如下所示，返回给前端前须将其中的数值**转换**成可读文本\n\n```js\n{\n  \"id\": 1, \n  \"name\": \"周杰伦\", \n  \"sex\": 1,        // 性别，1-男，2-女，存储在枚举类Sex.class中\n  \"classId\": 32,   // 班级id\n  \"hobby\": 2       // 爱好，0-无爱好,1-学习,2-音乐,3-运动...（存储在数据字典表中，分组名为\"hobby\"）\n}\n```\n\nStudentVO.java定义，增加相应的几个文本字段，并加上转换注解:\n\n```java\n/** 学生信息VO */\n@Data\npublic class StudentVO {\n    private Long id;\n    // 姓名\n    private String name;\n\n    // 性别值\n    private Integer sex;\n\n    // 性别（枚举转换，Sex是性别枚举类）\n    @TransformEnum(Sex.class)\n    private String sexName;\n\n    // 爱好code\n    private Integer hobby;\n\n    // 爱好名称（数据字典转换，字典的组为\"hobby\"）\n    @TransformDict(group = \"hobby\")\n    private String hobbyName;\n\n    // 班级id\n    private Long classId;\n\n     //班级名称（自定义转换——通过班级表的id转换成班级名称）\n    @TransformClass\n    private String className;\n}\n```\n  在文本字段上使用转换注解，其中`@TransformEnum`、`@TransformDict`为内置注解，`@TransformClass`为自定义注解，组件支持自定义注解来提高扩展性，自定义注解的使用说明见下文wiki\n\n### 2. 在查询接口的方法上添加`@Transform`注解，大功告成！\n   ```java\n   /** 学生接口 */\n   @RestController\n   @RequestMapping(\"/student\")\n   public class StudentController {\n\n    /**\n     * 查询学生信息\n     * 加上@Transform注解开启字段转换\n     */\n    @Transform\n    @GetMapping(\"/{id}\")\n    public StudentVO getStudent(@PathVariable Long id) {\n        StudentVO student = ...\n        // 这里假设从数据库查询出来的数据如下：\n        // {\n        //   \"id\": 1, \n        //   \"name\": \"周杰伦\", \n        //   \"sex\": 1,         // 性别，1-男，2-女\n        //   \"hobby\": 2,       // 爱好，0-无爱好,1-学习,2-音乐,3-运动,...\n        //   \"classId\": 32     // 班级id\n        \n        // }\n        return student;\n    }\n\n}\n   ```\n\n### 3. 测试\n\n前端访问`http://localhost:8080/student/1`，响应结果如下：\n\n   ```json\n   {\n  \"id\": 1,\n  \"name\": \"Jay\",\n  \"sex\": 1,\n  \"sexName\": \"男\",\n  \"hobby\": 2,\n  \"hobbyName\": \"音乐\"\n  \"classId\": 32,\n  \"className\": \"三年二班\"\n}\n   ```\n\n完整示例代码见项目中`transform-demo`模块的`StudentController`类\n\n## 依赖 / Dependency\n   ```xml\n   \u003cdependency\u003e\n       \u003cgroupId\u003eio.github.luo-zhan\u003c/groupId\u003e\n       \u003cartifactId\u003etransform-spring-boot-starter\u003c/artifactId\u003e\n       \u003cversion\u003e2.1.2-RELEASE\u003c/version\u003e\n   \u003c/dependency\u003e\n   \n  \u003c!-- MybatisPlus扩展，增加外键id转换和Page类解包功能，非必须 --\u003e\n   \u003cdependency\u003e\n       \u003cgroupId\u003eio.github.luo-zhan\u003c/groupId\u003e\n       \u003cartifactId\u003etransform-extension-for-mybatis-plus\u003c/artifactId\u003e\n       \u003cversion\u003e2.1.2-RELEASE\u003c/version\u003e\n   \u003c/dependency\u003e\n\n    \u003c!-- MybatisFlex扩展，增加外键id转换和Page类解包功能，非必须 --\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eio.github.luo-zhan\u003c/groupId\u003e\n        \u003cartifactId\u003etransform-extension-for-mybatis-flex\u003c/artifactId\u003e\n        \u003cversion\u003e2.1.2-RELEASE\u003c/version\u003e\n    \u003c/dependency\u003e\n \n   ```\n\n## 性能 / JMH\n\n使用JMH基准测试工具，分别测试了普通转换（transform），嵌套转换（transformNest）对一万、十万、百万数据的平均处理时间。\n\n```agsl\nJMH测试报告如下：\nCPU：Intel(R) Core(TM) i7-10700 CPU @ 2.90GHz\nBenchmark                         (number)   Mode     Score   Error   Units\nTransformBenchmark.transform         10000   avgt     1.130           ms/op\nTransformBenchmark.transform        100000   avgt    16.337           ms/op\nTransformBenchmark.transform       1000000   avgt   159.852           ms/op\nTransformBenchmark.transformNest     10000   avgt     4.019           ms/op\nTransformBenchmark.transformNest    100000   avgt    48.355           ms/op\nTransformBenchmark.transformNest   1000000   avgt   469.017           ms/op\n```\n\n\u003e 注意：以上测试未包含IO访问，如果涉及IO访问，由于组件设计了转换结果缓存，所以转换性能将与IO耗时以及请求数据重复率有很大关系，所以具体性能还需根据实际情况而定。\n\n测试代码详见`transform-demo`模块的`TransformBenchmark`类。\n\n## 开源协议 / License\n\nTransformer is under the Apache-2.0 License.\n\n## 使用文档 / WIKI\n\n这里仅简单介绍效果，更多功能的详细说明请参阅 [WIKI](https://github.com/luo-zhan/Transformer/wiki)\n\n## 讨论 / Discussions\n\n有任何问题或想说的，欢迎提issues或者来讨论组内畅所欲言\n\n[💬进入讨论组](https://github.com/luo-zhan/Transformer/discussions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluo-zhan%2Ftransformer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluo-zhan%2Ftransformer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluo-zhan%2Ftransformer/lists"}