diff --git a/README.md b/README.md index d6a4088a1..86b203d57 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ ### 目录索引 - [快速开始（3分钟）](#快速开始3分钟) +- [AI 编程智能体 SKILL 安装](#ai-编程智能体-skill-安装) - [我该选哪个模块？](#我该选哪个模块) - [Maven 引用方式](#maven-引用方式) - [最小示例](#最小示例) @@ -45,6 +46,41 @@ 2. 引入 Maven 依赖并选择对应模块 3. 参考最小示例完成初始化并调用 API +### AI 编程智能体 SKILL 安装 + +仓库的 [`skills`](skills) 目录提供面向 WxJava 用户和贡献者的通用 SKILL，包括模块选择、接入、排障、接口贡献和升级迁移。每个 SKILL 都以 `SKILL.md` 为入口，可用于支持该约定的 AI 编程智能体。 + +支持远程安装 SKILL 的智能体，可以直接使用自然语言指令安装所需目录。例如： + +> 安装 https://github.com/binarywang/WxJava/tree/develop/skills/wxjava-integration-guide 中的技能。 + +可安装的 SKILL 包括： + +- [模块选择](https://github.com/binarywang/WxJava/tree/develop/skills/wxjava-module-selector) +- [接入指南](https://github.com/binarywang/WxJava/tree/develop/skills/wxjava-integration-guide) +- [故障排查](https://github.com/binarywang/WxJava/tree/develop/skills/wxjava-troubleshooter) +- [接口贡献](https://github.com/binarywang/WxJava/tree/develop/skills/wxjava-api-contributor) +- [升级迁移](https://github.com/binarywang/WxJava/tree/develop/skills/wxjava-upgrade-guide) + +不支持远程安装时，可将所需的 `skills/wxjava-*` 目录复制到智能体的 SKILL 目录或工作区配置目录；不同智能体的目录和启用方式请以其官方文档为准。 + +以 Codex 为例，可复制到个人 SKILL 目录： + +```shell +git clone https://github.com/binarywang/WxJava.git +mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills" +cp -R WxJava/skills/wxjava-* "${CODEX_HOME:-$HOME/.codex}/skills/" +``` + +如果已在本仓库根目录，可直接执行： + +```shell +mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills" +cp -R skills/wxjava-* "${CODEX_HOME:-$HOME/.codex}/skills/" +``` + +重启或新建智能体会话后，即可按需使用。例如：`使用 wxjava-integration-guide 为我的 Spring Boot 项目接入微信支付。` + ### 我该选哪个模块？ | 业务场景 | 模块 | artifactId | diff --git a/skills/wxjava-api-contributor/SKILL.md b/skills/wxjava-api-contributor/SKILL.md new file mode 100644 index 000000000..b6896f105 --- /dev/null +++ b/skills/wxjava-api-contributor/SKILL.md @@ -0,0 +1,14 @@ +--- +name: wxjava-api-contributor +description: 按 WxJava 的 Maven 多模块、Java 8、公共 API 兼容性和 TestNG 约定，为微信官方接口新增或维护 SDK 支持。适用于新增 Service API、请求响应 Bean、序列化、HTTP 实现、Starter 配置或回归测试时。 +--- + +# WxJava 接口贡献 + +1. 先搜索开放与已关闭 Issue，确认需求是否已有讨论、实现、回归用例或官方接口变动；再确认微信产品和目标模块。 +2. 阅读对应 README、POM、相似接口、实现与测试，并读取 [贡献约定](references/contribution.md)。 +3. 将官方接口契约映射到 Service、实现、Bean、URL、序列化和测试；列出所有可能受影响的 HTTP 客户端和 Starter。 +4. 只做完成需求所需的最小改动；更新必要 Javadoc、测试与用户可见文档。 +5. 执行 `mvn -pl -am test`，并检查 `git diff --check`。 + +保持 Java 8 与公共 API、异常语义、JSON/XML 字段兼容性。涉及多 HTTP 客户端、单/多账号 Starter 或 Solon 插件时，检查等价实现是否需要同步。PR 应关联对应 Issue，目标分支为 `develop`。 diff --git a/skills/wxjava-api-contributor/agents/openai.yaml b/skills/wxjava-api-contributor/agents/openai.yaml new file mode 100644 index 000000000..acefb1b7e --- /dev/null +++ b/skills/wxjava-api-contributor/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "WxJava 接口贡献" + short_description: "按 WxJava 项目约定新增或维护 SDK 接口能力" + default_prompt: "使用 $wxjava-api-contributor 为 WxJava 新增微信接口支持。" diff --git a/skills/wxjava-api-contributor/references/contribution.md b/skills/wxjava-api-contributor/references/contribution.md new file mode 100644 index 000000000..6b8571e28 --- /dev/null +++ b/skills/wxjava-api-contributor/references/contribution.md @@ -0,0 +1,19 @@ +# 贡献约定 + +以微信官方接口定义和本仓库同类实现为准，核对路径、方法、字段名、必填项和响应结构。优先复用既有 HTTP 执行器、异常、配置、Gson/Jackson/XStream 映射和 TestNG 测试模式。 + +公共方法需要准确 Javadoc。不要吞异常、记录敏感值或无关重构。新增公开方法和 bug 修复均应有针对性测试；涉及公共模块、BOM 或多模块时扩大验证范围。 + +## 接口增量检查表 + +1. 从微信官方文档和相关 Issue 中确认接口可用条件、HTTP 方法、URL、必填字段、签名/加密要求和响应示例。 +2. 搜索同产品的相邻能力，复用其 Service 分层、Bean 命名、请求执行和错误处理模式；不要只新增 Bean 而遗漏 Service 暴露。 +3. 若接口尚未支持，优先使用现有通用执行能力；MP/CP Wiki 说明通用执行器会处理 access token 刷新及 `errcode` 到异常的转换。 +4. 为字段边界、空值、JSON/XML 映射和异常路径添加 TestNG 回归测试。API 路径或字段问题是历史 bug 的高频来源，例如 [#3982](https://github.com/binarywang/WxJava/issues/3982)、[#4000](https://github.com/binarywang/WxJava/issues/4000)。 +5. 按 [贡献指南](https://github.com/binarywang/WxJava/blob/develop/CONTRIBUTING.md) 使用 `develop` 作为 PR 目标；说明 Issue、兼容性影响和验证命令。 + +## 一手资料入口 + +- [如何调用 MP 未支持接口](https://github.com/binarywang/WxJava/wiki/MP_%E5%A6%82%E4%BD%95%E8%B0%83%E7%94%A8%E6%9C%AA%E6%94%AF%E6%8C%81%E7%9A%84%E6%8E%A5%E5%8F%A3) +- [如何调用 CP 未支持接口](https://github.com/binarywang/WxJava/wiki/CP_%E5%A6%82%E4%BD%95%E8%B0%83%E7%94%A8%E6%9C%AA%E6%94%AF%E6%8C%81%E7%9A%84%E6%8E%A5%E5%8F%A3) +- [关闭的新接口 Issue](https://github.com/binarywang/WxJava/issues?q=is%3Aissue%20state%3Aclosed%20label%3A%E6%96%B0%E6%8E%A5%E5%8F%A3) diff --git a/skills/wxjava-integration-guide/SKILL.md b/skills/wxjava-integration-guide/SKILL.md new file mode 100644 index 000000000..393438768 --- /dev/null +++ b/skills/wxjava-integration-guide/SKILL.md @@ -0,0 +1,14 @@ +--- +name: wxjava-integration-guide +description: 为 Java、Spring Boot 或 Solon 项目生成可验证的 WxJava 接入方案，包括模块选择、BOM、配置、最小调用代码以及单/多账号集成。适用于用户要求接入公众号、小程序、支付、企业微信、开放平台、视频号或微信小店时。 +--- + +# WxJava 接入指南 + +1. 确认微信产品、框架、单/多账号、部署形态和首个 API 调用。 +2. 读取 [接入约束](references/integration.md)，选择模块和配置方式。 +3. 先输出依赖与配置，再输出最小调用；每段示例注明应放置的位置和所依赖的模块。 +4. 输出脱敏配置和最小服务端代码；凭据一律用占位符。 +5. 给出本地验证步骤与安全提醒；支付、回调和证书示例不得直接用于生产。 + +保持 Java 8 兼容。生产集群必须使用可共享的配置存储或 token 存储；不要把内存实现当作多节点部署方案。引用已有 Demo、Wiki 或 README 作为继续阅读入口；不虚构配置键、SDK 方法或版本号。 diff --git a/skills/wxjava-integration-guide/agents/openai.yaml b/skills/wxjava-integration-guide/agents/openai.yaml new file mode 100644 index 000000000..622ec2ac9 --- /dev/null +++ b/skills/wxjava-integration-guide/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "WxJava 接入指南" + short_description: "生成可验证的 WxJava 最小接入方案与配置示例" + default_prompt: "使用 $wxjava-integration-guide 为我的项目生成 WxJava 接入代码。" diff --git a/skills/wxjava-integration-guide/references/integration.md b/skills/wxjava-integration-guide/references/integration.md new file mode 100644 index 000000000..ae441cc27 --- /dev/null +++ b/skills/wxjava-integration-guide/references/integration.md @@ -0,0 +1,22 @@ +# 接入约束 + +优先通过 `wx-java-bom` 统一管理多个 WxJava 模块版本。核心 SDK 模块是 MP、MiniApp、Pay、CP、Open、Channel、Qidian、Aispeech；框架集成模块位于 `spring-boot-starters` 与 `solon-plugins`。 + +查阅相应模块 README、根目录 [demo.md](https://github.com/binarywang/WxJava/blob/develop/demo.md) 和目标模块测试中的示例，确认配置属性与初始化模式。所有 `appId`、`secret`、商户私钥、API v3 密钥和证书均使用占位符，不得输出到日志。 + +## 实施检查表 + +1. 先完成一条只读或低风险 API 调用，再接入消息、支付或异步回调。 +2. 单实例可使用默认配置存储；多实例或集群需使用共享的 token/config storage，避免节点各自刷新 access token。 +3. 公众号、企业微信等回调必须先按平台要求校验消息合法性，再进入业务路由；支付回调还必须按商户单号实现幂等。 +4. 需要代理或私有网络出口时，明确区分正向代理与反向代理。支付 V3 的签名路径不能因反向代理路径前缀而被错误改写。 +5. HTTP 客户端类型、Starter 配置键和 Service 实现必须取自目标模块的当前 README、POM 或相邻 Demo；不要混用不同产品模块的配置前缀。 +6. Starter 自动配置与 Demo 手动初始化必须二选一后再给示例。发生空 key、注入为空或 NPE 时，先核对启动模块、profile、配置前缀和当前 `*Properties` 类；历史 [#2177](https://github.com/binarywang/WxJava/issues/2177) 是混用两种配置模型的案例。 +7. Quarkus 或 GraalVM 场景转到 [Quarkus 支持文档](https://github.com/binarywang/WxJava/blob/develop/docs/QUARKUS_SUPPORT.md)，不要套用 Spring Boot Starter 配置。 + +## 一手资料入口 + +- [MP Quick Start](https://github.com/binarywang/WxJava/wiki/MP_Quick-Start) +- [微信支付说明](https://github.com/binarywang/WxJava/wiki/%E5%BE%AE%E4%BF%A1%E6%94%AF%E4%BB%98) +- [SDK 正反向代理支持](https://github.com/binarywang/WxJava/wiki/SDK-%E9%92%88%E5%AF%B9%E5%BE%AE%E4%BF%A1-%E6%AD%A3%E5%90%91%E4%BB%A3%E7%90%86%E5%92%8C%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86%E6%94%AF%E6%8C%81) +- [HTTP 客户端升级指南](https://github.com/binarywang/WxJava/blob/develop/docs/HTTPCLIENT_UPGRADE_GUIDE.md) diff --git a/skills/wxjava-module-selector/SKILL.md b/skills/wxjava-module-selector/SKILL.md new file mode 100644 index 000000000..3d78c0ebf --- /dev/null +++ b/skills/wxjava-module-selector/SKILL.md @@ -0,0 +1,15 @@ +--- +name: wxjava-module-selector +description: 根据微信公众号、小程序、微信支付、企业微信、开放平台、视频号或微信小店、腾讯企点和微信智能对话等业务场景，为用户选择合适的 WxJava Maven 模块、BOM 和示例入口。适用于用户询问“该用哪个模块”、依赖坐标、产品边界或单/多账号 Starter 选择时。 +--- + +# WxJava 模块选择 + +1. 识别微信产品、服务端框架、是否多账号、是否包含支付或回调；信息不足时只询问必要问题。 +2. 读取 [模块映射](references/modules.md)，给出一个主推荐，以及组合模块的理由。 +3. 先区分产品边界，再选择核心 SDK；仅当项目确实依赖框架自动配置时才额外推荐 Starter 或 Solon 插件。 +4. 优先推荐 BOM；给出准确的 `groupId`、`artifactId`、相应 Demo、Wiki 或仓库文档入口。 +5. 说明服务端 SDK 的边界：移动端登录、分享等能力仍需微信官方客户端 SDK。 +6. 不臆测版本号；建议以 Maven Central 或项目 README 的当前版本为准。 + +使用“场景 → 模块 → 集成选项 → 下一步”的简短结构。涉及多账号时说明单账号与 multi Starter 的区别；不要在示例中泄露凭据。支付和回调场景必须提醒用户验证通知 URL、验签与幂等处理。 diff --git a/skills/wxjava-module-selector/agents/openai.yaml b/skills/wxjava-module-selector/agents/openai.yaml new file mode 100644 index 000000000..a3744af61 --- /dev/null +++ b/skills/wxjava-module-selector/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "WxJava 模块选择" + short_description: "按微信业务场景选择 WxJava 模块、依赖与示例" + default_prompt: "使用 $wxjava-module-selector 为我的微信业务选择合适的 WxJava 模块。" diff --git a/skills/wxjava-module-selector/references/modules.md b/skills/wxjava-module-selector/references/modules.md new file mode 100644 index 000000000..563cdbb95 --- /dev/null +++ b/skills/wxjava-module-selector/references/modules.md @@ -0,0 +1,37 @@ +# WxJava 模块映射 + +| 场景 | 核心模块 | +| --- | --- | +| 微信公众号 | `weixin-java-mp` | +| 微信小程序 | `weixin-java-miniapp` | +| 微信支付 | `weixin-java-pay` | +| 企业微信 | `weixin-java-cp` | +| 微信开放平台／第三方平台 | `weixin-java-open` | +| 视频号／微信小店 | `weixin-java-channel` | +| 腾讯企点／微信客服 | `weixin-java-qidian` | +| 微信智能对话／智能语音 | `weixin-java-aispeech` | + +多个模块并用时优先使用 `com.github.binarywang:wx-java-bom`。Spring Boot 集成从 `spring-boot-starters` 选择；Solon 集成从 `solon-plugins` 选择。 + +## 多账号集成范围 + +只有多个独立微信应用配置时才选择 multi 集成，并先按框架与产品核对目录是否存在： + +- Spring Boot：MP、MiniApp、CP、自建/第三方 CP、Pay、Open、Channel 都有相应 multi Starter。 +- Solon：仅 MP、MiniApp、CP、Channel 有 multi 插件；Pay、Open、Qidian 目前只有单账号插件，不要推荐不存在的 multi artifact。 + +## 选择检查点 + +- 公众号、小程序和企业微信的消息回调、token 与加解密配置彼此独立；不要因同属一个公司而复用不兼容的凭据或配置对象。 +- 企业微信的多应用应使用独立的 `WxCpConfigStorage` 与 `WxCpServiceImpl`；Wiki 明确指出复用 token、AES key 和 URL 会造成安全边界问题。 +- 支付能力通常与 MP、MiniApp 或 Open 同时使用：前者处理业务身份和消息，`weixin-java-pay` 处理商户签名、证书与支付回调。 +- 视频号／微信小店接口属于 `weixin-java-channel`；不要误归入 MP 或 Pay。 +- 腾讯企点与微信智能对话是独立 SDK 模块；不要将客服或智能对话需求默认归入 MP、CP 或 Channel。 +- 当能力在 MP 与 Open 等模块可能重叠时，按授权主体、官方 API 域和回调场景选择，不要只按“移动端”或“登录”字样判断。先在当前源码和 Issue 中确认覆盖状态，并标注“已确认 / 待查 / 需自行调用底层接口”。 +- BOM 适合同时使用多个 WxJava 模块。若项目还导入 Spring Boot 等上游 BOM，升级后执行 `mvn help:effective-pom` 与 `mvn dependency:tree`；历史 [#4058](https://github.com/binarywang/WxJava/issues/4058) 表明依赖管理顺序可能影响 Spring Data Redis 等依赖。 + +## 一手资料入口 + +- [WxJava Wiki 首页](https://github.com/binarywang/WxJava/wiki) +- [企业微信多应用配置](https://github.com/binarywang/WxJava/wiki/CP_%E5%A6%82%E4%BD%95%E6%94%AF%E6%8C%81%E5%A4%9A%E4%B8%AA%E4%BC%81%E4%B8%9A%E5%8F%B7%E5%BA%94%E7%94%A8%E6%88%96%E4%BC%81%E4%B8%9A%E5%8F%B7) +- [视频号／微信小店开发文档](https://github.com/binarywang/WxJava/wiki/0_%E8%A7%86%E9%A2%91%E5%8F%B7_%E5%BE%AE%E4%BF%A1%E5%B0%8F%E5%BA%97%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3) diff --git a/skills/wxjava-troubleshooter/SKILL.md b/skills/wxjava-troubleshooter/SKILL.md new file mode 100644 index 000000000..26d8c941e --- /dev/null +++ b/skills/wxjava-troubleshooter/SKILL.md @@ -0,0 +1,14 @@ +--- +name: wxjava-troubleshooter +description: 排查 WxJava 在配置初始化、access token、签名验签、支付证书、回调通知、序列化、网络请求和多账号隔离方面的问题。适用于用户提供异常、日志、请求响应或“WxJava 为什么不能调用”的场景。 +--- + +# WxJava 故障排查 + +1. 收集最小复现：产品模块、SDK 版本、JDK、框架、依赖树、异常堆栈、请求 ID 与脱敏后的配置形状。 +2. 将故障归类为依赖/初始化、token 与存储、请求契约、HTTP/代理、回调验签、支付证书或并发与生命周期。 +3. 依据 [诊断清单](references/diagnostics.md)，按最低成本、最可验证的顺序排查。 +4. 每次只提出一个可验证根因，给出最小修复、预期现象和回归验证动作。 +5. 签名、支付、回调和加密场景须核对编码、字段排序、金额精度、时间戳、证书链和重放保护。 + +要求遮蔽 secret、token、私钥、证书、签名原文和个人数据。不要建议关闭 TLS 校验或验签；区分已证实结论与待验证假设。遇到历史同类问题时，给出对应 Issue 或 Wiki 链接，但必须检查当前版本的实现后再套用修复。 diff --git a/skills/wxjava-troubleshooter/agents/openai.yaml b/skills/wxjava-troubleshooter/agents/openai.yaml new file mode 100644 index 000000000..f473f862f --- /dev/null +++ b/skills/wxjava-troubleshooter/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "WxJava 故障排查" + short_description: "定位 WxJava 配置、回调、签名与接口调用问题" + default_prompt: "使用 $wxjava-troubleshooter 排查我的 WxJava 调用异常。" diff --git a/skills/wxjava-troubleshooter/references/diagnostics.md b/skills/wxjava-troubleshooter/references/diagnostics.md new file mode 100644 index 000000000..acf115ae9 --- /dev/null +++ b/skills/wxjava-troubleshooter/references/diagnostics.md @@ -0,0 +1,27 @@ +# 诊断清单 + +- 配置：模块是否正确，应用标识和凭据是否配对，多账号配置是否被正确选择。 +- 请求：HTTP 方法、路径、必填字段和 JSON/XML 映射是否符合微信接口契约。 +- 认证：token 缓存、签名字段、时间戳、nonce、证书和密钥格式是否有效。 +- 网络：DNS、代理、超时、TLS 证书校验和响应关闭是否正常。 +- 回调：回调 URL 可访问、验签参数完整、幂等处理和资源释放是否存在。 + +从精确异常和最小请求入手，不用“重试”替代根因分析。 + +## 高频场景 + +| 症状 | 优先检查 | 依据 | +| --- | --- | --- | +| 多节点间歇性 token 失效 | 是否共享 token/config storage，是否让各节点并发刷新 | Wiki 的 MP/CP 配置存储说明与集群案例 | +| `NoClassDefFoundError`、`NoSuchMethodError` | `mvn dependency:tree`、HttpClient/commons-lang/xstream 冲突及 BOM 是否统一版本 | Wiki 的异常排查页与 HTTP 客户端升级指南 | +| 回调验签或重复处理 | 原始请求体、时间戳/nonce/签名、回调 URL、业务幂等键 | MP 合法性校验与支付回调说明 | +| HTTP 连接、超时或代理问题 | 连接/读取超时、代理、TLS、正反向代理是否混用 | Wiki 的 HttpClient 参数与代理文档 | +| 企业微信会话存档崩溃 | 是否仍手动销毁旧 SDK 实例，是否已迁移安全 API | [会话存档安全使用指南](https://github.com/binarywang/WxJava/blob/develop/docs/CP_MSG_AUDIT_SDK_SAFE_USAGE.md) | +| 视频号/小店接口 404 或字段不匹配 | 当前官方路径与请求字段、目标 SDK 版本、历史 Issue 是否已修复 | 关闭的 bug Issue，如 [#3982](https://github.com/binarywang/WxJava/issues/3982) | + +## 一手资料入口 + +- [常见异常首页](https://github.com/binarywang/WxJava/wiki) +- [MP 消息合法性验证](https://github.com/binarywang/WxJava/wiki/MP_%E9%AA%8C%E8%AF%81%E6%B6%88%E6%81%AF%E5%90%88%E6%B3%95%E6%80%A7) +- [HttpClient 参数配置](https://github.com/binarywang/WxJava/wiki/HttpClient%E7%9B%B8%E5%85%B3%E5%8F%82%E6%95%B0%E7%9A%84%E8%AE%BE%E7%BD%AE%E6%96%B9%E6%B3%95) +- [关闭的 bug Issue](https://github.com/binarywang/WxJava/issues?q=is%3Aissue%20state%3Aclosed%20label%3Abug) diff --git a/skills/wxjava-upgrade-guide/SKILL.md b/skills/wxjava-upgrade-guide/SKILL.md new file mode 100644 index 000000000..624a75233 --- /dev/null +++ b/skills/wxjava-upgrade-guide/SKILL.md @@ -0,0 +1,14 @@ +--- +name: wxjava-upgrade-guide +description: 规划 WxJava 的版本升级与迁移，检查 BOM、模块依赖、Java 版本、配置与公共 API 兼容性，并提供可回滚的验证步骤。适用于用户从旧版升级、切换依赖管理方式、处理兼容性告警或制定升级发布计划时。 +--- + +# WxJava 升级迁移 + +1. 收集当前与目标版本、已用模块、JDK、框架、BOM 使用情况、依赖树、代理配置和关键调用路径。 +2. 读取 [迁移检查表](references/migration.md)，识别版本、依赖和配置边界。 +3. 按 HTTP 客户端、BOM、支付/回调、多账号、企业微信会话存档等变化类型选择迁移分支。 +4. 输出分阶段变更：依赖调整、编译、关键回归测试、灰度与明确回滚条件。 +5. 将不确定项标为待查，并引导查看目标版本的 release notes、README、Javadoc 与变更记录。 + +不要猜测废弃 API 或破坏性变更；以官方发布信息、当前代码与实际编译结果为准。默认保持 Java 8，除非目标版本明确改变此约束。不能以关闭验签、固定 token 或跳过测试作为回滚方案。 diff --git a/skills/wxjava-upgrade-guide/agents/openai.yaml b/skills/wxjava-upgrade-guide/agents/openai.yaml new file mode 100644 index 000000000..fdf8b71ec --- /dev/null +++ b/skills/wxjava-upgrade-guide/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "WxJava 升级迁移" + short_description: "规划 WxJava 版本升级、依赖调整与兼容性迁移" + default_prompt: "使用 $wxjava-upgrade-guide 制定 WxJava 版本升级方案。" diff --git a/skills/wxjava-upgrade-guide/references/migration.md b/skills/wxjava-upgrade-guide/references/migration.md new file mode 100644 index 000000000..443ac73a0 --- /dev/null +++ b/skills/wxjava-upgrade-guide/references/migration.md @@ -0,0 +1,37 @@ +# 迁移检查表 + +- 使用多个 WxJava 模块时，优先迁移到 `wx-java-bom`，避免模块版本漂移。 +- 清点 MP、MiniApp、Pay、CP、Open、Channel 及框架 Starter/插件的实际依赖。 +- 更新后先执行编译和受影响模块测试，再验证 token、回调、支付和关键业务链路。 +- 为依赖版本保留可快速恢复的变更记录；按灰度策略验证生产环境，且不将凭据写入代码或日志。 + +## 升级分支 + +### HTTP 客户端 + +从 4.7.x 起，项目支持并推荐 Apache HttpClient 5.x，同时保留部分 4.x 兼容性。先按 [HTTP 客户端升级指南](https://github.com/binarywang/WxJava/blob/develop/docs/HTTPCLIENT_UPGRADE_GUIDE.md) 核对模块、依赖与 `http-client-type`，再检查代理 host、port、username、password 的完整性。历史 [#3836](https://github.com/binarywang/WxJava/issues/3836) 表明可选代理配置也需要回归。 + +### BOM 与依赖冲突 + +`wx-java-bom` 从 4.8.3.B 起提供。导入 BOM 前后均执行： + +```shell +mvn help:effective-pom +mvn dependency:tree +``` + +特别回归由 Spring Boot BOM 管理的 Redis、HTTP 客户端和序列化依赖；[#4058](https://github.com/binarywang/WxJava/issues/4058) 是历史冲突案例。 + +### 企业微信会话存档 + +升级到 4.8.0 或更高版本时，查找旧的 `getChatDatas`、`getDecryptData`、`getChatPlainText`、`getMediaFile` 和手动 `Finance.DestroySdk()`。按 [ThreadLocal 生命周期迁移文档](https://github.com/binarywang/WxJava/blob/develop/docs/CP_MSG_AUDIT_THREADLOCAL_LIFECYCLE_REFACTOR.md) 切换至新 API，并做并发验证。 + +ThreadLocal SDK 不会在线程结束时自动释放。在线程池、定时任务或一次性线程中，必须在任务的 `finally` 块调用 `msgAuditService.closeThreadLocalSdk()`；应用停止时再用 `closeAllSdks()` 做全局兜底。不要在业务代码中直接调用 `Finance.DestroySdk()`。 + +### 回调与支付 + +验证不止于 HTTP 2xx：分别覆盖 token 获取、签名/证书校验、重复回调、业务状态转换和多账号路由。多账号异步任务必须显式传递 appId 或服务上下文，不能假定 ThreadLocal 自动继承。 + +## 验证与回滚 + +按“编译和单测 → 非生产凭据冒烟 → 灰度和监控”执行。出现依赖树冲突、验签/证书异常、回调错误或 native 崩溃时停止扩大灰度，恢复上一个已验证依赖组合后再以最小复现定位。