Merge branch 'binarywang:develop' into develop

Author: Winnie-by996

.github/agents/my-agent.agent.md

@@ -0,0 +1,15 @@
+---
+# Fill in the fields below to create a basic custom agent for your repository.
+# The Copilot CLI can be used for local testing: https://gh.io/customagents/cli
+# To make this agent available, merge this file into the default repository branch.
+# For format details, see: https://gh.io/customagents/config
+
+name: 全部用中文
+description: 需要用中文，包括PR标题和分析总结过程
+---
+
+# My Agent
+
+- 1、请使用中文输出思考过程和总结，包括PR标题，提交commit信息也要使用中文；
+- 2、生成代码时需要提供必要的单元测试代码；
+- 3、新增加的代码如果标记作者信息，请注意不要把作者名设为binarywang或者其他无关人员，要改为 GitHub Copilot。

.github/copilot-instructions.md

@@ -0,0 +1,202 @@
+# Copilot Instruction
+请始终使用中文生成 Pull Request 的标题、描述和提交信息
+
+
+# WxJava - 微信 Java SDK 开发说明
+
+WxJava 是一个支持多种微信平台的完整 Java SDK，包含公众号、小程序、微信支付、企业微信、开放平台、视频号、企点等多种功能模块。
+
+**请始终优先参考本说明，只有在遇到与此内容不一致的意外信息时，才退而使用搜索或 bash 命令。**
+
+## 高效开发指南
+
+### 前置条件与环境准备
+- **Java 要求**：JDK 8+（项目最低目标为 Java 8）
+- **Maven**：推荐 Maven 3.6+（已验证 Maven 3.9.11）
+- **IDE**：推荐使用 IntelliJ IDEA（项目针对 IDEA 优化）
+
+### 引导、构建与校验
+克隆仓库后按顺序执行以下命令：
+
+```bash
+# 1. 基础编译（请勿中断 - 约需 4-5 分钟）
+mvn clean compile -DskipTests=true --no-transfer-progress
+# 超时时间：建议设置 8 分钟以上。实际时间：约 4 分钟
+
+# 2. 完整打包（请勿中断 - 约需 2-3 分钟）  
+mvn clean package -DskipTests=true --no-transfer-progress
+# 超时时间：建议设置 5 分钟以上。实际时间：约 2 分钟
+
+# 3. 代码质量校验（请勿中断 - 约需 45-60 秒）
+mvn checkstyle:check --no-transfer-progress
+# 超时时间：建议设置 3 分钟以上。实际时间：约 50 秒
+```
+
+重要时间说明：
+- 绝对不要中断任意 Maven 构建命令
+- 编译阶段耗时最长（约 4 分钟），原因是项目包含 34 个模块
+- 后续构建会更快，因为存在增量编译
+- 始终使用 `--no-transfer-progress` 以减少日志噪音
+
+### 测试结构
+- **测试框架**：TestNG（非 JUnit）
+- **测试文件**：共有 298 个测试文件
+- **默认行为**：pom.xml 中默认禁用测试（`<skip>true</skip>`）
+- **测试配置**：测试需要通过 test-config.xml 提供真实的微信 API 凭据
+- **注意**：没有真实微信 API 凭据请不要尝试运行测试，测试将会失败
+
+## 项目结构与导航
+
+### 核心 SDK 模块（主要开发区）
+- `weixin-java-common/` - 通用工具与基础类（最重要）
+- `weixin-java-mp/` - 公众号 SDK
+- `weixin-java-pay/` - 微信支付 SDK
+- `weixin-java-miniapp/` - 小程序 SDK
+- `weixin-java-cp/` - 企业微信 SDK
+- `weixin-java-open/` - 开放平台 SDK
+- `weixin-java-channel/` - 视频号 / Channel SDK
+- `weixin-java-qidian/` - 企点 SDK
+
+### 框架集成模块
+- `spring-boot-starters/` - Spring Boot 自动配置 starter
+- `solon-plugins/` - Solon 框架插件
+- `weixin-graal/` - GraalVM 本地镜像支持
+
+### 配置与质量控制
+- `quality-checks/google_checks.xml` - Checkstyle 配置
+- `.editorconfig` - 代码格式规则（2 个空格等于 1 个制表）
+- `pom.xml` - 根级 Maven 配置
+
+## 开发工作流
+
+### 修改代码的流程
+1. 修改前务必先构建以建立干净基线：
+   ```bash
+   mvn clean compile --no-transfer-progress
+   ```
+
+2. 遵循代码风格（由 checkstyle 强制）：
+   - 缩进使用 2 个空格（不要用制表符）
+   - 遵循 Google Java 风格指南
+   - 在 IDE 中安装 EditorConfig 插件
+
+3. 增量验证修改：
+   ```bash
+   # 每次修改后运行：
+   mvn compile --no-transfer-progress
+   mvn checkstyle:check --no-transfer-progress
+   ```
+
+### 提交修改前的必须校验
+请务必按顺序完成以下校验步骤：
+
+1. 代码风格校验：
+   ```bash
+   mvn checkstyle:check --no-transfer-progress
+   # 必须通过 - 约需 50 秒
+   ```
+
+2. 完整清理构建：
+   ```bash
+   mvn clean package -DskipTests=true --no-transfer-progress  
+   # 必须成功 - 约需 2 分钟
+   ```
+
+3. 文档：为公共方法和类补充或更新 javadoc
+4. 贡献规范：遵循 `CONTRIBUTING.md`，Pull Request 必须以 `develop` 分支为目标
+
+## 模块依赖与构建顺序
+
+### 核心模块依赖（构建顺序）
+1. `weixin-graal`（GraalVM 支持）
+2. `weixin-java-common`（所有模块的基础）
+3. 核心 SDK 模块（mp、pay、miniapp、cp、open、channel、qidian）
+4. 框架集成（spring-boot-starters、solon-plugins）
+
+### 主要关系模式
+- 所有 SDK 模块都依赖于 `weixin-java-common`
+- Spring Boot starters 依赖对应的 SDK 模块
+- Solon 插件遵循与 Spring Boot starters 相同的依赖模式
+- 每个模块都有单账号与多账号配置支持
+
+## 常见任务与命令
+
+### 验证指定模块
+```bash
+# 构建单个模块（将 'weixin-java-mp' 替换为目标模块）：
+cd weixin-java-mp
+mvn clean compile --no-transfer-progress
+```
+
+### 检查依赖
+```bash
+# 分析依赖树：
+mvn dependency:tree --no-transfer-progress
+
+# 检查依赖更新：  
+./others/check-dependency-updates.sh
+```
+
+### 发布与发布准备
+```bash
+# 版本检查：
+mvn versions:display-property-updates --no-transfer-progress
+
+# 部署（需要凭据）：
+mvn clean deploy -P release --no-transfer-progress
+```
+
+## 重要文件与位置
+
+### 配置文件
+- `pom.xml` - 根级 Maven 配置与依赖管理
+- `quality-checks/google_checks.xml` - Checkstyle 规则
+- `.editorconfig` - IDE 格式化配置
+- `.github/workflows/maven-publish.yml` - CI/CD 工作流
+
+### 文档
+- `README.md` - 项目概览与使用说明（中文）
+- `CONTRIBUTING.md` - 贡献指南
+- `demo.md` - 示例项目与演示链接
+- 每个模块均有单独的文档与示例
+
+### 测试资源
+- `*/src/test/resources/test-config.sample.xml` - 测试配置模板
+- 测试运行需要真实的微信 API 凭据
+
+## SDK 使用模式
+
+### Maven 依赖示例
+```xml
+<dependency>
+  <groupId>com.github.binarywang</groupId>
+  <artifactId>weixin-java-mp</artifactId>  <!-- 或其他模块 -->
+  <version>4.7.0</version>
+</dependency>
+```
+
+### 常见开发区域
+- **API 客户端实现**：位于 `*/service/impl/` 目录
+- **模型类**：位于 `*/bean/` 目录
+- **配置**：位于 `*/config/` 目录
+- **工具类**：位于 `weixin-java-common` 的 `*/util/` 目录
+
+## 故障排查
+
+### 构建问题
+- **OutOfMemoryError**：增加 Maven 内存：`export MAVEN_OPTS="-Xmx2g"`
+- **编译失败**：通常为依赖问题 - 先执行 `mvn clean`
+- **Checkstyle 失败**：检查 IDE 的 `.editorconfig` 设置
+
+### 常见陷阱
+- **测试默认跳过**：这是正常现象 — 测试需要微信 API 凭据
+- **多模块变更**：总是在仓库根目录构建，而不是单独模块
+- **分支目标**：Pull Request 必须以 `develop` 分支为目标，而不是 `master` 或 `release`
+
+## 性能说明
+- **首次构建**：由于依赖下载，耗时 4-5 分钟
+- **增量构建**：通常更快（约 30-60 秒）
+- **Checkstyle**：运行迅速（约 50 秒），应当经常运行
+- **IDE 性能**：项目使用 Lombok，请确保启用注解处理
+
+注意：本项目为 SDK 库项目，而非可运行应用。修改应以 API 功能为主，不要改动应用级行为。

