精读《API设计原则》

自修《API结构设计准则》

精读《API设计原则》黄子毅

1 半小时前

下期自修的该文是：API结构设计准则

1 结语

优秀的 API 奥尔奈标识符，就如较好涵义对每一人。好的 API 不但有利于普通用户认知，合作开发时也会四两拨千斤，中后期保护着实一路顺风星路。

两个别忘了现职的同僚跟我说过，任何人在高速成长的标识符库，最少两年到两年要是解构一场，不然丧失的不但是生机，更丧失了可移植性与易用性。

2 文本概述

虽然责任编辑早已是译者后的该文，概述只列举不牵涉 c++ 基本概念的路子架构，技术细节请点选原文。

好 API 的6个个人风格

极简且完整、语法明晰单纯、合乎直觉、易于记忆和引导API普通用户写出可读标识符。

静态多态

尽量减少继承，让相似的类具备相似的 API，而不是统一继承两个父类。因为统一继承会带来 API public 数量过多，父级无意义的方法对用户产生误导。

基于属性的 API

属性指的是对象状态，通过属性为粒度的 API，有有利于普通用户认知 API 的含义，但需注意关联属性的顺序性。

API 语法和文档

比如传值 -1 的含义是什么？如果 API 文档不像http status codes一样健全，建议通过枚举的方式增加可读性。

命名的艺术

不要使用缩写，保持一致性。类命名以功能分组作为后缀，比零散命名更易懂。

函数命名要体现出是否包含副作用，参数过多时以对象作为传参，布尔参数改为枚举类型，或者分解为两个语法化 API。

3 自修

以下自修是对原文观点的补充。

Const 入参

eslint 有一条规则，不要直接改变入参的值。这个规则的初衷是解决函数副作用问题，禁止可能产生副作用标识符的产生。但却可以通过如下方式避免：

function (num) { let scopeNum = num scopeNum = 5 }

这是从包含指针类型编程语言学习过来的，因为当 *num 表示指针时，代表标识符可能产生副作用（修改入参的风险）。而 js 并不总是这样的，不但没有指针申明，基本类型也总是通过拷贝进入传参，非基本类型通过引用传递，也就是会发生通过如上标识符绕过检测，却依然产生副作用（改变函数入参）的情况。

为了避免副作用，建议引入 flow 或 typescript，通过 const 关键字与约定约束入参行为：

function (const num) { … }

将没有副作用函数的所有入参定义为 const 类型，静态检查阶段就禁止了对值的直接修改，同时因为有这个关键字的约束，在函数体内也约定不要通过引用浅拷贝修改它的值。

但这也无法彻底避免，仍然可以通过如下写法绕过检测，修改入参：

function (const num) { const scopeNum = { …num } scopeNum.a.b = c }

在 js 中没有完美的方式避免对入参的修改，但通过对入参修饰 const 关键字，可以对普通用户明确这是纯函数，对合作开发者提示不要写有副作用的标识符。

c++ 的 const 定义从编译开始就完全杜绝了修改的可能性，虽然有 const_cast “去” const 行为，但仍然不会改变入参的值（虽然可以后续对值修改，指针指向保持不变，但用 const 修饰的入参值永远不会改变）。

统一关键字库

所有api定义之前，先抽离业务和功能语法的关键字，统一关键字库; 可以更好的让多人协作看起来如出一辙, 而且关键字库更能够让调用者感觉到合乎直觉、语法明晰; 关键字库也是项目组新同学 PREDO 的文本之一, 很有带入感；

单一职责

接口结构设计尽量要做到单一职责,最细粒度化; 可以使用组合的方式把多个解耦的单个接口组合在一起作为两个大的功能项接口; 接口结构设计的单一职责，也更方便多人协作时候的扩展和组合;

面向未来的多态

对接口参数的扩展，我们要做到面向扩展开放，面向修改关闭; 升级做到要兼容，不然会导致大批量的下游不可用。

同时也要避免过度结构设计，当抽象功能只有一处使用时，尽量不要过早抽象。

不要重复局部命名

class User { // good setName() {} // bad setUserName() {} }

在有上下文环境的调用中，减少不必要的描述可以提高 API 的精简和明晰度。

const { setName } = this.props.store.user const { setVisible } = this.props.store.article

上述 setName setVisible 脱离了 user article 作用域，当隔着几百行调用时，早已不知所云。

4 总结

参考杰出类库是结构设计 API 很好的方法之一，比如责任编辑 c++ 参考的 Qt、js 可以参考 jQuery。

当 API 稳定后，需要花时间整理文档，因为写文档的思考过程可能推动着你解构和优化标识符。

最后，如果有精力，最好每两年解构一场（然后完整跑一遍测试）！

及时发布TMT行业动态,各大上市及热门创业互联网公司内幕八卦&融资并购&架构调整@分享年薪30万以上研发职业机会,提供职场建议和大牛职场心得!