优雅安全的API接口设计

前言

在实际工作中，我们需要经常跟第三方平台打交道，可能会对接第三方平台API接口，或者提供API接口给第三方平台调用。那么问题来了，如果设计一个优雅的API接口，能够满足：安全性、可重复调用、稳定性、好定位问题等多方面需求？今天跟大家一起聊聊设计API接口时，需要注意的一些地方，希望对你会有所帮助。

一、SIGN签名

为了请求接口参数被篡改，通常会API做签名处理，接口请求方通过参数+时间戳（加时间戳是为了给sign值加一个有效期）+密钥拼接为一个大众未知的字符串，然后进行MD5加密，生成一个SIGN值随参数一起传递到接口请求中。接口的网关，通过协定好的规则，对sign值进行验证，如果不符合规则，直接提示签名错误，直接拦截。

二、RSA加密

有些保密性很强的接口，通常参数整个是一段密文，一般是采用RSA非对称加密的方式，有两组密钥，请求方通过一对公钥来加密，接口方通过私钥解密；接口方返回的值通过另一对公钥加密，请求方通过另一对私钥来解密，密文再用BASE64加解密保证不受编码的影响。

三、设置接口IP白名单

通过设置接口IP白名单的方式，也可以防止一些三方平台非法调用接口。

四、限流

限流方法有三种：对请求ip做限流：比如同一个ip，在一分钟内，对API接口总的请求次数，不能超过10000次。对请求接口做限流：比如同一个ip，在一分钟内，对指定的API接口，请求次数不能超过2000次。对请求用户做限流：比如同一个AK/SK用户，在一分钟内，对API接口总的请求次数，不能超过10000次。我们在实际工作中，可以通过nginx，redis或者gateway实现限流的功能。

五、统一返回值

{
    "code":0,
    "message":null,
    "data":[{"id":123,"name":"abc"}]
}

除了统一正确状态的返回值，也要有错误态的返回值

六、接口请求日志

接口正式运行起来后，会产生大量的日志，特别不方便维护。可采用ElasticSearch中间件将日志存储起来，不仅方便管理，而且可以将系统所有的过程全部记录，便于过程分析。

七、幂等设计

第三方平台极有可能在极短的时间内，请求我们接口多次，比如：在1秒内请求两次。有可能是他们业务系统有bug，或者在做接口调用失败重试，因此我们的API接口需要做幂等设计。

也就是说要支持在极短的时间内，第三方平台用相同的参数请求API接口多次，第一次请求数据库会新增数据，但第二次请求以后就不会新增数据，但也会返回成功。

这样做的目的是不会产生错误数据。

我们在日常工作中，可以通过在数据库中增加唯一索引，或者在redis保存requestId和请求参来保证接口幂等性。

八、限制记录条数

对于对我提供的批量接口，一定要限制请求的记录条数。如果请求的数据太多，很容易造成API接口超时等问题，让API接口变得不稳定。通常情况下，建议一次请求中的参数，最多支持传入500条记录。如果用户传入多余500条记录，则接口直接给出提示。建议这个参数做成可配置的，并且要事先跟第三方平台协商好，避免上线后产生不必要的问题。

九、压测

上线前我们务必要对API接口做一下压力测试，知道各个接口的qps情况。

以便于我们能够更好的预估，需要部署多少服务器节点，对于API接口的稳定性至关重要。

之前虽说对API接口做了限流，但是实际上API接口是否能够达到限制的阀值，这是一个问号，如果不做压力测试，是有很大风险的。

比如：你API接口限流1秒只允许50次请求，但实际API接口只能处理30次请求，这样你的API接口也会处理不过来。

我们在工作中可以用jmeter或者apache benc对API接口做压力测试。

十、异步处理&消息队列

一般的API接口的逻辑都是同步处理的，请求完之后立刻返回结果。

但有时候，我们的API接口里面的业务逻辑非常复杂，特别是有些批量接口，如果同步处理业务，耗时会非常长。

这种情况下，为了提升API接口的性能，我们可以改成异步处理。

在API接口中可以发送一条mq消息，然后直接返回成功。之后，有个专门的mq消费者去异步消费该消息，做业务逻辑处理。

直接异步处理的接口，第三方平台有两种方式获取到。

第一种方式是：我们回调第三方平台的接口，告知他们API接口的处理结果，很多支付接口就是这么玩的。

第二种方式是：第三方平台通过轮询调用我们另外一个查询状态的API接口，每隔一段时间查询一次状态，传入的参数是之前的那个API接口中的id集合。

十一、数据脱敏

有时候第三方平台调用我们API接口时，获取的数据中有一部分是敏感数据，比如：用户手机号、银行卡号等等。

这样信息如果通过API接口直接保留到外网，是非常不安全的，很容易造成用户隐私数据泄露的问题。

这就需要对部分数据做数据脱敏了。

我们可以在返回的数据中，部分内容用星号代替。

已用户手机号为例：182****887。

这样即使数据被泄露了，也只泄露了一部分，不法分子拿到这份数据也没啥用

十二、完善的接口文档

说实话，一份完整的API接口文档，在双方做接口对接时，可以减少很多沟通成本，让对方少走很多弯路。

接口文档中需要包含如下信息：

接口地址请求方式，比如：post或get 请求参数和字段介绍返回值和字段介绍返回码和错误信息加密或签名示例完整的请求demo 额外的说明，比如：开通ip白名单。接口文档中最好能够统一接口和字段名称的命名风格，比如都用驼峰标识命名。

接口地址中可以加一个版本号v1，比如：v1/query/getCategory，这样以后接口有很大的变动，可以非常方便升级版本。

统一字段的类型和长度，比如：id字段用Long类型，长度规定20。status字段用int类型，长度固定2等。

统一时间格式字段，比如：time用String类型，格式为：yyyy-MM-dd

接口文档中写明AK/SK和域名，找某某单独提供等。推荐两个常用服务端接口开发语言的文档工具，PHP的APIDOC、JAVA的swagger,都可在coding的同时将接口文档编写出来，体验还是特别棒的。

前言