夜雨聆风前置认知
接口加密的核心目的：防止数据在传输过程中被窃听、篡改、伪造。根据加密逻辑分为三大类：对称加密、非对称加密、哈希加密（单向散列），三类算法用途不同，经常组合使用。
加密类型 1：对称加密（AES / DES 为代表）
1.1、核心原理
加密和解密使用同一个密钥，发送方用密钥加密明文，接收方用同一个密钥解密密文。
通俗类比：就像一把锁配一把钥匙，锁门和开门用同一把钥匙；双方都要有钥匙才能开锁。
1.2、主流代表算法
核心概念补充（测试必懂，否则调不通加密接口）
- 工作模式
常见 ECB、CBC、CTR 等，CBC 模式最常用，需要偏移量 IV - 填充方式
常见 PKCS5、PKCS7，数据长度不够分组时的补齐规则 - 偏移量 IV
CBC 模式下的初始向量，类似 “盐值”，增加加密随机性 - 输出格式
通常加密后是二进制，一般转成 Base64 字符串传输
1.3、完整加密通信流程
调用方和服务端提前约定好：加密算法（AES）、工作模式（CBC）、填充方式（PKCS7）、密钥、IV 偏移量 调用方把请求参数（JSON 字符串）用 AES 密钥加密，得到密文，转成 Base64 调用方把 Base64 密文放在请求体中，发送给服务端 服务端收到请求，把 Base64 密文转回二进制，用相同的 AES 密钥解密 解密成功得到明文参数，执行业务逻辑 服务端把响应数据用 AES 加密，返回给调用方 调用方用密钥解密响应，得到明文数据
1.4、适用场景
接口请求体 / 响应体整体加密（如金融、政务高安全项目） 大批量数据加密传输 前端敏感字段加密（如手机号、身份证号）
1.5、可直接执行的测试方法
- 1.5.1、正向加密解密验证
操作：用约定的密钥、算法、模式加密明文，再用相同配置解密，验证解密后和原文一致 预期：明文 → 加密 → 解密 = 原明文，无乱码、无丢失 - 1.5.2、错误密钥验证
操作：用错误的密钥加密请求，发送给服务端 预期：服务端解密失败，返回对应错误码，不返回明文数据，不抛出 500 异常 - 1.5.3、篡改密文验证
操作：修改密文中的任意字符，发送给服务端 预期：解密失败，返回错误，不能解析出错乱数据 - 1.5.4、配置一致性验证
操作：对照接口文档，逐一核对算法、模式、填充方式、密钥长度、IV、输出格式 预期：所有配置和文档约定一致，缺一项都要找开发确认 - 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、可直接执行的测试方法
- 2.6.1、公钥加密私钥解密验证
操作：用公钥加密明文，用对应私钥解密，验证解密后与原文一致 预期：加解密配对正确，数据完整 - 2.6.2、错误密钥解密验证
操作：用 A 的公钥加密，用 B 的私钥解密 预期：解密失败，无法得到明文 - 2.6.3、私钥签名公钥验签验证
操作：用私钥对数据签名，用公钥验证签名有效性 预期：签名验证通过，确认数据未篡改 - 2.6.4、篡改数据验签验证
操作：对签名后的数据修改任意内容，再验签 预期：验签失败，能识别数据被篡改 - 2.6.5、密钥长度合规性验证
操作：确认 RSA 密钥长度是否≥2048 位 预期：符合安全规范，不使用 1024 位及以下弱密钥
加密类型 3：哈希加密（单向散列，MD5 / SHA 系列）
3.1、核心原理
也叫单向散列算法，不可逆，只能明文加密成密文，不能从密文还原成明文。相同输入永远得到相同定长输出，输入微小变化会导致输出完全不同（雪崩效应）。
通俗类比：就像人的指纹，每个人的指纹唯一，但你不能从指纹还原出整个人。
3.2、主流代表算法
核心概念：加盐（Salt）
为什么加盐：直接 MD5 密码容易被彩虹表破解，加盐后相同密码哈希值不同，大幅提升破解难度 用法： MD5(密码 + 盐值)或MD5(盐值 + 密码 + 盐值)，盐值是随机字符串，每个用户一个盐注意：盐值不能写死在代码里，要随机生成，和哈希值一起存数据库
3.3、典型应用场景
- 密码加密存储
数据库不存明文密码，只存密码的哈希值，校验时重新哈希对比 - 接口参数签名
对请求参数拼接后做哈希，防止参数被篡改（Day2 的签名鉴权核心） - 文件完整性校验
下载文件后计算 MD5，和官方对比，确认文件没被篡改 - 数据去重、唯一标识
3.4、可直接执行的测试方法
- 3.4.1、一致性验证
操作：相同输入多次计算哈希值 预期：输出完全一致，无差异 - 3.4.2、雪崩效应验证
操作：修改输入中的一个字符，重新计算哈希 预期：输出结果完全不同，无规律 - 3.4.3、加盐哈希验证
操作：按照约定的加盐规则，拼接明文和盐值，计算哈希 预期：和服务端计算结果一致，加盐顺序、拼接方式完全对齐 - 3.4.4、不可逆验证
操作：拿到哈希值，尝试反推明文 预期：无法直接反推，符合单向特性 - 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、 企业级接口文档规范
- 4.1、命名统一规范
参数名全系统风格统一（全下划线或全驼峰，不混用） 接口名语义清晰，不用缩写、不用歧义词汇 错误码命名规则统一，不同模块有固定号段 - 4.2、信息完整规范
所有参数必填性、类型、取值范围明确，无 “待定”“待补充” 所有枚举值列出全部可选值和含义 嵌套对象、数组必须逐层展开，不省略 - 4.3、示例真实规范
请求、响应示例为真实可用数据，能直接复制调试 示例数据符合字段类型、长度、取值范围约束 - 4.4、版本同步规范
接口变更必须同步更新文档 有明确的版本号和变更记录，标注变更时间、变更内容、变更人 - 4.5、权限清晰规范
每个接口明确标注鉴权要求、权限等级 全局鉴权规则和特殊接口鉴权分别说明
5、接口文档常见问题
参数缺失必填性、类型说明 响应体字段不全，嵌套对象不展开 错误码缺失，或只有 code 没有说明 文档和代码实现不一致（参数名、类型、返回值对不上） 没有示例，或示例是假数据无法调试 鉴权说明模糊，不知道要不要传 Token 枚举值、取值范围不明确 接口变更不更新文档，版本混乱
三、核心易混点深度辨析
1、 加密 vs 编码 vs 哈希
2、鉴权 vs 加密
鉴权：身份校验，解决 “你是谁、能不能访问” 的问题，是访问控制 加密：数据保护，解决 “数据会不会被偷看、篡改” 的问题，是数据安全 关系：二者独立又配合，比如登录接口：密码用 RSA 加密传输，登录成功后用 Token 鉴权
3. 对称加密 vs 非对称加密
4、 接口文档 vs 需求文档
需求文档：从业务角度描述功能、规则、场景，面向产品、业务、测试 接口文档：从技术角度描述接口的输入输出、参数、格式，面向开发、测试、对接方 测试原则：以需求文档为准，接口文档是实现依据；文档和需求冲突时，按需求来，同步确认开发
四、新手避坑指南（高频误区，提前规避）
❌ 误区：MD5 是加密算法
✅ 纠正：MD5 是哈希散列算法，不可逆，严格来说不属于加密；加密的核心特征是可逆解密
❌ 误区：Base64 能加密数据
✅ 纠正：Base64 只是编码格式，任何人都能直接解码，完全没有安全性，不能当加密用
❌ 误区：RSA 加密速度快，适合加密整个请求体
✅ 纠正：非对称加密速度很慢，只适合加密小数据（如密码、对称密钥），大数据量加密一定用对称加密
❌ 误区：接口文档都是对的，按文档测就行
✅ 纠正：文档滞后是常态，测试要带着怀疑的态度读文档，发现不一致及时确认，不能全信文档
❌ 误区：参数只有 Query 和 Body 两种
✅ 纠正：路径参数、表单参数都是常见类型，特别是文件上传必须用 form-data，传参方式错了接口一定调不通
❌ 误区：密码加密存储用 MD5 就够了
✅ 纠正：纯 MD5 可被彩虹表破解，必须加盐，且现在更推荐用 bcrypt、Argon2 等专用密码哈希算法
