开源软件程序设计接口

软件程序接口设计

重要性

为什么要重视API设计？

• 降低用户学习成本
• 例如：用户主要使用Python
• Tensorflow把C++ API包装成Python
• 开源软件不是单独的存在
• API决定技术栈的稳定性
• 为上层建筑打下基础
• API设计VS底层技术
• API设计又超高的性价比

新挑战

• 用户需求未知

• 用户群体割裂
• 把需求缝合进同一套API

基本原则

原则一、代码未动，设计先行

• 有设计，才有可能有好的设计
• 有API设计倒推代码结构

• 谨慎修改API，重走设计流程
• 谨慎增加API,会增加历史包袱

API设计文档里有什么？

• 把设计文档当教程写
• 单个函数定义VS完整代码段

• 写完整的代码段

output_tensor=x_text
for layer in model.layers:
     output_tesor=layer(output_tensor)
     print(output_tensor)

class Layer(tf.Module):
     def __call__(self,tensor):
          pass

原则二、所想即所得

• 好的API设计

• 正例

Model
model=keras.Sequential([
   layers.Conv2D(filters=32,kernel_size=3,activation='relu'),
   layers.Conv2D(filters=32,kernel_size=3,activation='relu'),
   layers.Flatten(),
   layers.Dense(10,activation='softmax'),
   ])

model.compile(
    optimizer='adam',
    loss='categorical_crossentropy')
model.fit(x_train,y_train,epochs=3)
model.predict(x_test)

• 最差API设计

• 反例

Tensor
# 给用户灌输编译器中的概念
x=tf.placeholder("float",None)
y=x*2
# y是tensor,能相乘却没有值
with tf.Session() as session:
     result=session.run(y,feed_dict={x:[1,2,3]})
     print(result)

• 如何兼顾两者的需求？

• 让用户只学习必要的知识

model.compile(
    optimizer='adam',
    loss='categorical_crossentropy'
    model.fit(x_train,y_train,epochs=3)

科学家VS工程师

• 只学习必要的内容

• 降低学习门槛

原则三、让用户在交互中学习

• 代码不是一种静态的存在
• 引入时间维度

• 用户难以一次行写对

• 在试错中前进

• 尽早捕捉异常

• 发出有意义的信息

• 最佳错误信息：指导用户如何修正

一条朴素的API评价标准

用户能轻易掌握API的使用逻辑，并在根据这种逻辑构建自己的应用，而很少查阅文档。

总结

重要性	新挑战	基本原则
① 降低学习成本；②生态稳定性；③高性价比	① 无法提前接触用户；② 用户群体割裂	原则一代码未动、设计先行：谨慎修改增加API、写完整代码段; 原则二、所想即所得:契合用户心理表征、尽量不灌输新概念、不迷惑用户、只学需要的；原则三、让用户在交互中学习:用户需要试错、尽早捕捉异常 、抛出有意义的异常信息、指导用户修正