Skip to content

Latest commit

 

History

History
51 lines (33 loc) · 2.31 KB

23.精读API设计原则.md

File metadata and controls

51 lines (33 loc) · 2.31 KB
Raw

023.精读《API 设计原则》.md

  • API 优秀利于使用者了解，开发效率增快， 后期维护更加顺畅

优秀 API 六个设计原则

  1. 静态多态，减少继承，类似的 API 不统一继承一个父类，因为统一继承导致 API public 数量过多，父类无意义方法对用户不友好
  2. 基于属性的 API， 属性对应于对象状态，通过属性为指标颗粒度的 API 便于使用者理解 API，需注意关联属性的顺序
  3. API 语义和文档 ， API 注释中应有其参数(params) 和使用方法(methods)和意图(intent)
  4. 命名统一，不要用缩写，保持格式一致性，无论驼峰式写法还是 kebabs 式，命名最好能体现其副作用，参数过多用对象作为传参展开(JS: ...运算符) 布尔参数改为枚举类型

addon

  • const入参，不要直接改变入参值，不然死在那都哭不出来，用一个另外的变量把入参值引用或者值拷贝：

    function (num) {
    let scopeNum = num;
    scopeNum = 5 
    return scopeNum
}
function (const num) { // 这样传参能保证不能直接修改,取消入参的副作用
    // 以上写法是纯函数标记手法
    // 也可以引入`flow` 或者 `typeScript`
}--

  • 统一关键字库

    • api 定义之前，抽离业务和功能语义关键字(TS 中抽离类型定义放入.d.ts 文件)让调用者感觉符合直觉，语义清晰

    • 单一职责 最细颗粒度化，使用组合方式把多个解耦的单个接口组合成为一个大的功能接口， 接口设计单一职责， 方便多人协作时拓展和组合

    • 面向未来的多态，面向拓展开发，面向修改关闭,升级做到兼容，不然会导致下游接口不可用(现在理解不了。。)

    • 不要重复局部命名 上下文调用减少不必要的描述，提高 API 的精简度和清晰度，同时也要避免过度使用解构，容易丢失上下文，对变量环境来源一无所知(隔着几百行调用，上下文见鬼了)

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

summary

  • 参考类库设计
  • API 稳定之后，花时间整理文档，写文档的思考过程可能推动你重构和优化代码
  • 有精力给我半年重构一次代码，测试完整跑一遍