标准API接口设计规范

接口签名

接口签名是一种常见的安全措施，用于确保API请求的完整性和身份验证。

实现步骤

以下是实现接口签名的一般步骤：

参数收集：首先，收集所有将发送到API的参数，包括例如用户ID、操作类型、请求数据等。
排序：为了确保签名的一致性，通常需要对参数进行字典序排序。
拼接字符串：将排序后的参数与其值拼接成一个字符串。通常还会在这个字符串中包含一个时间戳和一个密钥（Secret Key）。例如：stringToSign = method + path + params + timestamp + secretKey其中：
- method 是HTTP请求方法，如GET或POST。
- path 是API的路径。
- params 是经过排序的参数字符串。
- timestamp 是请求发起的时间戳。
- secretKey 是只有服务器和客户端知道的密钥。
散列加密：使用一个散列函数，如MD5、SHA-1或SHA-256，对上一步生成的字符串进行加密，生成签名。例如：sign = hash(stringToSign)
发送请求：在发送API请求时，在请求参数或请求头中增加sign参数。
服务器验证：服务器接收到请求后，会用相同的方法重新生成签名，并与客户端提供的签名进行比对。如果两者一致，则认为请求是合法的。
安全考虑：
- 确保secretKey安全，不要泄露给未经授权的第三方。
- 可以考虑使用HTTPS来加密传输过程，防止中间人攻击。
- 签名中包含时间戳可以防止重放攻击，需要验证时间戳的有效性。
错误处理：如果签名验证失败，服务器应该返回一个错误响应，并记录可能的安全事件。接口签名机制能够有效地防止API请求被篡改，确保数据的安全性和请求的合法性。不过，它不提供加密通信的功能，因此对于敏感信息的传输，还需要结合使用加密技术。

案例

生成密钥对

$originalUuid = Uuid::uuid4()->toString();

$app_key = str_replace('-', '', $originalUuid); // 唯一标识ID uuid

$timestamp = time();

$app_secret = sha1($app_key . '|'.$timestamp); // sha1(app_key + update_time)

$createData = [

    'app_name' => '阿克苏平台',

    'app_key' => $app_key,

    'app_secret' => password_hash($app_secret, PASSWORD_DEFAULT), // 加密保存

    'create_time' => $timestamp,

    'update_time' => $timestamp

];

if(AppModel::create($createData)){

    return response_json(200, 'ok');

}

校验签名

// [1] 从请求头中获取签名

$signature = $this->request->header()['x-resty-signature'] ?? '';

// [2] 签名解析 获取： 哈希算法 和 明文数据

list($hashType, $hashValue) = explode('=', $signature, 2);

// [3] 获取请求的内容，格式为json字符换

$jsonContent = $this->request->getContent();

if(empty($jsonContent)) {

    return response_json(400, '请求内容不能为空');

}

$arrayContent = json_decode($jsonContent, true);

if(!isset($arrayContent['app_key']) || !isset($arrayContent['timestamp'])) {

    return response_json(400, '请求app_key timestamp不能为空');

}



if (($arrayContent['timestamp'] + 20) < time() ) {

    return response_json(403, 'timestamp过期');

}

$appInfo = AppModel::where('app_key',$arrayContent['app_key'])->findOrEmpty();

if($appInfo->isEmpty()) {

    return response_json(400, '无效的app_key');

}

// [4] 生成 appSecret

$appSecret = sha1($appInfo->app_key . '|'.$appInfo->update_time);

// [5] hash_hmac — 使用 HMAC 方法生成带有密钥的哈希值

$checkHash = hash_hmac($hashType, json_encode($arrayContent), $appSecret);

// [6] 签名校验

if ($checkHash != $hashValue) {

    return response_json(403, '无效的签名',$this->request->header());

}

return response_json(200, 'ok',$arrayContent);

数据加密

在设计和实现API接口时，我们经常需要处理一些敏感数据，例如用户的登录密码、银行卡号、身份证号码等。这些信息若以明文形式在网络上传输，将面临极大的安全风险，容易受到恶意监听和数据泄露的威胁。

在设计和实现API接口时，我们经常需要处理一些敏感数据，例如用户的登录密码、银行卡号、转账金额和身份证号码等。这些信息若以明文形式在网络上传输，将面临极大的安全风险，容易受到恶意监听和数据泄露的威胁。

