从零开始，用Spring Boot搭建一个支持AI对话、图片识别、文件读取的微信公众号智能助手，附完整代码和踩坑记录

前言

大家好！ 最近做了一个微信公众号后台开发的课程实验，从最基础的消息收发开始，一步步加上了AI智能回复、搜索增强、图片识别、文件读取等功能，踩了不少坑，也学到了很多东西。

这是一篇微信公众号智能后台的部署与二次开发指南，完整的项目代码我已经开源到GitHub了，包含了所有功能，大家直接下载就能用。这篇文章主要教你三件事：如何把项目跑起来 → 如何换上自己的API和测试号 → 如何二次开发加功能 → 常见问题怎么解决。

  1. 怎么跑起来：如何申请API、配置项目、启动运行

  2. 怎么改成你自己的：哪些配置要换、怎么换上你的测试号和API Key

  3. 怎么加功能：想二次开发加新功能，应该改哪里、怎么加

文末还有我开发过程中踩过的所有坑和解决方案，遇到问题先看FAQ，基本都能找到答案。

GitHub地址：https://github.com/Pearl-Yang/wechat-demo.git

最终能实现的功能：

  • 基础消息收发

  • 消息数据库存储

  • AI智能对话（豆包大模型）

  • 异步消息处理（解决5秒超时）

  • 搜索增强回复（博查搜索API）

  • Word文档生成（三种模式）

  • 图片识别（多模态AI）

  • 多轮消息合并理解

  • 文件读取（TXT/Word/PDF）

技术栈：

  • 后端框架：Spring Boot 2.7.18

  • 开发语言：Java 8

  • 数据库：MySQL 8.0 + MyBatis

  • 连接池：Druid

  • AI服务：火山引擎豆包大模型

  • 搜索服务：博查搜索API

  • 文档处理：Apache POI + PDFBox

  • 内网穿透：natapp

一、快速开始：5分钟跑起来

这一章告诉你最快跑起来需要做什么，跟着步骤走，5分钟就能让你的公众号回复消息。

1.1 第一步：下载代码

先从GitHub把代码克隆下来：

git clone https://github.com/Pearl-Yang/wechat-demo.git
cd wechat-demo

或者直接下载ZIP包解压也行。

1.2 第二步：你需要申请的东西

在开始配置之前，你需要先申请好这些东西：

名称

是否必做

用途

微信公众平台测试号

必做

微信公众号后台

火山引擎豆包API

必做

AI智能对话

natapp内网穿透

必做

本地开发调试

博查搜索API

选做

搜索增强功能

MySQL数据库

必做

存储消息记录

具体的申请步骤在下一章会详细讲，你可以先去申请，申请完再回来配置。

1.3 第三步：环境要求

确保你的电脑上已经装好了这些：

  • JDK 8 或更高版本（推荐Java 8，兼容性最好）

  • MySQL 8.0 或 5.7 版本

  • Maven（IDEA自带的也行）

  • IntelliJ IDEA（社区版就够用）

1.3.1 安装JDK

我们用Java 17.

  1. 下载JDK 17：可以去Oracle官网或者OpenJDK下载

  2. 安装JDK

  3. 配置环境变量（JAVA_HOME、PATH）

  4. 验证：打开命令行，输入 java -version，能看到版本号就说明装好了

1.3.2 安装IntelliJ IDEA

IDEA是最好用的Java开发工具，社区版免费就够用。

  1. 下载IDEA：https://www.jetbrains.com/idea/download/

  2. 安装IDEA

  3. 首次运行选择社区版（Community）

1.3.3 安装MySQL

我们用MySQL 8.0来存储消息。

  1. 下载MySQL：https://dev.mysql.com/downloads/mysql/

  2. 安装MySQL，设置root密码（建议设成123456，方便记忆）

  3. 验证：打开命令行，输入 mysql -u root -p，输入密码能登录就说明装好了

1.3.4 安装Maven

IDEA自带Maven，一般不用单独装。如果想自己装也可以，版本3.6以上就行。

环境都准备好了的话，就可以继续往下看了！

小贴士：所有API的密钥和配置信息，建议单独存一个记事本里，后面填配置文件的时候直接复制粘贴，避免输错。

二、准备工作：申请API

这一章详细讲解每个API的申请步骤，跟着一步步来就行。所有密钥都建议单独存一个记事本，后面配置的时候直接复制。

2.1 微信公众平台测试号

做微信公众号开发，首先得有一个公众号。如果是个人学习用，申请测试号就够了，功能齐全，还不需要认证。

