极客视点
极客时间编辑部
极客时间编辑部
113240 人已学习
免费领取
课程目录
已完结/共 3766 讲
2020年09月 (90讲)
时长 05:33
2020年08月 (93讲)
2020年07月 (93讲)
时长 05:51
2020年06月 (90讲)
2020年05月 (93讲)
2020年04月 (90讲)
2020年03月 (92讲)
时长 04:14
2020年02月 (87讲)
2020年01月 (91讲)
时长 00:00
2019年12月 (93讲)
2019年11月 (89讲)
2019年10月 (92讲)
2019年09月 (90讲)
时长 00:00
2019年08月 (91讲)
2019年07月 (92讲)
时长 03:45
2019年06月 (90讲)
2019年05月 (99讲)
2019年04月 (114讲)
2019年03月 (122讲)
2019年02月 (102讲)
2019年01月 (104讲)
2018年12月 (98讲)
2018年11月 (105讲)
时长 01:23
2018年10月 (123讲)
时长 02:06
2018年09月 (119讲)
2018年08月 (123讲)
2018年07月 (124讲)
2018年06月 (119讲)
时长 02:11
2018年05月 (124讲)
时长 03:16
2018年04月 (120讲)
2018年03月 (124讲)
2018年02月 (112讲)
2018年01月 (124讲)
时长 02:30
时长 02:34
2017年12月 (124讲)
时长 03:09
2017年11月 (120讲)
2017年10月 (86讲)
时长 03:18
时长 03:31
时长 04:25
极客视点
15
15
1.0x
00:00/03:00
登录|注册

阿里研究员谷朴:API设计最佳实践的思考

讲述:丁婵大小:1.37M时长:03:00
要设计一个能够长期保持稳定的 API 是一项及其困难的事情,日前,阿里研究员谷朴发文,分享了他们对于 API 设计最佳实践的思考。本文精选其中的 5 点,希望给你带来参考价值。
1. 写详细的文档
如今,一个应用依赖大量的服务,而每个服务 API 又在不断的演进过程中,准确的记录每个字段和每个方法,并保持更新,对于减少客户端的开发踩坑、减少出问题的几率,提升整体的研发效率至关重要。
2. 不同层建议采用不同的数据模型
当 API 设计倾向于不同的层采用一样的模型时,可能意味着这个 Service 本身的职责没有定义清楚。不同的层采用同样的数据结构带来的问题在于 API 的演进和维护过程。一个系统演进过程中可能需要替换掉后端的存储,可能因为性能优化的关系需要分离缓存等需求,这时会发现将两个层的数据绑定一起,会带来不必要的耦合而阻碍演进。
3. 命名与标识
当 API 定义了一个资源对象,下面一般需要的是提供命名 / 标识。在 naming/ID 方面,一般有两个选择(不是指系统内部的 ID,而是会暴露给用户的):
用 free-form string 作为 ID(string nameAsId)
用结构化数据表达 naming/ID
何时选择哪个方法,需要具体分析。采用 Free-form string 的方式定义的命名,为系统的具体实现留下了最大的自由度。带来的问题是命名的内在结构本身并非 API 强制定义的一部分,转为变成实现细节。如果命名本身存在结构,客户端需要有提取结构信息的逻辑。这是一个需要做的平衡。
如果资源 Resource 对象的抽象模型自然包含结构化的标识信息,则采用结构化方式会简化客户端与之交互的逻辑,强化概念模型。这时牺牲掉标识的灵活度,换取其他方面的优势。
4. 更新操作,尽量保持幂等性
具有幂等性(Idempotency )性质的操作可以被多次实施并且不会影响到初次实施的结果。在系统设计中会带来很多便利性,例如客户端可以更安全的重试,从而让复杂的流程实现更为简单。
5. 批量更新
批量更新如何设计是一个常见的 API 设计决策,常见有两种模式,客户端批量更新,或者服务端实现批量更新。
API 的设计者可能会希望实现一个服务端的批量更新能力,但建议尽量避免这样做。除非对于客户来说提供原子化 + 事务性的批量很有意义(all-or-nothing),否则实现服务端的批量更新有诸多的弊端,而客户端批量更新则有优势。
确认放弃笔记?
放弃后所记笔记将不保留。
新功能上线,你的历史笔记已初始化为私密笔记,是否一键批量公开?
批量公开的笔记不会为你同步至部落
公开
同步至部落
取消
完成
0/2000
荧光笔
直线
曲线
笔记
复制
AI
  • 深入了解
  • 翻译
    • 英语
    • 中文简体
    • 中文繁体
    • 法语
    • 德语
    • 日语
    • 韩语
    • 俄语
    • 西班牙语
    • 阿拉伯语
  • 解释
  • 总结
该免费文章来自《极客视点》,如需阅读全部文章,
请先领取课程
免费领取
登录 后留言

全部留言(2)

  • 最新
  • 精选
  • 走小調的凡世林
    要是有对应事例说明就好了
  • 小胖
    简直太深奥了。。。
收起评论
显示
设置
留言
2
收藏
98
沉浸
阅读
分享
手机端
快捷键
回顶部