如何优雅设计 API 接口,实现统一格式返回?

标签: 设计 api 接口 | 发表时间:2020-02-02 00:05 | 作者:aoxiang
出处:http://weekly.dockone.io

【编者的话】在移动互联网,分布式、微服务盛行的今天,现在项目绝大部分都采用的微服务框架,前后端分离方式。


题外话:前后端的工作职责越来越明确,现在的前端都称之为大前端,技术栈以及生态圈都已经非常成熟;以前后端人员瞧不起前端人员,那现在后端人员要重新认识一下前端,前端已经很成体系了。
一般系统的大致整体架构图如下:

需要说明的是,有些小伙伴会回复说,这个架构太简单了吧,太low了,什么网关啊,缓存啊,消息中间件啊,都没有。因为老顾这篇主要介绍的是API接口,所以我们聚焦点,其他的模块小伙伴们自行去补充。

接口交互

前端和后端进行交互,前端按照约定请求URL路径,并传入相关参数,后端服务器接收请求,进行业务处理,返回数据给前端。

针对URL路径的restful风格,以及传入参数的公共请求头的要求(如:app_version,api_version,device等),这里就不介绍了,注重介绍一下后端服务器如何实现把数据返回给前端。

返回格式

后端返回给前端我们一般用JSON体方式,定义如下:
{  
#返回状态码
code:integer, 
#返回信息描述
message:string,
#返回值
data:object


CODE状态码

code返回状态码,一般小伙伴们是在开发的时候需要什么,就添加什么。

如接口要返回用户权限异常,我们加一个状态码为101吧,下一次又要加一个数据参数异常,就加一个102的状态码。这样虽然能够照常满足业务,但状态码太凌乱了。

我们应该可以参考HTTP请求返回的状态码。

下面是常见的HTTP状态码:
  • 200 – 请求成功
  • 301 – 资源(网页等)被永久转移到其它URL
  • 404 – 请求的资源(网页等)不存在
  • 500 – 内部服务器错误



我们可以参考这样的设计,这样的好处就把错误类型归类到某个区间内,如果区间不够,可以设计成4位数。
  • 1000~1999 区间表示参数错误
  • 2000~2999 区间表示用户错误
  • 3000~3999 区间表示接口异常


这样前端开发人员在得到返回值后,根据状态码就可以知道,大概什么错误,再根据message相关的信息描述,可以快速定位。

Message

这个字段相对理解比较简单,就是发生错误时,如何友好的进行提示。一般的设计是和code状态码一起设计,如:

再在枚举中定义,状态码。

状态码和信息就会一一对应,比较好维护。

Data

返回数据体,JSON格式,根据不同的业务又不同的JSON体。

我们要设计一个返回体类Result。

控制层Controller

我们会在controller层处理业务请求,并返回给前端,以order订单为例:

我们看到在获得order对象之后,我们是用的Result构造方法进行包装赋值,然后进行返回。小伙伴们有没有发现,构造方法这样的包装是不是很麻烦,我们可以优化一下。

美观优化

我们可以在Result类中,加入静态方法,一看就懂。

那我们来改造一下Controller。

代码是不是比较简洁了,也美观了。

优雅优化

上面我们看到在Result类中增加了静态方法,使得业务处理代码简洁了。但小伙伴们有没有发现这样有几个问题:
  1. 每个方法的返回都是Result封装对象,没有业务含义。
  2. 在业务代码中,成功的时候我们调用Result.success,异常错误调用Result.failure。是不是很多余。
  3. 上面的代码,判断id是否为null,其实我们可以使用hibernate validate做校验,没有必要在方法体中做判断。


我们最好的方式直接返回真实业务对象,最好不要改变之前的业务方式,如下图:

这个和我们平时的代码是一样的,非常直观,直接返回order对象,这样是不是很完美。那实现方案是什么呢?

实现方案

小伙伴们怎么去实现是不是有点思路,在这个过程中,我们需要做几个事情:
  1. 定义一个注解@ResponseResult,表示这个接口返回的值需要包装一下
  2. 拦截请求,判断此请求是否需要被@ResponseResult注解
  3. 核心步骤就是实现接口ResponseBodyAdvice和@ControllerAdvice,判断是否需要包装返回值,如果需要,就把Controller接口的返回值进行重写。


注解类

用来标记方法的返回值,是否需要包装。

拦截器

拦截请求,是否此请求返回的值需要包装,其实就是运行的时候,解析@ResponseResult注解。

此代码核心思想,就是获取此请求,是否需要返回值包装,设置一个属性标记。

重写返回体


上面代码就是判断是否需要返回值包装,如果需要就直接包装。这里我们只处理了正常成功的包装,如果方法体报异常怎么办?处理异常也比较简单,只要判断body是否为异常类。

怎么做全局的异常处理,篇幅原因,老顾这里就不做介绍了,只要思路理清楚了,自行改造就行。

重写Controller


在控制器类上或者方法体上加上@ResponseResult注解,这样就ok了,简单吧。到此返回的设计思路完成,是不是又简洁,又优雅。

总结

这个方案还有没有别的优化空间,当然是有的。如:每次请求都要反射一下,获取请求的方法是否需要包装,其实可以做个缓存,不需要每次都需要解析。当然整体思路了解,小伙伴们就可以在此基础上面自行扩展。

原文链接: https://segmentfault.com/a/1190000021653916

相关 [设计 api 接口] 推荐:

API设计新思维:用流畅接口构造内部DSL

- 风子 - 酷壳 - CoolShell.cn
感谢@weidagang (Todd)向酷壳投递本文. 程序设计语言的抽象机制包含了两个最基本的方面:一是语言关注的基本元素/语义;另一个是从基本元素/语义到复合元素/语义的构造规则. 在C、C++、Java、C#、Python等通用语言中,语言的基本元素/语义往往离问题域较远,通过API库的形式进行层层抽象是降低问题难度最常用的方法.

如何优雅设计 API 接口,实现统一格式返回?

- - DockOne.io
【编者的话】在移动互联网,分布式、微服务盛行的今天,现在项目绝大部分都采用的微服务框架,前后端分离方式. 题外话:前后端的工作职责越来越明确,现在的前端都称之为大前端,技术栈以及生态圈都已经非常成熟;以前后端人员瞧不起前端人员,那现在后端人员要重新认识一下前端,前端已经很成体系了. 一般系统的大致整体架构图如下:.

各个IP API接口

- - 谁主沉浮
腾讯的IP地址API接口地址: http://fw.qq.com/ipaddress. 返回的是数据格式为:var IPData = new Array(“114.218.183.139″,””,”江苏省”,”苏州市”);. .

Java API 设计清单 « 友好的API

- - 东西
在设计Java API的时候总是有很多不同的规范和考量. 与任何复杂的事物一样,这项工作往往就是在考验我们思考的缜密程度. 就像飞行员起飞前的检查清单,这张清单将帮助软件设计者在设计Java API的过程中回忆起那些明确的或者不明确的规范. 本文也可以看作为“ API设计指南”这篇文章的附录. 我们还准备了一些前后比对的例子来展示这个列表如何帮助你理清设计需求,找出错误,识别糟糕的设计实践以及如何寻找改进的时机.

API 设计二三事

- 烙饼 - 岁月如歌
所有程序员都是 API 设计者. 很认可 Dan Webb 的这句话. 近期刚好也有一些思考,总结分享下. jQuery 很优秀,原由之一就是其 API 具有很强的可预测性. 这样,不用详细阅读文档,根据直觉,就可以推测出 API 的一些高级用法,并且记忆深刻(因为是自己探索发现出来的). 我们可能会好奇,是什么让我们拥有这个“直觉”.

RESTful API 设计指南

- - 阮一峰的网络日志
网络应用程序,分为前端和后端两个部分. 当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备......). 因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信. 这导致API构架的流行,甚至出现 "API First"的设计思想. RESTful API是目前比较成熟的一套互联网应用程序的API设计理论.

