71 lines
2.7 KiB
Markdown
71 lines
2.7 KiB
Markdown
# 前端工作清单：请求/响应参数加密对接
|
||
|
||
本文档用于前端工程师对接后端新增的“请求/响应参数加密”能力。
|
||
|
||
## 一、背景与目标
|
||
|
||
- 后端新增可配置的参数加密能力（默认关闭）。
|
||
- 当服务端开启时，前端需按约定对请求体进行加密，并能解密响应体。
|
||
|
||
## 二、开关与触发规则
|
||
|
||
- 只有当后端配置开启时才需要启用前端加密。
|
||
- 通过请求头 `X-App-Encrypt: 1` 标记本次请求体已加密。
|
||
- 如果后端开启“响应加密”，返回会带响应头 `X-App-Encrypt: 1`，响应体为加密载荷。
|
||
- 白名单路径（如 `/swagger/`）不会被加解密；前端无需处理。
|
||
|
||
## 三、加密协议与格式
|
||
|
||
- 加密算法：AES-GCM。
|
||
- 密钥：后端配置 `payload_crypto.secret_key`，需与前端一致。
|
||
- 请求/响应体加密后的 JSON 结构：
|
||
|
||
```json
|
||
{ "nonce": "base64", "ciphertext": "base64" }
|
||
```
|
||
|
||
- `nonce` 为 AES-GCM 的随机随机数（Base64），`ciphertext` 为密文（Base64）。
|
||
|
||
## 四、前端需要实现的功能
|
||
|
||
1. **请求加密**
|
||
- 当后端开启 `payload_crypto.request.enable` 时，对请求 JSON 体加密。
|
||
- 请求头添加 `X-App-Encrypt: 1`。
|
||
- 发送的请求体替换为加密后的 JSON 结构（`nonce` + `ciphertext`）。
|
||
|
||
2. **响应解密**
|
||
- 如果响应头包含 `X-App-Encrypt: 1`，则对响应体解密。
|
||
- 解密后得到原始 JSON，再进入业务处理流程。
|
||
|
||
3. **错误处理**
|
||
- 解密失败时要能捕获并上报（日志/埋点），避免页面卡死。
|
||
- 解密失败可提示“数据解析失败，请重试”。
|
||
|
||
4. **降级与兼容**
|
||
- 若响应体不是加密结构（未带头或非 JSON），直接走原逻辑。
|
||
- 与后端保持兼容：后端若未开启加密，不应影响现有请求。
|
||
|
||
## 五、实现建议
|
||
|
||
- 统一封装在请求拦截器/响应拦截器层：
|
||
- Web：Axios 拦截器。
|
||
- 小程序：封装 `wx.request` 统一处理。
|
||
- AES-GCM 需支持：
|
||
- Web: Web Crypto API（`window.crypto.subtle`）。
|
||
- 小程序: 引入可用的 AES-GCM 实现库（需确认平台支持）。
|
||
- `nonce` 长度以 AES-GCM 要求为准（通常 12 字节）。
|
||
|
||
## 六、需要后端确认的信息
|
||
|
||
- `payload_crypto.secret_key` 的实际值（生产环境）。
|
||
- 是否强制 `payload_crypto.request.required`（如果强制，所有接口必须加密）。
|
||
- 哪些接口在白名单（默认 `/swagger/`）。
|
||
|
||
## 七、联调检查清单
|
||
|
||
- 请求体加密后，后端可以正常解析并返回业务数据。
|
||
- 响应解密后，数据结构与未加密时一致。
|
||
- 错误场景：
|
||
- 缺少 `X-App-Encrypt` 头且后端强制加密时应收到 400。
|
||
- 非 JSON 响应不应被尝试解密。
|