编写令人愉悦的API接口(一)

引言

API接口是服务端与客户端沟通的桥梁.较好的API设计能减少客户端与服务端的联调时间,更加关注于自己本身代码的优化与业务层的逻辑.

API设计知识点

API组成

良好的API接口应该从这下面几个方向进行优化

准确的API协议
准确的内容类型
统一的返回类型以及异常处理
良好的接口版本控制体系
API接口路径尽量简短统一
性能与安全

实践

API协议类型划分

GET : 从服务器上获取一个具体的资源或者一个资源列表。
POST : 在服务器上创建一个新的资源。
PUT : 以整体的方式更新服务器上的一个资源。
PATCH : 只更新服务器上一个资源的一个属性。
DELETE : 删除服务器上的一个资源。
HEAD : 获取一个资源的元数据，如数据的哈希值或最后的更新时间。
OPTIONS : 获取客户端能对资源操作的信息。

其中GET,POST,PUT,PATCH,DELETE这五种协议在日常CRUD开发中最为常用以用户模块的业务场景分析

//获取用户列表(分页)
@GetMapping(value = "user")
public R selectList(UserSearch userSearch) {
    //userSearch 是一个搜索实体,里面有页码以及筛选条件属性
    return ResultUtil.data();
}
//获取单个用户信息
@GetMapping(value = "user/{id}")
public R selectOne(@PathVariable("id") String id) {
    //获取用户信息,与分页接口相同采用GET协议,用path传值id,区别与分页的接口
    return ResultUtil.data();
}
//新增用户
@PostMapping
public R add(@RequestBody User user) {
    //新增用户为新资源写入,采用POST接口,入参为用户的实体
    return ResultUtil.data();
}
//修改用户
@PutMapping("{id}")
public R upp(@PathVariable("id") String id,@RequestBody User user) {
    //修改用户所有属性,采用PUT接口,入参为用户的实体,同时id通过path传值
    return ResultUtil.data();
}
//删除用户
@DeleteMapping("{id}")
public R del(@PathVariable("id") String id) {
    //删除用户,采用DELETE协议,id通过path传值
    return ResultUtil.data();    
}
//修改用户部分属性(这里举例修改用户姓名)
@PatchMapping("user/userName/{id}")
public R uppPart(@PathVariable("id") String id,@PartBody String userName) {
    //修改用户部分属性,采用PATCH协议,在基础路由user后面加入要修改的属性名,入参用自定义注解@PartBody,原理就是解析body里单个叫userName的值,也可用Map接收,用自定义注解只是为了后期好维护.
    return ResultUtil.data();    
}

注:切记不要直接使用@RequestMapping()注解,不准确的接口协议定义会导致url重复,客户端也可以通过任意协议调用API接口,很不规范

内容类型(content-Type)规范

application/x-www-form-urlencoded 类型

代码实例

application/x-www-form-urlencoded form表单的默认传输格式,常会在后面跟上编码,即:application/x-www-form-urlencoded;charset=utf-8
此传输格式时,数据会以键值对的形式传输
当为GET请求时,浏览器用x-www-form-urlencoded的编码方式把form数据转换成一个字串（name1=value1&name2=value2...),然后把这个字串append到url后面，用?分割，加载这个新的url。需要对参数进行 urlencode 编码和序列化
当为POST请求时,浏览器把form数据封装到http body中,不可用@RequestBody注解修饰接收实体.

multipart/form-data 类型

代码实例

multipart/form-data form表单的扩展传输格式
此传输格式时会把整个表单以控件为单位分割，并为每个部分加上Content-Disposition(form-data或者file),Content-Type(默认为text/plain),name(控件name)等信息，并加上分割符(boundary)。
当为GET请求时,入参对象或者单属性均可与传入的name键值对一一对应
当为POST请求时,浏览器把form数据封装到http body中,不可用@RequestBody注解修饰接收实体.

application/json 类型

代码实例

application/json JSON传输,现在比较推荐的传输方式
此传输格式时,数据主体是序列化后的JSON字符串
当为GET请求时,?传参方式可传值,参数名为实体内的属性值,用@RequestBody注解修饰,可直接获取到参数名对应的入参
当为POST请求时候,入参封装在body中,用@RequestBody注解修饰接收实体

统一返回类

统一返回类是必须的.统一以后客户端就只需要一个公共解析类即可.对应的业务模型放在泛型result对象中,客户端就只需要用对应的解析器解析剩下的部分.

返回类R

@Data
public class R<T> implements Serializable
    private static final long serialVersionUID = 1L;
    //标识请求是否成功
    private boolean success;
    //操作成功或者失败后,客户端的提示信息
    private String message;
    //http状态码或者自定义的异常状态码
    private Integer code;
    //当前请求的返回时间
    private long timestamp = System.currentTimeMillis();
    //返回给客户端的业务主体数据,可为列表或者单个对象
    private T result;
}

封装返回类工具类 ResultUtil

主要封装一些常用的成功,失败或者回参的静态方法,在控制层返回前端时,只需要返回 ResultUtil.xxx() 对应的方法即可 ResultUtil 代码实例

错误码及消息 ErrorCode

用枚举类型定义ErrorCode,在程序异常时可直接调用 error(Integer code, String msg) 返回给客户端对应的业务异常或者其他系统异常 ErrorCode 代码实例

统一异常处理

异常拦截类 GlobalExceptionHandler

定义 GlobalExceptionHandler 类,用@ControllerAdvice修饰,可实现统一的异常拦截,代码示例中拦截了常见的一些异常类型.

//参照格式
//ExceptionHandler 指定需要拦截的异常类型
@ExceptionHandler(value = Exception.class)
@ResponseBody
//HttpServletRequest 可得到对应的请求参数,Exception 对象可得到对应的异常输出,可记录在日志中便于排查,再返回给客户端相对友好的提示
public R ExceptionHandler(HttpServletRequest req, Exception e) {
        log.error(String.format("Exception requestURI:%s", req.getRequestURI()), e);
        return ResultUtil.error(500, "服务器内部错误");
}

GlobalExceptionHandler 代码实例

业务异常类 BusinessException

定义业务异常类是为了一些比较特殊的情况,此类继承RuntimeException,在复杂的业务中也可定义多个业务异常类型,业务中出现一些逻辑异常就可使用这个业务异常抛出,比如字效验密码错误或者某字段数值超出临界内等等情况.可与上面的ErrorCode类结合使用,定义code应该避免一些系统预设的 http状态码 BusinessException 代码实例

后记

本文主要介绍了API遵循Restful方式的设计方案,传输内容规范以及统一返回类和统一异常拦截.涉及到的代码已经更新到github上 easyDemo-validation 项目中,下一期的文章会给大家分享validation验证包的使用以及接口设计上统一规范的小技巧,欢迎大家start持续关注.