.github/workflows/maven-publish.yml

@@ -33,7 +33,22 @@ jobs:
             VERSION="${BASE_VER}.B"
             TAG="v${BASE_VER}"
             IS_RELEASE="true"
-            echo "Matched release commit: VERSION=$VERSION, TAG=$TAG"
+            echo "Matched test release commit: VERSION=$VERSION, TAG=$TAG"
+            # 检查并打tag
+            if git tag | grep -q "^$TAG$"; then
+              echo "Tag $TAG already exists."
+            else
+              git config user.name "Binary Wang"
+              git config user.email "a@binarywang.com"
+              git tag -a "$TAG" -m "Release $TAG"
+              git push origin "$TAG"
+              echo "Tag $TAG created and pushed."
+            fi
+          elif [[ "$COMMIT_MSG" =~ ^:bookmark:\ 发布\ ([0-9]+\.[0-9]+\.[0-9]+)\ 正式版本 ]]; then
+            VERSION="${BASH_REMATCH[1]}"
+            TAG="v${VERSION}"
+            IS_RELEASE="true"
+            echo "Matched formal release commit:  VERSION=$VERSION, TAG=$TAG"
             # 检查并打tag
             if git tag | grep -q "^$TAG$"; then
               echo "Tag $TAG already exists."

README.md

