# 前言

> 基于 Spring Boot 3 + Java 17 的企业微信 AI Bot 集成开发文档，涵盖 WebSocket 长连接和 URL 回调两种集成方式的完整实践。



## 一、应用场景

| 场景 | 说明 | 适用模式 |
|------|------|----------|
| **智能客服** | 在群聊/单聊中接收用户消息，自动回复或转人工 | URL 回调 / WebSocket |
| **自动化估值** | 接收结构化车辆信息，调用第三方接口返回估价结果 | URL 回调 |
| **线索推送** | 解析群聊中的商机信息，推送给对应销售人员 | WebSocket |
| **多轮交互** | 引导用户确认/修改信息，实现对话式流程 | URL 回调 |
| **定时通知** | 通过 API 主动向指定用户/群发送消息 | API 推送 |



## 二、架构总览

```mermaid
graph TB
 subgraph 企业微信服务端
 A[企业微信用户] -->|发送消息| B[企业微信 AI Bot 平台]
 end

 subgraph 集成方式
 B -->|方式一: WebSocket 推送| C[WebSocket Client 长连接]
 B -->|方式二: HTTP POST| D[URL Callback 回调接口]
 end

 subgraph Spring Boot 应用
 C --> E[WeComBotWebSocketClient]
 D --> F[WeComCallbackController]
 E --> G[WeComBotServiceImpl]
 F --> G
 G --> H[消息解析 结构化/命令/JSON]
 G --> I[业务处理 估值/推送/回复]
 G --> J[Redis 缓存 access_token/会话]
 end

 subgraph 外部系统
 I --> K[车300 API]
 I --> L[企业微信 消息推送 API]
 end

 style C fill:#e1f5fe
 style D fill:#fff3e0
 style G fill:#e8f5e9
```



## 三、两种集成方式对比

| 对比项 | WebSocket 长连接 | URL 回调模式 |
|--------|------------------|-------------|
| **连接方式** | 客户端主动连接企业微信服务器 | 企业微信向你的服务器推送 HTTP 请求 |
| **实时性** | 实时推送，延迟低 | 准实时，依赖 HTTP 请求 |
| **网络要求** | 需要能访问企业微信 WebSocket 地址 | 需要公网可访问的 HTTPS 地址 |
| **消息解密** | 不需要（消息已解密） | 需要 AES 解密（EncodingAESKey） |
| **消息回复** | 通过 API 发送 | 被动回复 / response_url |
| **超时限制** | 无（长连接保活） | 被动回复 5s，response_url 30s |
| **可靠性** | 需处理断线重连 | HTTP 请求天然可靠 |
| **部署复杂度** | 简单（无需公网地址） | 需要域名 + HTTPS + Nginx 反代 |
| **适用场景** | 内部群消息监听、线索推送 | 交互式对话、自动化估值 |



## 四、URL 回调模式（推荐）

### 4.1 集成流程

```mermaid
sequenceDiagram
 participant User as 企业微信用户
 participant WX as 企业微信服务器
 participant Server as Spring Boot 应用
 participant API as 第三方 API

 User->>WX: 发送消息（@机器人）
 WX->>Server: POST /wechat/callback（加密消息）
 Server->>Server: AES 解密消息
 Server->>Server: 解析消息内容

 alt 结构化车辆信息
 Server-->>WX: 被动回复确认信息
 WX-->>User: 显示确认卡片
 User->>WX: 回复"确认"
 WX->>Server: POST 确认消息
 Server->>API: 异步调用估值接口
 API-->>Server: 返回估价结果
 Server->>WX: response_url 发送结果
 WX-->>User: 显示估价结果
 else 命令格式
 Server->>API: 调用估值接口
 API-->>Server: 返回结果
 Server-->>WX: 被动回复结果
 WX-->>User: 显示结果
 end
```

### 4.2 配置步骤

#### 1. 企业微信管理后台配置

在企业微信管理后台 → 应用管理 → 智能机器人 → URL 回调配置：

- **URL**: `https://你的域名/wechat/callback`
- **Token**: 自定义字符串（需与代码中一致）
- **EncodingAESKey**: 系统自动生成（43位）

