快速开始

概述

本章将简单的介绍如何在 SpringBoot 项目中基本的使用 crane4j。

一、引入 cranej4

若你是 SpringBoot 项目，直接引入 crane4j-spring-boot-starter 依赖即可：

<dependency>
    <groupId>top.crane4j</groupId>
    <artifactId>crane4j-spring-boot-starter</artifactId>
    <version>${last-version}</version>
</dependency>

在启动类添加 @EnableScane 注解启用自动配置，并添加 doSomething 方法，下文代码默认执行于该方法：

@EnableCrane4j // 启用 crane4j
@SpringBootApplication
public class Application {

    @Autowrite
    private OperateTemplate operateTemplate;

    @PostConstruct
    public void doSomething() {
        // 下文示例执行的代码
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

OperateTemplate 为 crane4j 参照 Spring 中各种 XXXTemplate 提供的辅助类，用于简化手动填充；

二、配置数据源

第二步，我们先提前配置两个数据源，一个用于根据 id 返回 StudentClass 对象，另一个用于根据字典值返回性别名称：

StudentClass 如下：

@AllArgsConstructor // 使用 lombok 生成 get 方法和全参构造器
@Getter
public class StudentClass {
    private Integer id;
    private String name;
}

创建两个容器，并将其注册到 Spring 中：

@Configuration
public class DataContainerConfig {

    // 声明应该 namespace 为 student-class ，能够根据 classId 返回 StudentClass 的数据源容器
    @Bean
    public Container<Integer> studentClassContainer() {
        // 输入 [1, 2]
        // 返回 {1={ id = 1, name = class1 }, 2={ id = 2, name = "class2"}
        return LambdaContainer(
            "student-class",  ids -> ids.stream().collect(
                Collectors.toMap(Fucntion.identity, id -> new StudentClass(id, "一年" + id + "班")
            )
        )
    }
    
    // 声明一个 namespace 为 gender，能够根据字典值返回性别名称的数据源容器
    @Bean
    public Container<String> genderContainer() {
        Map<Integer> sources = new HashMap<>();
        sources.put(0, "女");
        sources.put(1, "男");
        return ConstantContainer.forMap("gender", sources);
    }
}

• crane4j 中的数据源容器即数据源，一个容器实例对应一个填充数据源；
• 除了上述的编码式注册外，也支持通过更多种途径创建更多数据源类型的容器，具体参考后文数据源容器一节。

三、配置并完成填充操作

配置

创建一个 Student 类，我们将根据其 classId 字段获取 StudentClass 对象，并将 StudentClass.name 映射至 Student.className ：

@RequiredArgsConstructor // 使用 lombok 生成 get 方法和构造器
@Getter
@Setter
public class Student {
    private final String name;

    @Assemble(namespace = "student-class", props = @Mapping(src = "name", ref = "className"))
    private final Integer classId;
    private String className;

    @Assemble(namespace = "gender", props = @Mapping(ref = "sexName"))
    private final Integer sex;
    private String sexName;
}

执行代码

然后我们在项目启动后执行下述代码：

public void doSomething {
    List<Student> students = Arrays.asList(
        new Student("小红", 1, 0), new Student("小明", 2, 1)
    );
    operateTemplate.execute(students);
}

执行后，students 中的对象将会被填充：

[
    {
        "name": "小红",
        "classId": 1,
        "className": "一年1班",
        "sex": 0,
        "sexName": "女"
    },
    {
        "name": "小明",
        "classId": 2,
        "className": "一年2班",
        "sex": 1,
        "sexName": "男"
    }
]

• @Assemble 注解用于声明一次填充操作，在 crane4j 中称为 装配，具体参见后文装配操作一节；
• @Mapping 用于指明数据源对象上的字段要如何映射到待处理对象的字段上，具体参见后文字段映射一节；
• 上述示例为手动填充的基本流程，如果在 Spring 环境中还支持自动填充，具体参见后文自动填充一节；

四、配置并完成嵌套填充

配置

假如我们有一个多级的嵌套的结构，我们可以通过 @Disassemble 去声明一个拆卸操作：

@RequiredArgsConstructor
@Data
public class Student {
    private final String name;
    
    // 声明拆卸操作并指定类型，若为泛型或不确定类型，也可以不指定等运行时自动解析
    // 字段的类型可以是数组、集合或者单个对象
    @Disassemble(type = StudentClass.class)
    private final StudentClass studentClass; 
}

@RequiredArgsConstructor
@Data
public class StudentClass {
    @Assemble(namespace = "student-class", @Props = @Mapping(src = "name", ref = "name"))
    private final Integer id;
    private String name;
}

执行代码

然后我们依然在项目启动后执行下述代码：

public void doSomething {
    List<Student> students = Arrays.asList(
        new Student("小红", new StudentClass(1)), new Student("小明", new StudentClass(2))
    );
    operateTemplate.execute(students);
}

执行后，students 中的对象将会被填充：

[
    {
        "name": "小红",
        "studentClass": {
            "id": 1,
            "name": "一年1班"
        }
    },
    {
        "name": "小明",
        "studentClass": {
            "id": 2,
            "name": "一年2班"
        }
    }
]

对于嵌套的对象，填充前需要先将其取出并展开，在 crane4j 中将该步操作称为拆卸，具体参见后文拆卸操作一节；