plusone-commons/plusone-commons/docs/5_model.md

5. 数据模型

5.1. 业务模型

	类型	描述
接口	IDCardNumber	身份证号
值对象	» Chinese2ndGenIDCardNumber	中国二代居民身份证号
值对象	SemVer	语义化版本号
值对象（枚举）	Gender	性别
值对象（抽象类）	ValidatableStringRecord	带校验的字符串值对象

5.2. 数据传输对象

5.2.1. 分页查询

PagingAndSortingQueryParams （分页排序查询参数）

PagingAndSortingQueryParams 包含三个主要的属性：

• size - 每页显示的记录数
• pageNum - 当前页码
• orderBy - 排序条件

分页必须伴随着排序，不然可能出现同一个对象重复出现在不同页，有的对象不被查询到的情况。

其中 orderBy 是一个 List<String>，可以指定多个排序条件，每个排序条件是一个字符串， 格式为“属性名-ASC”或“属性名-DESC”，分别表示升序和降序。

例如当 orderBy 的值为 ["name-ASC","age-DESC"]，意味着要按 name 进行升序排列，name 相同的情况下则按 age 进行降序排列。

用户可继承 PagingAndSortingQueryParams 构建自己的分页查询入参，子类需在构造器中调用 PagingAndSortingQueryParams 的构造器，传入一个 PagingParamsBuilder 用于构建分页参数。同一场景下，复用一个 {@link PagingParamsBuilder} 实例即可。

构建 PagingParamsBuilder 时，需传入一个 Map 作为可排序字段的白名单，key 是供前端指定用于排序的属性名，value 是对应数据库中的字段名，只有在白名单中指定的属性名才允许作为排序条件。

@ToString(callSuper = true)
class AccountQueryParams extends PagingAndSortingQueryParams {

    private static final Map<String, String> PROPERTY_COLUMN_MAP = ImmutableMap.<String, String>builder()
            .put("id", "id")
            .put("username", "username")
            .build();

    private static final PagingParamsBuilder PAGING_PARAMS_BUILDER = PagingAndSortingQueryParams
            .pagingParamsBuilder(20, 100, PROPERTY_COLUMN_MAP);

    public AccountQueryParams() {
        super(PAGING_PARAMS_BUILDER);
    }

    private @Getter @Setter Long id;
    private @Getter @Setter String username;
    private @Getter @Setter String email;
    private @Getter @Setter Integer status;
}

使用时调用 PagingAndSortingQueryParams#buildPagingParams() 方法获取分页参数 PagingParams。分页结果可以存放到 PageResult 中，作为出参。

public PageResult<AccountVO> queryPage(AccountQueryParams params) {
    // 获取分页参数
    PagingParams pagingParams = params.buildPagingParams();
    // 从 params 获取字段查询条件，从 pagingParams 获取分页条件，查询一页数据
    List<AccountVO> list = accountQueries.queryAccountList(params, pagingParams);
    // 查询总记录数
    long count = accountQueries.countAccount(params);
    // 返回分页结果
    return PageResult.of(list, count);
}

5.2.2. UnifiedResponse

UnifiedResponse 对返回给前端的数据进行封装，包含 code、message、data。

UnifiedResponses 是 UnifiedResponse 的工厂类。用于快速构建 UnifiedResponse 对象，默认的成功代码为 2000000。

用户可以继承 UnifiedResponses 实现自己的工厂类，自定义 SUCCESS_CODE 和 DEFAULT_SUCCESS_MSG，以及工厂方法。如下所示：

// 自定义工厂类
public static class CustomUnifiedResponses extends UnifiedResponses {
    public static final String SUCCESS_CODE = "000";
    public static final String DEFAULT_SUCCESS_MSG = "成功";
    public static <T> UnifiedResponse<T> success() {
        return of(SUCCESS_CODE, DEFAULT_SUCCESS_MSG);
    }
    public static <T> UnifiedResponse<T> success(@Nullable String message) {
        return of(SUCCESS_CODE, message);
    }
    public static <T> UnifiedResponse<T> success(@Nullable String message, @Nullable T data) {
        return of(SUCCESS_CODE, message, data);
    }
    private CustomUnifiedResponses() {
        super();
    }
}
// 使用自定义工厂类
CustomUnifiedResponses.success("查询成功", userList); // 状态码为 000

见 issue#22 @Gitea