#### 2. application.yml 配置

```yaml
wecom:
 bot:
 corp-id: 你的企业ID
 agent-id: 你的应用ID
 secret: 你的应用Secret
 # URL 回调方式配置
 token: 企业微信后台配置的Token
 encoding-aes-key: 企业微信后台的EncodingAESKey
 # 生产环境禁用 WebSocket
 enabled: false
```

#### 3. 回调验证接口（GET）

企业微信在保存回调 URL 时，会发送一次 GET 请求验证：

```java
@Anonymous // 跳过 Spring Security 认证
@RestController
@RequestMapping("/wechat")
public class WeComCallbackController {

 @Value("${wecom.bot.token}")
 private String token;

 @Value("${wecom.bot.encoding-aes-key}")
 private String encodingAesKey;

 /**
 * 验证回调 URL（企业微信后台保存配置时调用）
 */
 @GetMapping("/callback")
 public void verifyCallback(
 @RequestParam("msg_signature") String msgSignature,
 @RequestParam("timestamp") String timestamp,
 @RequestParam("nonce") String nonce,
 @RequestParam("echostr") String echostr,
 HttpServletResponse response) {
 try {
 // 1. 解密 echostr
 String decrypted = WXBizMsgCrypt.decrypt(echostr, encodingAesKey);

 // 2. 返回解密后的明文（必须是纯文本）
 response.setContentType("text/plain;charset=UTF-8");
 response.getWriter().write(decrypted);
 } catch (Exception e) {
 log.error("回调验证失败", e);
 response.setStatus(500);
 }
 }
}
```

#### 4. 消息接收接口（POST）

```java
@Anonymous
@PostMapping("/callback")
public String receiveMessage(@RequestBody String body) {
 // 1. 解析请求体
 JSONObject message = JSON.parseObject(body);
 String encrypt = message.getString("encrypt");
 String responseUrl = message.getString("response_url");

 // 2. 解密消息
 if (encrypt != null && !encrypt.isEmpty()) {
 String decrypted = WXBizMsgCrypt.decrypt(encrypt, encodingAesKey);
 message = JSON.parseObject(decrypted);
 // 提取字段（兼容多种格式）
 String msgType = message.getString("MsgType"); // 标准格式
 if (msgType == null) msgType = message.getString("msgtype"); // AI Bot 格式
 String fromUser = extractFromUser(message);
 String content = extractContent(message);
 responseUrl = message.getString("response_url");
 }

 // 3. 处理消息并回复
 if (content.contains("【车型")) {
 return handleStructuredMessage(content, fromUser, responseUrl);
 } else if (content.startsWith("估值")) {
 return handleCommandValuation(content, fromUser, responseUrl);
 }

 return buildReply("帮助信息...");
}
```

#### 5. 消息加解密

```java
public class WXBizMsgCrypt {

 /**
 * AES-256/CBC/PKCS7 解密
 * 消息格式: random(16B) + msg_len(4B) + msg + appId
 */
 public static String decrypt(String encrypt, String encodingAesKey) throws Exception {
 // 1. Base64 解码 AESKey（43字符 + "=" → 32字节）
 byte[] aesKey = Base64.getDecoder().decode(encodingAesKey + "=");

 // 2. Base64 解码密文
 byte[] encrypted = Base64.getDecoder().decode(encrypt);

 // 3. AES/CBC 解密（IV = aesKey[0..15]）
 Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
 cipher.init(Cipher.DECRYPT_MODE,
 new SecretKeySpec(aesKey, "AES"),
 new IvParameterSpec(Arrays.copyOfRange(aesKey, 0, 16)));
 byte[] decrypted = cipher.doFinal(encrypted);

 // 4. 提取消息：跳过 random(16B)，读取 msg_len(4B)，再读取 msg
 int msgLen = ByteBuffer.wrap(decrypted, 16, 4).getInt();
 return new String(decrypted, 20, msgLen, StandardCharsets.UTF_8);
 }
}
```

#### 6. 消息回复

**方式一：被动回复（5秒内）**

直接返回 JSON 字符串作为 HTTP 响应体：

