一 安全性问题
1.1 调用接口的先决条件-token
appid，
appkey，
timestamp，
nonce，
sign。我们通过以上几个参数来获取调用系统的凭证。
appid和
appkey可以直接通过平台线上申请，也可以线下直接颁发。
appid是全局唯一的，每个
appid将对应一个客户，
appkey需要高度保密。
timestamp是时间戳，使用系统当前的unix时间戳。时间戳的目的就是为了减轻DOS攻击。防止请求被拦截后一直尝试请求接口。服务器端设置时间戳阀值，如果请求时间戳和服务器时间超过阀值，则响应失败。
nonce是随机值。随机值主要是为了增加
sign的多变性，也可以保护接口的幂等性，相邻的两次请求
nonce不允许重复，如果重复则认为是重复提交，响应失败。
sign是参数签名，将
appkey，
timestamp，
nonce拼接起来进行md5加密（当然使用其他方式进行不可逆加密也没问题）。
token，使用参数
appid，
timestamp，
nonce，
sign来获取token，作为系统调用的唯一凭证。
token可以设置一次有效（这样安全性更高），也可以设置时效性，这里推荐设置时效性。如果一次有效的话这个接口的请求频率可能会很高。
token推荐加到请求头上，这样可以跟业务参数完全区分开来。
1.2 使用POST作为接口请求方式
1.3 客户端IP白名单
1.4 单个接口针对ip限流
1.5 记录接口请求日志
1.6 敏感数据脱敏
RSA非对称加密。非对称加密算法有两个密钥，这两个密钥完全不同但又完全匹配。只有使用匹配的一对公钥和私钥，才能完成对明文的加密和解密过程。
二 幂等性问题
三 数据规范问题
3.1 版本控制
3.2 响应状态码规范
| 分类 | 描述 |
|---|---|
| 1xx | 信息，服务器收到请求，需要请求者继续执行操作 |
| 2xx | 成功 |
| 3xx | 重定向，需要进一步的操作以完成请求 |
| 4xx | 客户端错误，请求包含语法错误或无法完成请求 |
| 5xx | 服务端错误 |
状态码枚举类：
public enum CodeEnum {
// 根据业务需求进行添加
SUCCESS(200,"处理成功"),
ERROR_PATH(404,"请求地址错误"),
ERROR_SERVER(505,"服务器内部发生错误");
private int code;
private String message;
CodeEnum(int code, String message) {
this.code = code;
this.message = message;
}
public int getCode() {
return code;
}
public void setCode(int code) {
this.code = code;
}
public String getMessage() {
return message;
}
public void setMessage(String message) {
this.message = message;
}
}
3.3 统一响应数据格式
为了方便给客户端响应，响应数据会包含三个属性，状态码（code）,信息描述（message）,响应数据（data）。客户端根据状态码及信息描述可快速知道接口，如果状态码返回成功，再开始处理数据。
响应结果定义及常用方法：
public class R implements Serializable {
private static final long serialVersionUID = 793034041048451317L;
private int code;
private String message;
private Object data = null;
public int getCode() {
return code;
}
public void setCode(int code) {
this.code = code;
}
public String getMessage() {
return message;
}
public void setMessage(String message) {
this.message = message;
}
public Object getData() {
return data;
}
/**
* 放入响应枚举
*/
public R fillCode(CodeEnum codeEnum){
this.setCode(codeEnum.getCode());
this.setMessage(codeEnum.getMessage());
return this;
}
/**
* 放入响应码及信息
*/
public R fillCode(int code, String message){
this.setCode(code);
this.setMessage(message);
return this;
}
/**
* 处理成功，放入自定义业务数据集合
*/
public R fillData(Object data) {
this.setCode(CodeEnum.SUCCESS.getCode());
this.setMessage(CodeEnum.SUCCESS.getMessage());
this.data = data;
return this;
}
}
总结
本篇文章从安全性、幂等性、数据规范等方面讨论了API设计规范。除此之外，一个好的API还少不了一个优秀的接口文档。接口文档的可读性非常重要，虽然很多程序员都不喜欢写文档，而且不喜欢别人不写文档。为了不增加程序员的压力，推荐使用swagger或其他接口管理工具，通过简单配置，就可以在开发中测试接口的连通性，上线后也可以生成离线文档用于管理API。
最近整理一份面试资料《Java技术栈学习手册》，覆盖了Java技术、面试题精选、Spring全家桶、Nginx、SSM、微服务、数据库、数据结构、架构等等。
获取方式：点“ 在看，关注公众号 Java后端 并回复 777 领取，更多内容陆续奉上。
推
荐
阅
读
1. 介绍一款 API 敏捷开发工具
2. 这 4 种 ThreadLocal 你都知道吗？
3. Windows 给力！可以扔掉 Linux 虚拟机了！
4. 25 张图搞懂「文件系统」
5. 干掉烦人的 Null ！
喜欢文章，点个
在看
本文分享自微信公众号 - Java后端（web_resource）。
如有侵权，请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”，欢迎正在阅读的你也加入，一起分享。
相关文章
暂无评论...
致力于称为最好的程序员导航网站