乐于分享
好东西不私藏

接口加密全体系与接口文档规范【day3】

接口加密全体系与接口文档规范【day3】
一、接口加密方式全解析

前置认知

接口加密的核心目的:防止数据在传输过程中被窃听、篡改、伪造。根据加密逻辑分为三大类:对称加密、非对称加密、哈希加密(单向散列),三类算法用途不同,经常组合使用。

加密类型 1:对称加密(AES / DES 为代表)

1.1、核心原理

加密和解密使用同一个密钥,发送方用密钥加密明文,接收方用同一个密钥解密密文。

通俗类比:就像一把锁配一把钥匙,锁门和开门用同一把钥匙;双方都要有钥匙才能开锁。

1.2、主流代表算法

算法
密钥长度
安全性
速度
现状
DES
56 位
低,易被暴力破解
快
已淘汰,仅老旧系统使用
3DES
112/168 位
中等
慢
逐步淘汰
AES(高级加密标准)
128/192/256 位
高,当前主流
极快
全球通用,企业首选

核心概念补充(测试必懂,否则调不通加密接口)

  • 工作模式
    常见 ECB、CBC、CTR 等,CBC 模式最常用,需要偏移量 IV
  • 填充方式
    常见 PKCS5、PKCS7,数据长度不够分组时的补齐规则
  • 偏移量 IV
    CBC 模式下的初始向量,类似 “盐值”,增加加密随机性
  • 输出格式
    通常加密后是二进制,一般转成 Base64 字符串传输
注意:加密接口调不通,90% 是因为算法、模式、填充、密钥、IV、输出格式这 6 个点没对齐

1.3、完整加密通信流程

  • 调用方和服务端提前约定好:加密算法(AES)、工作模式(CBC)、填充方式(PKCS7)、密钥、IV 偏移量
  • 调用方把请求参数(JSON 字符串)用 AES 密钥加密,得到密文,转成 Base64
  • 调用方把 Base64 密文放在请求体中,发送给服务端
  • 服务端收到请求,把 Base64 密文转回二进制,用相同的 AES 密钥解密
  • 解密成功得到明文参数,执行业务逻辑
  • 服务端把响应数据用 AES 加密,返回给调用方
  • 调用方用密钥解密响应,得到明文数据

1.4、适用场景

  • 接口请求体 / 响应体整体加密(如金融、政务高安全项目)
  • 大批量数据加密传输
  • 前端敏感字段加密(如手机号、身份证号)

1.5、可直接执行的测试方法

  1. 1.5.1、正向加密解密验证
    • 操作:用约定的密钥、算法、模式加密明文,再用相同配置解密,验证解密后和原文一致
    • 预期:明文 → 加密 → 解密 = 原明文,无乱码、无丢失
  2. 1.5.2、错误密钥验证
    • 操作:用错误的密钥加密请求,发送给服务端
    • 预期:服务端解密失败,返回对应错误码,不返回明文数据,不抛出 500 异常
  3. 1.5.3、篡改密文验证
    • 操作:修改密文中的任意字符,发送给服务端
    • 预期:解密失败,返回错误,不能解析出错乱数据
  4. 1.5.4、配置一致性验证
    • 操作:对照接口文档,逐一核对算法、模式、填充方式、密钥长度、IV、输出格式
    • 预期:所有配置和文档约定一致,缺一项都要找开发确认
  5. 1.5.5、边界数据验证
    • 操作:加密空字符串、超长字符串、特殊字符内容
    • 预期:加密解密正常,不报错、不截断

加密类型 2:非对称加密(RSA 为代表)

2.1、核心原理

加密和解密使用一对不同的密钥:公钥(Public Key)和私钥(Private Key)。公钥公开给所有人,私钥自己保管。

  • 公钥加密 → 只能用私钥解密(用于加密传输)
  • 私钥签名 → 只能用公钥验签(用于身份认证、防篡改)
  • 通俗类比:公钥是公开的锁,所有人都能拿到锁把信锁上;私钥是唯一的钥匙,只有主人能开锁读信。

2.2、主流代表算法

  • RSA
    最主流、应用最广的非对称加密算法,密钥长度通常 1024/2048/4096 位,2048 位是当前安全标准
  • SM2:国密算法,国内政务、金融项目强制要求
  • ECC:椭圆曲线加密,相同安全强度下密钥更短,移动端常用

2.3、两大核心应用场景(必须区分,测试重点不同)

