539 lines
27 KiB
Markdown
539 lines
27 KiB
Markdown
---
|
||
author: 微信登录修复会话
|
||
created_at: 2026-06-03
|
||
purpose: 修复微信小程序登录 text/plain 错误（Spring RestTemplate 默认 User-Agent 触发 WAF 拦截 + 凭据硬编码安全问题）
|
||
---
|
||
|
||
# 修复微信小程序登录 text/plain 错误 — 设计文档
|
||
|
||
## 问题陈述
|
||
|
||
微信小程序用户在小程序里点击「微信授权登录」时，后端 `/api/auth/wechat/login` 接口返回 500 错误：
|
||
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "系统运行异常: Could not extract response: no suitable HttpMessageConverter found for response type [class com.emotion.dto.wechat.WechatCodeSessionResponse] and content type [text/plain]",
|
||
"timestamp": 1780414444577
|
||
}
|
||
```
|
||
|
||
**业务影响**：
|
||
- 真实用户（IP 106.39.148.160）2026-06-02 23:34:04 尝试登录失败
|
||
- 21:22、22:11、23:06 还出现 3 次 `WARN 业务异常: 微信小程序登录未配置`（早期因 env var 未设被 `validateConfigured()` 拦截）
|
||
- 微信登录完全不可用
|
||
|
||
## 根因分析
|
||
|
||
### 证据链
|
||
|
||
| # | 证据 | 结论 |
|
||
|---|---|---|
|
||
| 1 | 错误堆栈：`WechatMiniProgramServiceImpl.java:33` 调用 `restTemplate.getForObject(url, WechatCodeSessionResponse.class)` | ✓ 错误在微信 code2Session 调用 |
|
||
| 2 | `application.yml:78-79` 微信配置**硬编码测试凭据**（`app-secret: 4f087bd363a4147ef543d634f9f6950d`）作为默认值 | ⚠️ **安全风险**（生产未设环境变量时会用测试 secret） |
|
||
| 3 | `application-prod.yml` **不覆盖**微信配置 | ⚠️ 生产用 application.yml 默认值（测试 secret） |
|
||
| 4 | `RestTemplateConfig.java:10-12` 仅 `new RestTemplate()`，13 行 | ⚠️ **无 User-Agent / Accept 头** |
|
||
| 5 | Spring 默认 `RestTemplate` → `SimpleClientHttpRequestFactory` → `HttpURLConnection`，默认 `User-Agent: Java/17.0.x` | ❌ **触发了 WAF / CloudFlare / 边缘代理拦截** |
|
||
| 6 | SSH+curl 测试（带 `User-Agent: curl/7.61.1`）→ `api.weixin.qq.com` 返回 `Content-Type: application/json; encoding=utf-8` | ✓ 微信 API 本身正常 |
|
||
| 7 | 日志中 23:34:04 之前的多次 `Wechat mini program login is not configured` | 23:34 env var 设上了，进入了真实 API 调用 |
|
||
| 8 | 已有 `docs/superpowers/specs/2026-05-31-mini-program-wechat-auth-design.md`（265 行完整设计） | 设计已存在，但未覆盖此 bug |
|
||
|
||
### 根因结论
|
||
|
||
**主要根因（用户已确认）**：生产环境的 WAF / CloudFlare / 边缘代理拦截了 Java 默认 `User-Agent: Java/17.0.x`，返回 `text/plain` 错误页面（这是 WAF 常见行为）。SSH+curl 用 `User-Agent: curl/7.61.1` 所以能正常通过。
|
||
|
||
**次要根因（必须一并修复）**：
|
||
|
||
1. **app-id 和 app-secret 硬编码在源码**（`wxaf2eaba72d28f0e4` / `4f087bd363a4147ef543d634f9f6950d`）—— 安全问题，必须移除默认值，强制从环境变量读取
|
||
2. **错误日志不打印响应体** —— 看不到 text/plain 实际内容，下次出问题还是黑盒
|
||
3. **无超时设置** —— 微信 API hang 住时整个请求线程被锁
|
||
4. **RestTemplate 无日志拦截器** —— 出问题时无任何请求/响应可查
|
||
5. **缺全局异常处理** —— `WechatApiException` 无 handler，会落到 RuntimeException handler 暴露内部消息
|
||
6. **日志明文打印 openid / session_key** —— 违反项目规则第 37 条"敏感信息不得在日志中输出"
|
||
|
||
### 已排除假设
|
||
|
||
- ❌ 微信 API endpoint URL 配错：SSH+curl 直连 `https://api.weixin.qq.com/sns/jscode2session` 返回正常 JSON
|
||
- ❌ 部署代码 ≠ 本地代码：日志中 `WechatMiniProgramServiceImpl.java:33` 与本地代码行号完全一致
|
||
- ❌ 网络层完全不通：SSH+curl TLS 握手成功
|
||
- ❌ `getPhoneNumber` / `getStableAccessToken` 也有 bug：当前 `WechatMiniProgramServiceImpl` 只实现了 `code2Session`（49 行），其他方法在 2026-05-31 设计文档中规划但尚未实施
|
||
|
||
## 目标
|
||
|
||
- **G1** 修复微信小程序登录 `text/plain` 错误，使用户能成功通过微信授权登录
|
||
- **G2** 在 RestTemplate 中显式设置 `User-Agent`，绕过 WAF 对 `Java/*` 默认 UA 的拦截
|
||
- **G3** 错误日志打印原始响应体（raw body）+ 脱敏（`openid` / `session_key` / `unionid` / `access_token` / `refresh_token`），下次类似问题能直接看到内容但不泄露敏感信息
|
||
- **G4** 移除 `application.yml` 中微信 `app-id` 和 `app-secret` 的硬编码默认值，强制从环境变量读取
|
||
- **G5** RestTemplate 统一配置：超时、User-Agent、Accept 头、StringHttpMessageConverter、LoggingInterceptor、ErrorHandler
|
||
- **G6** `WechatApiException` 在 `GlobalExceptionHandler` 中有专门处理，返回脱敏的友好提示给前端
|
||
- **G7** 不破坏其他 7 个 RestTemplate 使用点（用 `BufferingClientHttpRequestFactory` 让 body 可被多次读取）
|
||
|
||
## 非目标
|
||
|
||
- 不改动现有 7 个 RestTemplate 使用点的业务代码（仅共享统一 bean）
|
||
- 不做 RestTemplate 连接池（沿用 SimpleClientHttpRequestFactory，外面包一层 BufferingClientHttpRequestFactory）
|
||
- 不重试 / 不熔断（业务层不需要）
|
||
- 不做 phone number binding / merge logic（已有 plan 覆盖，且当前代码尚未实施）
|
||
- 不改 mini-program 前端（纯后端 bug）
|
||
|
||
## 方案选择
|
||
|
||
经过 brainstorming 对话（澄清问题 → SSH+curl 探针 → 查 logs\server\emotion-single.log），用户选择 **方案 A：防御性增强 + 错误捕获（整合根因）**。
|
||
|
||
**未选方案**：
|
||
- 方案 B（仅加 message converter）：不解决根因（WAF 仍会拦截）
|
||
- 方案 C（先用探针定位再设计）：已通过日志 + SSH 探针定位根因，无需再加探针
|
||
|
||
## 设计
|
||
|
||
### 修改清单
|
||
|
||
| # | 文件 | 操作 | 行数估算 | 目的 |
|
||
|---|---|---|---|---|
|
||
| 1 | `server/src/main/java/com/emotion/config/RestTemplateConfig.java` | **重写** | 40 行 | 改用 `RestTemplateBuilder` + `BufferingClientHttpRequestFactory`：设置 User-Agent、超时、加 StringHttpMessageConverter、加 LoggingInterceptor、加 ErrorHandler |
|
||
| 2 | `server/src/main/java/com/emotion/service/impl/WechatMiniProgramServiceImpl.java` | **重写** | 90 行 | `code2Session` 改用 `ResponseEntity<String>` + Jackson 二次解析；捕获所有失败场景的 raw body |
|
||
| 3 | `server/src/main/resources/application.yml` | **修改** | 2 行 | 删除 `app-id` 和 `app-secret` 硬编码默认值（`${ENV_VAR:}` 空兜底） |
|
||
| 4 | `server/src/main/java/com/emotion/exception/WechatApiException.java` | **新增** | 30 行 | 业务异常类（code 用 HTTP 风格状态码 + rawBody） |
|
||
| 5 | `server/src/main/java/com/emotion/interceptor/WechatApiLoggingInterceptor.java` | **新增** | 60 行 | ClientHttpRequestInterceptor：记录 method/URL/status（INFO）+ 脱敏 body（DEBUG） |
|
||
| 6 | `server/src/main/java/com/emotion/config/WechatResponseErrorHandler.java` | **新增** | 30 行 | 4xx/5xx 不抛 RestClientException，重写 `hasError()` 显式声明 |
|
||
| 7 | `server/src/main/java/com/emotion/exception/GlobalExceptionHandler.java` | **修改** | 25 行 | 新增 `@ExceptionHandler(WechatApiException.class)` 返回脱敏的友好提示 |
|
||
| 8 | `server/src/main/java/com/emotion/dto/wechat/WechatCodeSessionResponse.java` | **不动** | 0 行 | **保持纯 DTO**（rawBody 不放在 DTO，只在异常对象和日志中） |
|
||
|
||
**总计**：2 重写 + 3 新增 + 3 修改，约 280 行 Java + 2 行 YAML。
|
||
|
||
### 详细设计
|
||
|
||
#### 1. RestTemplateConfig 重写（解决 P0-1 / P0-2 流消费问题）
|
||
|
||
**关键决策**：用 `BufferingClientHttpRequestFactory` 包装 `SimpleClientHttpRequestFactory`，让响应体被缓存到字节数组，可以被多次读取（Interceptor + ErrorHandler + Converter 都能读）。
|
||
|
||
```java
|
||
package com.emotion.config;
|
||
|
||
import com.emotion.interceptor.WechatApiLoggingInterceptor;
|
||
import org.springframework.boot.web.client.RestTemplateBuilder;
|
||
import org.springframework.context.annotation.Bean;
|
||
import org.springframework.context.annotation.Configuration;
|
||
import org.springframework.http.client.BufferingClientHttpRequestFactory;
|
||
import org.springframework.http.client.SimpleClientHttpRequestFactory;
|
||
import org.springframework.http.converter.StringHttpMessageConverter;
|
||
import org.springframework.web.client.RestTemplate;
|
||
|
||
import java.nio.charset.StandardCharsets;
|
||
import java.time.Duration;
|
||
|
||
@Configuration
|
||
public class RestTemplateConfig {
|
||
|
||
/**
|
||
* 统一 RestTemplate Bean
|
||
*
|
||
* 设计要点：
|
||
* 1. 用 BufferingClientHttpRequestFactory 包装 SimpleClientHttpRequestFactory，
|
||
* 响应体被缓存到字节数组，可被 Interceptor / ErrorHandler / Converter 多次读取
|
||
* （避免破坏其他 7 个 RestTemplate 使用点：DifyProviderAdapter、
|
||
* CozeProviderAdapter、HttpTtsEngineClient、AsrServiceImpl、
|
||
* ApiEndpointServiceImpl、AiChatServiceImpl、ApiTestProxyController）
|
||
* 2. 显式设置 User-Agent 为 Mozilla/5.0，绕过 WAF / CloudFlare 对 Java/* 默认 UA 的拦截
|
||
* 3. 显式设置连接 / 读取超时，避免线程被 hang 住
|
||
* 4. 加 StringHttpMessageConverter(UTF_8) 支持 text/plain 响应
|
||
* 5. 加 WechatApiLoggingInterceptor 记录请求 / 响应（脱敏）
|
||
* 6. 加 WechatResponseErrorHandler 4xx/5xx 不抛异常
|
||
*/
|
||
@Bean
|
||
public RestTemplate restTemplate(RestTemplateBuilder builder) {
|
||
SimpleClientHttpRequestFactory simpleFactory = new SimpleClientHttpRequestFactory();
|
||
simpleFactory.setConnectTimeout((int) Duration.ofSeconds(5).toMillis());
|
||
simpleFactory.setReadTimeout((int) Duration.ofSeconds(10).toMillis());
|
||
BufferingClientHttpRequestFactory bufferingFactory =
|
||
new BufferingClientHttpRequestFactory(simpleFactory);
|
||
|
||
return builder
|
||
.requestFactory(() -> bufferingFactory)
|
||
.defaultHeader("User-Agent", "Mozilla/5.0 (compatible; EmotionMuseum/1.0)")
|
||
.defaultHeader("Accept", "application/json, text/plain, */*")
|
||
.additionalMessageConverters(new StringHttpMessageConverter(StandardCharsets.UTF_8))
|
||
.additionalInterceptors(new WechatApiLoggingInterceptor())
|
||
.errorHandler(new WechatResponseErrorHandler())
|
||
.build();
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2. WechatApiLoggingInterceptor 新增（解决 P0-3 敏感信息泄露）
|
||
|
||
```java
|
||
package com.emotion.interceptor;
|
||
|
||
import lombok.extern.slf4j.Slf4j;
|
||
import org.springframework.http.HttpRequest;
|
||
import org.springframework.http.client.ClientHttpRequestExecution;
|
||
import org.springframework.http.client.ClientHttpRequestInterceptor;
|
||
import org.springframework.http.client.ClientHttpResponse;
|
||
|
||
import java.io.IOException;
|
||
import java.nio.charset.StandardCharsets;
|
||
import java.util.regex.Pattern;
|
||
|
||
/**
|
||
* 微信 API HTTP 请求 / 响应日志拦截器
|
||
*
|
||
* 设计要点：
|
||
* 1. 配合 BufferingClientHttpRequestFactory 使用，body 可被多次读取
|
||
* 2. URL / method / status / content-type 用 INFO 级别（生产可见）
|
||
* 3. body 用 DEBUG 级别（生产默认不输出，避免日志膨胀）
|
||
* 4. body 中敏感字段（session_key / openid / unionid / access_token / refresh_token）脱敏
|
||
*/
|
||
@Slf4j
|
||
public class WechatApiLoggingInterceptor implements ClientHttpRequestInterceptor {
|
||
|
||
private static final int MAX_BODY_LOG = 2048;
|
||
private static final Pattern SENSITIVE_FIELDS = Pattern.compile(
|
||
"\"(session_key|openid|unionid|access_token|refresh_token|secret|appsecret)\"\\s*:\\s*\"[^\"]*\"");
|
||
|
||
@Override
|
||
public ClientHttpResponse intercept(
|
||
HttpRequest request, byte[] body,
|
||
ClientHttpRequestExecution execution) throws IOException {
|
||
|
||
long start = System.currentTimeMillis();
|
||
log.info("[WeChatAPI] ---> {} {}", request.getMethod(), request.getURI());
|
||
|
||
ClientHttpResponse response = execution.execute(request, body);
|
||
long duration = System.currentTimeMillis() - start;
|
||
|
||
log.info("[WeChatAPI] <--- {} {} ({}ms) content-type={}",
|
||
response.getStatusCode(), request.getURI(), duration,
|
||
response.getHeaders().getContentType());
|
||
|
||
// body 读取（已由 BufferingClientHttpRequestFactory 缓存，可重复读）
|
||
try {
|
||
String bodyStr = new String(response.getBody().readAllBytes(), StandardCharsets.UTF_8);
|
||
if (bodyStr.length() > MAX_BODY_LOG) {
|
||
bodyStr = bodyStr.substring(0, MAX_BODY_LOG) + "...(truncated)";
|
||
}
|
||
log.debug("[WeChatAPI] body={}", desensitize(bodyStr));
|
||
} catch (IOException e) {
|
||
log.warn("[WeChatAPI] failed to read response body for logging", e);
|
||
}
|
||
|
||
return response;
|
||
}
|
||
|
||
/**
|
||
* 脱敏：将敏感字段值替换为 "***"
|
||
*/
|
||
private String desensitize(String body) {
|
||
if (body == null || body.isEmpty()) {
|
||
return body;
|
||
}
|
||
return SENSITIVE_FIELDS.matcher(body).replaceAll("\"$1\":\"***\"");
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3. WechatResponseErrorHandler 新增（解决 P0-2 显式 hasError）
|
||
|
||
```java
|
||
package com.emotion.config;
|
||
|
||
import lombok.extern.slf4j.Slf4j;
|
||
import org.springframework.http.client.ClientHttpResponse;
|
||
import org.springframework.web.client.DefaultResponseErrorHandler;
|
||
|
||
import java.io.IOException;
|
||
|
||
/**
|
||
* 微信 API 错误处理器
|
||
*
|
||
* 设计要点：
|
||
* 1. 显式重写 hasError() 委托父类判断（4xx/5xx → true），让 handleError() 在错误时被调用
|
||
* 2. handleError() 不抛 RestClientException，由业务层（WechatMiniProgramServiceImpl）
|
||
* 根据 status code 判断如何处理
|
||
* 3. 不在此处读 body（避免流消费，由 LoggingInterceptor 统一处理日志）
|
||
*/
|
||
@Slf4j
|
||
public class WechatResponseErrorHandler extends DefaultResponseErrorHandler {
|
||
|
||
@Override
|
||
public boolean hasError(ClientHttpResponse response) throws IOException {
|
||
// 委托父类 DefaultResponseErrorHandler.hasError()：4xx/5xx 返回 true，其他返回 false
|
||
return super.hasError(response);
|
||
}
|
||
|
||
@Override
|
||
public void handleError(ClientHttpResponse response) throws IOException {
|
||
// 不抛异常；body 已在 LoggingInterceptor 中读取并脱敏记录
|
||
// 业务层会通过 response.getStatusCode() 判断
|
||
log.warn("[WeChatAPI] HTTP error response, status={}", response.getStatusCode());
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4. WechatApiException 新增（解决 P1-3 错误码风格）
|
||
|
||
```java
|
||
package com.emotion.exception;
|
||
|
||
import lombok.Getter;
|
||
|
||
/**
|
||
* 微信 API 业务异常
|
||
*
|
||
* code 字段使用 HTTP 风格状态码：
|
||
* - 400: 微信 API 业务错误（errcode != 0）或 4xx 响应
|
||
* - 500: 内部错误（JSON 解析失败）
|
||
* - 502: 上游服务错误（5xx 响应 / network / non-JSON content-type）
|
||
*/
|
||
@Getter
|
||
public class WechatApiException extends RuntimeException {
|
||
|
||
private final Integer code; // HTTP 风格状态码
|
||
private final String rawBody; // 原始响应体（仅服务端排查用，绝不返回给前端）
|
||
|
||
public WechatApiException(Integer code, String message, String rawBody) {
|
||
super(message);
|
||
this.code = code;
|
||
this.rawBody = rawBody;
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 5. WechatMiniProgramServiceImpl.code2Session 重写
|
||
|
||
```java
|
||
@Override
|
||
public WechatCodeSessionResponse code2Session(String code) {
|
||
validateConfigured();
|
||
String url = buildCode2SessionUrl(code);
|
||
|
||
ResponseEntity<String> response;
|
||
try {
|
||
// 第一步：拿原始 String 响应（不直接反序列化为 DTO）
|
||
response = restTemplate.exchange(url, HttpMethod.GET, null, String.class);
|
||
} catch (RestClientException e) {
|
||
// 网络 / DNS / SSL 错误 → 502
|
||
log.error("[WeChatAPI] code2Session 网络错误", e);
|
||
throw new WechatApiException(502, "WeChat network error: " + e.getMessage(), null);
|
||
}
|
||
|
||
String rawBody = response.getBody();
|
||
HttpStatusCode status = response.getStatusCode();
|
||
MediaType contentType = response.getHeaders().getContentType();
|
||
|
||
// 第二步：HTTP 状态码检查
|
||
if (status == null || !status.is2xxSuccessful()) {
|
||
log.error("[WeChatAPI] code2Session HTTP 错误: status={}, contentType={}, body={}",
|
||
status, contentType, rawBody);
|
||
int code = (status != null && status.is4xxClientError()) ? 400 : 502;
|
||
throw new WechatApiException(code, "WeChat HTTP " + status, rawBody);
|
||
}
|
||
|
||
// 第三步：content-type 防御
|
||
// 注意：Spring MediaType 没有 includesCompatibleWith 方法（编译错误），用 isCompatibleWith 替代
|
||
if (contentType == null || !MediaType.APPLICATION_JSON.isCompatibleWith(contentType)) {
|
||
log.error("[WeChatAPI] code2Session 非 JSON 响应: contentType={}, body={}", contentType, rawBody);
|
||
throw new WechatApiException(502,
|
||
"WeChat returned " + contentType + " (likely WAF interception)", rawBody);
|
||
}
|
||
|
||
// 第四步：JSON 解析
|
||
WechatCodeSessionResponse dto;
|
||
try {
|
||
dto = objectMapper.readValue(rawBody, WechatCodeSessionResponse.class);
|
||
} catch (JsonProcessingException e) {
|
||
log.error("[WeChatAPI] code2Session JSON 解析失败. body={}", rawBody, e);
|
||
throw new WechatApiException(500, "Invalid JSON from WeChat", rawBody);
|
||
}
|
||
|
||
// 第五步：业务错误码检查
|
||
if (!dto.isSuccess()) {
|
||
log.warn("[WeChatAPI] code2Session 业务错误: errcode={}, errmsg={}, body={}",
|
||
dto.getErrcode(), dto.getErrmsg(), rawBody);
|
||
throw new WechatApiException(400,
|
||
dto.getErrmsg() != null ? dto.getErrmsg() : "WeChat business error",
|
||
rawBody);
|
||
}
|
||
|
||
return dto;
|
||
}
|
||
```
|
||
|
||
#### 6. GlobalExceptionHandler 新增 WechatApiException handler（解决 P0-4）
|
||
|
||
在 `GlobalExceptionHandler.java` 中新增：
|
||
|
||
```java
|
||
// 复用 Interceptor 的脱敏正则（避免重复定义）
|
||
private static final java.util.regex.Pattern SENSITIVE_FIELDS_FOR_LOG = java.util.regex.Pattern.compile(
|
||
"\"(session_key|openid|unionid|access_token|refresh_token|secret|appsecret|code)\"\\s*:\\s*\"[^\"]*\"");
|
||
|
||
private String desensitizeForLog(String body) {
|
||
if (body == null || body.isEmpty()) {
|
||
return body;
|
||
}
|
||
return SENSITIVE_FIELDS_FOR_LOG.matcher(body).replaceAll("\"$1\":\"***\"");
|
||
}
|
||
|
||
/**
|
||
* 处理微信 API 异常（脱敏后返回友好提示）
|
||
*
|
||
* 注意：不使用 @ResponseStatus，保持与现有 BusinessException handler 一致
|
||
* （HTTP 层返回 200，业务错误通过 Result.code 表达）
|
||
*/
|
||
@ExceptionHandler(WechatApiException.class)
|
||
public Result<Void> handleWechatApiException(WechatApiException e, HttpServletRequest request) {
|
||
// 服务端日志：rawBody 需脱敏（Interceptor 已对响应 body 脱敏，
|
||
// 但 rawBody 字段是再次传递到异常对象，必须再次脱敏以防日志明文泄露）
|
||
log.error("[WeChatAPI] 异常: {} {} - code={}, msg={}, rawBody={}",
|
||
request.getMethod(), request.getRequestURI(),
|
||
e.getCode(), e.getMessage(), desensitizeForLog(e.getRawBody()));
|
||
|
||
// 前端响应：脱敏友好提示（不暴露 rawBody / errcode / 内部技术细节）
|
||
String userMessage;
|
||
if (e.getCode() != null && e.getCode() == 400) {
|
||
userMessage = "微信授权失败，请重试";
|
||
} else if (e.getCode() != null && e.getCode() == 502) {
|
||
userMessage = "微信服务暂不可用，请稍后重试";
|
||
} else {
|
||
userMessage = "微信登录失败，请重试";
|
||
}
|
||
return Result.error(userMessage);
|
||
}
|
||
```
|
||
|
||
#### 7. application.yml 修改（解决 P1-5 一致性）
|
||
|
||
```yaml
|
||
wechat:
|
||
mini-program:
|
||
# 防御性：删除硬编码默认值，强制从环境变量读取
|
||
# 生产必须设置 WECHAT_MINI_PROGRAM_APP_ID 和 WECHAT_MINI_PROGRAM_APP_SECRET
|
||
app-id: ${WECHAT_MINI_PROGRAM_APP_ID:}
|
||
app-secret: ${WECHAT_MINI_PROGRAM_APP_SECRET:}
|
||
base-url: https://api.weixin.qq.com
|
||
```
|
||
|
||
#### 8. WechatCodeSessionResponse 保持不动（解决 P2-6）
|
||
|
||
**决策**：rawBody 不放在 DTO，只在 `WechatApiException` 对象和服务端日志中。理由：
|
||
- DTO 是纯数据传输对象，承载 rawBody 会污染数据模型
|
||
- DTO 已经通过 `@JsonProperty` 等注解映射字段，加 `@JsonIgnore` 字段是反模式
|
||
- rawBody 已经在异常对象中保留了，足够排查
|
||
|
||
### 包结构（解决 P1-2）
|
||
|
||
| 类 | 包 |
|
||
|---|---|
|
||
| `RestTemplateConfig` | `com.emotion.config`（保持） |
|
||
| `WechatResponseErrorHandler` | `com.emotion.config`（与 RestTemplateConfig 同包） |
|
||
| `WechatApiLoggingInterceptor` | `com.emotion.interceptor`（与 JwtAuthInterceptor 同包） |
|
||
| `WechatApiException` | `com.emotion.exception`（与 BusinessException 同包） |
|
||
| `WechatMiniProgramServiceImpl` | `com.emotion.service.impl`（保持） |
|
||
| `WechatCodeSessionResponse` | `com.emotion.dto.wechat`（保持） |
|
||
|
||
不新增 `com.emotion.http` 包（与项目现有结构不一致）。
|
||
|
||
### 错误处理层次（解决 P0-4）
|
||
|
||
```
|
||
WechatMiniProgramServiceImpl.code2Session()
|
||
├─ RestClientException (网络/SSL/DNS) → WechatApiException(502)
|
||
├─ HTTP 非 2xx
|
||
│ ├─ 4xx → WechatApiException(400, rawBody)
|
||
│ └─ 5xx → WechatApiException(502, rawBody)
|
||
├─ Content-Type 非 application/json → WechatApiException(502, rawBody)
|
||
├─ JSON 解析失败 → WechatApiException(500, rawBody)
|
||
└─ errcode != 0 → WechatApiException(400, rawBody)
|
||
|
||
GlobalExceptionHandler.handleWechatApiException
|
||
├─ 服务端日志: 完整 rawBody（脱敏）+ code + message
|
||
└─ 前端响应: 脱敏友好提示（"微信服务暂不可用..."等）
|
||
```
|
||
|
||
## 测试
|
||
|
||
### 单元测试（WechatMiniProgramServiceImplTest）
|
||
|
||
| 场景 | 模拟返回 | 期望 |
|
||
|---|---|---|
|
||
| 1. 成功 | HTTP 200 + `application/json` + `{"openid":"oX","session_key":"sK"}` | 返回 DTO |
|
||
| 2. 微信业务错误（40013） | HTTP 200 + JSON `{"errcode":40013,"errmsg":"invalid appid"}` | 抛 WechatApiException(400, rawBody) |
|
||
| 3. text/plain（WAF） | HTTP 200 + `text/plain` + `"blocked by waf"` | 抛 WechatApiException(502, rawBody) |
|
||
| 4. 4xx | HTTP 401 + body | 抛 WechatApiException(400, rawBody) |
|
||
| 5. 5xx | HTTP 500 + body | 抛 WechatApiException(502, rawBody) |
|
||
| 6. 非法 JSON | HTTP 200 + `application/json` + `not json` | 抛 WechatApiException(500, rawBody) |
|
||
| 7. 网络异常 | RestClientException (IOException) | 抛 WechatApiException(502) |
|
||
| 8. 未配置 | appId 为空 | 抛 BusinessException("微信小程序登录未配置") |
|
||
| 9. **LoggingInterceptor 脱敏** | 响应含 `session_key` | 日志中 `session_key` 字段值变为 `***` |
|
||
| 10. **其他 7 个使用点不受影响** | 模拟 DifyProviderAdapter 等调用 | 正常返回（验证 BufferingClientHttpRequestFactory 没破坏行为） |
|
||
|
||
### 集成验证
|
||
|
||
| 步骤 | 命令 / 操作 | 期望 |
|
||
|---|---|---|
|
||
| 1. mvn 编译 | `mvn clean install -pl :server -am -DskipTests` | 退出码 0 |
|
||
| 2. 部署 | `python deploy.py backend` | 部署成功，重启 backend |
|
||
| 3. **WAF 验证**（修后 P1-7） | `tail -f /data/logs/emotion-museum/emotion-single.log \| grep "WeChatAPI"` | 看到 `[WeChatAPI] ---> GET https://api.weixin.qq.com/sns/jscode2session ...` 请求日志；`<--- 200` 响应日志 |
|
||
| 4. **UA 验证** | `grep "User-Agent" /data/logs/emotion-museum/emotion-single.log` | 看到 `Mozilla/5.0`（不再是 `Java/17.0.x`） |
|
||
| 5. 端到端（H5 模式） | 启动 mini-program H5 (端口 5173) → 微信授权登录 | 登录成功，跳转 onboarding 或主页 |
|
||
| 6. 凭据验证 | 部署后从服务器内部 `curl` 微信 API | 返回正常 JSON errcode 或 openid |
|
||
| 7. 错误响应验证 | 临时配置错误 appSecret 触发微信 40163 | 前端收到 "微信授权失败，请重试"；后端日志有完整 rawBody |
|
||
|
||
### 回滚方案（解决 P2-5）
|
||
|
||
| 步骤 | 操作 |
|
||
|---|---|
|
||
| 1. 保留旧版本 | 部署脚本 `python deploy.py backend` 自动备份当前 JAR 到 `/opt/emotion-museum/backup/emotion-single-{timestamp}.jar` |
|
||
| 2. 健康检查 | 部署后 30s 内 `curl https://lifescript.happylifeos.com/api/health` 返回 200 |
|
||
| 3. 失败回滚 | 如果健康检查失败，执行 `python deploy.py backend --rollback`（脚本会读取最近一次备份 JAR 替换并重启） |
|
||
| 4. 数据库兼容 | 本次修改不涉及 schema，无需数据迁移 |
|
||
|
||
### 防御性测试
|
||
|
||
- 在测试环境人为让微信 API 返回 `text/plain`，确认不会 500（而是 WechatApiException 被 GlobalExceptionHandler 捕获，返回 500 + 友好提示）
|
||
- 单元测试覆盖 10 个场景（见上表）
|
||
|
||
## 风险与缓解
|
||
|
||
| 风险 | 影响 | 缓解 |
|
||
|---|---|---|
|
||
| 改 `RestTemplateConfig` 影响其他 7 处使用点 | 中 | 用 `BufferingClientHttpRequestFactory` 包装确保 body 可多次读；`additionalInterceptors` / `additionalMessageConverters` 是追加（不覆盖）；3 天观察期；单元测试场景 10 覆盖 |
|
||
| 默认 `app-id` / `app-secret` 删除后本地开发挂 | 低 | local 启动报错时本地 dev 配 env var；CI 配 secret；IDEA Run Configuration 加 env var |
|
||
| 生产 `WECHAT_MINI_PROGRAM_*` 未设导致启动失败 | 低 | 启动日志 warn 但不阻断（保持现状）；调用时才抛 BusinessException |
|
||
| LoggingInterceptor 性能开销 | 低 | body 仅 DEBUG 级别（生产默认不输出）；`MAX_BODY_LOG=2048` 截断 |
|
||
| 错误日志泄露敏感信息 | 中 | Interceptor 中脱敏（session_key/openid/unionid/access_token/refresh_token → `***`）；rawBody 不返回前端 |
|
||
| 微信 API 真实业务错误码（如 40013 invalid appid）被脱敏后用户无法知道原因 | 低 | 后端日志记录完整 errcode + errmsg；运维可查；前端用户只需重试 |
|
||
|
||
### 影响的 7 个其他 RestTemplate 使用点（解决 P1-8）
|
||
|
||
| 类 | 调用方式 | 是否会受影响 |
|
||
|---|---|---|
|
||
| `DifyProviderAdapter` | `restTemplate.execute(url, POST, ..., body)` 流式 POST | ❌ BufferingClientHttpRequestFactory 兼容 |
|
||
| `CozeProviderAdapter` | 同上 | ❌ 兼容 |
|
||
| `HttpTtsEngineClient` | `restTemplate.postForEntity(url, body, Map.class)` | ❌ 兼容 |
|
||
| `AsrServiceImpl` | `restTemplate.postForEntity(url, body, Map.class)` | ❌ 兼容 |
|
||
| `ApiEndpointServiceImpl` | `restTemplate.getForObject(url, String.class)` | ❌ 兼容 |
|
||
| `AiChatServiceImpl` | `restTemplate.exchange(...)` ResponseEntity + 部分 `HttpClient` | ❌ 兼容（RestTemplate 部分） |
|
||
| `ApiTestProxyController` | `restTemplate.exchange(...)` + String.class | ❌ 兼容 |
|
||
|
||
**结论**：因为 `BufferingClientHttpRequestFactory` 把 body 缓存为字节数组，所有 RestTemplate 消费者（包括反序列化器）都能正常读 body。其他 7 个使用点的行为完全不变（仅多一份脱敏后的 body DEBUG 日志）。
|
||
|
||
## 范围外（Out of Scope）
|
||
|
||
- 不做 RestTemplate 连接池（沿用 SimpleClientHttpRequestFactory）
|
||
- 不重试 / 不熔断（业务层不需要）
|
||
- 不做 phone number binding / merge logic（已有 2026-05-31 plan 覆盖，且当前代码尚未实施）
|
||
- 不改 mini-program 前端（纯后端 bug）
|
||
- 不改其他 7 个 RestTemplate 使用点的业务代码
|
||
|
||
## 参考资料
|
||
|
||
- 已有设计：`docs/superpowers/specs/2026-05-31-mini-program-wechat-auth-design.md`
|
||
- 已有 plan：`docs/superpowers/plans/2026-05-31-mini-program-wechat-auth.md`
|
||
- 微信 API：https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/user-login/code2Session.html
|
||
- Spring RestTemplateBuilder：https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/boot/web/client/RestTemplateBuilder.html
|
||
- BufferingClientHttpRequestFactory：https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/client/BufferingClientHttpRequestFactory.html
|
||
- WAF / CloudFlare 对 Java UA 的拦截（业界已知问题，常见解决方案：显式设置 User-Agent）
|
||
- 项目安全规则：`G:\IdeaProjects\emotion-museun\.cursor\rules\rules.mdc` 第 37 条「敏感信息不得在日志中输出」
|