安全建议

为了确保这些关键信息的安全，我们必须采取加密措施来保护数据的完整性和隐私性。以下是一些加强数据安全的建议：

使用HTTPS：始终通过HTTPS协议发送数据，利用SSL/TLS加密层来保护数据传输过程中的安全。
敏感数据加密：对于特别敏感的信息，如登录密码，应在客户端侧进行加密处理，确保只有授权的服务器端能够解密并访问原始数据。
散列密码存储：对于密码等验证信息，不应以明文形式存储或传输。应使用强散列函数（如bcrypt、scrypt或Argon2）来处理密码，并存储散列值。

案例

SM4算法是一种分组密码算法。其分组长度为128bit，密钥长度也为128bit。加密算法与密钥扩展算法均采用32轮非线性迭代结构，以字（32位）为单位进行加密运算，每一次迭代运算均为一轮变换函数F。SM4算法加/解密算法的结构相同，只是使用轮密钥相反，其中解密轮密钥是加密轮密钥的逆序。

SM4加密方式类似于AES加密，为对称加密，可以通过相应的秘钥进行加密和解密

加密

$key = '35d251411ea04318565f0dbda6ffb6a8';



// 加密内容

$content = [

    'name' => 'Tinywan',

    'School' => 'ZheJiang University',

    'age' => 24,

    'github' => [

        'url' => 'https://github.com/Tinywan',

        'start' => 2000,

    ],

];



// 必须转换为字符串

$content = json_encode($content, JSON_UNESCAPED_UNICODE);

$sm4 = new SM4($key);

$encryptContent = $sm4->encrypt($content);

var_dump($encryptContent);

// 加密内容：b4358f5860343dbf2089ba75ee55deca8d922a069413f39cb3f8b64c01048c780ba5f03290642505d65d79c59684d76cf42443047f547c9f29dc2a49f872a2719ce00539058ab1fb5830e8e0c10144b574a87118390baa765b3429ba7afe5d28

解密

$key = '35d251411ea04318565f0dbda6ffb6a8';



// 加密内容

$encryptContent = 'b4358f5860343dbf2089ba75ee55deca8d922a069413f39cb3f8b64c01048c780ba5f03290642505d65d79c59684d76cf42443047f547c9f29dc2a49f872a2719ce00539058ab1fb5830e8e0c10144b574a87118390baa765b3429ba7afe5d28';



$sm4 = new SM4($key);

$decryptedJsonContent = $sm4->decrypt($encryptContent);

print_r($decryptedJsonContent);

解密结果

{

    "name": "Tinywan",

    "School": "ZheJiang University",

    "age": 24,

    "github": {

        "url": "https://github.com/Tinywan",

        "start": 2021

    }

}

可以通过 json_decode($decryptedJsonContent, true) ，转换为数组使用

响应格式统一

API接口响应格式的统一对于客户端开发者来说非常重要，它有助于提高开发效率、降低出错率，并能够快速集成和调试接口。

格式建议

以下是一些建议，用于确保API响应格式的统一性：

明确的版本号：在响应中包含API版本号，这样在API更新时可以保持向后兼容性。
统一的状态码：使用标准HTTP状态码来表示请求的结果，如200表示成功，400表示客户端错误，500表示服务器错误等。
数据封装：响应的数据应该被封装在一个统一的字段中，例如data，这样可以在不同的响应中保持一致性。
分页信息：如果响应数据支持分页，应提供统一的分页信息，如total（总记录数）、perPage（每页记录数）、currentPage（当前页码）和totalPages（总页数）。

通过以上措施，可以确保API接口的响应格式统一、清晰，并且易于客户端开发者使用和集成。

案例

成功示例

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8



{

    "code": 0,

    "msg": "success",

    "data": {

        "token_type": "Bearer",

        "expires_in": 7200,

        "access_token": "XXXXXXXXXXX"

    }

}

异常实例

HTTP/1.1 401 Unauthorized

Content-Type: application/json;charset=UTF-8



{

    "code": 0,

    "msg": "应用信息不存在",

    "data": {}

}

本文章转载微信公众号@开源技术小栈