API设计点滴

API设计点滴

(是什么，为什么，怎么做)

是什么

–––

– 有人说下水道是一个城市的良心，我说良好的API设计是程序设计者的本份；

– 路上开车就像调用其他人写的API一样，想要不发生异常，老司机知道如何在API实现时就做好其输入输出的校验和异常处理;

– 其实API的设计应用范围很广的，除了软件开发活动中如何通过精心设计以达产品需求外，以下场景亦适用，比如: 开车

对外如根据路况，通过转向灯、喇叭（API)实现与其他行车人(其他系统、模块)交互; 交互的目的当然是想达到与所有参与道路车辆的和谐相处，以为整体交通效率、软件产品功能，性能之保证;

对内如根据各种输入条件(有没有人加塞、变道不打灯、有故障车停在超车道上等)实现加速、减速、换挡，转向等操作(算法逻辑);

对外接口的实现务必考虑外部模块、系统的、环境的要求; 人常说要培养预防性驾驶技能，谁知道你封装的API会被别人怎么用;

内部算法逻辑的实现可以不断完善、重构，比如手动挡需要一直练习哈;

为什么

–––

– 每天都有受到之前API设计的益，比如看似较为复杂的需求，只要充分发挥之前的在相关模块暴露出来的API，加以合理组合利用一般都可以事半功倍；

all the dots make one' s way

– 有时看似复杂问题的修复可能只是需要把相关API中输入参数从1变为0，而这更可能是收益于该API早前设计时的适应性、扩展性考虑;

– 需求首先对照的就是API设计;

– 工作中最核心的两件事: 对需求的理解和API的设计; 其实是一件啦; ​​​

– 大多应用软件系统实现上没有什么技术含量(如果你对技术的理解是纯粹的技术的话)，难得是理清需求、模块化需要实现的目标、为业务目标设计良好的API(这里良好意为:功能完整性、代码维护性、代码可复用性)，

基于以上，你才有更多的精力去思考什么是更合适的系统架构并于合适的时机去重构系统、某个功能模块要应用那种设计模式或最佳实践重构下比较好、哪个业务逻辑需要开启一个独立的工作线程还是要上线程池、最近自己发现的一个IPC库针对我们某项业务数据的流转效率更高，性能更好等等;

怎么做

–––

– API之间的顺序控制

尤其

同步操作改异步时

考虑更多参数需要处理响应

因为，原本被封装的细节需要应用端来处理了(更多的状态变量需要设置、更多的异常处理需要增加)

每个参数仅变化时通知硬件;

封装或调用算法模块时

合理枚举定义、

注意基于API实现业务逻辑时的各API调用时机;

注意因系统耦合导致的不同模块重置实现如系统全局状态API时顺序控制;

– 衡量API好坏的一个指角度，看新支持新需求实现、解决新发现问题时在修改接口还是实现;

重载API本身VS扩充现有API输入参数;

定义多个相关API以灵活支持相关功能时注意各API实现时的完备性;

– 在模块设计时的考虑

分模块 业务导向

分层，实现导向

分层设计时是层层封装、细化;向下要求;

分层实现时则随着影响范围的扩大要往更上层考虑;往上需求;

– 经常问面试候选人关于实现核心业务逻辑所需的工作线程是怎么封装和使用的问题，其实想要了解的无非是:

1. 你会为它抽象出几个API供外部模块使用（是否提供专门的模块初始化、状态运行控制、资源回收接口等）；

2. 用户参数的变化如何反应到线程体还不显著降低工作线程的运行效率（比如遇到互斥资源你可能想要加锁，那如何加锁效率更高、又如针对一个业务参数的响应线程体中是否对等定义相应的变量或开关等）；

– 起个好名字

API的设计，给函数或共有变量起个好名字，是成功的第一步： ​​​

ApI设计之命名要规范，因为以此小细节很可能事半功倍

API的命名需要至少深思熟虑，至少包括两点: 准确、适应性；其中前者指实现当前需求，后者则是考虑外部输入的可能变化；

– 选个默认值

考虑扩展性、易用性，完备性;

完备性: 调用方用例覆盖;

– Qt SDK就像一个行业老人一样，不仅实现了很好的API供大家享用，并且在其文档中为其封装的模块和API还做了必要的说明（不熟读其文档简直是做Qt开发人一大损失）；比如，软件设计模式中的单例大家到处用，但是在系统稍显复杂时，它自己封装的版本（QGLOBALSTATIC）好处就体现出来了，起码在程序的健壮性方面是这样；

– 人常说要不要写代码注释，我觉得以下场景应该要而且大有裨益:

当实现逻辑全是因业务规则要求之时；若非如此，下个维护人员（也可能是你自己）根本就看不懂；

开发人员自己的规约，比如只在控制器中处理参数量纲而把其取值校验放到模型里进行时；

一些特殊用途的变量定义，比如用来控制（暂停、中断）工作线程运行状态的）；

当你需要弥补因自己的API设计、封装可能不够完善时的补救工具，比如你是在库内管理内存还是需要使用方负责、输入输出参数有什么特殊要求，以及这些暴露出来的API之间是否存在约定的顺序控制逻辑；

– 解决问题大多时候是做加法，但有时做减法更重要:

API实现职责不够单一时，少用它，只在必需时; 或者给它首先先瘦身;

涉及设备间通信（如上位机发送下位机命令）时，只在参数真的改变时再下发; ​​​

如同步改异步操作场景;

– 程序设计中的代码复用至少包括: 模块（以dll方式体现）、API（头文件中public属性的函数），甚至还包括相关业务逻辑及数据（A模块的结果输入B再经过选择后发送A）； ​​​

参考

–––

– Qt

官方wiki https://wiki.qt.io/APIDesignPrinciples

a pdf from Nokia when Qt belong to it

https://harrymoreno.com/assets/the-little-manual-of-api-design.pdf

– Book

《C++ API 设计》Martin Reddy