@@ -18,9 +18,10 @@
   </a>
 </div>
 
-### 微信`Java`开发工具包，支持包括微信支付、开放平台、公众号、企业微信、视频号、小程序等微信功能模块的后端开发。
+### 微信 `Java` 开发工具包，支持包括微信支付、开放平台、公众号、企业微信、视频号、小程序等微信功能模块的后端开发。
+
+### 特别赞助
 <div align="center">
-  <b>特别赞助</b>
   <table cellspacing="0" cellpadding="0" width="500">
     <tr>
       <td align="center" colspan="3">
@@ -47,31 +48,59 @@
           <img height="120" src="https://gitee.com/binary/weixin-java-tools/raw/develop/images/qrcodes/mp.png" alt="mp qrcode">
         </a>
       </td>
-      <td align="center">
-        <a href="https://www.diboot.com?from=wxjava" target="_blank">
-          <img height="120" src="https://www.diboot.com/img/diboot_ad.png" alt="diboot低代码开发平台">
-        </a>
+      <td align="center" style="font-size: 18px; font-weight: bold; vertical-align: middle;">
+        赞助商招募中
       </td>
       <td align="center">
-        <a href="https://www.crmeb.com/xiazai" target="_blank">
-          <img height="120" src="https://crmebjavamer.oss-cn-beijing.aliyuncs.com/crmebimage/gitee/WechatIMG202.jpg" alt="ad">
+        <a href="https://github.crmeb.net/u/wxjava" target="_blank">
+          <img height="120" src="https://crmebjavamer.oss-cn-beijing.aliyuncs.com/crmebimage/image/2026/01/30/0a71b2b3535d42b187fff977c33faa30mh9gipgeja.png" alt="ad">
         </a>
       </td>
     </tr>
   </table>
 </div>
 