申请步骤：

  1. 打开微信公众平台测试号申请页面：https://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=sandbox/login

  2. 用微信扫码登录

  3. 登录后就能看到你的测试号信息，把这几个信息记下来：

    1. appID（测试号的唯一标识）

    2. appsecret（测试号的密钥）

    3. 微信号（测试号的微信号）

  4. 往下翻，找到"接口配置信息"，先空着，后面我们配置好服务器再填。

  5. 再往下，找到"测试号二维码"，用微信扫码关注你的测试号，这样才能收到消息。

提示：测试号是免费的，功能和正式公众号差不多，足够学习和测试用了。

2.2 火山引擎豆包API

我们用火山引擎的豆包大模型来实现AI对话功能。新用户有免费额度，足够学习用了。

申请步骤：

  1. 打开火山引擎官网：https://www.volcengine.com/

  2. 注册账号并登录（可以用抖音/头条账号登录）

  3. 进入"方舟大模型平台"：https://www.volcengine.com/product/ark

  4. 点击"立即使用"，进入控制台

  5. 左侧菜单找到"模型推理" → "接入点管理"

  6. 点击"创建接入点"

  7. 填写接入点信息：

  • 接入点名称：随便起，比如 wechat-demo
  • 模型：选择 Doubao-Seed-2.0-lite（这个模型支持多模态，性价比高）
  • 其他默认就行
  • 创建成功后，把接入点ID记下来（格式类似 ep-2026xxxxxx-xxxxx）

  1. 左侧菜单找到"API Key管理"

  2. 点击"创建API Key"

  3. 创建成功后，把API Key记下来（格式类似 sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx）

提示：新用户一般有免费额度，用完了也可以按量付费，很便宜，测试用不了几块钱。

1.3 博查搜索API（搜索增强功能）

如果想要实现"搜索增强"功能（让AI能搜索最新信息），可以申请博查搜索API。这个是选做的，不做也不影响基础功能。

申请步骤：

  1. 打开博查搜索官网：https://bocha.cn/

  2. 注册账号并登录

  3. 进入控制台，找到API Key管理

  4. 创建API Key

  5. 把API Key记下来

提示：博查搜索也有免费额度，个人学习完全够用。

1.4 natapp内网穿透

微信公众号需要一个公网可以访问的服务器地址来接收消息。本地开发的时候，我们可以用内网穿透工具把本地端口映射到公网。

natapp是比较常用的内网穿透工具，免费版就够用了。

申请步骤：

  1. 打开natapp官网：https://natapp.cn/

  2. 注册账号并登录

  3. 点击"购买隧道"，选择"免费隧道"

  4. 配置隧道：

    1. 隧道名称：随便起

    2. 本地端口：8080（我们Spring Boot项目用8080端口）

  1. 购买成功后，在"我的隧道"里能看到你的隧道信息

  2. 下载natapp客户端：根据你的系统下载对应的版本

  3. 把下载的客户端解压到一个目录

  4. 使用时点击目录进去，双击run_natapp.bat即可运行隧道。

提示：免费版的natapp每次重启地址都会变，所以每次重启natapp都要更新微信公众号的配置。

三、配置你的项目

API都申请好之后，我们来配置项目。主要就是改 application.yml 这个配置文件，把你自己的信息填进去。

3.1 配置文件详解

打开 src/main/resources/application.yml，这是完整的配置文件，我给你逐段讲解每个配置项是什么意思：

server:
  port: 8080                    # 项目端口号，默认8080
  servlet:
    context-path: /wechat       # 上下文路径，所有接口前面都要加 /wechat

spring:
  application:
    name: wechat-demo
  datasource:                   # 数据库连接配置
    type: com.alibaba.druid.pool.DruidDataSource
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/wechat_db?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
    username: root              # 数据库用户名，改成你自己的
    password: 123456            # 数据库密码，改成你自己的
    druid:
      initial-size: 5
      min-idle: 5
      max-active: 20
      max-wait: 60000

