# easy-excel

**Repository Path**: lovememo/easy-excel

## Basic Information

- **Project Name**: easy-excel
- **Description**: 开发目的,省去复杂的excel代码
使用xml配置的形式完成导入导出
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 84
- **Created**: 2017-12-24
- **Last Updated**: 2020-12-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 通用文件导入说明 v0.8
> 暂时仅仅实现了excel解析

## 一、模板说明

在`src`下的`import_template_config.xml`配置文件中，`<templates>`节点下可以配置多个excel文件的模板解析规则配置，说明如下：
* `<template>`定义了一个解析模板，针对excel仅仅支持一个sheet（可以指定sheet页面），有如下属性：
    * `templateCode`为模板编码，唯一定义一个模板。excel建议以excel0001顺序向下编码
    * `name` 模板名称
    * `fileType` 解析的文件类型，针对EXCEL，只要填写“EXCEL"即可。更多后续支持的类型可以参考`FileType`类
* `<template>`定义可选属性节点`<optional>`
    * `class`属性指定为`ExcelTemplateOptional`即可
    * `<sheetIndex>`指定解析的`excel` `sheet`页，从0开始计数。
* `<sections>`下的`<section>`节点指定了一个`sheet`所需要解析的区域/范围。可指定多个`<section>`。这里主要考虑到的情况是，通常情况下，一个`sheet`可以解析其数据头（行数确定），数据体（行数不确定），数据尾（行数确定）。而`<section>`就是针对这些情况，定义了一个解析的规则，整体设计思路可以参考下图：
`<section>`有如下属性
    * `sectionIndex`指定了本`section`在所有sections中的相对位置。默认值为0.
    * `sectionType`定义了section的类型，可填写HEADER BODY FOOTER，默认值为BODY。 具体定义参考`SectionType`类。
    * `parseType`定义了解析类型，针对HEADER FOOTER指定为`FIXED`即可。针对BODY指定为`DYNAMIC`即可。默认值为`DYNAMIC`。
    * `direction`定义了解析方向，HEADER填1，BODY填0，FOOTER填写-1。默认值为0。
    * `batchSize`定义了数据处理每个批次的记录数，默认值为2000。比如excel解析出来10条数据，batchSize设置为4，则解析器每解析出来4条数据就进行处理一次，一共处理三次（最后一次处理2条数据记录）。
        > 定义该值是为了控制内存大小，防止`OutOfMemory`异常。
    * `<startRowIndex>` 解析起始行，从0开始计数
    * `<startColIndex>` 解析起始列，从0开始计数 
    * `<endRowIndex>` 解析结束列，从0开始，为负数。-1表示倒数第一行，该参数仅仅针对FOOTER和BODY有效
    * `<rowCount>` 解析的行数，仅对HEADER和FOOTER有用
    * `<colCount>` 解析的列数
    * `<fields>`下的`<field>`属性定义了解析的字段。
        * `fieldIndex`定义了字段顺序，从0开始，顺序加1
        * `name`定义了字段名，后续数据处理以`name`的值作为字段名称。
        * `description`定义了字段说明，一般为中文说明
        * `validator` 定义了字段校验器，详见[校验规则定义](#validator)说明。
        * `filterError`默认为true。配合validator使用。当该字段解析出来的结果通过validator校验验证没有通过且同时filterError为false，则该数据还是会出现在解析结果中。如果校验结果没有通过，而filterError为true，则该字段的值将不会在后续handler中被处理到。
        * `<relativeRowPos>`相对section的行数（不是sheet中的行数），仅对HEADER 和 FOOTER有作用
        * `<relativeColumnPos>`相对section的列数（不是sheet中的列数），BODY中可不配置，程序将读取`fieldIndex`属性作为相对列数。
    * `<handlers>`下的`<handler>`定义了数据处理器集合。
        * `class` 定义了handler类名（包含包名）
        * `handlerIndex` 定了多个handler相对位置，程序按此字段排序顺序将数据交由handlers处理。
        > _注意_，此处定义的handler都需要实现`IFileHandler`接口。

        > handler的说明：每个section解析出来的数据是按批次交由handlers处理的。程序会顺序调用各个handler。每个handler的输入为前一个handler的输出（即`DataContext`对象）。

        > handler 中定义了对数据的最终处理，比如字典转换，保存到数据库等操作。


## 二、<span id='validator'>校验规则定义</span>

### 总体说明
在解析模板配置定义中的`<field>`节点有个`validator`属性，各开发人员可以自行指定解析规则。
* 每个解析规则以半角分号分隔“`；`”。
* 各个规则也有自己的参数，规则项和参数之间以半角冒号“`:`”分隔。
* 如果有多个参数，各个参数之间要以半角逗号"`,`"分隔。

举个例子：
```java
validator="isNullAble:false;maxAsciiLength:10;date:yyyy-MM-dd"
```
上述规则表示该字段为：
1. 必输项
2. 日期类型，日期格式为yyyy-MM-dd
3. 长度最大为10


### 校验规则详细说明

1. `date` 日期校验，参数为日期格式，遵循java的日期pattern规则
2. `dict` 字典，比如``` "dict:1,2,3"```表示输入的值必须为1或者2或者3
3. `digit` 由0-9组成的字符串
4. `isNullAble` 是否必输
5. `maxAsciiLength` 最大长度，一个全角字符的长度按3处理
6. `mustBe` 指定值，比如``` mustBe:上海```表示传入值必须为“上海”
7. `noCheck` 不校验，与其他规则项配合时，本规则项自动失效
8. `number` 数字,举例如下：
    * `number:5,2,>=100` 表示整数位置最大位数为5-2=3，小数位最大位数为2，该数字要大于等于100。比较操作符支持`>=， >， <=， < , ==`
    * `number:5,2` 表示整数位置最大位数为5-2=3，小数位最大位数为2
    * `number:5`表示整数位置最大位数为5
9. `regex` 正则校验器，参数有两个，一个是正则表达式，另一个是报错信息。举例如下：“`regex:[0-9]+,必须为数字编码`”
    > 该正则校验器不支持表达式中包含分号，逗号，冒号。如需更复杂逻辑可参考[自定义扩展](#extend)
1. `weakId` 身份证校验器，该校验器没有校验身份证最后一位校验码。
2. `weakPhone` 11位数字即认为合法手机号
> 约定：除了isNullAble及mustBe，否则其他校验规则在读取到的校验对象为空时，认为校验通过。
### <span id='extend'>自定义扩展</span>
校验规则项可以自定义扩展，步骤如下：
1. 定义规则项名称，比如“`email`”定义参数为company，表示邮箱服务器的公司，可以为空。我们期望的结果是
    * 校验输入字段一定是email格式；
    * 如果指定了公司名，比如“`email:sina`”表示一定是新浪公司的邮箱名
2. 开发规则相对应的类，命名格式为“`xxx.xxx.data.validate.impl.ValidatorItem`<font color='red'>Email</font>"，注意红色部分和我们在第1步中定义的规则项名称是一致的（首字母变大写），该类一定要继承AbsTractValidatorItem。其中initParam方法为初始化规则参数。validate方法是针对输入的data进行校验。具体实现可参考其他校验项实现方式。
3. 此外，如果需要实现的规则用正则表达式即可，可继承”`ValidatorItemRegex`“,具体可以参考`ValidatorItemWeakId`的实现方式。

## 三、调用流程



## 四、设计类图