API设计实例分析
通用IO API
目录
IO API设计实例分析

1.
2.
3.
4.
5.
IO要解决的功能
典型场景，划分功能
接口整理
标准使用方式（客户）
拦截[传输]过程
IO API实现说明
成本收益分析


2
IO API设计实例分析
3
IO要解决的功能
多数据类型
String、Byte[]、领域对象
多数据来源
文件、SPI Provider
异常处理、善后虚处理（如资源释放）
IO类型转换
附加分析：IO计数等等





4
典型场景，划分功能
1:
1:
1:
2:
3:
2:
4:
4:
2:
2:
3:
4:
2:
4:
4:
4:
4:
4:
2:
2:
2:
3:
5
File source = new File( getClass().getResource( "/iotest.txt" ).getFile() );
File destination = File.createTempFile( "test", ".txt" );
destination.deleteOnExit();
BufferedReader reader = new BufferedReader(new FileReader(source));
long count = 0;
try {
BufferedWriter writer = new BufferedWriter(new FileWriter(destination));
try {
String line = null;
while ((line = reader.readLine()) != null) {
count++;
writer.append( line ).append( '\n' );
}
writer.close();
} catch (IOException e) {
writer.close();
destination.delete();
}
} finally {
reader.close();
}
System.out.println(count)
接口整理(1)——输入
public interface
Input<T, SenderThrowableType extends Throwable>
{
<ReceiverThrowableType extends Throwable>
void transferTo(
Output<T,ReceiverThrowableType> output )
throws SenderThrowableType, ReceiverThrowableType;
}
6
接口整理(2)——输出
public interface
Output<T, ReceiverThrowableType extends Throwable> {
<SenderThrowableType extends Throwable>
void receiveFrom(
Sender<T, SenderThrowableType> sender)
throws ReceiverThrowableType, SenderThrowableType;
}
7
接口整理(3)——发送者
public interface
Sender<T, SenderThrowableType extends Throwable>
{
<ReceiverThrowableType extends Throwable>
void sendTo(
Receiver<T, ReceiverThrowableType> receiver)
throws ReceiverThrowableType, SenderThrowableType;
}
8
接口整理(4)——接受者
public interface
Receiver<T, ReceiverThrowableType extends Throwable>
{
void receive(T item)
throws ReceiverThrowableType;
}
9
标准使用方式（客户）



根据契约，然后可以制定几个输入输出（I/O）的标准。
比如：从文本文件中读取文本行后再写成文本文件。
这个操作可以静态方法中，方便的重用。
最后，拷贝文本文件可以写成：
File source = ...
File destination = ...
Inputs.text( source )
.transferTo( Outputs.text(destination) );
10
拦截[传输]过程——过滤的API
public static
<T, ReceiverThrowableType extends Throwable>
Output<T, ReceiverThrowableType>
filter( final Specification<T> specification,
final Output<T, ReceiverThrowableType> output) {
// create an Output that filters items
// based on the Specification<T> ...
}
interface Specification<T>
{
boolean test(T item);
}
11
拦截[传输]过程——过滤的使用代码
下面的例子删除文件中的空行：
File source = ...
File destination = ...
Inputs.text( source ).transferTo( Transforms.filter(new
Specification<String>()
{
public boolean test(String string)
{
return string.length() != 0;
}
}, Outputs.text(destination) );
12
拦截[传输]过程——传输类型转换的API
public static
<From,To,ReceiverThrowableType extends Throwable>
Output<From, ReceiverThrowableType>
map( final Function<From,To> function,
final Output<To, ReceiverThrowableType> output) {...}
interface Function<From, To>
{
To map(From from);
}
13
拦截[传输]过程——传输类型转换的使用代码
Input<String,IOException> input = ...;
Output<JSONObject,RuntimeException> output = ...;
input.transferTo(
Transforms.map(new String2JSON(), output);
File source = ...
File destination = ...
Counter<String> counter = new Counter<String>();
Inputs.text( source ).transferTo(
Transforms.map(counter, Outputs.text(destination) ));
System.out.println("Nr of lines:"+counter.getCount())
14
IO API实现说明
15
实现说明 & Demo

http://oldratlee.com/493/tech/java/java-api-designexercise.html

https://bitbucket.org/oldrat/io-api
16
成本收益分析
17
成本



分析好领域
需要让实现者理解保持一致
适当的文档让其它人了解你的设计


18
术语约定
分解方式
收效

DRY
KISS（客户API简单，实现涉及较多内容）

分离的功能






资源维护 和 操作分离（IO资源维护和IO操作分离）
核心功能 和 修饰性功能
分离功能之间功能方法参数关联起来，即外围功能持
有依赖功能，组合方式（非继承）。
各个功能有明确的接口，且是组合的，所以可以方便
Wrap，方便拦截加入修饰性功能。
同时整理出了API（外围接口）和SPI（内部接口）
19
引申

客户类不需要继承框架内的类
1.
2.
3.


从框架继承来的代码属于框架
框架应该从客户类提取需要的逻辑拼装运行
客户类不需要从框架继承额外的逻辑
客户 观察不到的 不要 出现在 API中
API使用方式 是 客户直觉期望使用方式
20
参考资料


How to Design a Good API and Why it Matters(by Joshua
Bloch) http://lcsd05.cs.tamu.edu/slides/keynote.pdf
The Little Manual of API Design
http://chaos.troll.no/~shausman/api-design/api-design.pdf


Practical API Design: Confessions of a Java Framework
Architect http://www.amazon.com/Practical-API-Design-Confessions-Framework/dp/1430243171
Google Search http://www.google.com.hk/search?&q=api+design
21
The Design Process

《The Little Manual of API Design》第三章“The Design
Process”，可以实际操作：
1.
2.
3.
4.
5.
6.
7.
8.
9.
22
Know the requirements
Write use cases before you write any other code
Look for similar APIs in the same library
Define the API before you implement it
Have your peers review your API
Write several examples against the API
Prepare for extensions
Don’t publish internal APIs without review
When in doubt, leave it out
23