聊聊API接口设计

随着各行各业精细化的发展，企业使用到的系统也越来越专业化。出于业务需求，会存在多个系统互相调用。本文将结合实践，聊聊API接口设计。

「主要从这三方面来设计接口：」

1. 「接口安全」
2. 「接口规范」
3. 「接口文档」

安全性:

安全性，是系统中最重要的，可以通过这几点来处理。

• 络传输协议
  防止数据被轻易抓取，可以采用https作为接口的网络传输协议，进而保证数据包不被轻易的抓取和分析，有利于保护用户的隐私信息。
• 接口请求方式
  推荐接口使用post方式。调用接口使用的多是get和post，get把参数暴露在URL中，而且长度也有限制，post将请求参数放入到RequestBody中，参数长度无限制。
• 接口限流机制
  限流也是出于系统安全性考虑，避免某一时段调用接口激增导致服务宕机。另外，还可以根据实际的业务场景，选择是否进行防刷机制。常用的有图形验证码、第三方的智能验证码、IP限制等，可以有效防止异常请求。
• 鉴权机制
  调用接口先决条件，需要有一套鉴权机制，鉴权获取到的accessToken 由appId，appKey请求服务端获取。appId，appKey可以结合具体的需求，线下颁发给调用方或者通过平台线上申请。获取到的accessToken，可以设置一次有效，也可以设置一段时间内有效。如果设置一次有效，需要频繁的获取token信息，一般推荐设置accessToken一段时间内有效，具体设计，还得结合实际的业务需求做最后的定论。
• 数据加密，对敏感数据脱敏处理
  可以结合实际情况，对调用接口传输的参数，或者接口响应参数进行加密处理，即使被抓包获取到了数据，也很难分析数据的原始信息，可以提高数据的安全性。加密方式一般有对称加密算法DES、AES和非对称加密算法RSA。数据加密会增加客户端和服务端处理，因此不一定所有的接口都需要增加此机制。
• 数据签名，防止数据被篡改
  签名参数中，可以加入timestamp、nonce、其它参数，设计一套组合规则，使用MD5不可逆的加密算法进行加密。其中，timestamp 是一个时间戳，服务端设置一个阀值，当请求端传输的时间戳不在有效阀值内，返回响应失败，可以有效的减轻DOS攻击。nonce用于处理重复请求，如果一段时间内，有相同的nonce，说明是重复请求，可以直接返回响应失败。

规范性：

• 接口命名规范
  通过URL中的接口名，可以很清晰的知道接口是做什么业务操作的，一般采用这样的格式：
  /控制器名/方法名
  。例如,用户消息列表接口接口：

/**
 * 消息列表
 *
 * @date 2020/12/12 10:25
 */
@RequestMapping(value = "/message/listMessage", method = RequestMethod.POST)
public Map<String, Object> listMessage(@RequestBody Map<String, Object> paramMap) {
    // 业务逻辑处理

复制

• 统一接口返回参数格式
  为了方便接口调用方使用接口，必须包含 resultCode
  -返回状态码、resultMsg
  -返回状态描述、resultData
  -返回信息。我们可以封装公用方法，统一处理返回信息，例如：

/**
* 添加返回结果
*
* @param key        状态码
* @param resultData 返回结果信息
* @return 处理后的返回信息
*/
public static Map<String, Object> addMsgToResult(String key, Map<String, Object>... resultData) {
   // 处理返回信息
   Map<String, Object> convertResultData;
   if (resultData.length > 0 && MapUtils.isNotEmpty(resultData[0])) {
    // 返回数据统一格式处理
    convertResultData = this.convertData(resultData[0]);
   } else {
    convertResultData = MapUtils.EMPTY_MAP;
   }

   // 返回信息
   Map<String, Object> returnMap = new HashMap<>();
   // 返回“返回状态码”
   returnMap.put("resultCode", key);
   // 返回状态描述
   returnMap.put("resultMsg", getProperty(key));
   // 返回信息
   returnMap.put("resultData", convertResultData);
   return returnMap;
}


复制

• 接口定义的功能单一性
  单一性是指接口设计上仅做此接口相关的功能，例如登录接口登录成功后，返回用户的必要信息如userId，而不要去做与登录不相关的信息。如果一个接口的功能做的很大很全，后期需求变更，影响范围将扩大，不便于后期的扩展性，同时也会影响到传输效率。
• 版本控制
  API接口上线后，后续调整不能影响老版本使用，因此要在接口设计中加上版本相关控制。一般方式有：
• 给所有的接口设置统一的版本，在URL中添加统一的版本号；
• 每个接口都有版本号，通过参数传输一个version版本参数。鲸技术平台使用的就是此方案。
• 清晰的日志规范
  打印日志，是方便排查问题，出现异常可以快速定位，因此，打印的日志信息建议包含接口名称、接口业务数据关键索引列、需要关注的详细日志内容。
  对于请求接口参数、接口响应结果，一般可以通过AOP全局记录。例如，AOP中增加入参和出参的打印，可以清晰的定位某某用户请求哪个接口的详细信息：

logger.info("请求接口URL：【{}】，userId：【{}】，请求参数：【{}】", new Object[]{url, userId, paramMap});
logger.info("请求接口URL：【{}】，userId：【{}】，返回数据：【{}】", new Object[]{url, userId, resultMap});

复制

• 增加监控机制
  可以实时主动监控系统是否异常并及时报警，通过监控系统的接口快照，便于异常分析、错误分析等。

• 接口测试用例
  接口开发完后，为了验证接口是否达到预期，单元测试必不可少。一个接口，往往会涉及到多个测试用例，因此新增完接口后，建议把测试用例类提交到版本库， 后续其他人维护接口的时候，可以更清晰的了解接口需求逻辑。

接口文档：

为什么需要接口文档呢？伴随着业务的发展，接口会越来越多。有了一个统一的接口文档，可以方便各端开发人员进行沟通、交流。后期项目维护，或者人员更迭，有了接口文档方便查看、维护。优秀的接口文档，可读性是非常重要的。如何写好接口文档，目标就是用户可以根据你的接口文档能直接使用API，而不是一直要找设计人员问你一堆问题。

下面列出文档需包含的内容：

• 接口名称
  例如 消息列表接口：/user/listMessage
• URI
  提供接口客户端使用的全路径，如果有不同的环境，可以分别在文档中标明，例如:

测试环境地址：https://jing-server-test.com/user/listMessage
生产环境地址：https://jing-server.com/user/listMessage

复制

• 请求协议
  HTTP；HTTPS

• 请求方式
  POST；GET等

• 请求头部

• 请求参数
  

• 响应参数
  业务输出相关的参数
  

• 备注
  接口的描述信息、需要注意事项、返回码等
  

• 请求示例
  
  

• 响应示例
  定义的返回结果数据结构，清晰、直观。
  一般包含：1：返回成功示例；2：返回失败示例。
  

总结

接口设计是个细致活，本文结合以往的经验介绍了一下API接口的设计事项，过程中往往还会有其它情况，因此需要结合实际三思而后行，才能设计出更好的API接口。

- END -