开发者必备——API设计问题-阿里云开发者社区

开发者社区> 人工智能> 正文

开发者必备——API设计问题

简介: 本文主要探讨RPC和RESTFul两种API风格的特点以及在开发中应该如何进行技术选型,截取了部分网上社区,文章关于API设计的想法和观点供读者参考取舍。

本文主要探讨RPC和RESTFul两种API风格的特点以及在开发中应该如何进行技术选型,截取了部分网上社区,文章关于API设计的想法和观点供读者参考取舍。

1,背景简述

API学名:应用程序接口(Application Programming Interface)

通俗的打个比方,人与人之间通过语言来交流,而程序和程序之间通过API来交流。

目前市场主流的API设计包括RPC,RESTFul,GraphQL等设计思路,关于API风格优劣,好坏众说纷纭,但客观来说:RPC资历最老,并沿用至今,RESTFul后来者居上,火了好大一阵,最新的GraphQL据说会在Githup下一版投入使用。API的选择问题丝毫不亚于跨端框架Flutter和RN的激烈斗争。但笔者坚持认为:软件开发没有银弹,技术终究会被历史裹挟,不断推进,但对于开发者来说,也许没有永恒的银弹,但在当下选择适合自己业务场景的技术却是举足轻重。

本篇文章主要探讨前两种API设计的优缺点以供读者进行技术决策的参考。

2,RPC以动词为核心

2.1 命名风格

RPC 形式的API通常是动宾结构:

getUserInfo,createUser,getUserById

由于接口的个性化需求,添加新功能时,API中可能会引入其他的动词或介词如By,With,create等等,这也是RESTFul征讨RPC的主要原因

  • 一是嫌它丑
  • 二是认为它不够通用(在服务端更新了之后,客户端也需要阅读文档,适应服务端)

2.2 常用实践

  • 面向接口编程

在参数传递过程中使用接口而不是实现类,使程序更加灵活可扩展

例如使用Map而不是HashMap,TreeMap,使用List而不是ArrayList,LinkedList

  • 方法重载

通俗来讲,省去了方法名,使得API调用更加方便

3,RESTFul以名词为核心

“表述性状态转移”

3.1命名风格

/admin/users (查询用户) 
/admin/users (新增用户) 
/admin/users (更新用户) 
/admin/users (删除用户) 

虽然有点不太恰当,但RESTFul的以名词为核心的API风格其实就是把动词使用请求方法代替了,所谓的表述性状态转移实际上就是用请求方法屏蔽掉了API的部分实现。但不可否认的是,这样对于API的可读性的确有显著提高。

 @RequestMapping(value = "/user", method = RequestMethod.GET)
 @RequestMapping(value = "/user", method = RequestMethod.DELETE)

然而,RESTFul并不能很好适应API的复杂性,例如常见的登录注册功能使用RESTFul的风格难以对资源进行抽象。RESTFul对于单资源的增删改查的确可以实现API的升级,但由于其接口粒度过粗,对于多资源的查询操作难以设计出合理的API。

3.2 常用实践

  • 资源名使用复数

不要混淆名词单数和复数,为了保持简单,只对所有资源使用复数。

  • 避免多级 URL(存在争议)

    获取某个作者的某一类文章
    GET /authors/12/categories/2
    
    GET /authors/12?categories=2
    
    ==============================
    查询已发布的文章
    GET /articles/published
    
    GET /articles?published=true

4,如何对RPC和RESTFul进行技术决策?

  • 可读性

相对于RPC,RESTFul风格的API具有更强的可读性,更加利于理解

  • 兼容性

RESTFul相对于RPC接口,粒度更大。

RESTFul适合应用于开发API的增删改查,而RPC适合更加精细化可定制的业务场景

在实现开发接口API,RESTFul有更好的表现。

在实现业务系统,RPC具有更高的定制化能力。

5,关于API接口设计的一些讨论

image-20200709111457661

image-20200709111508228

image-20200709111702816

image-20200709111721022

image-20200709111820030

image-20200709111852275

image-20200709111908448

image-20200709114828574

image-20200709115106018

image-20200709115153692

image-20200709115218633

image-20200709115249440

image-20200709115324286

image-20200709115410141

image-20200709115625104

image-20200709115853172

image-20200709120021467

image-20200709120257806

image-20200709120624273

image-20200709120707848

image-20200709120737495

image-20200709120830415

image-20200709140838672

参考文章

浅谈如何设计API

restful与rpc风格

REST与RESTFul API最佳实践

API 设计最佳实践的思考

RESTful API 最佳实践

image-20200709165702108

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

分享:
人工智能
使用钉钉扫一扫加入圈子
+ 订阅

了解行业+人工智能最先进的技术和实践,参与行业+人工智能实践项目

其他文章