阿里研究员谷朴: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)
- 最新
- 精选
- 走小調的凡世林要是有对应事例说明就好了
- 小胖简直太深奥了。。。
收起评论