How to Design a Good API

and Why it Matters

What is an API？

Why is API Design Important?

  • API 是公司、组织的重要资产
  • API 也可能是负担
  • 公共 API 一旦发布无法撤回
  • 每个开发者都是 API Designer
  • 节省开发者时间，提高效率
  • 设计 API 的过程是提高代码质量的过程

Wealth?

Love?

Laziness！

Characteristics of a Good API

  • Easy to learn
  • Easy to use, even without documentation 
  • Hard to misuse
  • Easy to read and maintain code that uses it
  • Sufficiently powerful to satisfy requirements
  • Easy to extend
  • Aimed at its audience
  • 即使对事物的内在本质并不清楚，也可以很好地使用它
  • 例如：手机、电视、汽车……
  • 例如：软件、高级语言、数据库……
  • 不同层次的理解：用户、维修人员、开发者、架构师、设计师……

Cluelessness 无绪

操作系统

处理器

主存

IO设备

文件

虚拟存储器

指令集

进程

虚拟机

计算机系统提供的一些抽象

  • 航母设计师不需要了解一颗螺丝钉如何制造
  • 找到一种编程实践方法，让开发者不需要了解所有事情
  • API 是对所需知识的抽象，它将系统的复杂性隐藏起来

选择性无绪

所有设计原则都围绕着 “隐藏复杂性” 这一根本目标

  • 收集需求，带着质疑
    • “他的问题是什么”而不是“他要什么”
      • onFirstComponentOfTheSecondPageVisible(callback) => onPageVisible(pageNumber, callback)
      • “提供全景图下载功能” => “让全景图能离线播放”
    • 对问题抽象，创建用例：API 要解决什么问题
    • 更抽象的问题可能更容易解决，收益也更大

The Process of API Design

  • 简短的 API spec 
    • 敏捷比完整更重要，易于修改
    • 找更多人讨论，听取意见（需求方、senior engineers……）
    • 做好决定后不断填充细节
  • 尽早动手写原型代码：核心用例，尽早发现问题
  • 保持合理预期
    •     满足所有人的需求 => do one thing and do it well
    •     完美的设计 => 为修改留出余地

The Process of API Design

  • API Should Do One Thing and Do it Well
    • 如果某个 API 很难命名，很可能抽象不好
    • 灵活地拆分合并模块
  • API Should Be As Small As Possible
    • 首先要满足需求
    • 如果不确定是否需要这个 API，先不要
    • 概念的多少比 API 的多少更重要

General Principles

webpack：概念、接口、用法都多

Text

Text

Redux：接口少，概念多

Text

jQuery & Lodash：接口多，概念少

gulp：接口少，概念也少

  • Implementation Should Not Impact API
    • API 不应该暴露出内部实现
      • 增加使用者负担
      • 给未来的修改造成困难
  • Minimize Accessibility of Everything
    • 让类、方法、成员、函数尽可能私有、局部
    • 尽可能地隐藏信息
    • 尽量让模块能够被独立地理解、使用、测试

General Principles

calculateNewPosition(event: MouseEvent) {
    return {
        x: event.clientX + 100,
        y: event.clientY + 50
    };
}

calculateNewPosition(position: Vector2) {
    return {
        x: position.x + 100,
        y: position.y + 50
    };
}

CSS

  • Similar things should look similar
    • 概念、代码风格保持一致
    • 尽量遵循所在平台约定俗成的概念和规则
    • 大多数时候 API 应该是对称的
  • Be opinionated
    • 既可以这样又可以那样时，要有明确的规范
    • 代码风格、概念要清晰，一致

General Principles

$.each V.S. $.map

Vue Component Lifecycle APIs

Node.js Callback Style

  • Minimize Mutability
  • Subclass Only Where It Makes Sense
  • Avoid ambiguous overloadings
  • User of API should not be surprised by behavior
  • Report Errors as Soon as Possible After They Occur
  • Use Appropriate Parameter and Return Types

Implementation Principles

  • API 的目的是隐藏复杂性，围绕这一目标，总结出了上述原则
  • 都是编程中基本原则的应用：
    • S.O.L.I.D
    • Least Knowledge

Summary

Made with Slides.com