人人都是API设计师：我对RESTful API、GraphQL、RPC API 的思考
有一段时间没怎么写文章了，今天提笔写一篇自己对API设计的思考。首先，为什么写这个话题呢？其一，我阅读了《阿里研究员谷朴：API设计最佳实践的思考》一文后受益良多，前两天并转载了这篇文章也引发了广大读者的兴趣，我觉得我应该把我自己的思考整理成文与大家一起分享与碰撞。其二，我觉得我针对这个话题，可以半个小时之内搞定，争取在1点前关灯睡觉，哈哈。
现在，我们来一起探讨API的设计之道。我会抛出几个观点，欢迎探讨。
一、定义好的规范，已经成功了一大半
通常情况下，规范就是大家约定俗成的标准，如果大家都遵守这套标准，那么自然沟通成本大大降低。例如，大家都希望从阿里的规范上面学习，在自己的业务中也定义几个领域模型：VO、BO、DO、DTO。其中，DO（Data Object）与数据库表结构一一对应，通过DAO层向上传输数据源对象。而DTO（Data Transfer Object）是远程调用对象，它是RPC服务提供的领域模型。对于BO（Business Object），它是业务逻辑层封装业务逻辑的对象，一般情况下，它是聚合了多个数据源的复合对象。那么，VO（View Object）通常是请求处理层传输的对象，它通过Spring框架的转换后，往往是一个JSON对象。
事实上，阿里这种复杂的业务中如果不划分清楚DO、BO、DTO、VO的领域模型，其内部代码很容易就混乱了，内部的RPC在service层的基础上又增加了manager层，从而实现内部的规范统一化。但是，如果只是单独的域又没有太多外部依赖，那么，完全不要设计这么复杂，除非预期到可能会变得庞大和复杂化。对此，设计过程中因地制宜就显得特别重要了。
另外一个规范的例子是RESTful API。在REST架构风格中，每一个URI代表一种资源。因此，URI是每一个资源的地址的唯一资源定位符。所谓资源，实际上就是一个信息实体，它可以是服务器上的一段文本、一个文件、一张图片、一首歌曲，或者是一种服务。RESTful API规定了通过GET、 POST、 PUT、 PATCH、 DELETE等方式对服务端的资源进行操作。
【GET】 /users #查询用户信息列表
【GET】 /users/1001 #查看某个用户信息
【POST】 /users #新建用户信息
【PUT】 /users/1001 #更新用户信息（全部字段）
【PATCH】 /users/1001 #更新用户信息（部分字段）
【DELETE】 /users/1001 #删除用户信息
事实上，RESTful API的实现分了四个层级。第一层次（Level 0）的Web API服务只是使用HTTP作为传输方式。第二层次（Level 1）的Web API服务引入了资源的概念。每个资源有对应的标识符和表达。第三层次（Level 2）的Web API服务使用不同的HTTP方法来进行不同的操作，并且使用HTTP状态码来表示不同的结果。第四层次（Level 3）的Web API服务使用HATEOAS。在资源的表达中包含了链接信息。客户端可以根据链接来发现可以执行的动作。通常情况下，伪RESTful API都是基于第一层次与第二层次设计的。例如，我们的Web API中使用各种动词，例如get_menu和save_menu，而真正意义上的RESTful API需要满足第三层级以上。如果我们遵守了这套规范，我们就很可能就设计出通俗易懂的API。
注意的是，定义好的规范，我们已经成功了一大半。如果这套规范是业内标准，那么我们可以大胆实践，不要担心别人不会用，只要把业界标准丢给他好好学习一下就可以啦。例如，Spring已经在Java的生态中举足轻重，如果一个新人不懂Spring就有点说不过去了。但是，很多时候因为业务的限制和公司的技术，我们可能使用基于第一层次与第二层次设计的伪RESTful API，但是它不一定就是落后的，不好的，只要团队内部形成规范，降低大家的学习成本即可。很多时候，我们试图改变团队的习惯去学习一个新的规范，所带来的收益（投入产出比）甚微，那就得不偿失了。
总结一下，定义好的规范的目的在于，降低学习成本，使得API尽可能通俗易懂。当然，设计的API通俗易懂还有其他方式，例如我们定义的API的名字易于理解，API的实现尽可能通用等。
二、探讨API接口的兼容性
API接口都是不断演进的。因此，我们需要在一定程度上适应变化。在RESTful API中，API接口应该尽量兼容之前的版本。但是，在实际业务开发场景中，可能随着业务需求的不断迭代，现有的API接口无法支持旧版本的适配，此时如果强制升级服务端的API接口将导致客户端旧有功能出现故障。实际上，Web端是部署在服务器，因此它可以很容易为了适配服务端的新的API接口进行版本升级，然而像Android端、IOS端、PC端等其他客户端是运行在用户的机器上，因此当前产品很难做到适配新的服务端的API接口，从而出现功能故障，这种情况下，用户必须升级产品到最新的版本才能正常使用。为了解决这个版本不兼容问题，在设计RESTful API的一种实用的做法是使用版本号。一般情况下，我们会在url中保留版本号，并同时兼容多个版本。
【GET】 /v1/users/{user_id} //版本v1的查询用户列表的API接口
【GET】 /v2/users/{user_id} //版本v2的查询用户列表的API接口
现在，我们可以不改变版本v1的查询用户列表的API接口的情况下，新增版本v2的查询用户列表的API接口以满足新的业务需求，此时，客户端的产品的新功能将请求新的服务端的API接口地址。虽然服务端会同时兼容多个版本，但是同时维护太多版本对于服务端而言是个不小的负担，因为服务端要维护多套代码。这种情况下，常见的做法不是维护所有的兼容版本，而是只维护最新的几个兼容版本，例如维护最新的三个兼容版本。在一段时间后，当绝大多数用户升级到较新的版本后，废弃一些使用量较少的服务端的老版本API接口版本，并要求使用产品的非常旧的版本的用户强制升级。注意的是，“不改变版本v1的查询用户列表的API接口”主要指的是对于客户端的调用者而言它看起来是没有改变。而实际上，如果业务变化太大，服务端的开发人员需要对旧版本的API接口使用适配器模式将请求适配到新的API接口上。
有趣的是，GraphQL提供不同的思路。GraphQL为了解决服务API接口爆炸的问题，以及将多个HTTP请求聚合成了一个请求，提出只暴露单个服务API接口，并且在单个请求中可以进行多个查询。GraphQL定义了API接口，我们可以在前端更加灵活调用，例如，我们可以根据不同的业务选择并加载需要渲染的字段。因此，服务端提供的全量字段，前端可以按需获取。GraphQL可以通过增加新类型和基于这些类型的新字段添加新功能，而不会造成兼容性问题。
此外，在使用RPC API过程中，我们特别需要注意兼容性问题，二方库不能依赖parent，此外，本地开发可以使用SNAPSHOT，而线上环境禁止使用，避免发生变更，导致版本不兼容问题。我们需要为每个接口都应定义版本号，保证后续不兼容的情况下可以升级版本。例如，Dubbo建议第三位版本号通常表示兼容升级，只有不兼容时才需要变更服务版本。
关于规范的案例，我们可以看看k8s和github，其中k8s采用了RESTful API，而github部分采用了GraphQL。
●https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.10/
●https://developer.github.com/v4/
三、提供清晰的思维模型
所谓思维模型，我的理解是针对问题域抽象模型，对域模型的功能有统一认知，构建某个问题的现实映射，并划分好模型的边界，而域模型的价值之一就是统一思想，明确边界。假设，大家没有清晰的思维模型，那么也不存在对API的统一认知，那么就很可能出现下面图片中的现实问题。
四、以抽象的方式屏蔽业务实现
我认为好的API接口具有抽象性，因此需要尽可能的屏蔽业务实现。那么，问题来了，我们怎么理解抽象性？对此，我们可以思考java.sql. Driver的设计。这里，java.sql.Driver是一个规范接口，而com.mysql.jdbc. Driver。
则是mysql-connector-java-xxx.jar对这个规范的实现接口。那么，切换成Oracle的成本就非常低了。
一般情况下，我们会通过API对外提供服务。这里，API提供服务的接口的逻辑是固定的，换句话说，它具有通用性。但是，但我们遇到具有类似的业务逻辑的场景时，即核心的主干逻辑相同，而细节的实现略有不同，那我们该何去何从？很多时候，我们会选择提供多个API接口给不同的业务方使用。事实上，我们可以通过SPI扩展点来实现的更加优雅。什么是SPI? SPI的英文全称是Serivce Provider Interface，即服务提供者接口，它是一种动态发现机制，可以在程序执行的过程中去动态的发现某个扩展点的实现类。因此，当API被调用时会动态加载并调用SPI的特定实现方法。
此时，你是不是联想到了模版方法模式。模板方法模式的核心思想是定义骨架，转移实现，换句话说，它通过定义一个流程的框架，而将一些步骤的具体实现延迟到子类中。事实上，在微服务的落地过程中，这种思想也给我们提供了非常好的理论基础。
现在，我们来看一个案例：电商业务场景中的未发货仅退款。这种情况在电商业务中非常场景，用户下单付款后由于各种原因可能就申请退款了。此时，因为不涉及退货，所以只需要用户申请退款并填写退款原因，然后让卖家审核退款。那么，由于不同平台的退款原因可能不同，我们可以考虑通过SPI扩展点来实现。
此外，我们还经常使用工厂方法+策略模式来屏蔽外部的复杂性。例如，我们对外暴露一个API接口getTask(int operation)，那么我们就可以通过工厂方法来创建实例，通过策略方法来定义不同的实现。
@Component
public class TaskManager {
private static final Logger logger = LoggerFactory.
getLogger（TaskManager.class）;
private static TaskManager instance;
public MapInteger, ITask> taskMap = new HashMap<Integer,
ITask>（）;
public static TaskManager getInstance（） {
return instance;
}
public ITask getTask（int operation） {
return taskMap.get（operation）;
}
/**
*初始化处理过程
*/
@PostConstruct
private void init（） {
logger.info（"init task manager"）;
instance = new TaskManager（）;
//单聊消息任务
instance.taskMap.put（EventEnum.CHAT_REQ.getValue（）, new
ChatTask（））;
//群聊消息任务
instance.taskMap.put（EventEnum.GROUP_CHAT_REQ.getValue（）,
new GroupChatTask（））;
//心跳任务
instance.taskMap.put（EventEnum.HEART_BEAT_REQ.getValue（）,
new HeatBeatTask（））;
}
}
还有一种屏蔽内部复杂性设计就是外观接口，它是将多个服务的接口进行业务封装与整合并提供一个简单的调用接口给客户端使用。这种设计的好处在于，客户端不再需要知道那么多服务的接口，只需要调用这个外观接口即可。但是，坏处也是显而易见的，即增加了服务端的业务复杂度，接口性能不高，并且复用性不高。因此，因地制宜，尽可能保证职责单一，而在客户端进行“乐高式”组装。如果存在SEO优化的产品，需要被类似于百度这样的搜索引擎收录，可以当首屏的时候，通过服务端渲染生成HTML，使之让搜索引擎收录，若不是首屏的时候，可以通过客户端调用服务端RESTful API接口进行页面渲染。
此外，随着微服务的普及，我们的服务越来越多，许多较小的服务有更多的跨服务调用。因此，微服务体系结构使得这个问题更加普遍。为了解决这个问题，我们可以考虑引入一个“聚合服务”，它是一个组合服务，可以将多个微服务的数据进行组合。这样设计的好处在于，通过一个“聚合服务”将一些信息整合完后再返回给调用方。注意的是，“聚合服务”也可以有自己的缓存和数据库。事实上，聚合服务的思想无处不在，例如Serverless架构。我们可以在实践的过程中采用AWS Lambda作为Serverless服务背后的计算引擎，而AWS Lambda是一种函数即服务（Function-as-a-Servcie, FaaS）的计算服务，我们直接编写运行在云上的函数。那么，这个函数可以组装现有能力做服务聚合。
当然，还有很多很好的设计，我也会在陆续在公众号中以续补的方式进行补充与探讨。
五、考虑背后的性能
我们需要考虑入参字段的各种组合导致数据库的性能问题。有的时候，我们可能暴露太多字段给外部组合使用，导致数据库没有相应的索引而发生全表扫描。事实上，这种情况在查询的场景特别常见。因此，我们可以只提供存在索引的字段组合给外部调用，或者在下面的案例中，要求调用方必填taskId和caseId来保证我们数据库合理使用索引，进一步保证服务提供方的服务性能。
ResultVoid> agree（Long taskId, Long caseId, Configger configger）;
同时，对于报表操作、批量操作、冷数据查询等API应该可以考虑异步能力。
此外，GraphQL虽然解决将多个HTTP请求聚合成了一个请求，但是schema会逐层解析方式递归获取全部数据。例如分页查询的统计总条数，原本1次可以搞定的查询，演变成了N + 1次对数据库查询。此外，如果写得不合理还会导致恶劣的性能问题，因此，我们在设计的过程中特别需要注意。
六、异常响应与错误机制
业内对RPC API抛出异常，还是抛出错误码已经有太多的争论。《阿里巴巴Java开发手册》建议：跨应用RPC调用优先考虑使用isSuccess()方法、“错误码”、“错误简短信息”。关于RPC方法返回方式使用Result方式的理由： 1）使用抛异常返回方式，调用方如果没有捕获到，就会产生运行时错误。2）如果不加栈信息，只是new自定义异常，加入自己的理解的error message，对于调用端解决问题的帮助不会太多。如果加了栈信息，在频繁调用出错的情况下，数据序列化和传输的性能损耗也是问题。当然，我也支持这个论点的实践拥护者。
public ResultXxxDTO> getXxx（String param） {
try {
// ...
return Result.create（xxxDTO）;
} catch （BizException e） {
log.error（"...", e）;
return Result.createErrorResult（e.getErrorCode（）,
e.getErrorInfo（）, true）;
}
}
在Web API设计过程中，我们会使用ControllerAdvice统一包装错误信息。而在微服务复杂的链式调用中，我们会比单体架构更难以追踪与定位问题。因此，在设计的时候，需要特别注意。一种比较好的方案是，当RESTful API接口出现非2xx的HTTP错误码响应时，采用全局的异常结构响应信息。其中，code字段用来表示某类错误的错误码，在微服务中应该加上“{biz_name}/”前缀以便于定位错误发生在哪个业务系统上。我们来看一个案例，假设“用户中心”某个接口没有权限获取资源而出现错误，我们的业务系统可以响应“UC/AUTH_DENIED”，并且通过自动生成的UUID值的request_id字段，在日志系统中获得错误的详细信息。
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"code": "INVALID_ARGUMENT",
"message": "{error message}",
"cause": "{cause message}",
"request_id": "01234567-89ab-cdef-0123-456789abcdef",
"host_id": "{server identity}",
"server_time": "2014-01-01T12:00:00Z"
}
七、思考API的幂等性
幂等机制的核心是保证资源唯一性，例如客户端重复提交或服务端的多次重试只会产生一份结果。支付场景、退款场景，涉及金钱的交易不能出现多次扣款等问题。事实上，查询接口用于获取资源，因为它只是查询数据而不会影响到资源的变化，因此不管调用多少次接口，资源都不会改变，所以是它是幂等的。而新增接口是非幂等的，因为调用接口多次，它都将会产生资源的变化。因此，我们需要在出现重复提交时进行幂等处理。那么，如何保证幂等机制呢？事实上，我们有很多实现方案。其中，一种方案就是常见的创建唯一索引。在数据库中针对我们需要约束的资源字段创建唯一索引，可以防止插入重复的数据。但是，遇到分库分表的情况是，唯一索引也就不那么好使了，此时，我们可以先查询一次数据库，然后判断是否约束的资源字段存在重复，没有的重复时再进行插入操作。注意的是，为了避免并发场景，我们可以通过锁机制，例如悲观锁与乐观锁保证数据的唯一性。这里，分布式锁是一种经常使用的方案，它通常情况下是一种悲观锁的实现。但是，很多人经常把悲观锁、乐观锁、分布式锁当作幂等机制的解决方案，这个是不正确的。除此之外，我们还可以引入状态机，通过状态机进行状态的约束以及状态跳转，确保同一个业务的流程化执行，从而实现数据幂等。事实上，并不是所有的接口都要保证幂等，换句话说，是否需要幂等机制可以通过考量需不需要确保资源唯一性，例如行为日志可以不考虑幂等性。当然，还有一种设计方案是接口不考虑幂等机制，而是在业务实现的时候通过业务层面来保证，例如允许存在多份数据，但是在业务处理的时候获取最新的版本进行处理。