本文主要探讨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接口设计的一些讨论
![2a2c746c8b46218305a8f70734efb41a.png](https://i-blog.csdnimg.cn/blog_migrate/9c2a482cd4bf8524e4aa1cd9518743a3.png)
![251ae79d47fec02a0a6269c339529f98.png](https://i-blog.csdnimg.cn/blog_migrate/b1cd028ee2d2fb5b96ccd848b3465361.jpeg)
![6e2de5dee6dc1d8c4b49a6b8089b108c.png](https://i-blog.csdnimg.cn/blog_migrate/0ab2b796d5815ce98cc90d35c77d3296.png)
![1153a7f94e2fb3f572a4b64a4e8cd228.png](https://i-blog.csdnimg.cn/blog_migrate/9e404eec447d371ff4508cdcd8980af2.png)
![7ff992cc0d16d66ba495d486b972f236.png](https://i-blog.csdnimg.cn/blog_migrate/e50db9916896946eb96f4b6ac7708a53.jpeg)
![fa405585ba4f08bc4c30d6130a43b0c1.png](https://i-blog.csdnimg.cn/blog_migrate/7a4b0a4793cbbdd7c96c1913c5d877b4.png)
![53d5f73979c9f29c331523892704a53f.png](https://i-blog.csdnimg.cn/blog_migrate/7142e724745381047bdbea67cda1db8a.png)
![f9e049b6836b100f1dc9d8e5b4efde01.png](https://i-blog.csdnimg.cn/blog_migrate/7b67ea885a441cba607752a3395cd3f1.jpeg)
![e01e4db40235cdb7b35ac8a08df5bcda.png](https://i-blog.csdnimg.cn/blog_migrate/a230bc074d129b3b41566cf886f08996.jpeg)
![d14bbe17fe905c35f10d17047e4ee3c8.png](https://i-blog.csdnimg.cn/blog_migrate/9b126be36e086e4293a6666695d57dbd.jpeg)
![06fc24524de6d062cd05b73400edd91d.png](https://i-blog.csdnimg.cn/blog_migrate/b450f2628bf9a7521cdb99b327dc06ee.png)
![cdfecd187960f20358476cff7e4d122c.png](https://i-blog.csdnimg.cn/blog_migrate/e7b8e9b21af62c4b864d08d186eb5275.png)
![a7bee54c7fd0d1dea333c88118d15a26.png](https://i-blog.csdnimg.cn/blog_migrate/92728fb94868ccef07ea8fb154300773.png)
![a275e9f7f2a270e6c447c157693fb817.png](https://i-blog.csdnimg.cn/blog_migrate/7ed4e750fb6e455adfe3b265b3b18ba0.jpeg)
![32ddd9ea85cfd45f87dc067dc19580c6.png](https://i-blog.csdnimg.cn/blog_migrate/f8decd9aab6893ca7003a2041e3d2d7c.jpeg)
![35c05a060e12419ecbb5e0e1e3adc02b.png](https://i-blog.csdnimg.cn/blog_migrate/c8fef8e78556fd471160725969f51df5.jpeg)
![7c13e74874e8f04bc64b2a3f090e7994.png](https://i-blog.csdnimg.cn/blog_migrate/06b8a96ac6f51b8ac52877d04be14ef9.jpeg)
![fc80726756b9bfe7ace0edd5cacf8048.png](https://i-blog.csdnimg.cn/blog_migrate/e0ef7ca02b75061034603301c8319cd6.jpeg)
![be1d4045170427039fe7f7447d35217c.png](https://i-blog.csdnimg.cn/blog_migrate/41b1d1807613370175d0a13351900ac7.jpeg)
![f373c302928ea12989bac79f91c190b8.png](https://i-blog.csdnimg.cn/blog_migrate/9722cd8876a7063dce62b227a20e6518.png)
![901f9b7524c0be6b77bfc3dd15d036d3.png](https://i-blog.csdnimg.cn/blog_migrate/74ccc850ff13db8f6acab4ab82ff04b5.png)
![c14d1c2d731f975e6c8249b60c61ed05.png](https://i-blog.csdnimg.cn/blog_migrate/8a99c51192f1dadd121d548e79899e76.png)
![ffbdb279198400d8079252607c0e2221.png](https://i-blog.csdnimg.cn/blog_migrate/68807008107729f89221ed9ec7052515.jpeg)
参考文章
浅谈如何设计API
restful与rpc风格
REST与RESTFul API最佳实践
API 设计最佳实践的思考
RESTful API 最佳实践