Web API 设计摘要

- - CSDN博客架构设计推荐文章
最近读了一本微电子书 Brian Mulloy 所著《Web API Design》感觉颇多收获,特对其内容做了个整理摘要以便回顾其观点精华以指导日常工作中的设计思路. 本文主要讲述 Web API 设计,追求一种更务实的 REST 风格. 正如作者所说 REST 是一种架构风格,而非严格的标准,没必要在形式定义上去做过多真论,到底什么才是真正的 REST.

Web API设计方法论

- - 博客园_知识库
  英文原文: A Web API Design Methodology.    为 Web 设计、实现和维护 API 不仅仅是一项挑战;对很多公司来说,这是一项势在必行的任务. 本系列 将带领读者走过一段旅程,从为 API 确定业务用例到设计方法论,解决实现难题,并从长远的角度看待在 Web 上维护公共 API.

思考系统API设计的问题

- edware_love - C++博客-首页原创精华区
最近正好在思考系统API设计中考量的一些问题,. 我现在的理解是这样的,假设有巨大的真实内存. windows首先将高2G的内存自己占了,用作各种内核对象. 这2G内存共享给每个进程,但进程不能直接访问,只能通过windows给定的函数访问. : 然后每个进程都给他2G内存,进程如果创建自己的对象就放到自己那2G内存里面,如果要建立内核对象就放到共享的那高2G里面去.

如何设计一个优秀的API

- - 标点符
到目前为止,已经负责API接近两年了,这两年中发现现有的API存在的问题越来越多,但很多API一旦发布后就不再能修改了,即时升级和维护是必须的. 一旦API发生变化,就可能对相关的调用者带来巨大的代价,用户需要排查所有调用的代码,需要调整所有与之相关的部分,这些工作对他们来说都是额外的. 如果辛辛苦苦完成这些以后,还发现了相关的bug,那对用户的打击就更大.