mybatis:                        # MyBatis配置
  mapper-locations: classpath:mapper/*.xml
  type-aliases-package: com.example.wechat.entity
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

# 微信公众号配置
wechat:
  appid: your_appid             # ⭐ 改成你的微信测试号appID
  appsecret: your_appsecret     # ⭐ 改成你的微信测试号appsecret
  token: wechat.token           # 可以自定义，和微信后台保持一致就行
  encodingaeskey: your_encodingaeskey_here

# AI智能回复配置
ai:
  enabled: true                 # 是否开启AI功能
  api-url: https://ark.cn-beijing.volces.com/api/v3/chat/completions
  api-key: your_key             # ⭐ 改成你的火山引擎API Key
  model: your_point             # ⭐ 改成你的推理接入点名称
  system-prompt: 你是微信公众号助手，请用简洁友好的语气回答问题。
  max-tokens: 2000
  temperature: 0.7

# 搜索增强配置
search:
  enabled: true                 # 是否开启搜索增强功能，不用就设为false
  api-type: bocha
  api-key: your_key             # ⭐ 改成你的博查搜索API Key（不用可以不改）
  endpoint: https://api.bocha.cn/v1/web-search
  result-count: 3

# Word文档配置
word:
  storage-path: ./files         # Word文件存储路径

# 应用公网地址
app:
  public-url: your_natapp_url   # ⭐ 改成你的natapp公网地址，要加 /wechat 后缀

logging:
  level:
    com.example.wechat: debug
    org.mybatis: debug

3.2 需要修改的配置清单

总结一下，你需要修改的配置项有这几个：

配置项

说明

是否必改

spring.datasource.username

数据库用户名

✅ 必改

spring.datasource.password

数据库密码

✅ 必改

wechat.appid

微信测试号appID

✅ 必改

wechat.appsecret

微信测试号appsecret

✅ 必改

ai.api-key

火山引擎API Key

✅ 必改

ai.model

推理接入点名称

✅ 必改

search.api-key

博查搜索API Key

⚪ 选改

app.public-url

natapp公网地址

✅ 必改

注意：app.public-url 一定要加上 /wechat 后缀，比如 http://xxxx.natappfree.cc/wechat，不然文件下载链接会不对。

3.3 初始化数据库

配置文件改好之后，我们来初始化数据库。项目里有个 sql/init.sql 文件，直接执行就行。

或者手动执行下面的SQL：
 

CREATE DATABASE IF NOT EXISTS wechat_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

USE wechat_db;

CREATE TABLE `wechat_message` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `msg_type` tinyint DEFAULT NULL COMMENT '消息类型：1-用户消息 2-回复消息',
  `msg_id` bigint DEFAULT NULL COMMENT '微信消息ID',
  `from_user_name` varchar(255) DEFAULT NULL COMMENT '发送方openId',
  `to_user_name` varchar(255) DEFAULT NULL COMMENT '公众号ID',
  `content_type` varchar(50) DEFAULT NULL COMMENT '消息类型text/image等',
  `content` text COMMENT '消息内容',
  `create_time` bigint DEFAULT NULL COMMENT '微信消息时间戳',
  `local_create_time` datetime DEFAULT NULL COMMENT '本地入库时间',
  `related_msg_id` bigint DEFAULT NULL COMMENT '关联用户消息ID',
  `is_ai_reply` tinyint DEFAULT '0' COMMENT '是否AI回复：0关键词 1AI',
  PRIMARY KEY (`id`),
  KEY `idx_from_user` (`from_user_name`),
  KEY `idx_msg_type` (`msg_type`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='微信消息记录表';

执行完之后，数据库就准备好了。

3.4 检查一下

改完配置、初始化完数据库，先确认这几件事：

  • ✅ MySQL服务已经启动

  • ✅ 数据库用户名密码正确

  • ✅ 数据库 wechat_db 已经创建

  • ✅ wechat_message 表已经建好

  • ✅ 所有API Key都已经填对了

没问题的话，我们就可以启动运行了！

四、启动运行

配置都改好了，现在我们来启动项目，验证一下能不能正常运行。

4.1 启动natapp

首先启动natapp内网穿透，这样微信才能访问到你的本地服务。

打开命令行，进入natapp所在目录，直接双击 run_natapp.bat 也行）

启动成功后，你会看到一个公网域名，比如 http://xxxx.natappfree.cc，把这个记下来。

注意：免费版natapp每次重启地址都会变，如果后面发现收不到消息了，先检查natapp地址是不是变了。

4.2 配置微信测试号后台

现在我们去微信测试号后台配置接口地址。

  1. 登录微信公众平台测试号

  2. 找到"接口配置"区域

  3. URL 填：你的natapp地址/wechat/wx（比如 http://xxxx.natappfree.cc/wechat/wx）

  4. Token 填：wechat.token（和你 application.yml 里的 token 保持一致）

  5. 点击"提交"

注意： URL一定要加上 /wechat/wx 后缀，因为我们项目配置了上下文路径 /wechat，而微信接口在 /wx 路径下。

如果提交成功，说明你的服务已经可以被微信访问到了。如果提交失败，检查一下：

  • natapp是否正常启动

  • URL是否正确（注意两个wechat）

  • Token是否和配置文件一致

  • 项目是否已经启动（哦对，我们还没启动项目，先启动项目再提交）

4.3 启动Spring Boot项目

用IDEA打开项目，找到 WechatApplication.java 启动类，右键点击运行。

或者用命令行启动：

启动成功后，控制台会显示 "Started WechatApplication"，说明项目启动成功了。

4.4 验证微信接口

项目启动成功后，回到微信测试号后台，点击"提交"按钮验证接口配置。

如果提示"配置成功"，恭喜你！微信接口已经通了。

如果提示"配置失败"，不要慌，按照下面的顺序检查：

  1. 检查natapp是否正常启动，地址有没有变

  2. 检查URL是否正确，格式是 http://xxxx.natappfree.cc/wechat/wx

  3. 检查Token是否和配置文件里的一致

  4. 检查项目是否正常启动，控制台有没有报错

  5. 检查防火墙是否阻止了8080端口

4.5 测试消息

接口配置成功后，我们来测试一下消息。

用微信扫描测试号的二维码关注测试号，然后发送一条消息，比如"你好"。

如果收到了回复，说明一切正常！🎉

如果没收到回复，检查一下：

  • 微信测试号的接口配置是否正确

  • 项目是否正常运行

  • natapp地址有没有变

  • 控制台有没有报错信息

五、项目结构说明：每个文件是干嘛的

项目跑起来之后，你可能想知道每个文件是干嘛的，这样后面改起来才心里有数。这一章给你详细讲解项目结构。

5.1 整体目录结构

wechat-demo/
├── pom.xml                          # Maven配置文件，管理依赖
├── README.md                        # 项目说明文档
├── sql/
│   └── init.sql                     # 数据库初始化脚本
└── src/
    ├── main/
    │   ├── java/com/example/wechat/
    │   │   ├── WechatApplication.java      # 启动类，项目入口
    │   │   ├── controller/                 # 控制器层，接收请求
    │   │   │   ├── WechatController.java   # 微信消息入口控制器
    │   │   │   └── FileController.java     # 文件下载控制器
    │   │   ├── service/                    # 业务层，处理核心逻辑
    │   │   │   ├── WechatService.java      # 业务接口
    │   │   │   ├── CustomerMessageService.java  # 客服消息推送服务
    │   │   │   └── impl/
    │   │   │       └── WechatServiceImpl.java  # 业务实现，核心逻辑都在这里
    │   │   ├── mapper/                     # 数据访问层，操作数据库
    │   │   │   └── MessageMapper.java      # 消息数据库操作接口
    │   │   ├── entity/                     # 实体类，对应数据库表
    │   │   │   └── Message.java            # 消息实体类
    │   │   └── util/                       # 工具类，封装通用功能
    │   │       ├── WechatUtil.java         # 微信工具类：签名验证、XML解析
    │   │       ├── AiUtil.java             # AI调用工具类
    │   │       ├── WechatTokenUtil.java    # access_token获取和缓存
    │   │       ├── SearchUtil.java         # 搜索API调用工具类
    │   │       ├── WordUtil.java           # Word文档生成工具类
    │   │       └── FileUtil.java           # 文件读取工具类
    │   └── resources/
    │       ├── application.yml             # 配置文件，所有配置都在这里
    │       └── mapper/
    │           └── MessageMapper.xml       # MyBatis SQL映射文件
    └── test/
        └── java/com/example/wechat/
            └── WechatApplicationTests.java # 测试类

5.2 各层职责说明

项目采用经典的三层架构，职责清晰：

Controller层（控制器层）

  • 负责接收HTTP请求

  • 参数校验和转换

  • 调用Service层处理业务

  • 返回响应结果

  • 不包含业务逻辑

Service层（业务层）

  • 核心业务逻辑都在这里

  • 调用Mapper层操作数据库

  • 调用Util层的工具类

  • 事务控制一般在这一层

Mapper层（数据访问层）

  • 负责数据库的增删改查

  • 接口定义在Java文件里

  • SQL语句写在XML文件里

  • 不包含业务逻辑

Util层（工具层）

  • 封装通用的工具方法

  • 比如调用第三方API、解析XML、生成文档等

  • 不包含业务逻辑，可以复用

Entity层（实体层）

  • 对应数据库表的Java类

  • 每个字段对应表的一列

  • 只有getter和setter，没有业务方法

5.3 核心文件详解

5.3.1 WechatServiceImpl.java（核心中的核心）

这个文件是整个项目的核心，大部分业务逻辑都在这里。主要功能：

  • 接收微信消息，判断消息类型

  • 关键词回复处理

  • AI智能回复处理

  • 异步消息处理（解决5秒超时）

  • 搜索增强功能

  • Word文档生成

  • 图片识别

  • 多轮消息合并

如果你想改业务逻辑，大部分情况都是改这个文件。

5.3.2 application.yml（配置中心）

所有的配置都在这里，包括：

  • 数据库连接配置

  • 微信公众号配置

  • AI API配置

  • 搜索API配置

  • 其他功能开关

想改配置直接改这个文件就行，不用改代码。

5.3.3 pom.xml（依赖管理）

这个文件管理项目所有的依赖包。如果你想加新的功能，需要引入新的依赖，就在这个文件里加。

比如想加Redis缓存，就在dependencies里加Redis的依赖。

5.3.4 WechatController.java（入口控制器）

微信的所有消息都会先到这里，然后转发给Service层处理。主要做两件事：

  1. 处理微信的服务器验证请求（GET请求）

  2. 接收微信的消息推送（POST请求）

一般不需要改这个文件，除非你想加新的接口。

六、如何二次开发：想加功能怎么改

项目跑起来了，结构也搞清楚了，接下来就是最关键的：想加新功能，应该怎么改？

这一章教你二次开发的一般步骤，还有三个具体的示例，跟着做就能学会。

6.1 加新功能的一般步骤

不管加什么功能，大致都是这几步：

  1. 判断要不要加依赖：如果功能需要新的第三方库，就在 pom.xml 里加依赖

  2. 判断要不要加配置：如果功能需要配置项（比如API Key、开关等），就在 application.yml 里加

  3. 判断要不要加工具类：如果是调用第三方API或者通用功能，就在 util 包下加工具类

  4. 判断要不要加业务逻辑：核心业务逻辑在 service 层，需要的话加接口和实现类

  5. 判断要不要加数据库表：如果需要存储新的数据，就在 entity 加实体类、mapper 加接口、resources/mapper 加XML

  6. 判断要不要加新接口：如果需要新的HTTP接口，就在 controller 包下加控制器

  7. 集成到主流程：在 WechatServiceImpl 里把新功能集成进去

是不是有点抽象？没关系，下面给你三个具体的例子，一看就懂了。

6.2 添加依赖：pom.xml怎么改

如果你的新功能需要第三方库，就在 pom.xml 的 <dependencies> 节点里加。

比如想加Redis缓存，就加：

<!-- Redis缓存 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

注意事项：

  • 依赖要加在 <dependencies> 标签里面

  • Spring Boot的依赖一般不用写版本号，由parent管理

  • 加完依赖记得刷新Maven，让IDEA下载下来

  • 如果不确定依赖怎么写，去官网或者Maven中央仓库查

6.3 加配置：application.yml怎么加

如果你的功能需要配置项（比如API Key、功能开关、超时时间等），就在 application.yml 里加。

比如想加一个翻译功能的配置：

# 翻译功能配置
translate:
  enabled: true           # 是否开启翻译功能
  app-id: your_app_id     # 翻译API的appId
  app-key: your_app_key   # 翻译API的密钥
  default-from: auto      # 默认源语言
  default-to: en          # 默认目标语言

建议：

  • 相关的配置放在一起，用注释说明是干嘛的

  • 布尔类型的配置用 enabled 命名，方便开关功能

  • 敏感信息（如API Key）不要硬编码在代码里，都放配置文件

在代码里读取配置：

用 @Value 注解读取：

@Value("${translate.enabled}")
private boolean translateEnabled;

@Value("${translate.app-id}")
private String translateAppId;

或者用配置类（配置项多的时候推荐）：

@ConfigurationProperties(prefix = "translate")
public class TranslateProperties {
    private boolean enabled;
    private String appId;
    private String appKey;
    // getter和setter
}

6.4 要不要加新的Java类？加在哪个包？

很多同学纠结：我这个功能应该加在哪里？给你一个简单的判断方法：

功能类型

放在哪个包

命名规范

接收HTTP请求

controller

XxxController

业务逻辑处理

service / service.impl

XxxService / XxxServiceImpl

操作数据库

mapper / entity

XxxMapper / Xxx

调用第三方API、通用工具方法

util

XxxUtil

配置项

config / 直接用@Value

XxxProperties

异常处理

exception

XxxException

简单判断方法：

  • 如果是对外提供接口 → 加在 controller

  • 如果是核心业务逻辑 → 加在 service

  • 如果是操作数据库 → 加在 mapper + entity

  • 如果是通用工具、调用第三方 → 加在 util

  • 如果功能很简单，只有几行代码 → 直接在 WechatServiceImpl 里加就行，不用单独建类

6.5 示例1：加一个新的关键词回复

最简单的二次开发，只需要改一个文件：WechatServiceImpl.java

场景： 想加一个关键词"帮助"，用户发"帮助"就回复使用说明。

步骤：

  1. 打开 WechatServiceImpl.java

  2. 找到处理文本消息的方法（一般叫 handleTextMessage 之类的）

  3. 在关键词判断的地方加一个新的if判断

  4. // 关键词回复
if ("帮助".equals(content) || "help".equalsIgnoreCase(content)) {
    String helpText = "使用说明：\n" +
            "1. 直接聊天就能和AI对话\n" +
            "2. 发图片可以识别图片内容\n" +
            "3. 发文件可以读取文件内容\n" +
            "4. 发送【生成文档+内容】可以生成Word文档\n" +
            "5. 更多功能等你探索~";
    return buildTextReplyMessage(toUserName, fromUserName, helpText);
}

    就这么简单！加完重启项目就能用了。

    进阶： 如果关键词很多，可以把关键词和回复存在数据库里，或者存在配置文件里，这样加关键词不用改代码。

    6.6 示例2：接入一个新的第三方API

    稍微复杂一点，以接入"百度翻译API"为例。

    步骤：

    第一步：申请API

  5. 去百度翻译开放平台注册账号

  6. 申请通用翻译API

  7. 拿到 APP ID 和 密钥第二步：加配置 在 application.yml 里加配置：

# 百度翻译配置
translate:
  enabled: true
  app-id: your_app_id
  app-key: your_app_key

第三步：加工具类 在 util 包下新建 TranslateUtil.java：

@Component
public class TranslateUtil {

    @Value("${translate.app-id}")
    private String appId;

    @Value("${translate.app-key}")
    private String appKey;

    // 调用百度翻译API的方法
    public String translate(String text, String from, String to) {
        // 这里写调用API的代码
        // 1. 拼接请求参数
        // 2. 发送HTTP请求
        // 3. 解析返回结果
        // 4. 返回翻译后的文本
        return null;
    }
}

第四步：加业务逻辑 在 WechatServiceImpl 里注入工具类，然后在合适的地方调用：

@Autowired
private TranslateUtil translateUtil;

// 在处理消息的地方加判断
if (content.startsWith("翻译") || content.startsWith("翻译 ")) {
    String text = content.substring(2).trim();
    String result = translateUtil.translate(text, "auto", "en");
    return buildTextReplyMessage(toUserName, fromUserName, result);
}

第五步：测试 重启项目，发"翻译 你好"试试，看能不能返回英文。

接入其他第三方API的思路都是一样的：申请API → 加配置 → 写工具类 → 业务逻辑调用。

6.7 示例3：加一个新的消息类型处理

微信支持很多消息类型：文本、图片、语音、视频、地理位置、链接等等。项目里已经处理了文本和图片，现在我们来加语音消息的处理。

步骤：

  1. 打开 WechatServiceImpl.java

  2. 找到处理消息的主方法，里面应该有判断消息类型的地方

  3. 加一个语音消息的分支

if ("voice".equals(msgType)) {
    // 语音消息
    String recognition = map.get("Recognition"); // 语音识别结果（需要开通语音识别功能）
    // 可以把识别后的文本当成普通文本消息处理
    return handleTextMessage(toUserName, fromUserName, recognition, msgId, createTime);
}

微信支持的消息类型：

  • text：文本消息

  • image：图片消息

  • voice：语音消息

  • video：视频消息

  • shortvideo：短视频消息

  • location：地理位置消息

  • link：链接消息

  • event：事件消息（关注、取消关注、点击菜单等）

想支持哪种，就加对应的处理逻辑就行。

6.8 开发小建议

最后给你几个开发建议，少走弯路：

  1. 先小后大：先改小功能验证思路，再逐步加复杂功能，不要一上来就改一大堆

  2. 勤加注释：自己写的代码要加注释，过一个月你自己都忘了当时怎么想的

  3. 分步测试：改完一部分就测一下，不要全改完再测，出问题不知道是哪改坏的

  4. 配置开关：新功能最好加个enabled开关，出问题可以随时关掉，不影响主功能

  5. 异常处理：调用第三方API一定要加try-catch，不要因为一个功能挂了导致整个公众号用不了

七、常见问题FAQ（踩坑记录）

这一章是我开发过程中踩过的所有坑，遇到问题先看这里，基本都能找到答案。

7.1 微信验证失败怎么办？

现象： 在微信后台点击"提交"验证接口，提示"配置失败"。

排查顺序：

  1. 检查natapp是否正常启动

    1. 看看natapp窗口有没有报错

    2. 访问一下natapp地址，看能不能打开

  2. 检查URL是否正确

    1. 格式应该是：http://xxxx.natappfree.cc/wechat/wx

    2. 注意有两个wechat：一个是上下文路径，一个是接口路径

    3. 不要少了最后的 /wx

  3. 检查Token是否一致

    1. 微信后台填的Token和 application.yml 里的 wechat.token 必须完全一致

    2. 注意前后不要有空格

  4. 检查项目是否启动

    1. 看看控制台有没有 "Started WechatApplication"

    2. 有没有报错信息

  5. 检查控制台日志

    1. 微信验证的时候，控制台应该会有请求日志

    2. 如果没有日志，说明请求没到你的服务，检查natapp和URL

    3. 如果有日志但报错，根据错误信息排查

7.2 收不到消息回复怎么办？

现象： 关注了测试号，发消息没反应。

排查顺序：

  1. 检查微信测试号接口配置

    1. 是不是显示"配置成功"

    2. URL和Token对不对

  2. 检查项目运行状态

    1. 项目有没有正常启动

    2. 控制台有没有报错

  3. 检查natapp地址

    1. 免费版natapp每次重启地址都会变

    2. 地址变了要同时更新微信后台和配置文件

  4. 查看控制台日志

    1. 发消息的时候控制台有没有收到请求

    2. 有没有报错信息

    3. 有没有返回响应

  5. 检查消息类型

    1. 目前支持文本和图片消息

    2. 语音、视频等其他消息可能没有处理

7.3 AI调用失败怎么办？

现象： 发消息不回复，或者回复"AI调用失败"。

排查顺序：

  1. 检查API Key是否正确

    1. application.yml 里的 ai.api-key 对不对

    2. 注意不要有多余的空格

  2. 检查接入点名称

    1. ai.model 填的是接入点名称（Endpoint ID），不是模型名称

    2. 去火山方舟控制台确认一下

  3. 检查账户余额

    1. 火山引擎是按量付费的，看看账户有没有余额

    2. 新用户有免费额度，用完了需要充值

  4. 检查网络

    1. 能不能正常访问火山引擎的API地址

    2. 有没有被防火墙拦截

  5. 查看错误日志

    1. 控制台应该会打印具体的错误信息

    2. 根据错误码去官方文档查原因

7.4 natapp免费版地址总是变怎么办？

现象： 每次重启natapp，地址就变了，要改好几个地方，很麻烦。

解决方案：

  1. 买付费版：付费版有固定域名，省心，也不贵

  2. 每次重启后更新两个地方：

    1. application.yml 里的 app.public-url

    2. 微信公众号后台的接口配置URL

  3. 用其他内网穿透工具：比如cpolar、ngrok等，有些有免费固定域名

小技巧：开发的时候natapp不要关，一直开着，地址就不会变。

7.5 长消息被截断怎么办？

现象： AI回复的内容很长，但是只显示了一部分。

原因： 微信客服消息单条文本有2048字节限制，超过了就会被截断或者发送失败。

解决方案： 项目里已经做了分段处理，会把长文本拆成多条消息发送。

如果还是有问题，检查一下：

  • 分段的阈值是不是设得太大了

  • 编码问题导致字节数计算不对

  • 有没有特殊字符占字节

7.6 为什么有时候会收到重复消息？

现象： 发一条消息，有时候会收到两条回复。

原因： 微信的5秒超时机制。如果你的服务5秒内没有返回响应，微信会重试，就会导致消息重复处理。

解决方案： 项目里已经用了异步+客服消息的架构，正常不会有这个问题。

如果还是有，检查一下：

  • 是不是网络太慢，导致同步响应超过5秒

  • 异步处理是不是正常工作

  • 有没有做消息去重（用msgId判断）

7.7 Word文件下载链接打不开怎么办？

现象： 生成了Word文档，但是点击下载链接显示404。

原因： 大概率是公网地址配置错了，少了上下文路径。

解决方案：

  • 检查 app.public-url 配置

  • 一定要加上 /wechat 后缀

  • 正确格式：http://xxxx.natappfree.cc/wechat

7.8 搜索功能总是干扰正常回答怎么办？

现象： 问一些常识问题，AI的回答反而不对，因为被搜索结果带偏了。

原因： 搜索结果的质量参差不齐，有时候会干扰AI的判断。

解决方案：

  • 优化提示词，告诉AI什么时候用搜索结果，什么时候不用

  • 加一个判断，只有特定类型的问题才调用搜索

  • 降低搜索结果的权重

  • 不用搜索功能的话，直接把 search.enabled 设为 false

7.9 access_token过期了怎么办？

现象： 客服消息发送失败，提示token过期。

原因： 微信的access_token有效期是7200秒（2小时），过期了就不能用了。

解决方案： 项目里已经做了自动刷新机制，正常不会有问题。

如果还是有问题，检查一下：

  • 刷新token的定时任务有没有正常工作

  • appid和appsecret对不对

  • 有没有频繁刷新导致被限流

7.10 数据库连不上怎么办？

现象： 启动项目报错，说数据库连接失败。

排查顺序：

  1. 检查MySQL服务是否启动

    1. Windows：去服务里看MySQL服务有没有启动

    2. Mac/Linux：执行 brew services list 或 systemctl status mysql

  2. 检查用户名密码

    1. application.yml 里的用户名密码对不对

    2. 能不能用命令行登录：mysql -u root -p

  3. 检查数据库是否存在

    1. 有没有创建 wechat_db 数据库

    2. 执行 show databases; 看看

  4. 检查端口

    1. MySQL默认端口是3306

    2. 如果改了端口，配置文件里也要改

  5. 检查防火墙

    1. 本地的话一般不用考虑

    2. 远程数据库的话，检查防火墙和安全组

八、总结与拓展方向

看到这里，你应该已经能把项目跑起来，并且知道怎么改了。最后做个总结，再给你一些拓展方向。

8.1 本文总结

这篇指南主要讲了四件事：

  1. 怎么跑起来：下载代码 → 申请各种API → 配置项目 → 启动运行

  2. 项目结构：每个文件是干嘛的，各层职责是什么

  3. 怎么二次开发：加功能的一般步骤，三个具体示例

  4. 常见问题：开发过程中可能遇到的坑和解决方案

8.2 可以拓展的方向

这个项目只是基础版，你可以在这个基础上加很多功能，比如：

功能类：

  • 加菜单功能：自定义公众号菜单

  • 加关注回复：用户关注时自动发欢迎语

  • 加签到功能：每日签到积分

  • 加抽奖功能：公众号抽奖活动

  • 加客服系统：人工客服接入

  • 加数据统计：消息量、用户数统计

技术类：

  • 接入Redis：缓存热点数据、access_token等

  • 加消息队列：异步处理更可靠

  • 加限流：防止恶意请求

  • 加日志系统：更完善的日志记录

  • 加监控：服务健康监控

  • 部署到服务器：不用本地开发了，直接部署到云服务器

AI类：

  • 换其他大模型：比如GPT、Claude、文心一言等

  • 加人设：给AI设定特定的角色人设

  • 加知识库：基于你的文档做问答

  • 加多模态：支持语音、视频理解

  • 加Agent：让AI能调用工具

8.3 写在最后

微信公众号开发看起来复杂，其实核心就是接收消息、处理消息、返回消息这三步。把基础流程跑通之后，加功能就是不断往里面填东西。

建议你先把项目跑起来，然后试着改一个小功能，比如加个关键词回复，感受一下整个流程。然后再慢慢加复杂的功能。

如果这篇文章对你有帮助，别忘了去GitHub给个Star~ 有问题也可以在Issues里提。

祝你开发顺利！🎉

GitHub地址：GitHub - Pearl-Yang/wechat-demo: 这是一个微信公众号后台开发的课程实验项目，从最基础的消息收发开始，逐步拓展了数据库存储、AI 智能回复、异步处理、搜索增强、文档生成、图片识别、多轮对话、文件读取等功能。 项目采用渐进式迭代的开发方式，每一步都是可运行的完整功能，适合作为微信公众号开发的学习参考。 · GitHub这是一个微信公众号后台开发的课程实验项目，从最基础的消息收发开始，逐步拓展了数据库存储、AI 智能回复、异步处理、搜索增强、文档生成、图片识别、多轮对话、文件读取等功能。 项目采用渐进式迭代的开发方式，每一步都是可运行的完整功能，适合作为微信公众号开发的学习参考。 - Pearl-Yang/wechat-demohttps://github.com/Pearl-Yang/wechat-demo.git

# 微信 # spring boot # 后端 # maven # 搜索引擎 # 火山引擎 # github
Logo
AI编程社区

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

码道 · 寻艺——从零构建“非遗交互式对话平台“的完整实践

avatar AI编程社区

码道：用 Python + FastAPI 快速构建一个学生信息管理接口：从零到 Swagger 在线文档

在日常开发和教学中，我们经常需要一套简单、可控、能快速上手的后端接口来演示"前后端分离"、练习 Restful API 设计，或者作为前端联调的 Mock 服务。传统做法往往是搭一套完整的 Web 工程：配置数据库、编写 DAO、引入 ORM、做请求分发……一套流程下来，光环境搭建就要花去不少时间，对于想快速验证想法、或者刚入门 API 开发的同学来说，显得过于沉重。

avatar AI编程社区

码道：从零构建学生信息管理系统 API：FastAPI 内存版 CRUD 项目全解析

FastAPI 的强大，很大程度上来自 Pydantic 的校验能力。我们写下类型声明，FastAPI 在运行时自动把它变成边界检查器。name：字符串，长度限制 1 到 50；age：整数，限制在 6 到 120 之间（ge大于等于、le小于等于）；gender：字符串，用正则限定只能是"男"“女”“其他”；email：邮箱格式字符串；grade与major：可选字段，代表班级和专业方向。

avatar AI编程社区