2.3.1、场景 1:数据加密传输
  • 用法:发送方用接收方的公钥加密数据,接收方用自己的私钥解密
  • 特点:只有持有私钥的人能解密,防止数据被窃听
  • 典型案例:登录密码加密传输,前端用后端公钥加密密码,后端用私钥解密
2.3.2、场景 2:数字签名与验签
  • 用法:发送方用自己的私钥对数据签名,接收方用发送方的公钥验签
  • 作用:确认数据是发送方发的,且中途没被篡改
  • 典型案例:支付回调签名,平台用私钥对回调数据签名,商户用公钥验签,防止伪造回调

2.4、RSA 加密通信流程(以登录密码加密为例)

  • 后端生成一对 RSA 公钥和私钥,私钥自己保管,公钥返回给前端
  • 用户输入密码,前端用后端的公钥加密密码,得到密文
  • 前端把密码密文传给后端
  • 后端用自己的私钥解密密文,得到明文密码
  • 后端校验密码正确性,返回登录结果

2.5、适用场景

  • 密钥交换、对称密钥的加密分发
  • 登录密码、敏感信息的加密传输
  • 数字签名、支付回调、接口防伪造
  • 低数据量、高安全要求的场景

2.6、可直接执行的测试方法

  1. 2.6.1、公钥加密私钥解密验证
    • 操作:用公钥加密明文,用对应私钥解密,验证解密后与原文一致
    • 预期:加解密配对正确,数据完整
  2. 2.6.2、错误密钥解密验证
    • 操作:用 A 的公钥加密,用 B 的私钥解密
    • 预期:解密失败,无法得到明文
  3. 2.6.3、私钥签名公钥验签验证
    • 操作:用私钥对数据签名,用公钥验证签名有效性
    • 预期:签名验证通过,确认数据未篡改
  4. 2.6.4、篡改数据验签验证
    • 操作:对签名后的数据修改任意内容,再验签
    • 预期:验签失败,能识别数据被篡改
  5. 2.6.5、密钥长度合规性验证
    • 操作:确认 RSA 密钥长度是否≥2048 位
    • 预期:符合安全规范,不使用 1024 位及以下弱密钥

加密类型 3:哈希加密(单向散列,MD5 / SHA 系列)

3.1、核心原理

也叫单向散列算法,不可逆,只能明文加密成密文,不能从密文还原成明文。相同输入永远得到相同定长输出,输入微小变化会导致输出完全不同(雪崩效应)。

通俗类比:就像人的指纹,每个人的指纹唯一,但你不能从指纹还原出整个人。

3.2、主流代表算法

核心概念:加盐(Salt)

  • 为什么加盐:直接 MD5 密码容易被彩虹表破解,加盐后相同密码哈希值不同,大幅提升破解难度
  • 用法:MD5(密码 + 盐值) 或 MD5(盐值 + 密码 + 盐值),盐值是随机字符串,每个用户一个盐
  • 注意:盐值不能写死在代码里,要随机生成,和哈希值一起存数据库

3.3、典型应用场景

  • 密码加密存储
    数据库不存明文密码,只存密码的哈希值,校验时重新哈希对比
  • 接口参数签名
    对请求参数拼接后做哈希,防止参数被篡改(Day2 的签名鉴权核心)
  • 文件完整性校验
    下载文件后计算 MD5,和官方对比,确认文件没被篡改
  • 数据去重、唯一标识

3.4、可直接执行的测试方法

  1. 3.4.1、一致性验证
    • 操作:相同输入多次计算哈希值
    • 预期:输出完全一致,无差异
  2. 3.4.2、雪崩效应验证
    • 操作:修改输入中的一个字符,重新计算哈希
    • 预期:输出结果完全不同,无规律
  3. 3.4.3、加盐哈希验证
    • 操作:按照约定的加盐规则,拼接明文和盐值,计算哈希
    • 预期:和服务端计算结果一致,加盐顺序、拼接方式完全对齐
  4. 3.4.4、不可逆验证
    • 操作:拿到哈希值,尝试反推明文
    • 预期:无法直接反推,符合单向特性
  5. 3.4.5、密码存储安全验证
    • 操作:查看数据库用户表,确认密码字段
    • 预期:不存储明文密码,只存储哈希值,且有加盐处理

补充:混合加密机制

纯对称或纯非对称都有短板,真实项目几乎都是组合使用,最典型的就是 HTTPS 的 TLS 握手流程:

  • 客户端和服务端建立连接,服务端返回公钥证书
  • 客户端生成一个随机对称密钥,用服务端公钥加密这个对称密钥,发给服务端
  • 服务端用私钥解密,得到对称密钥
  • 后续所有通信都用这个对称密钥加密数据
    核心逻辑:用非对称加密解决对称密钥的安全分发问题,用对称加密解决大数据量加密的性能问题