+### 目录索引
+- [快速开始（3分钟）](#快速开始3分钟)
+- [我该选哪个模块？](#我该选哪个模块)
+- [Maven 引用方式](#maven-引用方式)
+- [最小示例](#最小示例)
+- [重要信息](#重要信息)
+- [其他说明](#其他说明)
+- [版本说明](#版本说明)
+- [应用案例](#应用案例)
+- [特别赞助](#特别赞助)
+- [贡献者列表](#贡献者列表)
+
+### 快速开始（3分钟）
+1. 根据业务场景选择模块（见下方“我该选哪个模块？”）
+2. 引入 Maven 依赖并选择对应模块
+3. 参考最小示例完成初始化并调用 API
+
+### 我该选哪个模块？
+
+| 业务场景 | 模块 | artifactId |
+|---|---|---|
+| 微信公众号开发 | MP | `weixin-java-mp` |
+| 微信小程序开发 | MiniApp | `weixin-java-miniapp` |
+| 微信支付 | Pay | `weixin-java-pay` |
+| 企业微信 | CP | `weixin-java-cp` |
+| 微信开放平台（第三方平台） | Open | `weixin-java-open` |
+| 视频号 / 微信小店 | Channel | `weixin-java-channel` |
+
+> 移动端（iOS/Android）微信登录、分享等能力仍需集成微信官方客户端 SDK；本项目为服务端 SDK。
+
 ### 重要信息
 1. [`WxJava` 荣获 `GitCode` 2024年度十大开源社区奖项](https://mp.weixin.qq.com/s/wM_UlMsDm3IZ1CPPDvcvQw)。
 2. 项目合作洽谈请联系微信`binary0000`（在微信里自行搜索并添加好友，请注明来意，如有关于SDK问题需讨论请参考下文入群讨论，不要加此微信）。
-3. **2024-12-30 发布 [【4.7.0正式版】](https://mp.weixin.qq.com/s/_7k-XLYBqeJJhvHWCsdT0A)**！
-4. 贡献源码可以参考视频：[【贡献源码全过程（上集）】](https://mp.weixin.qq.com/s/3xUZSATWwHR_gZZm207h7Q)、[【贡献源码全过程（下集）】](https://mp.weixin.qq.com/s/nyzJwVVoYSJ4hSbwyvTx9A) ，友情提供：[程序员小山与Bug](https://space.bilibili.com/473631007)
-5. 新手重要提示：本项目仅是一个SDK开发工具包，未提供Web实现，建议使用 `maven` 或 `gradle` 引用本项目即可使用本SDK提供的各种功能，详情可参考 **[【Demo项目】](demo.md)** 或本项目中的部分单元测试代码；
-6. 微信开发新手请务必阅读【开发文档】（[Gitee Wiki](https://gitee.com/binary/weixin-java-tools/wikis/Home) 或者 [Github Wiki](https://github.com/binarywang/WxJava/wiki)）的常见问题部分，可以少走很多弯路，节省不少时间。
-7. 技术交流群：想获得QQ群/微信群/钉钉企业群等信息的同学，请使用微信扫描上面的微信公众号二维码关注 `WxJava` 后点击相关菜单即可获取加入方式，同时也可以在微信中搜索 `weixin-java-tools` 或 `WxJava` 后选择正确的公众号进行关注，该公众号会及时通知SDK相关更新信息，并不定期分享微信Java开发相关技术知识；
-8. 钉钉技术交流群：`32206329`（技术交流2群）, `30294972`（技术交流1群，目前已满），`35724728`（通知群，实时通知Github项目变更记录）。
-9. 微信开发新手或者Java开发新手在群内提问或新开Issue提问前，请先阅读[【提问的智慧】](https://github.com/ryanhanwu/How-To-Ask-Questions-The-Smart-Way/blob/master/README-zh_CN.md)，并确保已查阅过 [【开发文档Wiki】](https://github.com/binarywang/WxJava/wiki) ，避免浪费大家的宝贵时间；
-10. 寻求帮助时需贴代码或大长串异常信息的，请利用 http://paste.ubuntu.com 
+3. **2026-01-03 发布 [【4.8.0正式版】](https://mp.weixin.qq.com/s/mJoFtGc25pXCn3uZRh6Q-w)**！
+5. 贡献源码可以参考视频：[【贡献源码全过程（上集）】](https://mp.weixin.qq.com/s/3xUZSATWwHR_gZZm207h7Q)、[【贡献源码全过程（下集）】](https://mp.weixin.qq.com/s/nyzJwVVoYSJ4hSbwyvTx9A) ，友情提供：[程序员小山与Bug](https://space.bilibili.com/473631007)
+6. 新手重要提示：本项目仅是一个SDK开发工具包，未提供Web实现，建议使用 `maven` 或 `gradle` 引用本项目即可使用本SDK提供的各种功能，详情可参考 **[【Demo项目】](demo.md)** 或本项目中的部分单元测试代码；
+7. 微信开发新手请务必阅读【开发文档】（[Gitee Wiki](https://gitee.com/binary/weixin-java-tools/wikis/Home) 或者 [Github Wiki](https://github.com/binarywang/WxJava/wiki)）的常见问题部分，可以少走很多弯路，节省不少时间。
+8. 技术交流群：想获得QQ群/微信群/钉钉企业群等信息的同学，请使用微信扫描上面的微信公众号二维码关注 `WxJava` 后点击相关菜单即可获取加入方式，同时也可以在微信中搜索 `weixin-java-tools` 或 `WxJava` 后选择正确的公众号进行关注，该公众号会及时通知SDK相关更新信息，并不定期分享微信Java开发相关技术知识；
+9. 钉钉技术交流群：`32206329`（技术交流2群）, `30294972`（技术交流1群，目前已满），`35724728`（通知群，实时通知Github项目变更记录）。
+10. 微信开发新手或者Java开发新手在群内提问或新开Issue提问前，请先阅读[【提问的智慧】](https://github.com/ryanhanwu/How-To-Ask-Questions-The-Smart-Way/blob/master/README-zh_CN.md)，并确保已查阅过 [【开发文档Wiki】](https://github.com/binarywang/WxJava/wiki) ，避免浪费大家的宝贵时间；
+11. 寻求帮助时需贴代码或大长串异常信息的，请利用 http://paste.ubuntu.com 
 
 --------------------------------
 ### 其他说明
@@ -95,7 +124,7 @@
 <dependency>
   <groupId>com.github.binarywang</groupId>
   <artifactId>（不同模块参考下文）</artifactId>
-  <version>4.7.0</version>
+  <version>4.8.0</version>
 </dependency>
 ```
 
@@ -106,6 +135,51 @@
   - 企业微信：`weixin-java-cp`
   - 微信视频号/微信小店：`weixin-java-channel`
 
+**注意**：
+- **移动应用开发**：如果你的移动应用（iOS/Android App）需要接入微信登录、分享等功能：
+  - 微信登录（网页授权）：使用 `weixin-java-open` 模块，在服务端处理 OAuth 授权
+  - 微信支付：使用 `weixin-java-pay` 模块
+  - 客户端集成：需使用微信官方提供的移动端SDK（iOS/Android），本项目为服务端SDK
+- **微信开放平台**（`weixin-java-open`）主要用于第三方平台，代公众号或小程序进行开发和管理
+
+
+
+---------------------------------
+### 最小示例
+
+<details>
+<summary>公众号（MP）示例：获取 AccessToken</summary>
+
+```java
+WxMpDefaultConfigImpl config = new WxMpDefaultConfigImpl();
+config.setAppId("your-app-id");
+config.setSecret("your-secret");
+
+WxMpService wxMpService = new WxMpServiceImpl();
+wxMpService.setWxMpConfigStorage(config);
+
+String accessToken = wxMpService.getAccessToken();
+System.out.println(accessToken);
+```
+
+</details>
+
+<details>
+<summary>小程序（MiniApp）示例：code2Session</summary>
+
+```java
+WxMaDefaultConfigImpl config = new WxMaDefaultConfigImpl();
+config.setAppid("your-app-id");
+config.setSecret("your-secret");
+
+WxMaService wxMaService = new WxMaServiceImpl();
+wxMaService.setWxMaConfig(config);
+
+WxMaJscode2SessionResult result = wxMaService.getUserService().getSessionInfo("js-code");
+System.out.println(result.getOpenid());
+```
+
+</details>
 
 ---------------------------------
 ### 版本说明