```java
private String buildReply(String content) {
 JSONObject message = new JSONObject();
 message.put("msgtype", "text");
 JSONObject text = new JSONObject();
 text.put("content", content);
 message.put("text", text);
 return message.toJSONString();
}
```

**方式二：response_url 异步回复（30秒内，一次性）**

```java
private void sendResponse(String responseUrl, String content) {
 JSONObject message = new JSONObject();
 message.put("msgtype", "markdown"); // 必须用 markdown！
 JSONObject markdown = new JSONObject();
 markdown.put("content", content);
 message.put("markdown", markdown);

 HttpHeaders headers = new HttpHeaders();
 headers.setContentType(MediaType.APPLICATION_JSON);
 HttpEntity<String> request = new HttpEntity<>(message.toJSONString(), headers);
 restTemplate.postForEntity(responseUrl, request, String.class);
}
```

**方式三：企业应用消息 API（不限时）**

```java
// 通过 access_token 调用消息推送 API
String url = "https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=" + accessToken;
JSONObject message = new JSONObject();
message.put("touser", userId);
message.put("msgtype", "text");
message.put("agentid", agentId);
JSONObject text = new JSONObject();
text.put("content", content);
message.put("text", text);
restTemplate.postForEntity(url, message, String.class);
```



## 五、WebSocket 长连接模式

### 5.1 集成流程

```mermaid
sequenceDiagram
 participant App as Spring Boot 应用
 participant WX as 企业微信 WebSocket 服务
 participant User as 企业微信用户

 App->>WX: 1. 调用 API 获取 WebSocket URL
 WX-->>App: 返回 wss://xxx 地址
 App->>WX: 2. 建立 WebSocket 连接
 Note over App,WX: 连接保持（心跳保活）

 User->>WX: 3. @机器人 发送消息
 WX->>App: 4. 推送消息（已解密）
 App->>App: 5. 解析并处理消息
 App->>WX: 6. 调用消息 API 回复
 WX-->>User: 7. 显示回复
```

### 5.2 代码实现

#### 1. 添加依赖

```xml
<dependency>
 <groupId>org.java-websocket</groupId>
 <artifactId>Java-WebSocket</artifactId>
 <version>1.5.3</version>
</dependency>
```

#### 2. WebSocket 客户端

```java
public class WeComBotWebSocketClient extends WebSocketClient {

 private final IWeComBotService botService;

 public WeComBotWebSocketClient(URI serverUri, IWeComBotService botService) {
 super(serverUri);
 this.botService = botService;
 }

 @Override
 public void onOpen(ServerHandshake handshakedata) {
 log.info("WebSocket 连接已建立");
 }

 @Override
 public void onMessage(String message) {
 log.info("收到消息: {}", message);
 // 解析消息并调用业务服务处理
 JSONObject msg = JSON.parseObject(message);
 String content = msg.getString("content");
 String fromUser = msg.getString("from_user");
 // 处理业务逻辑...
 botService.sendTextMessage(fromUser, "收到：" + content);
 }

 @Override
 public void onClose(int code, String reason, boolean remote) {
 log.warn("WebSocket 连接关闭: code={}, reason={}", code, reason);
 // 自动重连
 reconnect();
 }

 @Override
 public void onError(Exception ex) {
 log.error("WebSocket 错误", ex);
 }
}
```

#### 3. 签名工具

```java
public class WeComSignUtil {
 /**
 * 生成 WebSocket 连接签名
 * 算法: SHA256(secret + timestamp + nonce)
 */
 public static String generateSignature(String secret, String timestamp, String nonce) {
 String signStr = secret + timestamp + nonce;
 MessageDigest digest = MessageDigest.getInstance("SHA-256");
 byte[] hash = digest.digest(signStr.getBytes(StandardCharsets.UTF_8));
 // 转为十六进制字符串
 StringBuilder hexString = new StringBuilder();
 for (byte b : hash) {
 String hex = Integer.toHexString(0xff & b);
 if (hex.length() == 1) hexString.append('0');
 hexString.append(hex);
 }
 return hexString.toString();
 }
}
```

#### 4. 启动时自动连接

