Octopus
Octopus
(就是一個名字而已~) 是一個簡單的java excel匯入匯出工具。目的是不用接觸Apache POI的API就可以完成簡單的Excel匯出匯入。
同時,可以自定義表格樣式,匯入檢驗資料合法和轉換資料。
最大的特點就是匯出複雜結構物件時自動繪製表頭
不BB,直接上圖
為了準確性,演示的例子都是完整的單元測試程式碼,都可以在測試路徑找到原始碼,各位客官可以clone下來跑一下看效果,包括上面這個複雜例子(ApplicantExample)喔
從Maven匯入
為了方便使用,直接用Github做了一個私人倉庫
增加倉庫
<repositories>
<repository>
<id>chenhuanming-repo</id>
<name>chenhuanming-repo</name>
<url>https://raw.githubusercontent.com/zerouwar/my-maven-repo/master</url>
</repository>
</repositories>
複製程式碼
引入依賴
<dependency>
<groupId>cn.chenhuanming</groupId>
<artifactId>octopus</artifactId>
<version>1.0.0</version>
</dependency>
複製程式碼
匯出Excel
從最簡單的例子開始
我們從最簡單的例子開始——匯出一些地址資料。Address
類只有兩個屬性
@Data
@AllArgsConstructor
@NoArgsConstructor
public class Address {
private String city;
private String detail;
}
複製程式碼
在匯出前,我們需要建立一個XML檔案定義怎樣去匯出
<?xml version="1.0" encoding="UTF-8"?>
<Root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/zerouwar/my-maven-repo/master/cn/chenhuanming/octopus/1.0.0/octopus.xsd"
class="cn.chenhuanming.octopus.entity.Address">
<Field name="city" description="City"/>
<Field name="detail" description="Detail"/>
</Root>
複製程式碼
首先,建立Root
根元素。這裡引用octopus.xsd檔案幫助我們編寫XML
然後,賦值class
屬性,代表我們要匯出的類全限定名
最後,建立兩個Field
元素,代表要匯出類的兩個屬性
name
屬性值就是Address
裡的屬性名,實際上Octopus呼叫其getter方法獲取值,所以要確保有getter方法
description
屬性會被用在繪製表頭
我們可以開始做最後一件事,編寫Java程式碼
public class AddressExample {
List<Address> addresses;
/**
* make testing data
*/
@Before
public void prepare() {
addresses = new ArrayList<>();
DataFactory df = new DataFactory();
for (int i = 0; i < df.getNumberBetween(5, 10); i++) {
addresses.add(new Address(df.getCity(), df.getAddress()));
}
}
@Test
public void export() throws FileNotFoundException {
//where to export
String rootPath = this.getClass().getClassLoader().getResource("").getPath();
FileOutputStream os = new FileOutputStream(rootPath + "/address.xlsx");
//read config from address.xml
InputStream is = this.getClass().getClassLoader().getResourceAsStream("address.xml");
ConfigReader configReader = Octopus.getXMLConfigReader(is);
try {
Octopus.writeOneSheet(os, configReader, "address", addresses);
} catch (IOException e) {
System.out.println("export failed");
}
}
}
複製程式碼
這是一個完整的單元測試程式碼,不過匯出Excel其實只要兩步:
- 從XML配置檔案中建立一個
ConfigReader
物件 - 呼叫
Octopus.writeOneSheet()
,傳入匯出的檔案,configReader,工作表的名字和資料
下面是匯出的Excel檔案
自動繪製表頭
Octopus支援匯出複雜物件時自動繪製表頭
這次我們來匯出一些公司資料,這裡是Company
類
@Data
@AllArgsConstructor
@NoArgsConstructor
public class Company {
private String name;
private Address address;
}
複製程式碼
然後我們建立一個 company.xml 配置檔案
<Root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/zerouwar/my-maven-repo/master/cn/chenhuanming/octopus/1.0.0/octopus.xsd"
class="cn.chenhuanming.octopus.entity.Address">
<Field name="name"
description="Name"
color="#ff0000"/>
<Header name="address" description="Address">
<Field name="city" description="City"/>
<Field name="detail" description="Detail"/>
</Header>
</Root>
複製程式碼
我們用Header
元素代表要匯出Company
的一個複雜屬性,同時設定字型顏色是紅色
Java程式碼基本跟之前的一樣
public class CompanyExample {
List<Company> companies;
/**
* make testing data
*/
@Before
public void prepare() {
companies = new ArrayList<>();
DataFactory df = new DataFactory();
for (int i = 0; i < df.getNumberBetween(5, 10); i++) {
companies.add(new Company(df.getBusinessName(), new Address(df.getCity(), df.getAddress())));
}
}
@Test
public void export() throws FileNotFoundException {
//where to export
String rootPath = this.getClass().getClassLoader().getResource("").getPath();
FileOutputStream os = new FileOutputStream(rootPath + "/company.xlsx");
//read config from company.xml
InputStream is = this.getClass().getClassLoader().getResourceAsStream("company.xml");
ConfigReader configReader = Octopus.getXMLConfigReader(is);
try {
Octopus.writeOneSheet(os, configReader, "company", companies);
} catch (IOException e) {
System.out.println("export failed");
}
}
}
複製程式碼
最後是匯出的Excel檔案
Octopus可以處理更復雜的資料,你可以在cn.chenhuanming.octopus.example.ApplicantExample
檢視這個更復雜的例子
轉換資料
有時你想轉換匯出的資料。例如,在上一個例子中,我們不想匯出整個Address
物件,把它當做一個字串匯出
我們所需要做的只是實現一個Formatter
public class AddressFormatter implements Formatter<Address> {
@Override
public String format(Address address) {
return address.getCity() + "," + address.getDetail();
}
@Override
public Address parse(String str) {
String[] split = str.split(",");
if (split.length != 2) {
return null;
}
return new Address(split[0], split[1]);
}
}
複製程式碼
parse
方法用於匯入Excel時,只要關注format
方法。這裡接受一個Address物件,返回一個字串。
最後,配置AddressFormatter
到XML檔案
<Field name="name"
description="Name"
color="#ff0000"/>
<Field name="address"
description="Address"
formatter="cn.chenhuanming.octopus.formatter.AddressFormatter"/>
複製程式碼
最後匯出的結果
匯入Excel
我們直接拿上一個例子的匯出結果來演示匯入,共用同一個ConfigReader
,直接編寫匯入的程式碼
//First get the excel file
FileInputStream fis = new FileInputStream(rootPath + "/company2.xlsx");
try {
SheetReader<Company> importData = Octopus.readFirstSheet(fis, configReader, new DefaultCellPosition(1, 0));
for (Company company : importData) {
System.out.println(company);
}
} catch (Exception e) {
System.out.println("import failed");
}
複製程式碼
在控制檯可以看到列印匯入結果,可以看到,之前的AddressFormatter
也完成了資料的轉換工作
Company(name=Graham Motor Services, address=Address(city=Monroe, detail=666 Bonnair Ave))
Company(name=Social Circle Engineering, address=Address(city=Fort Gaines, detail=956 Third Ridge))
Company(name=Enigma Cafe, address=Address(city=Mcdonough, detail=1278 Midway Trail))
Company(name=Hapeville Studios, address=Address(city=Riceboro, detail=823 Tuscarawas Blvd))
Company(name=Thalman Gymnasium, address=Address(city=Ebenezer, detail=1225 Blackwood Avenue))
Company(name=Sparks Pro Services, address=Address(city=Darien, detail=1362 Woodlawn Lane))
Company(name=Toccoa Development, address=Address(city=Ridgeville, detail=1790 Lawn Ave))
複製程式碼
匯入校驗資料
有時候我們對匯入的資料有一定的要求,Octopus提供簡單的資料校驗配置
首先給我們的Company
增加一個status
屬性,只能是 good,bad和closed 三個值其中一個,同時name
不可以為空,看一下XML配置檔案
<?xml version="1.0" encoding="UTF-8"?>
<Root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/zerouwar/my-maven-repo/master/cn/chenhuanming/octopus/1.0.0/octopus.xsd"
class="cn.chenhuanming.octopus.entity.Company">
<Field name="name"
description="Name"
color="#ff0000"
is-blankable="false"/>
<Field name="address"
description="Address"
formatter="cn.chenhuanming.octopus.formatter.AddressFormatter"
/>
<Field name="status"
description="Status"
options="good|bad|closed"/>
<!--| split options -->
</Root>
複製程式碼
這是我們要匯入的Excel,可以看到裡面有非法資料
看一下怎麼編寫Java程式碼
@Test
public void importCheckedData() throws IOException, InvalidFormatException {
InputStream is = this.getClass().getClassLoader().getResourceAsStream("wrongCompany.xlsx");
ConfigReader configReader = new XmlConfigReader(this.getClass().getClassLoader().getResourceAsStream("company3.xml"));
final SheetReader<CheckedData<Company>> sheetReader = Octopus.readFirstSheetWithValidation(is,configReader,new DefaultCellPosition(1,0));
for (CheckedData<Company> checkedData : sheetReader) {
System.out.println(checkedData);
}
}
複製程式碼
這裡我們呼叫Octopus.readFirstSheetWithValidation
,獲取帶校驗結果的SheetReader
,看一下匯入的結果
CheckedData(data=Company(name=Graham Motor Services, address=Address(city=Monroe, detail=666 Bonnair Ave), status=good), exceptions=[])
CheckedData(data=Company(name=Social Circle Engineering, address=Address(city=Fort Gaines, detail=956 Third Ridge), status=null), exceptions=[cn.chenhuanming.octopus.exception.NotAllowValueException])
CheckedData(data=Company(name=null, address=Address(city=Mcdonough, detail=1278 Midway Trail), status=null), exceptions=[cn.chenhuanming.octopus.exception.CanNotBeBlankException, cn.chenhuanming.octopus.exception.NotAllowValueException])
複製程式碼
可以看到每一個CheckData
有一個data
屬性和一個exceptions
列表。
這個異常列表存放著匯入時每一個單元格可能出現的校驗錯誤,異常型別都是ParseException
除了is-blankable
和options
,還可以通過regex
配置正規表示式檢查。當校驗錯誤時,會丟擲對應的ParseException
子類
is-blankable
:丟擲CanNotBeBlankException
options
:丟擲NotAllowValueException
regex
:丟擲PatternNotMatchException
你可以通過這些異常來進行跟進一步的處理。如果上面三種校驗方式不能滿足需求,在Formatter
的parse
丟擲自定義的ParseException
。Octopus會捕獲它們放到exceptions
列表中,並自動把單元格位置和你的配置內容塞到ParseException
中,這樣你可以自己選擇處理這些異常資料
以上程式碼都可以在測試路徑cn.chenhuanming.octopus.example
找到,通過這些例子可以感受下Octopus的魅力
Q&A
沒有Java註解配置?
目前只提供XML配置,因為XML和類檔案解耦,有時候你無法修改類程式碼時,尤其是匯出場景,XML會是更好的選擇。如果你是”anti-xml”,可以實現註解版ConfigReader
,把註解配置轉換成Field
,這應該不會很難。後面我有空再弄註解配置吧~
需要操作Apache POI?
Octopus
類可以提供一行程式碼式的API,讓你不用碰Apache POI的API。但是如果你確實需要用到Apache POI,可以先看一下Octopus核心類SheetWriter
和SheetReader
程式碼。我在設計的時候儘量考慮擴充套件,並且完全基於介面實現,實在不行可以選擇繼承重寫,屬性基本都是protected,或者直接自己實現介面