API设计的第一直觉陷阱

好的API设计就是让这个承诺尽可能稳定尽可能好用 尽可能经得起时间考验

剑飞
1/14API设计的第一直觉陷阱

第一直觉是程序员最危险的朋友

01命题

先说清本页判断

02解释

补足为什么

03行动

留下下一步

把“第一直觉是程序员最”落到一个具体项目里看结果
2/14API设计的第一直觉陷阱

"这个功能我是这样实现的

最直接的直觉是"这个功能我是这样实现的所以API就这样设计
3/14API设计的第一直觉陷阱

一个典型的例子是分页参数

offset=0&limit=20`因为这直接对应了数据库查询的 `OFFSET 0 LIMIT 20`

命题先说清本页判断
解释补足为什么
行动留下下一步
4/14API设计的第一直觉陷阱

另一个例子是错误码设计

命题先说清本页判断
解释补足为什么
行动留下下一步
把“另一个例子是错误码”落到一个具体项目里看结果
5/14API设计的第一直觉陷阱

当你想改实现的时候

01命题

先说清本页判断

02解释

补足为什么

03行动

留下下一步

把“当你想改实现的时候”落到一个具体项目里看结果
6/14API设计的第一直觉陷阱

"这个功能需要什么参数

第一直觉的设计是"这个功能需要什么参数就加什么参数

命题先说清本页判断
解释补足为什么
行动留下下一步
7/14API设计的第一直觉陷阱

参数之间有隐式依赖

`f` 和 `g` 不能同时为 true
8/14API设计的第一直觉陷阱

让想法成结构

01语言

先变成材料

02材料

再形成结构

03结构

最后推动行动

把“让想法成结构”落到一个具体项目里看结果
9/14API设计的第一直觉陷阱

第一直觉的错误处理是

命题先说清本页判断
解释补足为什么
行动留下下一步
把“第一直觉的错误处理是”落到一个具体项目里看结果
10/14API设计的第一直觉陷阱

前端怎么catch

用异常控制正常流程的问题是调用方必须读文档才知道哪些异常是"正常的" 哪些是真的错误
11/14API设计的第一直觉陷阱

用返回值表达预期的变体

更好的设计是用返回值表达预期的变体用异常表达真正的错误

命题先说清本页判断
解释补足为什么
行动留下下一步
12/14API设计的第一直觉陷阱

带走四步

找项目

从真实任务开始

出材料

把想法变成可处理内容

做交付

用结果判断能力

可复用

把完成沉淀为流程

13/14API设计的第一直觉陷阱

让能力长出来

好的API设计 就是让这个承诺尽可能稳定尽可能好用 尽可能经得起时间考验

返回原文
上一篇没有更多文章下一篇没有更多文章