```java
@Component
public class WeComBotStartupListener implements ApplicationRunner {

 @Autowired
 private WeComBotProperties properties;

 @Autowired
 private IWeComBotService botService;

 @Override
 public void run(ApplicationArguments args) {
 if (!properties.isEnabled()) {
 log.info("企业微信 WebSocket 客户端已禁用");
 return;
 }

 String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
 String nonce = WeComSignUtil.generateNonce(16);
 String signature = WeComSignUtil.generateSignature(
 properties.getSecret(), timestamp, nonce);

 // 获取 WebSocket 地址并连接
 String wsUrl = properties.getWebsocketHost();
 WeComBotWebSocketClient client = new WeComBotWebSocketClient(
 new URI(wsUrl), botService);
 client.connect();
 }
}
```



## 六、消息解析策略

### 支持的三种消息格式

```java
public Map<String, String> parseStructuredMessage(String message) {
 Map<String, String> params = new HashMap<>();
 String[] lines = message.split("\\r?\\n");

 for (String line : lines) {
 line = line.trim();
 if (line.isEmpty()) continue;

 // 第一级匹配: 【标签】值 格式
 Matcher matcher = Pattern.compile("【(.+?)[】）](.+)").matcher(line);
 if (!matcher.find()) {
 // 第二级匹配: 标签：值 格式
 matcher = Pattern.compile("(.+?)[：:](.+)").matcher(line);
 if (!matcher.find()) continue;
 }

 String label = matcher.group(1).trim().replaceAll("\\s+", "");
 String value = matcher.group(2).trim();

 switch (label) {
 case "车型": parseCarType(value, params); break;
 case "上牌日期": parseRegistrationDate(value, params); break;
 case "真实公里": params.put("mileage", cleanMileage(value)); break;
 case "车辆颜色": params.put("color", value); break;
 case "车牌归属": params.put("city", value); break;
 }
 }
 return params;
}
```

> **注意**：`Matcher.find()` 是**有状态的**，每次调用会消费匹配结果。不能对同一个 Matcher 调用两次 `find()` 来判断是否匹配成功。应先存储 `find()` 的返回值，再使用 `group()` 获取分组。



## 七、常见问题与解决方案

### 7.1 回调验证失败（errCode: 70002）

| 原因 | 解决方案 |
|------|----------|
| Token 不一致 | 确保 `application.yml` 中的 `token` 与企业微信后台完全一致 |
| Spring Security 未放行 | 在 `SecurityConfig` 中添加 `.requestMatchers("/wechat/callback").permitAll()` |
| 签名验证逻辑错误 | 可先跳过签名验证，直接返回解密后的 echostr |
| 响应格式错误 | 验证接口必须返回**纯文本**，不能是 JSON |

### 7.2 消息回复失败（errcode: 40008）

| 原因 | 解决方案 |
|------|----------|
| msgtype 使用 text | response_url 回复时 **必须使用 `markdown`** 类型 |
| 响应格式错误 | 不能返回 `AjaxResult` 包装，必须返回**原始 JSON 字符串** |
| response_url 过期 | response_url 是一次性链接，30秒内有效 |

### 7.3 AES 解密卡住（cipher.doFinal 挂起）

**现象**：日志打印到 `开始 cipher.doFinal` 后不再输出。

**原因分析**：

1. **JDK 熵池不足**：`/dev/random` 阻塞（Linux 服务器常见）
2. **EncodingAESKey 不匹配**：密钥错误导致解密进入异常路径
3. **JDK 版本 Bug**：某些 JDK 版本的 JCE 实现存在线程阻塞问题

**解决方案**：

```bash
# 1. JVM 启动参数添加随机数源
-Djava.security.egd=file:/dev/./urandom
-Dsecurerandom.source=file:/dev/./urandom

# 2. 安装 haveged 增加系统熵池
sudo yum install -y haveged
sudo systemctl start haveged

# 3. 使用 BouncyCastle 替代 JDK JCE
# pom.xml 添加依赖
<dependency>
 <groupId>org.bouncycastle</groupId>
 <artifactId>bcprov-jdk15on</artifactId>
 <version>1.70</version>
</dependency>
```

**终极方案**：手动实现 AES/CBC 解密，完全绕过高层 API：

