开发者必备——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的主要原因

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

3.1 常用实践

• 面向接口编程

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

  例如使用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接口设计的一些讨论

参考文章

浅谈如何设计API

restful与rpc风格

REST与RESTFul API最佳实践

API 设计最佳实践的思考

RESTful API 最佳实践