二、接口文档核心结构与规范

1、接口文档的核心价值

接口文档是开发、测试、产品、第三方对接方的唯一共同契约,是所有接口工作的依据:

  • 开发:按文档开发接口,保证实现一致
  • 测试:按文档设计用例、写断言、判定缺陷
  • 对接方:按文档调用接口,完成业务对接
  • 核心原则:文档必须和代码同步,文档错误比没有文档危害更大

2、接口文档的两层结构

2.1、第一层:全局配置层(解读文档第一步先看全局)

所有接口通用的规则,放在文档首页 / 全局设置里,不看全局直接读接口一定会踩坑:

  • 全局域名与环境
    测试环境、预发环境、生产环境的域名地址
  • 全局鉴权规则
    鉴权方式、Token 放置位置、Token 格式、无需鉴权的接口列表
  • 全局请求头
    所有接口必须携带的公共请求头,如Content-Type、appId、timestamp
  • 统一响应结构
    全系统通用的响应体格式,如code/message/data三段式
  • 全局错误码
    系统级通用错误码,如 401 未授权、500 服务器错误
  • 数据格式约定
    时间格式(时间戳 / ISO 格式)、金额单位(分 / 元)、枚举值定义
  • 版本号
    当前文档版本、更新记录、变更说明

2.2、第二层:单接口详情层(每个接口独立的定义)

也就是单接口的 8 大核心要素,下面逐要素拆解到字段级,确保解读无遗漏。

3、单接口 8 大核心要素

3.1、要素 1:基础信息

  • 接口名称:清晰描述接口用途,如「用户手机号登录接口」
  • 接口描述:补充业务背景、使用场景、特殊说明
  • 所属模块:归属的业务模块,如用户模块、订单模块
  • 请求方法:GET/POST/PUT/DELETE 等,严格对应 RESTful 语义
  • 请求 URL:接口路径,不含域名,如/api/v1/user/login
  • 接口状态:开发中、已上线、已废弃

3.2、要素 2:请求头(Request Headers)

列出所有请求头要求,区分「必填」和「选填」,常见头字段:

测试注意点:必须确认每个头字段的必填性,遗漏必填头会导致接口报错

3.3、要素 3:请求参数(最核心、最容易出问题的部分)

必须区分 4 种参数类型,不同类型传参方式完全不同:

3.3.1、 路径参数(Path Parameters)
  • 位置:URL 路径中,用{}包裹,如/users/{userId}
  • 特点:必填,用于定位唯一资源
  • 示例:/users/123 中 123 就是 userId 的路径参数值
3.3.2、查询参数(Query Parameters)
  • 位置:URL 问号后面,用&拼接,如/users?page=1&size=10
  • 特点:多用于过滤、排序、分页,GET 接口的参数基本都是 Query 参数
  • 支持多值、数组
3.3.3、请求体参数(Body Parameters)
  • 位置:请求体中,JSON 格式,POST/PUT/PATCH 接口主要传参方式
  • 特点:参数量大、结构复杂,支持嵌套对象、数组
  • 对应 Content-Type:application/json
3.3.4、表单参数(Form Parameters)
  • 位置:表单格式提交
  • 分两种:application/x-www-form-urlencoded(普通表单)、multipart/form-data(文件上传)
  • 特点:文件上传必须用 form-data 格式

每个参数必须包含的 5 个属性:

  • 参数名:字段名称,严格区分大小写
  • 参数类型:string、int、boolean、object、array 等
  • 是否必填:是 / 否
  • 参数说明:字段含义、取值范围、枚举值
  • 示例值:真实可用的示例

3.4、要素 4:响应体(Response Body)

  • 统一外层结构:code(业务状态码)、message(提示信息)、data(响应数据)
  • data 部分详细拆解:每个字段的名称、类型、含义
  • 区分成功响应和失败响应,分别给出示例
  • 嵌套对象、数组必须逐层展开说明,不能只写 object 不拆字段

3.5、要素 5:错误码(Error Codes)

每个接口可能出现的业务错误码,必须包含:

  • 错误码值:如10001
  • 错误信息:如「用户名不存在」
  • 触发场景:什么情况下会返回这个错误码
  • 注意:全局错误码 + 接口业务错误码,共同组成完整的错误码体系,测试时每个错误码都要覆盖对应用例