```java
AESEngine aes = new AESEngine();
aes.init(false, new KeyParameter(aesKey));

for (int i = 0; i < numBlocks; i++) {
 aes.processBlock(cipherBlock, 0, plainBlock, 0);
 // 手动 CBC 异或
 for (int j = 0; j < 16; j++) {
 plainBlock[j] ^= prevBlock[j];
 }
}
```

### 7.4 WebSocket 连接失败（UnknownHostException）

| 原因 | 解决方案 |
|------|----------|
| 硬编码的 WS 地址无效 | 通过 API 动态获取 WebSocket 地址，不要硬编码 |
| 生产环境不需要 WebSocket | 设置 `wecom.bot.enabled=false` 禁用客户端 |

### 7.5 Matcher.find() 状态陷阱

```java
// ❌ 错误写法：两次 find() 消费了匹配结果
if (matcher.find()) { // 第一次 find()
 // ...
}
if (matcher.find()) { // 第二次 find() 返回 false！
 String label = matcher.group(1);
}

// ✅ 正确写法：保存 find() 结果
boolean matched = matcher.find();
if (matched) {
 String label = matcher.group(1);
}
```

### 7.6 response_url 只能使用一次

response_url 是**一次性**的临时链接，使用后即失效。如果需要多次回复，应使用企业应用消息 API。



## 八、Nginx 反向代理配置

```nginx
server {
 listen 443 ssl;
 server_name your-domain.com;

 ssl_certificate /path/to/cert.pem;
 ssl_certificate_key /path/to/key.pem;

 location /wechat/ {
 proxy_pass http://127.0.0.1:8080;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;

 # 超时设置（企业微信回调可能较慢）
 proxy_read_timeout 60s;
 proxy_send_timeout 60s;
 }
}
```



## 九、项目结构参考

```
ruoyi-system/src/main/java/com/ruoyi/system/wecom/
├── config/
│ └── WeComBotProperties.java # 配置属性类
├── controller/
│ └── WeComCallbackController.java # URL 回调控制器
├── service/
│ ├── IWeComBotService.java # 服务接口
│ └── impl/
│ └── WeComBotServiceImpl.java # 服务实现（消息解析/估值/推送）
└── util/
 ├── WXBizMsgCrypt.java # AES 消息加解密
 └── WeComSignUtil.java # SHA256 签名工具
```



## 十、关键注意事项

1. **消息类型**：response_url 回复必须用 `markdown` 类型，用 `text` 会报 40008 错误
2. **返回格式**：回调接口必须返回原始 JSON 字符串，不能用 `AjaxResult` 等框架包装
3. **安全放行**：回调路径必须添加 `@Anonymous` 注解，跳过 Spring Security 认证
4. **Token 一致性**：`application.yml` 中的 Token 必须与企业微信后台完全一致
5. **生产环境**：仅使用 URL 回调时，应禁用 WebSocket 客户端（`wecom.bot.enabled=false`）
6. **超时策略**：被动回复 5 秒限制，耗时操作（如估值）应使用 response_url 或异步 + 企业应用消息 API
7. **幂等处理**：企业微信可能重试推送，需防止重复处理同一消息

基于 Spring Boot 3 + Java 17 的企业微信 AI Bot 集成开发文档，涵盖 WebSocket 长连接和 URL 回调两种集成方式的完整实践。

企业微信 AI Bot 集成架构设计与工程实践

人工智能

基于SpringBoot3与Java17的企业微信AIBot集成开发实践，重点解析URL回调与WebSocket两种消息模式。涵盖智能客服、自动化估值、线索推送等场景，提供AES解密、消息解析、Nginx配置及常见问题解决方案，助力快速构建企业微信机器人应用。

代码解释

应用管理

服务器

WebSocket

Markdown

Nginx

Redis

Linux

Solid

Java

JSON

热销域名限时优惠，新客首年免费！


domain

2026上云采购 | AI焕新·智启新局

xiaowei

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

企业微信 AI Bot 集成架构设计与工程实践-腾讯云开发者社区-腾讯云

企业微信 AI Bot 集成架构设计与工程实践

企业微信 AI Bot 集成架构设计与工程实践

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