太强了！看看别人设计的安全好用的OpenApi！
点击上方 "程序架构之家" 关注公众号 设为星标 终身学习 技术干货 及时送达
往期回顾
图片
图片
图片
图片
图片
图片
图片
图片
图片
3、如何设计 API 接口，实现统一格式返回？4、使用 JFR 事件流 API 进行自动化测试终身学习知识星球
程序架构技术群
往期回顾
1、前阿里员工坦言：32岁，我的职业生涯要结束了
2、别惹怒程序员？国美APP弹窗辱骂自己老板：拖欠工资！
为了确保软件接口的标准化和规范化，实现业务模块的重用性和灵活性，并提高接口的易用性和安全性，OpenAPI规范应运而生。这一规范通过制定统一的接口协议，规定了接口的格式、参数、响应和使用方法等内容，从而提高了接口的可维护性和可扩展性。同时，为了也需要考虑接口的安全性和稳定性，本文将针对这些方面介绍一些具体的实践方式。
一、AppId和AppSecret
AppId的使用
AppId作为一种全局唯一的标识符，其作用主要在于方便用户身份识别以及数据分析等方面。为了防止其他用户通过恶意使用别人的AppId来发起请求，一般都会采用配对AppSecret的方式，类似于一种密码。AppId和AppSecret通常会组合生成一套签名，并按照一定规则进行加密处理。在请求方发起请求时，需要将这个签名值一并提交给提供方进行验证。如果签名验证通过，则可以进行数据交互，否则将被拒绝。这种机制能够保证数据的安全性和准确性，提高系统的可靠性和可用性。
AppId的生成
正如前面所说，AppId就是有一个身份标识，生成时只要保证全局唯一即可。
AppSecret生成
AppSecret就是密码，按照一般的的密码安全性要求生成即可。
二、sign签名
RSASignature
首先，在介绍签名方式之前，我们必须先了解2个概念，分别是：非对称加密算法（比如：RSA）、摘要算法（比如：MD5）。
简单来说，非对称加密的应用场景一般有两种，一种是公钥加密，私钥解密，可以应用在加解密场景中（不过由于非对称加密的效率实在不高，用的比较少），还有一种就是结合摘要算法，把信息经过摘要后，再用私钥加密，公钥用来解密，可以应用在签名场景中，也是我们将要使用到的方式。
大致看看RSASignature签名的方式，稍后用到SHA256withRSA底层就是使用的这个方法。
摘要算法与非对称算法的最大区别就在于，它是一种不需要密钥的且不可逆的算法，也就是一旦明文数据经过摘要算法计算后，得到的密文数据一定是不可反推回来的。
签名的作用
好了，现在我们再来看看签名，签名主要可以用在两个场景，一种是数据防篡改，一种是身份防冒充，实际上刚好可以对应上前面我们介绍的两种算法。
数据防篡改
顾名思义，就是防止数据在网络传输过程中被修改，摘要算法可以保证每次经过摘要算法的原始数据，计算出来的结果都一样，所以一般接口提供方只要用同样的原数据经过同样的摘要算法，然后与接口请求方生成的数据进行比较，如果一致则表示数据没有被篡改过。
身份防冒充
这里身份防冒充，我们就要使用另一种方式，比如SHA256withRSA，其实现原理就是先用数据进行SHA256计算，然后再使用RSA私钥加密，对方解的时候也一样，先用RSA公钥解密，然后再进行SHA256计算，最后看结果是否匹配。
三、使用示例
前置准备
- 在没有自动化开放平台时，
appId、appSecret可直接通过线下的方式给到接入方，appSecret需要接入方自行保存好，避免泄露。也可以自行 - 公私钥可以由接口提供方来生成，同样通过线下的方式，把私钥交给对方，并要求对方需保密。
交互流程
客户端准备
- 接口请求方，首先把业务参数，进行摘要算法计算，生成一个签名（sign）
// 业务请求参数
UserEntity userEntity = new UserEntity();
userEntity.setUserId("1");
userEntity.setPhone("13912345678");
// 使用sha256的方式生成签名
String sign = getSHA256Str(JSONObject.toJSONString(userEntity));
sign=c630885277f9d31cf449697238bfc6b044a78545894c83aad2ff6d0b7d486bc5
- 然后继续拼接
header部的参数，可以使用&符合连接，使用Set集合完成自然排序，并且过滤参数为空的key，最后使用私钥加签的方式，得到appSign。
Map<String, String> data = Maps.newHashMap();
data.put("appId", appId);
data.put("nonce", nonce);
data.put("sign", sign);
data.put("timestamp", timestamp);
Set<String> keySet = data.keySet();
String[] keyArray = keySet.toArray(new String[keySet.size()]);
Arrays.sort(keyArray);
StringBuilder sb = new StringBuilder();
for (String k : keyArray) {
if (data.get(k).trim().length() > 0) // 参数值为空，则不参与签名
sb.append(k).append("=").append(data.get(k).trim()).append("&");
}
sb.append("appSecret=").append(appSecret);
System.out.println("【请求方】拼接后的参数：" + sb.toString());
System.out.println();
【请求方】拼接后的参数：appId=123456&nonce=1234&sign=c630885277f9d31cf449697238bfc6b044a78545894c83aad2ff6d0b7d486bc5×tamp=1653057661381&appSecret=654321
【请求方】appSign：m/xk0fkDZlHEkbYSpCPdpbriG/EWG9gNZtInoYOu2RtrLMzHNM0iZe1iL4p/+IedAJN2jgG9pS5o5NZH1i55TVoTbZePdCbR9CEJoHq2TZLIiKPeoRgDimAl14V5jHZiMQCXS8RxWT63W8MKFyZQtB7xCtxVD7+IvLGQOAWn7QX+EmfAUvhgjkaVf2YLk9J9LqtyjfTYeloiP901ZsBZo5y9Gs5P73b+JoEcxmGZRv+Fkv3HnHWTQEpl7W6Lrmd0j44/XupwzHxaanRo5k0ALOVSFohdyMtHk3eOYx/bj+GeMKf8PN4J4tsPndnjyu4XUOnh74aaW9oC2DLiIzr4+Q==
- 最后把参数组装，发送给接口提供方。
Header header = Header.builder()
.appId(appId)
.nonce(nonce)
.sign(sign)
.timestamp(timestamp)
.appSign(appSign)
.build();
APIRequestEntity apiRequestEntity = new APIRequestEntity();
apiRequestEntity.setHeader(header);
apiRequestEntity.setBody(userEntity);
String requestParam = JSONObject.toJSONString(apiRequestEntity);
System.out.println("【请求方】接口请求参数: " + requestParam);
【请求方】接口请求参数: {"body":{"phone":"13912345678","userId":"1"},"header":{"appId":"123456","appSign":"m/xk0fkDZlHEkbYSpCPdpbriG/EWG9gNZtInoYOu2RtrLMzHNM0iZe1iL4p/+IedAJN2jgG9pS5o5NZH1i55TVoTbZePdCbR9CEJoHq2TZLIiKPeoRgDimAl14V5jHZiMQCXS8RxWT63W8MKFyZQtB7xCtxVD7+IvLGQOAWn7QX+EmfAUvhgjkaVf2YLk9J9LqtyjfTYeloiP901ZsBZo5y9Gs5P73b+JoEcxmGZRv+Fkv3HnHWTQEpl7W6Lrmd0j44/XupwzHxaanRo5k0ALOVSFohdyMtHk3eOYx/bj+GeMKf8PN4J4tsPndnjyu4XUOnh74aaW9oC2DLiIzr4+Q==","nonce":"1234","sign":"c630885277f9d31cf449697238bfc6b044a78545894c83aad2ff6d0b7d486bc5","timestamp":"1653057661381"}}
服务端准备
- 从请求参数中，先获取
body的内容，然后签名，完成对参数校验
Header header = apiRequestEntity.getHeader();
UserEntity userEntity = JSONObject.parseObject(JSONObject.toJSONString(apiRequestEntity.getBody()), UserEntity.class);
// 首先，拿到参数后同样进行签名
String sign = getSHA256Str(JSONObject.toJSONString(userEntity));
if (!sign.equals(header.getSign())) {
throw new Exception("数据签名错误！");
}
- 从
header中获取相关信息，并使用公钥进行验签，完成身份认证
// 从header中获取相关信息，其中appSecret需要自己根据传过来的appId来获取
String appId = header.getAppId();
String appSecret = getAppSecret(appId);
String nonce = header.getNonce();
String timestamp = header.getTimestamp();
// 按照同样的方式生成appSign，然后使用公钥进行验签
Map<String, String> data = Maps.newHashMap();
data.put("appId", appId);
data.put("nonce", nonce);
data.put("sign", sign);
data.put("timestamp", timestamp);
Set<String> keySet = data.keySet();
String[] keyArray = keySet.toArray(new String[keySet.size()]);
Arrays.sort(keyArray);
StringBuilder sb = new StringBuilder();
for (String k : keyArray) {
if (data.get(k).trim().length() > 0) // 参数值为空，则不参与签名
sb.append(k).append("=").append(data.get(k).trim()).append("&");
}
sb.append("appSecret=").append(appSecret);
if (!rsaVerifySignature(sb.toString(), appKeyPair.get(appId).get("publicKey"), header.getAppSign())) {
throw new Exception("公钥验签错误！");
}
System.out.println();
System.out.println("【提供方】验证通过！");
完整代码示例
package openApi;
import com.alibaba.fastjson.JSONObject;
import com.google.common.collect.Maps;
import lombok.SneakyThrows;
import org.apache.commons.codec.binary.Hex;
import java.nio.charset.StandardCharsets;
import java.security.*;
import java.security.interfaces.RSAPrivateKey;
import java.security.interfaces.RSAPublicKey;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.*;
public class AppUtils {
/**
* key:appId、value:appSecret
*/
static Map<String, String> appMap = Maps.newConcurrentMap();
/**
* 分别保存生成的公私钥对
* key:appId，value:公私钥对
*/
static Map<String, Map<String, String>> appKeyPair = Maps.newConcurrentMap();
public static void main(String[] args) throws Exception {
// 模拟生成appId、appSecret
String appId = initAppInfo();
// 根据appId生成公私钥对
initKeyPair(appId);
// 模拟请求方
String requestParam = clientCall();
// 模拟提供方验证
serverVerify(requestParam);
}
private static String initAppInfo() {
// appId、appSecret生成规则，依据之前介绍过的方式，保证全局唯一即可
String appId = "123456";
String appSecret = "654321";
appMap.put(appId, appSecret);
return appId;
}
private static void serverVerify(String requestParam) throws Exception {
APIRequestEntity apiRequestEntity = JSONObject.parseObject(requestParam, APIRequestEntity.class);
Header header = apiRequestEntity.getHeader();
UserEntity userEntity = JSONObject.parseObject(JSONObject.toJSONString(apiRequestEntity.getBody()), UserEntity.class);
// 首先，拿到参数后同样进行签名
String sign = getSHA256Str(JSONObject.toJSONString(userEntity));
if (!sign.equals(header.getSign())) {
throw new Exception("数据签名错误！");
}
// 从header中获取相关信息，其中appSecret需要自己根据传过来的appId来获取
String appId = header.getAppId();
String appSecret = getAppSecret(appId);
String nonce = header.getNonce();
String timestamp = header.getTimestamp();
// 按照同样的方式生成appSign，然后使用公钥进行验签
Map<String, String> data = Maps.newHashMap();
data.put("appId", appId);
data.put("nonce", nonce);
data.put("sign", sign);
data.put("timestamp", timestamp);
Set<String> keySet = data.keySet();
String[] keyArray = keySet.toArray(new String[keySet.size()]);
Arrays.sort(keyArray);
StringBuilder sb = new StringBuilder();
for (String k : keyArray) {
if (data.get(k).trim().length() > 0) // 参数值为空，则不参与签名
sb.append(k).append("=").append(data.get(k).trim()).append("&");
}
sb.append("appSecret=").append(appSecret);
if (!rsaVerifySignature(sb.toString(), appKeyPair.get(appId).get("publicKey"), header.getAppSign())) {
throw new Exception("公钥验签错误！");
}
System.out.println();
System.out.println("【提供方】验证通过！");
}
public static String clientCall() {
// 假设接口请求方与接口提供方，已经通过其他渠道，确认了双方交互的appId、appSecret
String appId = "123456";
String appSecret = "654321";
String timestamp = String.valueOf(System.currentTimeMillis());
// 应该为随机数，演示随便写一个
String nonce = "1234";
// 业务请求参数
UserEntity userEntity = new UserEntity();
userEntity.setUserId("1");
userEntity.setPhone("13912345678");
// 使用sha256的方式生成签名
String sign = getSHA256Str(JSONObject.toJSONString(userEntity));
Map<String, String> data = Maps.newHashMap();
data.put("appId", appId);
data.put("nonce", nonce);
data.put("sign", sign);
data.put("timestamp", timestamp);
Set<String> keySet = data.keySet();
String[] keyArray = keySet.toArray(new String[keySet.size()]);
Arrays.sort(keyArray);
StringBuilder sb = new StringBuilder();
for (String k : keyArray) {
if (data.get(k).trim().length() > 0) // 参数值为空，则不参与签名
sb.append(k).append("=").append(data.get(k).trim()).append("&");
}
sb.append("appSecret=").append(appSecret);
System.out.println("【请求方】拼接后的参数：" + sb.toString());
System.out.println();
// 使用sha256withRSA的方式对header中的内容加签
String appSign = sha256withRSASignature(appKeyPair.get(appId).get("privateKey"), sb.toString());
System.out.println("【请求方】appSign：" + appSign);
System.out.println();
// 请求参数组装
Header header = Header.builder()
.appId(appId)
.nonce(nonce)
.sign(sign)
.timestamp(timestamp)
.appSign(appSign)
.build();
APIRequestEntity apiRequestEntity = new APIRequestEntity();
apiRequestEntity.setHeader(header);
apiRequestEntity.setBody(userEntity);
String requestParam = JSONObject.toJSONString(apiRequestEntity);
System.out.println("【请求方】接口请求参数: " + requestParam);
return requestParam;
}
/**
* 私钥签名
*
* @param privateKeyStr
* @param dataStr
* @return
*/
public static String sha256withRSASignature(String privateKeyStr, String dataStr) {
try {
byte[] key = Base64.getDecoder().decode(privateKeyStr);
byte[] data = dataStr.getBytes();
PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(key);
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
PrivateKey privateKey = keyFactory.generatePrivate(keySpec);
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(privateKey);
signature.update(data);
return new String(Base64.getEncoder().encode(signature.sign()));
} catch (Exception e) {
throw new RuntimeException("签名计算出现异常", e);
}
}
/**
* 公钥验签
*
* @param dataStr
* @param publicKeyStr
* @param signStr
* @return
* @throws Exception
*/
public static boolean rsaVerifySignature(String dataStr, String publicKeyStr, String signStr) throws Exception {
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
X509EncodedKeySpec x509EncodedKeySpec = new X509EncodedKeySpec(Base64.getDecoder().decode(publicKeyStr));
PublicKey publicKey = keyFactory.generatePublic(x509EncodedKeySpec);
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initVerify(publicKey);
signature.update(dataStr.getBytes());
return signature.verify(Base64.getDecoder().decode(signStr));
}
/**
* 生成公私钥对
*
* @throws Exception
*/
public static void initKeyPair(String appId) throws Exception {
KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
keyPairGenerator.initialize(2048);
KeyPair keyPair = keyPairGenerator.generateKeyPair();
RSAPublicKey publicKey = (RSAPublicKey) keyPair.getPublic();
RSAPrivateKey privateKey = (RSAPrivateKey) keyPair.getPrivate();
Map<String, String> keyMap = Maps.newHashMap();
keyMap.put("publicKey", new String(Base64.getEncoder().encode(publicKey.getEncoded())));
keyMap.put("privateKey", new String(Base64.getEncoder().encode(privateKey.getEncoded())));
appKeyPair.put(appId, keyMap);
}
private static String getAppSecret(String appId) {
return String.valueOf(appMap.get(appId));
}
@SneakyThrows
public static String getSHA256Str(String str) {
MessageDigest messageDigest;
messageDigest = MessageDigest.getInstance("SHA-256");
byte[] hash = messageDigest.digest(str.getBytes(StandardCharsets.UTF_8));
return Hex.encodeHexString(hash);
}
}
四、常见防护手段
timestamp
前面在接口设计中，我们使用到了timestamp，这个参数主要可以用来防止同一个请求参数被无限期的使用。
稍微修改一下原服务端校验逻辑，增加了5分钟有效期的校验逻辑。
private static void serverVerify(String requestParam) throws Exception {
APIRequestEntity apiRequestEntity = JSONObject.parseObject(requestParam, APIRequestEntity.class);
Header header = apiRequestEntity.getHeader();
UserEntity userEntity = JSONObject.parseObject(JSONObject.toJSONString(apiRequestEntity.getBody()), UserEntity.class);
// 首先，拿到参数后同样进行签名
String sign = getSHA256Str(JSONObject.toJSONString(userEntity));
if (!sign.equals(header.getSign())) {
throw new Exception("数据签名错误！");
}
// 从header中获取相关信息，其中appSecret需要自己根据传过来的appId来获取
String appId = header.getAppId();
String appSecret = getAppSecret(appId);
String nonce = header.getNonce();
String timestamp = header.getTimestamp();
// 请求时间有效期校验
long now = LocalDateTime.now().atZone(ZoneId.systemDefault()).toInstant().toEpochMilli();
if ((now - Long.parseLong(timestamp)) / 1000 / 60 >= 5) {
throw new Exception("请求过期！");
}
cache.put(appId + "_" + nonce, "1");
// 按照同样的方式生成appSign，然后使用公钥进行验签
Map<String, String> data = Maps.newHashMap();
data.put("appId", appId);
data.put("nonce", nonce);
data.put("sign", sign);
data.put("timestamp", timestamp);
Set<String> keySet = data.keySet();
String[] keyArray = keySet.toArray(new String[0]);
Arrays.sort(keyArray);
StringBuilder sb = new StringBuilder();
for (String k : keyArray) {
if (data.get(k).trim().length() > 0) // 参数值为空，则不参与签名
sb.append(k).append("=").append(data.get(k).trim()).append("&");
}
sb.append("appSecret=").append(appSecret);
if (!rsaVerifySignature(sb.toString(), appKeyPair.get(appId).get("publicKey"), header.getAppSign())) {
throw new Exception("验签错误！");
}
System.out.println();
System.out.println("【提供方】验证通过！");
}
nonce
nonce值是一个由接口请求方生成的随机数，在有需要的场景中，可以用它来实现请求一次性有效，也就是说同样的请求参数只能使用一次，这样可以避免接口重放攻击。
具体实现方式：接口请求方每次请求都会随机生成一个不重复的nonce值，接口提供方可以使用一个存储容器（为了方便演示，我使用的是guava提供的本地缓存，生产环境中可以使用redis这样的分布式存储方式），每次先在容器中看看是否存在接口请求方发来的nonce值，如果不存在则表明是第一次请求，则放行，并且把当前nonce值保存到容器中，这样，如果下次再使用同样的nonce来请求则容器中一定存在，那么就可以判定是无效请求了。
这里可以设置缓存的失效时间为5分钟，因为前面有效期已经做了5分钟的控制。
static Cache<String, String> cache = CacheBuilder.newBuilder()
.expireAfterWrite(5, TimeUnit.MINUTES)
.build();
private static void serverVerify(String requestParam) throws Exception {
APIRequestEntity apiRequestEntity = JSONObject.parseObject(requestParam, APIRequestEntity.class);
Header header = apiRequestEntity.getHeader();
UserEntity userEntity = JSONObject.parseObject(JSONObject.toJSONString(apiRequestEntity.getBody()), UserEntity.class);
// 首先，拿到参数后同样进行签名
String sign = getSHA256Str(JSONObject.toJSONString(userEntity));
if (!sign.equals(header.getSign())) {
throw new Exception("数据签名错误！");
}
// 从header中获取相关信息，其中appSecret需要自己根据传过来的appId来获取
String appId = header.getAppId();
String appSecret = getAppSecret(appId);
String nonce = header.getNonce();
String timestamp = header.getTimestamp();
// 请求时间有效期校验
long now = LocalDateTime.now().atZone(ZoneId.systemDefault()).toInstant().toEpochMilli();
if ((now - Long.parseLong(timestamp)) / 1000 / 60 >= 5) {
throw new Exception("请求过期！");
}
// nonce有效性判断
String str = cache.getIfPresent(appId + "_" + nonce);
if (Objects.nonNull(str)) {
throw new Exception("请求失效！");
}
cache.put(appId + "_" + nonce, "1");
// 按照同样的方式生成appSign，然后使用公钥进行验签
Map<String, String> data = Maps.newHashMap();
data.put("appId", appId);
data.put("nonce", nonce);
data.put("sign", sign);
data.put("timestamp", timestamp);
Set<String> keySet = data.keySet();
String[] keyArray = keySet.toArray(new String[0]);
Arrays.sort(keyArray);
StringBuilder sb = new StringBuilder();
for (String k : keyArray) {
if (data.get(k).trim().length() > 0) // 参数值为空，则不参与签名
sb.append(k).append("=").append(data.get(k).trim()).append("&");
}
sb.append("appSecret=").append(appSecret);
if (!rsaVerifySignature(sb.toString(), appKeyPair.get(appId).get("publicKey"), header.getAppSign())) {
throw new Exception("验签错误！");
}
System.out.println();
System.out.println("【提供方】验证通过！");
}
访问权限
数据访问权限，一般可根据appId的身份来获取开放给其的相应权限，要确保每个appId只能访问其权限范围内的数据。
参数合法性校验
参数的合法性校验应该是每个接口必备的，无论是前端发起的请求，还是后端的其他调用都必须对参数做校验，比如：参数的长度、类型、格式，必传参数是否有传，是否符合约定的业务规则等等。
推荐使用SpringBoot Validation来快速实现一些基本的参数校验。
参考如下示例：
@Data
@ToString
public class DemoEntity {
// 不能为空，比较时会除去空格
@NotBlank(message = "名称不能为空")
private String name;
// amount必须是一个大于等于5，小于等于10的数字
@DecimalMax(value = "10")
@DecimalMin(value = "5")
private BigDecimal amount;
// 必须符合email格式
@Email
private String email;
// size长度必须在5到10之间
@Size(max = 10, min = 5)
private String size;
// age大小必须在18到35之间
@Min(value = 18)
@Max(value = 35)
private int age;
// user不能为null
@NotNull
private User user;
// 限制必须为小数，且整数位integer最多2位，小数位fraction最多为4位
@Digits(integer = 2, fraction = 4)
private BigDecimal digits;
// 限制必须为未来的日期
@Future
private Date future;
// 限制必须为过期的日期
@Past
private Date past;
// 限制必须是一个未来或现在的时间
@FutureOrPresent
private Date futureOrPast;
// 支持正则表达式
@Pattern(regexp = "^\\d+$")
private String digit;
}
@RestController
@Slf4j
@RequestMapping("/valid")
public class TestValidController {
@RequestMapping("/demo1")
public String demo12(@Validated @RequestBody DemoEntity demoEntity) {
try {
return "SUCCESS";
} catch (Exception e) {
log.error(e.getMessage(), e);
return "FAIL";
}
}
}
限流保护
在设计接口时，我们应当对接口的负载能力做出评估，尤其是开放给外部使用时，这样当实际请求流量超过预期流量时，我们便可采取相应的预防策略，以免服务器崩溃。
一般来说限流主要是为了防止恶意刷站请求，爬虫等非正常的业务访问，因此一般来说采取的方式都是直接丢弃超出阈值的部分。
限流的具体实现有多种，单机版可以使用Guava的RateLimiter，分布式可以使用Redis，想要更加完善的成套解决方案则可以使用阿里开源的Sentinel。
敏感数据访问
敏感信息一般包含，身份证、手机号、银行卡号、车牌号、姓名等等，应该按照脱敏规则进行处理。
白名单机制
使用白名单机制可以进一步加强接口的安全性，一旦服务与服务交互可以使用，接口提供方可以限制只有白名单内的IP才能访问，这样接口请求方只要把其出口IP提供出来即可。
黑名单机制
与之对应的黑名单机制，则是应用在服务端与客户端的交互，由于客户端IP都是不固定的，所以无法使用白名单机制，不过我们依然可以使用黑名单拦截一些已经被识别为非法请求的IP。
五、其他考虑
- 名称和描述：API 的名称和描述应该简洁明了，并清晰地表明其功能和用途。
- 请求和响应：API 应该支持标准的 HTTP 请求方法，如 GET、POST、PUT 和 DELETE，并定义这些方法的参数和响应格式。
- 错误处理：API 应该定义各种错误码，并提供有关错误的详细信息。
- 文档和示例：API 应该提供文档和示例，以帮助开发人员了解如何使用该 API，并提供示例数据以进行测试。
- 可扩展：API应当考虑未来的升级扩展不但能够向下兼容（一般可以在接口参数中添加接口的版本号），还能方便添加新的能力。
六、额外补充
1. 关于MD5应用的介绍
在提到对于开放接口的安全设计时，一定少不了对于摘要算法的应用（MD5算法是其实现方式之一），在接口设计方面它可以帮助我们完成数据签名的功能，也就是说用来防止请求或者返回的数据被他人篡改。
本节我们单从安全的角度出发，看看到底哪些场景下的需求可以借助MD5的方式来实现。
密码存储
在一开始的时候，大多数服务端对于用户密码的存储肯定都是明文的，这就导致了一旦存储密码的地方被发现，无论是黑客还是服务端维护人员自己，都可以轻松的得到用户的账号、密码，并且其实很多用户的账号、密码在各种网站上都是一样的，也就是说一旦因为有一家网站数据保护的不好，导致信息被泄露，那可能对于用户来说影响的则是他的所有账号密码的地方都被泄露了，想想看这是多少可怕的事情。
所以，那应该要如何存储用户的密码呢？最安全的做法当然就是不存储，这听起来很奇怪，不存储密码那又如何能够校验密码，实际上不存储指的是不存储用户直接输入的密码。
如果用户直接输入的密码不存储，那应该存储什么呢？到这里，MD5就派上用场了，经过MD5计算后的数据有这么几个特点：
- 其长度是固定的。
- 其数据是不可逆的。
- 一份原始数据每次MD5后产生的数据都是一样的。
下面我们来实验一下
public static void main(String[] args) {
String pwd = "123456";
String s = DigestUtils.md5Hex(pwd);
System.out.println("第一次MD5计算：" + s);
String s1 = DigestUtils.md5Hex(pwd);
System.out.println("第二次MD5计算：" + s1);
pwd = "123456789";
String s3 = DigestUtils.md5Hex(pwd);
System.out.println("原数据长度变长，经过MD5计算后长度固定：" + s3);
}
第一次MD5计算：e10adc3949ba59abbe56e057f20f883e
第二次MD5计算：e10adc3949ba59abbe56e057f20f883e
原数据长度变长，经过MD5计算后长度固定：25f9e794323b453885f5181f1b624d0b
有了这样的特性后，我们就可以用它来存储用户的密码了。
public static Map<String, String> pwdMap = Maps.newConcurrentMap();
public static void main(String[] args) {
// 一般情况下，用户在前端输入密码后，向后台传输时，就已经是经过MD5计算后的数据了，所以后台只需要直接保存即可
register("1", DigestUtils.md5Hex("123456"));
// true
System.out.println(verifyPwd("1", DigestUtils.md5Hex("123456")));
// false
System.out.println(verifyPwd("1", DigestUtils.md5Hex("1234567")));
}
// 用户输入的密码，在前端已经经过MD5计算了，所以到时候校验时直接比对即可
public static boolean verifyPwd(String account, String pwd) {
String md5Pwd = pwdMap.get(account);
return Objects.equals(md5Pwd, pwd);
}
public static void register(String account, String pwd) {
pwdMap.put(account, pwd);
}
MD5后就安全了吗？
目前为止，虽然我们已经对原始数据进行了MD5计算，并且也得到了一串唯一且不可逆的密文，但实际上还远远不够，不信，我们找一个破解MD5的网站试一下！
我们把前面经过MD5计算后得到的密文查询一下试试，结果居然被查询出来了！
之所以会这样，其实恰好就是利用了MD5的特性之一：一份原始数据每次MD5后产生的数据都是一样的。
试想一想，虽然我们不能通过密文反解出明文来，但是我们可以直接用明文去和猜，假设有人已经把所有可能出现的明文组合，都经过MD5计算后，并且保存了起来，那当拿到密文后，只需要去记录库里匹配一下密文就能得到明文了，正如上图这个网站的做法一样。
对于保存这样数据的表，还有个专门的名词：彩虹表，也就是说只要时间足够、空间足够，也一定能够破解出来。
加盐
正因为上述情况的存在，所以出现了加盐的玩法，说白了就是在原始数据中，再掺杂一些别的数据，这样就不会那么容易破解了。
String pwd = "123456";
String salt = "wylsalt";
String s = DigestUtils.md5Hex(salt + pwd);
System.out.println("第一次MD5计算：" + s);
第一次MD5计算：b9ff58406209d6c4f97e1a0d424a59ba
你看，简单加一点内容，破解网站就查询不到了吧！
攻防都是在不断的博弈中进行升级，很遗憾，如果仅仅做成这样，实际上还是不够安全，比如攻击者自己注册一个账号，密码就设置成1。
String pwd = "1";
String salt = "wylsalt";
String s = DigestUtils.md5Hex(salt + pwd);
System.out.println("第一次MD5计算：" + s);
第一次MD5计算：4e7b25db2a0e933b27257f65b117582a
虽然要付费，但是明显已经是匹配到结果了。
所以说，无论是密码还是盐值，其实都要求其本身要保证有足够的长度和复杂度，这样才能防止像彩虹表这样被存储下来，如果再能定期更换一个，那就更安全了，虽说无论再复杂，理论上都可以被穷举到，但越长的数据，想要被穷举出来的时间则也就越长，所以相对来说也就是安全的。
数字签名
摘要算法另一个常见的应用场景就是数字签名了，前面章节也有介绍过了
大致流程，百度百科也有介绍
2. 对称加密算法
对称加密算法是指通过密钥对原始数据（明文），进行特殊的处理后，使其变成密文发送出去，数据接收方收到数据后，再使用同样的密钥进行特殊处理后，再使其还原为原始数据（明文），对称加密算法中密钥只有一个，数据加密与解密方都必须事先约定好。
对称加密算法特点
- 只有一个密钥，加密和解密都使用它。
- 加密、解密速度快、效率高。
- 由于数据加密方和数据解密方使用的是同一个密钥，因此密钥更容易被泄露。
常用的加密算法介绍
DES
其入口参数有三个：key、data、mode。key为加密解密使用的密钥，data为加密解密的数据，mode为其工作模式。当模式为加密模式时，明文按照64位进行分组，形成明文组，key用于对数据加密，当模式为解密模式时，key用于对数据解密。实际运用中，密钥只用到了64位中的56位，这样才具有高的安全性。
算法特点
DES算法具有极高安全性，除了用穷举搜索法对DES算法进行攻击外，还没有发现更有效的办法。而56位长的密钥的穷举空间为2^56，这意味着如果一台计算机的速度是每一秒钟检测一百万个密钥，则它搜索完全部密钥就需要将近2285年的时间，可见，这是难以实现的。然而，这并不等于说DES是不可破解的。而实际上，随着硬件技术和Internet的发展，其破解的可能性越来越大，而且，所需要的时间越来越少。使用经过特殊设计的硬件并行处理要几个小时。
为了克服DES密钥空间小的缺陷，人们又提出了3DES的变形方式。
3DES
3DES相当于对每个数据块进行三次DES加密算法，虽然解决了DES不够安全的问题，但效率上也相对慢了许多。
AES
AES用来替代原先的DES算法，是当前对称加密中最流行的算法之一。
ECB模式
AES加密算法中一个重要的机制就是分组加密，而ECB模式就是最简单的一种分组加密模式，比如按照每128位数据块大小将数据分成若干块，之后再对每一块数据使用相同的密钥进行加密，最终生成若干块加密后的数据，这种算法由于每个数据块可以进行独立的加密、解密，因此可以进行并行计算，效率很高，但也因如此，则会很容易被猜测到密文的规律。
private static final String AES_ALG = "AES";
private static final String AES_ECB_PCK_ALG = "AES/ECB/NoPadding";
public static void main(String[] args) throws Exception {
System.out.println("第一次加密：" + encryptWithECB("1234567812345678", "50AHsYx7H3OHVMdF123456", "UTF-8"));
System.out.println("第二次加密：" + encryptWithECB("12345678123456781234567812345678", "50AHsYx7H3OHVMdF123456", "UTF-8"));
}
public static String encryptWithECB(String content, String aesKey, String charset) throws Exception {
Cipher cipher = Cipher.getInstance(AES_ECB_PCK_ALG);
cipher.init(Cipher.ENCRYPT_MODE,
new SecretKeySpec(Base64.decodeBase64(aesKey.getBytes()), AES_ALG));
byte[] encryptBytes = cipher.doFinal(content.getBytes(charset));
return Hex.encodeHexString(encryptBytes);
}
第一次加密：87d2d15dbcb5747ed16cfe4c029e137c
第二次加密：87d2d15dbcb5747ed16cfe4c029e137c87d2d15dbcb5747ed16cfe4c029e137c
可以看出，加密后的密文明显也是重复的，因此针对这一特性可进行分组重放攻击。
CBC模式
CBC模式引入了初始化向量的概念（IV），第一组分组会使用向量值与第一块明文进行异或运算，之后得到的结果既是密文块，也是与第二块明文进行异或的对象，以此类推，最终解决了ECB模式的安全问题。
CBC模式的特点
CBC模式安全性比ECB模式要高，但由于每一块数据之间有依赖性，所以无法进行并行计算，效率没有ECB模式高。
-End-
精彩推荐 1、如何设计API返回码（错误码）？2、干货 | 常见的API接口漏洞总结3、如何设计 API 接口，实现统一格式返回？4、使用 JFR 事件流 API 进行自动化测试终身学习知识星球
构建高质量的终身学习知识星球，旨在帮助读者构建自己的知识体系。加入星球后，可以对星主进行一对一提问，还将获得终身学习体系架构中各个系列的学习内容，每个系列会形成特有的专栏，专栏内容为星主长期积累梳理构成，近期会不断的更新主题，适合读者根据自身情况构建自己的知识体系。同时还提供专栏学习打卡，以及赠书福利等。
程序架构技术群
构建高质量的技术交流社群，欢迎从事编程开发、技术招聘HR进群，也欢迎大家分享自己公司的内推信息，相互帮助，一起进步！
文明发言，以
交流技术、职位内推、行业探讨为主
广告人士勿入，切勿轻信私聊，防止被骗，加我好友，拉你进群
感谢关注，分享不易，提升自己，惠泽他人
终身学习，点赞关注不迷路