3.6、要素 6:鉴权说明

  • 是否需要鉴权:是 / 否
  • 鉴权方式:Token/JWT/AKSK 等
  • 权限要求:普通用户 / 管理员 / 特定角色
  • 越权说明:不同权限用户能访问的数据范围

3.7、要素 7:完整示例

  • 请求示例:完整的请求 URL、请求头、请求体示例,可直接复制调试
  • 响应示例:完整的成功响应、失败响应示例,字段和说明一一对应
  • 好的文档,示例一定是可直接运行的,不是随手写的假数据

3.8、要素 8:备注与特殊说明

  • 幂等性说明:接口是否幂等,重复调用会不会产生副作用
  • 限流说明:接口限流规则,每秒允许多少次请求
  • 依赖说明:依赖哪些其他接口、哪些服务
  • 废弃说明:是否即将废弃,替代接口是什么

4、 企业级接口文档规范

  1. 4.1、命名统一规范
    • 参数名全系统风格统一(全下划线或全驼峰,不混用)
    • 接口名语义清晰,不用缩写、不用歧义词汇
    • 错误码命名规则统一,不同模块有固定号段
  2. 4.2、信息完整规范
    • 所有参数必填性、类型、取值范围明确,无 “待定”“待补充”
    • 所有枚举值列出全部可选值和含义
    • 嵌套对象、数组必须逐层展开,不省略
  3. 4.3、示例真实规范
    • 请求、响应示例为真实可用数据,能直接复制调试
    • 示例数据符合字段类型、长度、取值范围约束
  4. 4.4、版本同步规范
    • 接口变更必须同步更新文档
    • 有明确的版本号和变更记录,标注变更时间、变更内容、变更人
  5. 4.5、权限清晰规范
    • 每个接口明确标注鉴权要求、权限等级
    • 全局鉴权规则和特殊接口鉴权分别说明

5、接口文档常见问题

  • 参数缺失必填性、类型说明
  • 响应体字段不全,嵌套对象不展开
  • 错误码缺失,或只有 code 没有说明
  • 文档和代码实现不一致(参数名、类型、返回值对不上)
  • 没有示例,或示例是假数据无法调试
  • 鉴权说明模糊,不知道要不要传 Token
  • 枚举值、取值范围不明确
  • 接口变更不更新文档,版本混乱

三、核心易混点深度辨析

1、 加密 vs 编码 vs 哈希

高频误区:Base64 是编码,不是加密;MD5 是哈希算法,不是加密算法(严格来说)

2、鉴权 vs 加密

  • 鉴权:身份校验,解决 “你是谁、能不能访问” 的问题,是访问控制
  • 加密:数据保护,解决 “数据会不会被偷看、篡改” 的问题,是数据安全
  • 关系:二者独立又配合,比如登录接口:密码用 RSA 加密传输,登录成功后用 Token 鉴权

3. 对称加密 vs 非对称加密

4、 接口文档 vs 需求文档

  • 需求文档:从业务角度描述功能、规则、场景,面向产品、业务、测试
  • 接口文档:从技术角度描述接口的输入输出、参数、格式,面向开发、测试、对接方
  • 测试原则:以需求文档为准,接口文档是实现依据;文档和需求冲突时,按需求来,同步确认开发

四、新手避坑指南(高频误区,提前规避)

  1. ❌ 误区:MD5 是加密算法

  2. ✅ 纠正:MD5 是哈希散列算法,不可逆,严格来说不属于加密;加密的核心特征是可逆解密

  3. ❌ 误区:Base64 能加密数据

  4. ✅ 纠正:Base64 只是编码格式,任何人都能直接解码,完全没有安全性,不能当加密用

  5. ❌ 误区:RSA 加密速度快,适合加密整个请求体

  6. ✅ 纠正:非对称加密速度很慢,只适合加密小数据(如密码、对称密钥),大数据量加密一定用对称加密

  7. ❌ 误区:接口文档都是对的,按文档测就行

  8. ✅ 纠正:文档滞后是常态,测试要带着怀疑的态度读文档,发现不一致及时确认,不能全信文档

  9. ❌ 误区:参数只有 Query 和 Body 两种

  10. ✅ 纠正:路径参数、表单参数都是常见类型,特别是文件上传必须用 form-data,传参方式错了接口一定调不通

  11. ❌ 误区:密码加密存储用 MD5 就够了

  12. ✅ 纠正:纯 MD5 可被彩虹表破解,必须加盐,且现在更推荐用 bcrypt、Argon2 等专用密码哈希算法

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料