From 606bf3a6084f1f91311bf3c04db541fd8c02621b Mon Sep 17 00:00:00 2001 From: Binary Wang Date: Mon, 20 Jul 2026 10:05:18 +0800 Subject: [PATCH 1/7] =?UTF-8?q?=E6=96=B0=E5=A2=9E=20WxJava=20=E7=94=A8?= =?UTF-8?q?=E6=88=B7=E6=8A=80=E8=83=BD=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/wxjava-api-contributor/SKILL.md | 13 +++++++++++++ skills/wxjava-api-contributor/agents/openai.yaml | 4 ++++ .../references/contribution.md | 5 +++++ skills/wxjava-integration-guide/SKILL.md | 13 +++++++++++++ skills/wxjava-integration-guide/agents/openai.yaml | 4 ++++ .../references/integration.md | 5 +++++ skills/wxjava-module-selector/SKILL.md | 14 ++++++++++++++ skills/wxjava-module-selector/agents/openai.yaml | 4 ++++ .../wxjava-module-selector/references/modules.md | 12 ++++++++++++ skills/wxjava-troubleshooter/SKILL.md | 13 +++++++++++++ skills/wxjava-troubleshooter/agents/openai.yaml | 4 ++++ .../references/diagnostics.md | 9 +++++++++ skills/wxjava-upgrade-guide/SKILL.md | 13 +++++++++++++ skills/wxjava-upgrade-guide/agents/openai.yaml | 4 ++++ .../wxjava-upgrade-guide/references/migration.md | 6 ++++++ 15 files changed, 123 insertions(+) create mode 100644 skills/wxjava-api-contributor/SKILL.md create mode 100644 skills/wxjava-api-contributor/agents/openai.yaml create mode 100644 skills/wxjava-api-contributor/references/contribution.md create mode 100644 skills/wxjava-integration-guide/SKILL.md create mode 100644 skills/wxjava-integration-guide/agents/openai.yaml create mode 100644 skills/wxjava-integration-guide/references/integration.md create mode 100644 skills/wxjava-module-selector/SKILL.md create mode 100644 skills/wxjava-module-selector/agents/openai.yaml create mode 100644 skills/wxjava-module-selector/references/modules.md create mode 100644 skills/wxjava-troubleshooter/SKILL.md create mode 100644 skills/wxjava-troubleshooter/agents/openai.yaml create mode 100644 skills/wxjava-troubleshooter/references/diagnostics.md create mode 100644 skills/wxjava-upgrade-guide/SKILL.md create mode 100644 skills/wxjava-upgrade-guide/agents/openai.yaml create mode 100644 skills/wxjava-upgrade-guide/references/migration.md diff --git a/skills/wxjava-api-contributor/SKILL.md b/skills/wxjava-api-contributor/SKILL.md new file mode 100644 index 000000000..258a7e066 --- /dev/null +++ b/skills/wxjava-api-contributor/SKILL.md @@ -0,0 +1,13 @@ +--- +name: wxjava-api-contributor +description: 按 WxJava 的 Maven 多模块、Java 8、公共 API 兼容性和 TestNG 约定，为微信官方接口新增或维护 SDK 支持。适用于新增 Service API、请求响应 Bean、序列化、HTTP 实现、Starter 配置或回归测试时。 +--- + +# WxJava 接口贡献 + +1. 确认微信产品和目标模块，阅读对应 README、POM、相似接口、实现与测试。 +2. 读取 [贡献约定](references/contribution.md)，将官方接口契约映射到 Service、实现、Bean、URL、序列化和测试。 +3. 只做完成需求所需的最小改动；更新必要 Javadoc、测试与用户可见文档。 +4. 执行 `mvn -pl -am test`，并检查 `git diff --check`。 + +保持 Java 8 与公共 API、异常语义、JSON/XML 字段兼容性。涉及多 HTTP 客户端、单/多账号 Starter 或 Solon 插件时，检查等价实现是否需要同步。 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..e3c7cbea0 --- /dev/null +++ b/skills/wxjava-api-contributor/references/contribution.md @@ -0,0 +1,5 @@ +# 贡献约定 + +以微信官方接口定义和本仓库同类实现为准，核对路径、方法、字段名、必填项和响应结构。优先复用既有 HTTP 执行器、异常、配置、Gson/Jackson/XStream 映射和 TestNG 测试模式。 + +公共方法需要准确 Javadoc。不要吞异常、记录敏感值或无关重构。新增公开方法和 bug 修复均应有针对性测试；涉及公共模块、BOM 或多模块时扩大验证范围。 diff --git a/skills/wxjava-integration-guide/SKILL.md b/skills/wxjava-integration-guide/SKILL.md new file mode 100644 index 000000000..9505d8957 --- /dev/null +++ b/skills/wxjava-integration-guide/SKILL.md @@ -0,0 +1,13 @@ +--- +name: wxjava-integration-guide +description: 为 Java、Spring Boot 或 Solon 项目生成可验证的 WxJava 接入方案，包括模块选择、BOM、配置、最小调用代码以及单/多账号集成。适用于用户要求接入公众号、小程序、支付、企业微信、开放平台、视频号或微信小店时。 +--- + +# WxJava 接入指南 + +1. 确认微信产品、框架、单/多账号和首个 API 调用。 +2. 读取 [接入约束](references/integration.md)，选择模块和配置方式。 +3. 输出可复制的依赖、脱敏配置和最小服务端代码；凭据一律用占位符。 +4. 给出本地验证步骤与安全提醒；支付、回调和证书示例不得直接用于生产。 + +保持 Java 8 兼容。引用已有 Demo 或 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..d079d2e9d --- /dev/null +++ b/skills/wxjava-integration-guide/references/integration.md @@ -0,0 +1,5 @@ +# 接入约束 + +优先通过 `wx-java-bom` 统一管理多个 WxJava 模块版本。核心 SDK 模块是 MP、MiniApp、Pay、CP、Open、Channel；框架集成模块位于 `spring-boot-starters` 与 `solon-plugins`。 + +查阅相应模块 README 和 `demo/` 的相邻示例，确认配置属性与初始化模式。所有 `appId`、`secret`、商户私钥、API v3 密钥和证书均使用占位符，不得输出到日志。 diff --git a/skills/wxjava-module-selector/SKILL.md b/skills/wxjava-module-selector/SKILL.md new file mode 100644 index 000000000..577c05630 --- /dev/null +++ b/skills/wxjava-module-selector/SKILL.md @@ -0,0 +1,14 @@ +--- +name: wxjava-module-selector +description: 根据微信公众号、小程序、微信支付、企业微信、开放平台、视频号或微信小店等业务场景，为用户选择合适的 WxJava Maven 模块、BOM 和示例入口。适用于用户询问“该用哪个模块”、依赖坐标、产品边界或单/多账号 Starter 选择时。 +--- + +# WxJava 模块选择 + +1. 识别微信产品、服务端框架和是否需要多账号；信息不足时只询问必要问题。 +2. 读取 [模块映射](references/modules.md)，给出一个主推荐，以及组合模块的理由。 +3. 优先推荐 BOM；给出准确的 `groupId`、`artifactId` 和相应 Demo 或 README。 +4. 说明服务端 SDK 的边界：移动端登录、分享等能力仍需微信官方客户端 SDK。 +5. 不臆测版本号；建议以 Maven Central 或项目 README 的当前版本为准。 + +使用“场景 → 模块 → 依赖 → 下一步”的简短结构。涉及多账号时说明单账号与 multi Starter 的区别；不要在示例中泄露凭据。 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..cb8bf5bc6 --- /dev/null +++ b/skills/wxjava-module-selector/references/modules.md @@ -0,0 +1,12 @@ +# WxJava 模块映射 + +| 场景 | 核心模块 | +| --- | --- | +| 微信公众号 | `weixin-java-mp` | +| 微信小程序 | `weixin-java-miniapp` | +| 微信支付 | `weixin-java-pay` | +| 企业微信 | `weixin-java-cp` | +| 微信开放平台／第三方平台 | `weixin-java-open` | +| 视频号／微信小店 | `weixin-java-channel` | + +多个模块并用时优先使用 `com.github.binarywang:wx-java-bom`。Spring Boot 集成从 `spring-boot-starters` 选择；Solon 集成从 `solon-plugins` 选择。只有多个独立微信应用配置时才选择名称含 `multi` 的 Starter 或插件。 diff --git a/skills/wxjava-troubleshooter/SKILL.md b/skills/wxjava-troubleshooter/SKILL.md new file mode 100644 index 000000000..4147235ce --- /dev/null +++ b/skills/wxjava-troubleshooter/SKILL.md @@ -0,0 +1,13 @@ +--- +name: wxjava-troubleshooter +description: 排查 WxJava 在配置初始化、access token、签名验签、支付证书、回调通知、序列化、网络请求和多账号隔离方面的问题。适用于用户提供异常、日志、请求响应或“WxJava 为什么不能调用”的场景。 +--- + +# WxJava 故障排查 + +1. 收集最小复现：产品模块、SDK 版本、JDK、框架、异常堆栈及脱敏后的配置形状。 +2. 依据 [诊断清单](references/diagnostics.md)，按配置、请求契约、认证材料、网络与回调顺序验证。 +3. 每次只提出一个可验证根因，给出最小修复和验证动作。 +4. 签名、支付、回调和加密场景须核对编码、字段排序、金额精度、时间戳、证书链和重放保护。 + +要求遮蔽 secret、token、私钥、证书、签名原文和个人数据。不要建议关闭 TLS 校验或验签；区分已证实结论与待验证假设。 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..d274919e7 --- /dev/null +++ b/skills/wxjava-troubleshooter/references/diagnostics.md @@ -0,0 +1,9 @@ +# 诊断清单 + +- 配置：模块是否正确，应用标识和凭据是否配对，多账号配置是否被正确选择。 +- 请求：HTTP 方法、路径、必填字段和 JSON/XML 映射是否符合微信接口契约。 +- 认证：token 缓存、签名字段、时间戳、nonce、证书和密钥格式是否有效。 +- 网络：DNS、代理、超时、TLS 证书校验和响应关闭是否正常。 +- 回调：回调 URL 可访问、验签参数完整、幂等处理和资源释放是否存在。 + +从精确异常和最小请求入手，不用“重试”替代根因分析。 diff --git a/skills/wxjava-upgrade-guide/SKILL.md b/skills/wxjava-upgrade-guide/SKILL.md new file mode 100644 index 000000000..f27790ff8 --- /dev/null +++ b/skills/wxjava-upgrade-guide/SKILL.md @@ -0,0 +1,13 @@ +--- +name: wxjava-upgrade-guide +description: 规划 WxJava 的版本升级与迁移，检查 BOM、模块依赖、Java 版本、配置与公共 API 兼容性，并提供可回滚的验证步骤。适用于用户从旧版升级、切换依赖管理方式、处理兼容性告警或制定升级发布计划时。 +--- + +# WxJava 升级迁移 + +1. 收集当前与目标版本、已用模块、JDK、框架、BOM 使用情况和关键调用路径。 +2. 读取 [迁移检查表](references/migration.md)，识别版本、依赖和配置边界。 +3. 输出分阶段变更：依赖调整、编译、关键回归测试、灰度与回滚条件。 +4. 将不确定项标为待查，并引导查看目标版本的 release notes、README、Javadoc 与变更记录。 + +不要猜测废弃 API 或破坏性变更；以官方发布信息和实际编译结果为准。默认保持 Java 8，除非目标版本明确改变此约束。 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..4ce4a8fd5 --- /dev/null +++ b/skills/wxjava-upgrade-guide/references/migration.md @@ -0,0 +1,6 @@ +# 迁移检查表 + +- 使用多个 WxJava 模块时，优先迁移到 `wx-java-bom`，避免模块版本漂移。 +- 清点 MP、MiniApp、Pay、CP、Open、Channel 及框架 Starter/插件的实际依赖。 +- 更新后先执行编译和受影响模块测试，再验证 token、回调、支付和关键业务链路。 +- 为依赖版本保留可快速恢复的变更记录；按灰度策略验证生产环境，且不将凭据写入代码或日志。 From c447e90ced6ab272fda4c1b567969b1c79615179 Mon Sep 17 00:00:00 2001 From: Binary Wang Date: Mon, 20 Jul 2026 10:08:29 +0800 Subject: [PATCH 2/7] =?UTF-8?q?=E8=A1=A5=E5=85=85=20Codex=20SKILL=20?= =?UTF-8?q?=E5=AE=89=E8=A3=85=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/README.md b/README.md index d6a4088a1..3b81e4d49 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ ### 目录索引 - [快速开始（3分钟）](#快速开始3分钟) +- [Codex SKILL 安装](#codex-skill-安装) - [我该选哪个模块？](#我该选哪个模块) - [Maven 引用方式](#maven-引用方式) - [最小示例](#最小示例) @@ -45,6 +46,27 @@ 2. 引入 Maven 依赖并选择对应模块 3. 参考最小示例完成初始化并调用 API +### Codex SKILL 安装 + +仓库的 [`skills`](skills) 目录提供面向 WxJava 用户和贡献者的 Codex SKILL，包括模块选择、接入、排障、接口贡献和升级迁移。 + +克隆仓库后，将所需 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/" +``` + +重启或新建 Codex 会话后，即可按需使用，例如：`使用 $wxjava-integration-guide 为我的 Spring Boot 项目接入微信支付。` + ### 我该选哪个模块？ | 业务场景 | 模块 | artifactId | From b3d244fe69e3461628152ae45629d840ac97c6a6 Mon Sep 17 00:00:00 2001 From: Binary Wang Date: Mon, 20 Jul 2026 10:10:08 +0800 Subject: [PATCH 3/7] =?UTF-8?q?=E5=AE=8C=E5=96=84=E9=80=9A=E7=94=A8?= =?UTF-8?q?=E6=99=BA=E8=83=BD=E4=BD=93=20SKILL=20=E5=AE=89=E8=A3=85?= =?UTF-8?q?=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3b81e4d49..55d7660ea 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ ### 目录索引 - [快速开始（3分钟）](#快速开始3分钟) -- [Codex SKILL 安装](#codex-skill-安装) +- [AI 编程智能体 SKILL 安装](#ai-编程智能体-skill-安装) - [我该选哪个模块？](#我该选哪个模块) - [Maven 引用方式](#maven-引用方式) - [最小示例](#最小示例) @@ -46,11 +46,13 @@ 2. 引入 Maven 依赖并选择对应模块 3. 参考最小示例完成初始化并调用 API -### Codex SKILL 安装 +### AI 编程智能体 SKILL 安装 -仓库的 [`skills`](skills) 目录提供面向 WxJava 用户和贡献者的 Codex SKILL，包括模块选择、接入、排障、接口贡献和升级迁移。 +仓库的 [`skills`](skills) 目录提供面向 WxJava 用户和贡献者的通用 SKILL，包括模块选择、接入、排障、接口贡献和升级迁移。每个 SKILL 都以 `SKILL.md` 为入口，可用于支持该约定的 AI 编程智能体。 -克隆仓库后，将所需 SKILL 复制到 Codex 的个人 SKILL 目录： +克隆仓库后，将所需的 `skills/wxjava-*` 目录导入所使用智能体的 SKILL 目录或工作区配置目录。不同智能体的目录和启用方式可能不同，请以其官方文档为准。 + +以 Codex 为例，可复制到个人 SKILL 目录： ```shell git clone https://github.com/binarywang/WxJava.git @@ -65,7 +67,7 @@ mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills" cp -R skills/wxjava-* "${CODEX_HOME:-$HOME/.codex}/skills/" ``` -重启或新建 Codex 会话后，即可按需使用，例如：`使用 $wxjava-integration-guide 为我的 Spring Boot 项目接入微信支付。` +重启或新建智能体会话后，即可按需使用。例如：`使用 wxjava-integration-guide 为我的 Spring Boot 项目接入微信支付。` ### 我该选哪个模块？ From ef784bcef68d7269a157507899fe92087e0dfc1b Mon Sep 17 00:00:00 2001 From: Binary Wang Date: Mon, 20 Jul 2026 10:10:51 +0800 Subject: [PATCH 4/7] =?UTF-8?q?=E8=A1=A5=E5=85=85=E8=BF=9C=E7=A8=8B?= =?UTF-8?q?=E5=AE=89=E8=A3=85=20SKILL=20=E6=8C=87=E4=BB=A4=E7=A4=BA?= =?UTF-8?q?=E4=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 55d7660ea..86b203d57 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,19 @@ 仓库的 [`skills`](skills) 目录提供面向 WxJava 用户和贡献者的通用 SKILL，包括模块选择、接入、排障、接口贡献和升级迁移。每个 SKILL 都以 `SKILL.md` 为入口，可用于支持该约定的 AI 编程智能体。 -克隆仓库后，将所需的 `skills/wxjava-*` 目录导入所使用智能体的 SKILL 目录或工作区配置目录。不同智能体的目录和启用方式可能不同，请以其官方文档为准。 +支持远程安装 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 目录： From 4c79d249066f976b9f75dfb95d8bb94e7f34fc9a Mon Sep 17 00:00:00 2001 From: Binary Wang Date: Mon, 20 Jul 2026 10:15:59 +0800 Subject: [PATCH 5/7] =?UTF-8?q?=E7=BB=86=E5=8C=96=20WxJava=20=E6=8A=80?= =?UTF-8?q?=E8=83=BD=E5=AE=9E=E8=B7=B5=E6=8C=87=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/references/repository-research.md | 128 ++++++++++++++++++ skills/wxjava-api-contributor/SKILL.md | 11 +- .../references/contribution.md | 14 ++ skills/wxjava-integration-guide/SKILL.md | 9 +- .../references/integration.md | 17 +++ skills/wxjava-module-selector/SKILL.md | 11 +- .../references/modules.md | 15 ++ skills/wxjava-troubleshooter/SKILL.md | 11 +- .../references/diagnostics.md | 18 +++ skills/wxjava-upgrade-guide/SKILL.md | 9 +- .../references/migration.md | 29 ++++ 11 files changed, 249 insertions(+), 23 deletions(-) create mode 100644 skills/references/repository-research.md diff --git a/skills/references/repository-research.md b/skills/references/repository-research.md new file mode 100644 index 000000000..3a283f24e --- /dev/null +++ b/skills/references/repository-research.md @@ -0,0 +1,128 @@ +# WxJava 一手资料研究与 SKILL 增强建议 + +本文件为五个 WxJava SKILL 的维护者提供可复用的事实来源和细化方向。资料仅来自 +`binarywang/WxJava` 的仓库、GitHub Issue 与 GitHub Wiki；Wiki 中有历史内容，使用时应 +将其视为排障线索，代码、当前 README、当前 POM 和发布说明优先。 + +## 统一的事实来源与使用原则 + +- [README：模块表、JDK 8 下限、BOM 和 Demo 入口](https://github.com/binarywang/WxJava/blob/develop/README.md) + 是模块选择和依赖示例的首选入口。BOM 从 `4.8.3.B` 起提供，且 README 明确只在同时使用 + 多个 WxJava 模块时推荐它。 +- [CONTRIBUTING.md](https://github.com/binarywang/WxJava/blob/develop/CONTRIBUTING.md) 规定 PR + 的 fork、`develop` 目标分支及代码风格，是贡献型输出的最终依据。 +- [GitHub Wiki 首页](https://github.com/binarywang/WxJava/wiki/Home) 集中列出了 token、依赖冲突、 + 小程序解密和集群部署等常见问题；生成建议前必须与当前代码和 README 交叉核对。 +- 回答具体微信接口的支持范围时，先搜索当前源码和 [Issues](https://github.com/binarywang/WxJava/issues)， + 不要从历史 Wiki 推断“当前仍支持”或“当前仍缺失”。例如 [#4007](https://github.com/binarywang/WxJava/issues/4007) + 是仍打开的 MP OAuth2 能力缺失请求，而 [#4005](https://github.com/binarywang/WxJava/issues/4005) + 是已关闭的服务号二维码跳转接口请求；两者不应得到同样结论。 + +## 按 SKILL 的可落地增强 + +### `wxjava-module-selector` + +1. **把“产品边界”拆细。** 除 README 的 MP、MiniApp、Pay、CP、Open、Channel 映射外，明确追问： + 企业微信是自建应用还是第三方应用；开放平台是网站 OAuth 还是第三方平台代理；视频号是否已升级为 + 微信小店。后一个边界可链接 [视频号／微信小店 Wiki](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)。 +2. **把“SDK 是否已经覆盖”加入标准输出。** 先给主模块，再列“已在当前源码确认 / 需查 Issue / + 需用户自行调用底层接口”三种状态；[#4007](https://github.com/binarywang/WxJava/issues/4007)、 + [#4006](https://github.com/binarywang/WxJava/issues/4006)（MP OCR）展示了用户常把产品能力误认为 + SDK 已覆盖。 +3. **多账号不是附加项。** 有多个独立 appId、公众号或商户时，输出必须让用户确认隔离方式；Wiki 的 + [CP 多应用说明](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) + 明确提醒各应用共用 token、AES key 与 URL 有严重安全风险；[#3421](https://github.com/binarywang/WxJava/issues/3421) + 和 [#3556](https://github.com/binarywang/WxJava/issues/3556) 都是多实例需求的实际信号。 +4. **BOM 的推荐应带条件。** 同时使用多个 WxJava 模块时推荐 BOM；如同时依赖 Spring Boot 等上游 BOM， + 要在输出中附加 `mvn help:effective-pom` 和 `mvn dependency:tree` 检查。已关闭的 + [#4058](https://github.com/binarywang/WxJava/issues/4058) 记录过 BOM import 影响 Spring Data Redis + 版本和 scope 的实例，不能把“使用 BOM”输出成无条件操作。 +5. **允许真实的能力重叠。** 不能仅凭模块名称断言移动端 OAuth 能力归属：在 + [#3729](https://github.com/binarywang/WxJava/issues/3729) 中维护者明确 MP 和 Open 都实现了相关能力。 + 技能应按授权主体、微信官方 API 域和回调场景推荐，并在存在重叠时解释两个可选项。 + +### `wxjava-integration-guide` + +1. **接入输出按“依赖 → 配置 → 服务初始化 → 一条 API → 回调/验证”组织。** README 的 Maven 段和 + [Demo 入口](https://github.com/binarywang/WxJava/blob/develop/demo.md) 是依赖与示例的首选来源；不要用 + Wiki 的旧版本号直接生成 POM。 +2. **在单/多账号分流前先问四项：** 产品、框架、独立账号数、首个 API。没有这些信息时，不要臆造 + Starter 的前缀或配置键。反向代理、统一 token 服务等非默认部署，需要转到 + [代理与反向代理 Wiki](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) + 再从当前 Starter 源码核验属性。 +3. **支付最小示例必须有异步回调的验签和业务幂等。** + [支付 Wiki](https://github.com/binarywang/WxJava/wiki/%E5%BE%AE%E4%BF%A1%E6%94%AF%E4%BB%98) 指出回调应 + 校验签名、订单业务需避免重复处理；当前仓库的 + [新版商户转账用法](https://github.com/binarywang/WxJava/blob/develop/docs/NEW_TRANSFER_API_USAGE.md) + 还要求处理授权相关错误、转账状态和回调验签。技能应在产出中显式区分“示例可运行”和“生产安全”。 +4. **集群部署默认提示共享存储。** [MP 配置存储 Wiki](https://github.com/binarywang/WxJava/wiki/MP_WxMpConfigStorage) + 和 [CP 配置存储 Wiki](https://github.com/binarywang/WxJava/wiki/CP_WxCpConfigStorage) 都说明生产集群应提供 + 可共享 access token 的存储实现；这比让每个节点各自刷新 token 更可靠。 +5. **加入部署环境分支。** 对 Quarkus/GraalVM，转到仓库的 + [Quarkus 支持文档](https://github.com/binarywang/WxJava/blob/develop/docs/QUARKUS_SUPPORT.md)，确认 + 4.7.8.B+、Native Image 构建与反射限制，而非套用 Spring Boot 配置。 +6. **Starter 与 demo 配置必须分开。** [#2177](https://github.com/binarywang/WxJava/issues/2177) 是将 demo + 配置与 Starter 属性模型混用而产生空 key/NPE 的历史案例。技能要先判定自动装配还是手动初始化，随后 + 读取当前 Starter 的 `*Properties` 类核验属性；注入为空时先检查 profile、配置前缀和启动模块。 + +### `wxjava-troubleshooter` + +将诊断树固定为“版本与模块 → 最小堆栈/响应 → 配置与多账号选择 → 认证材料 → 依赖树 → +网络/回调”。每次输出要提出一个检查动作和预期结果，而不是笼统建议重试。 + +| 症状／证据 | 先做的检查 | 一手来源与应写入 SKILL 的规则 | +| --- | --- | --- | +| token 失效、集群间不一致 | 确认 config storage 类型、节点是否共享、是否不必要地强制刷新 | [MP 刷新 token](https://github.com/binarywang/WxJava/wiki/MP_%E5%88%B7%E6%96%B0access_token) 与 [CP 刷新 token](https://github.com/binarywang/WxJava/wiki/CP_%E5%88%B7%E6%96%B0access_token) 说明常规调用自动刷新；[#3354](https://github.com/binarywang/WxJava/issues/3354)、[#3742](https://github.com/binarywang/WxJava/issues/3742) 是并发/刷新类报告。禁止将 token、secret 贴入日志。 | +| 签名错误、支付回调验签失败 | 保存脱敏后的响应码、请求路径、timestamp/nonce 是否存在、证书/公钥来源；先验签，后执行业务 | [新版转账文档](https://github.com/binarywang/WxJava/blob/develop/docs/NEW_TRANSFER_API_USAGE.md) 的回调示例；[#3399](https://github.com/binarywang/WxJava/issues/3399)、[#3610](https://github.com/binarywang/WxJava/issues/3610)、[#3915](https://github.com/binarywang/WxJava/issues/3915) 表明头部、证书和字段规范是高频根因。绝不建议关闭验签或 TLS 校验。 | +| `NoClassDefFoundError` / `NoSuchMethodError` / 启动失败 | 执行 `mvn dependency:tree`，检查冲突库、BOM import 顺序和打包产物 | [Wiki 依赖异常页](https://github.com/binarywang/WxJava/wiki/NoClassDefFoundError%E3%80%81NoSuchMethodError%E6%88%96ClassNotFoundException%E7%AD%89%E5%BC%82%E5%B8%B8%E7%9A%84%E8%A7%A3%E5%86%B3%E5%8A%9E%E6%B3%95)；[#4058](https://github.com/binarywang/WxJava/issues/4058) 是 Spring Boot BOM 影响的具体复现。输出中必须区分 IDE classpath 与部署包。 | +| Boot 3 或依赖库升级后注入失败 | 记录 JDK、Boot、WxJava 组合；先升级到适配的当前 WxJava 发行版，并用 dependency tree 核对 Jedis/OkHttp 等 | [#3150](https://github.com/binarywang/WxJava/issues/3150)（历史 Boot 3 兼容性）与 [#3129](https://github.com/binarywang/WxJava/issues/3129)（Jedis 冲突）说明必须检查实际组合；[#2987](https://github.com/binarywang/WxJava/issues/2987) 是 OkHttp 版本不匹配导致 `NoSuchFieldError` 的案例。不要靠猜单一库版本修复。 | +| 升级到 4.8 后 HTTP 客户端异常 | 先确认 HTTP client 版本、代理 host/port/username/password 是否完整，再看当前升级指南 | [HttpClient 升级指南](https://github.com/binarywang/WxJava/blob/develop/docs/HTTPCLIENT_UPGRADE_GUIDE.md) 与 [#3836](https://github.com/binarywang/WxJava/issues/3836)；技能应特别要求检查可选代理密码的空值，而非让用户修改无关业务代码。 | +| CP 会话存档偶发 SIGSEGV/JVM 崩溃 | 立即检查是否还在调用旧 API 或手动 `Finance.DestroySdk()`；升级后改用框架管理生命周期的新 API | [会话存档生命周期重构](https://github.com/binarywang/WxJava/blob/develop/docs/CP_MSG_AUDIT_THREADLOCAL_LIFECYCLE_REFACTOR.md) 和 [安全使用迁移文档](https://github.com/binarywang/WxJava/blob/develop/docs/CP_MSG_AUDIT_SDK_SAFE_USAGE.md)；[#3670](https://github.com/binarywang/WxJava/issues/3670) 提供了旧 API + 手动销毁导致 native 崩溃的完整实例。此类问题不要建议“多重试”。 | +| 小程序用户数据解密 JSON 异常 | 核验 session key、encryptedData/iv、Base64 和微信端签名条件，保留脱敏异常 | [Wiki 首页](https://github.com/binarywang/WxJava/wiki/Home) 指向 [#359](https://github.com/binarywang/WxJava/issues/359)；技能应把它归入输入/签名契约，而非泛化为 Gson 故障。 | + +### `wxjava-api-contributor` + +1. **把“缺接口”和“实现错误”分开走。** 新接口先检索当前 Service、实现、Bean 和未关闭 Issue；已有 + [CP/MP 调用未支持接口 Wiki](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) + 可作为临时绕过线索（实际实现时需按目标模块选择对应 API），但不能替代 SDK 的正式扩展。 +2. **新增接口的 checklist 具体到仓库结构：** 官方契约 → 目标 `*Service` 方法 → `*ServiceImpl` + 的 URL/HTTP 执行 → 请求与响应 Bean 的 JSON/XML 映射 → Javadoc → TestNG 成功、错误和字段回归测试 + → 相邻 Starter/多账号/HTTP 实现是否受影响。这对应仓库 AGENTS 指南和 + [CONTRIBUTING.md](https://github.com/binarywang/WxJava/blob/develop/CONTRIBUTING.md) 的当前流程。 +3. **用近期 Issue 强制字段审查。** [#3999](https://github.com/binarywang/WxJava/issues/3999)、 + [#4000](https://github.com/binarywang/WxJava/issues/4000)、[#3917](https://github.com/binarywang/WxJava/issues/3917)、 + [#3941](https://github.com/binarywang/WxJava/issues/3941) 都是支付 Bean 漏字段或映射缺失。技能应该要求对 + 官方请求/响应字段逐项对照，尤其是 optional 字段、嵌套金额字段和 callback `change_type`。 +4. **提交前给出精确命令。** 默认 `mvn -pl -am test`；公共模块/BOM/多模块改动扩展范围，并总是 + 跑 `git diff --check`。要明确 PR 面向 `develop`，不混入格式化或依赖升级。 +5. **Issue 模板要足以落地实现。** 参考 [#3327](https://github.com/binarywang/WxJava/issues/3327) 和 + [#4008](https://github.com/binarywang/WxJava/issues/4008)，要求提供官方文档 URL、API 域/Base URL、认证 + 方式、请求/响应样例、与既有模块的边界和遗漏接口清单。新 API 不能仅因名称相近就塞进既有模块。 + 若是紧急生产需求，参考 [#3163](https://github.com/binarywang/WxJava/issues/3163)：使用已验证 commit + 或组织内构建物，同时仍以单主题、可合并的 PR 回馈上游。 + +### `wxjava-upgrade-guide` + +1. **升级前的基线收集必须可执行：** `mvn dependency:tree`、现用 WxJava artifact 与版本、JDK、 + Spring Boot/Solon 版本、是否 import BOM、代理配置、关键 API（尤其 token、回调、支付、会话存档）。 +2. **按升级类型分支，而不是只改版本号。** + - HTTP client 迁移：按 [HTTPCLIENT_UPGRADE_GUIDE.md](https://github.com/binarywang/WxJava/blob/develop/docs/HTTPCLIENT_UPGRADE_GUIDE.md) + 执行依赖、配置、应用测试；[#3836](https://github.com/binarywang/WxJava/issues/3836) 说明代理配置的空值路径也要回归。 + - CP 会话存档：4.8.0 后按 [ThreadLocal 生命周期迁移](https://github.com/binarywang/WxJava/blob/develop/docs/CP_MSG_AUDIT_THREADLOCAL_LIFECYCLE_REFACTOR.md) + 逐一替换旧 API，删除手动 SDK 生命周期管理，并进行并发/压力验证。 + - BOM 导入：根据 README 的 `4.8.3.B+` 前提，先验证 effective POM 和 dependency tree；[#4058](https://github.com/binarywang/WxJava/issues/4058) + 的已关闭报告意味着要在 Spring Boot 项目中专门回归 Redis 等受 Spring BOM 管理的依赖。 +3. **升级验证应分三层：** 编译与单测 → 非生产凭据下的 API 冒烟（token、回调验签、支付） → 灰度与可观测性。 + 支付与转账不能仅凭 HTTP 2xx 宣称成功；[#4050](https://github.com/binarywang/WxJava/issues/4050) 的 202 + 响应问题说明要核对该 API 的官方成功语义及业务后续状态。 +4. **回滚条件必须明确：** 保留上一个可用依赖锁定/构建物；若出现签名、证书、回调、依赖树或 native + 崩溃异常，停止扩大灰度，先以最小复现定位。不要把关闭校验、固定 token 或跳过验签当作回滚方案。 +5. **多账号回调是独立回归项。** [#2995](https://github.com/binarywang/WxJava/issues/2995) 的历史回归显示： + 回调处理应先由请求/消息确定 appId，显式切换服务上下文后再路由；异步任务也要显式传递 appId，不能 + 假定 ThreadLocal 自动继承。升级后需至少覆盖单账号和多账号的真实回调路径。 + +## 维护方式 + +每次细化某个 SKILL 时，优先把本文件列出的通用原则转成该 SKILL 的简短决策步骤，并把专题细节放入其 +自己的 `references/` 文件。新增事实必须附上当前仓库、Wiki 或 GitHub Issue 的精确 URL；若 Issue 已关闭， +只把它作为问题模式或历史复现，不作为当前行为的证明。 diff --git a/skills/wxjava-api-contributor/SKILL.md b/skills/wxjava-api-contributor/SKILL.md index 258a7e066..b6896f105 100644 --- a/skills/wxjava-api-contributor/SKILL.md +++ b/skills/wxjava-api-contributor/SKILL.md @@ -5,9 +5,10 @@ description: 按 WxJava 的 Maven 多模块、Java 8、公共 API 兼容性和 T # WxJava 接口贡献 -1. 确认微信产品和目标模块，阅读对应 README、POM、相似接口、实现与测试。 -2. 读取 [贡献约定](references/contribution.md)，将官方接口契约映射到 Service、实现、Bean、URL、序列化和测试。 -3. 只做完成需求所需的最小改动；更新必要 Javadoc、测试与用户可见文档。 -4. 执行 `mvn -pl -am test`，并检查 `git diff --check`。 +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 插件时，检查等价实现是否需要同步。 +保持 Java 8 与公共 API、异常语义、JSON/XML 字段兼容性。涉及多 HTTP 客户端、单/多账号 Starter 或 Solon 插件时，检查等价实现是否需要同步。PR 应关联对应 Issue，目标分支为 `develop`。 diff --git a/skills/wxjava-api-contributor/references/contribution.md b/skills/wxjava-api-contributor/references/contribution.md index e3c7cbea0..c5c5d3b3d 100644 --- a/skills/wxjava-api-contributor/references/contribution.md +++ b/skills/wxjava-api-contributor/references/contribution.md @@ -3,3 +3,17 @@ 以微信官方接口定义和本仓库同类实现为准，核对路径、方法、字段名、必填项和响应结构。优先复用既有 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. 按 [贡献指南](../../../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 index 9505d8957..393438768 100644 --- a/skills/wxjava-integration-guide/SKILL.md +++ b/skills/wxjava-integration-guide/SKILL.md @@ -5,9 +5,10 @@ description: 为 Java、Spring Boot 或 Solon 项目生成可验证的 WxJava # WxJava 接入指南 -1. 确认微信产品、框架、单/多账号和首个 API 调用。 +1. 确认微信产品、框架、单/多账号、部署形态和首个 API 调用。 2. 读取 [接入约束](references/integration.md)，选择模块和配置方式。 -3. 输出可复制的依赖、脱敏配置和最小服务端代码；凭据一律用占位符。 -4. 给出本地验证步骤与安全提醒；支付、回调和证书示例不得直接用于生产。 +3. 先输出依赖与配置，再输出最小调用；每段示例注明应放置的位置和所依赖的模块。 +4. 输出脱敏配置和最小服务端代码；凭据一律用占位符。 +5. 给出本地验证步骤与安全提醒；支付、回调和证书示例不得直接用于生产。 -保持 Java 8 兼容。引用已有 Demo 或 README 作为继续阅读入口；不虚构配置键、SDK 方法或版本号。 +保持 Java 8 兼容。生产集群必须使用可共享的配置存储或 token 存储；不要把内存实现当作多节点部署方案。引用已有 Demo、Wiki 或 README 作为继续阅读入口；不虚构配置键、SDK 方法或版本号。 diff --git a/skills/wxjava-integration-guide/references/integration.md b/skills/wxjava-integration-guide/references/integration.md index d079d2e9d..8b841538e 100644 --- a/skills/wxjava-integration-guide/references/integration.md +++ b/skills/wxjava-integration-guide/references/integration.md @@ -3,3 +3,20 @@ 优先通过 `wx-java-bom` 统一管理多个 WxJava 模块版本。核心 SDK 模块是 MP、MiniApp、Pay、CP、Open、Channel；框架集成模块位于 `spring-boot-starters` 与 `solon-plugins`。 查阅相应模块 README 和 `demo/` 的相邻示例，确认配置属性与初始化模式。所有 `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 支持文档](../../../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 客户端升级指南](../../../docs/HTTPCLIENT_UPGRADE_GUIDE.md) diff --git a/skills/wxjava-module-selector/SKILL.md b/skills/wxjava-module-selector/SKILL.md index 577c05630..3ab354236 100644 --- a/skills/wxjava-module-selector/SKILL.md +++ b/skills/wxjava-module-selector/SKILL.md @@ -5,10 +5,11 @@ description: 根据微信公众号、小程序、微信支付、企业微信、 # WxJava 模块选择 -1. 识别微信产品、服务端框架和是否需要多账号；信息不足时只询问必要问题。 +1. 识别微信产品、服务端框架、是否多账号、是否包含支付或回调；信息不足时只询问必要问题。 2. 读取 [模块映射](references/modules.md)，给出一个主推荐，以及组合模块的理由。 -3. 优先推荐 BOM；给出准确的 `groupId`、`artifactId` 和相应 Demo 或 README。 -4. 说明服务端 SDK 的边界：移动端登录、分享等能力仍需微信官方客户端 SDK。 -5. 不臆测版本号；建议以 Maven Central 或项目 README 的当前版本为准。 +3. 先区分产品边界，再选择核心 SDK；仅当项目确实依赖框架自动配置时才额外推荐 Starter 或 Solon 插件。 +4. 优先推荐 BOM；给出准确的 `groupId`、`artifactId`、相应 Demo、Wiki 或仓库文档入口。 +5. 说明服务端 SDK 的边界：移动端登录、分享等能力仍需微信官方客户端 SDK。 +6. 不臆测版本号；建议以 Maven Central 或项目 README 的当前版本为准。 -使用“场景 → 模块 → 依赖 → 下一步”的简短结构。涉及多账号时说明单账号与 multi Starter 的区别；不要在示例中泄露凭据。 +使用“场景 → 模块 → 集成选项 → 下一步”的简短结构。涉及多账号时说明单账号与 multi Starter 的区别；不要在示例中泄露凭据。支付和回调场景必须提醒用户验证通知 URL、验签与幂等处理。 diff --git a/skills/wxjava-module-selector/references/modules.md b/skills/wxjava-module-selector/references/modules.md index cb8bf5bc6..7f3ea55c1 100644 --- a/skills/wxjava-module-selector/references/modules.md +++ b/skills/wxjava-module-selector/references/modules.md @@ -10,3 +10,18 @@ | 视频号／微信小店 | `weixin-java-channel` | 多个模块并用时优先使用 `com.github.binarywang:wx-java-bom`。Spring Boot 集成从 `spring-boot-starters` 选择；Solon 集成从 `solon-plugins` 选择。只有多个独立微信应用配置时才选择名称含 `multi` 的 Starter 或插件。 + +## 选择检查点 + +- 公众号、小程序和企业微信的消息回调、token 与加解密配置彼此独立；不要因同属一个公司而复用不兼容的凭据或配置对象。 +- 企业微信的多应用应使用独立的 `WxCpConfigStorage` 与 `WxCpServiceImpl`；Wiki 明确指出复用 token、AES key 和 URL 会造成安全边界问题。 +- 支付能力通常与 MP、MiniApp 或 Open 同时使用：前者处理业务身份和消息，`weixin-java-pay` 处理商户签名、证书与支付回调。 +- 视频号／微信小店接口属于 `weixin-java-channel`；不要误归入 MP 或 Pay。 +- 当能力在 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 index 4147235ce..26d8c941e 100644 --- a/skills/wxjava-troubleshooter/SKILL.md +++ b/skills/wxjava-troubleshooter/SKILL.md @@ -5,9 +5,10 @@ description: 排查 WxJava 在配置初始化、access token、签名验签、 # WxJava 故障排查 -1. 收集最小复现：产品模块、SDK 版本、JDK、框架、异常堆栈及脱敏后的配置形状。 -2. 依据 [诊断清单](references/diagnostics.md)，按配置、请求契约、认证材料、网络与回调顺序验证。 -3. 每次只提出一个可验证根因，给出最小修复和验证动作。 -4. 签名、支付、回调和加密场景须核对编码、字段排序、金额精度、时间戳、证书链和重放保护。 +1. 收集最小复现：产品模块、SDK 版本、JDK、框架、依赖树、异常堆栈、请求 ID 与脱敏后的配置形状。 +2. 将故障归类为依赖/初始化、token 与存储、请求契约、HTTP/代理、回调验签、支付证书或并发与生命周期。 +3. 依据 [诊断清单](references/diagnostics.md)，按最低成本、最可验证的顺序排查。 +4. 每次只提出一个可验证根因，给出最小修复、预期现象和回归验证动作。 +5. 签名、支付、回调和加密场景须核对编码、字段排序、金额精度、时间戳、证书链和重放保护。 -要求遮蔽 secret、token、私钥、证书、签名原文和个人数据。不要建议关闭 TLS 校验或验签；区分已证实结论与待验证假设。 +要求遮蔽 secret、token、私钥、证书、签名原文和个人数据。不要建议关闭 TLS 校验或验签；区分已证实结论与待验证假设。遇到历史同类问题时，给出对应 Issue 或 Wiki 链接，但必须检查当前版本的实现后再套用修复。 diff --git a/skills/wxjava-troubleshooter/references/diagnostics.md b/skills/wxjava-troubleshooter/references/diagnostics.md index d274919e7..e88411d99 100644 --- a/skills/wxjava-troubleshooter/references/diagnostics.md +++ b/skills/wxjava-troubleshooter/references/diagnostics.md @@ -7,3 +7,21 @@ - 回调：回调 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 | [会话存档安全使用指南](../../../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 index f27790ff8..624a75233 100644 --- a/skills/wxjava-upgrade-guide/SKILL.md +++ b/skills/wxjava-upgrade-guide/SKILL.md @@ -5,9 +5,10 @@ description: 规划 WxJava 的版本升级与迁移，检查 BOM、模块依赖 # WxJava 升级迁移 -1. 收集当前与目标版本、已用模块、JDK、框架、BOM 使用情况和关键调用路径。 +1. 收集当前与目标版本、已用模块、JDK、框架、BOM 使用情况、依赖树、代理配置和关键调用路径。 2. 读取 [迁移检查表](references/migration.md)，识别版本、依赖和配置边界。 -3. 输出分阶段变更：依赖调整、编译、关键回归测试、灰度与回滚条件。 -4. 将不确定项标为待查，并引导查看目标版本的 release notes、README、Javadoc 与变更记录。 +3. 按 HTTP 客户端、BOM、支付/回调、多账号、企业微信会话存档等变化类型选择迁移分支。 +4. 输出分阶段变更：依赖调整、编译、关键回归测试、灰度与明确回滚条件。 +5. 将不确定项标为待查，并引导查看目标版本的 release notes、README、Javadoc 与变更记录。 -不要猜测废弃 API 或破坏性变更；以官方发布信息和实际编译结果为准。默认保持 Java 8，除非目标版本明确改变此约束。 +不要猜测废弃 API 或破坏性变更；以官方发布信息、当前代码与实际编译结果为准。默认保持 Java 8，除非目标版本明确改变此约束。不能以关闭验签、固定 token 或跳过测试作为回滚方案。 diff --git a/skills/wxjava-upgrade-guide/references/migration.md b/skills/wxjava-upgrade-guide/references/migration.md index 4ce4a8fd5..947dfb2c6 100644 --- a/skills/wxjava-upgrade-guide/references/migration.md +++ b/skills/wxjava-upgrade-guide/references/migration.md @@ -4,3 +4,32 @@ - 清点 MP、MiniApp、Pay、CP、Open、Channel 及框架 Starter/插件的实际依赖。 - 更新后先执行编译和受影响模块测试，再验证 token、回调、支付和关键业务链路。 - 为依赖版本保留可快速恢复的变更记录；按灰度策略验证生产环境，且不将凭据写入代码或日志。 + +## 升级分支 + +### HTTP 客户端 + +从 4.7.x 起，项目支持并推荐 Apache HttpClient 5.x，同时保留部分 4.x 兼容性。先按 [HTTP 客户端升级指南](../../../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 生命周期迁移文档](../../../docs/CP_MSG_AUDIT_THREADLOCAL_LIFECYCLE_REFACTOR.md) 切换至框架管理生命周期的新 API，并做并发验证。 + +### 回调与支付 + +验证不止于 HTTP 2xx：分别覆盖 token 获取、签名/证书校验、重复回调、业务状态转换和多账号路由。多账号异步任务必须显式传递 appId 或服务上下文，不能假定 ThreadLocal 自动继承。 + +## 验证与回滚 + +按“编译和单测 → 非生产凭据冒烟 → 灰度和监控”执行。出现依赖树冲突、验签/证书异常、回调错误或 native 崩溃时停止扩大灰度，恢复上一个已验证依赖组合后再以最小复现定位。 From 25e96b7cc0e6403110e690fe10b065ea1d8336b7 Mon Sep 17 00:00:00 2001 From: Binary Wang Date: Mon, 20 Jul 2026 10:19:49 +0800 Subject: [PATCH 6/7] =?UTF-8?q?=E7=A7=BB=E9=99=A4=E6=8A=80=E8=83=BD?= =?UTF-8?q?=E7=A0=94=E7=A9=B6=E5=BA=95=E7=A8=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/references/repository-research.md | 128 ----------------------- 1 file changed, 128 deletions(-) delete mode 100644 skills/references/repository-research.md diff --git a/skills/references/repository-research.md b/skills/references/repository-research.md deleted file mode 100644 index 3a283f24e..000000000 --- a/skills/references/repository-research.md +++ /dev/null @@ -1,128 +0,0 @@ -# WxJava 一手资料研究与 SKILL 增强建议 - -本文件为五个 WxJava SKILL 的维护者提供可复用的事实来源和细化方向。资料仅来自 -`binarywang/WxJava` 的仓库、GitHub Issue 与 GitHub Wiki；Wiki 中有历史内容，使用时应 -将其视为排障线索，代码、当前 README、当前 POM 和发布说明优先。 - -## 统一的事实来源与使用原则 - -- [README：模块表、JDK 8 下限、BOM 和 Demo 入口](https://github.com/binarywang/WxJava/blob/develop/README.md) - 是模块选择和依赖示例的首选入口。BOM 从 `4.8.3.B` 起提供，且 README 明确只在同时使用 - 多个 WxJava 模块时推荐它。 -- [CONTRIBUTING.md](https://github.com/binarywang/WxJava/blob/develop/CONTRIBUTING.md) 规定 PR - 的 fork、`develop` 目标分支及代码风格，是贡献型输出的最终依据。 -- [GitHub Wiki 首页](https://github.com/binarywang/WxJava/wiki/Home) 集中列出了 token、依赖冲突、 - 小程序解密和集群部署等常见问题；生成建议前必须与当前代码和 README 交叉核对。 -- 回答具体微信接口的支持范围时，先搜索当前源码和 [Issues](https://github.com/binarywang/WxJava/issues)， - 不要从历史 Wiki 推断“当前仍支持”或“当前仍缺失”。例如 [#4007](https://github.com/binarywang/WxJava/issues/4007) - 是仍打开的 MP OAuth2 能力缺失请求，而 [#4005](https://github.com/binarywang/WxJava/issues/4005) - 是已关闭的服务号二维码跳转接口请求；两者不应得到同样结论。 - -## 按 SKILL 的可落地增强 - -### `wxjava-module-selector` - -1. **把“产品边界”拆细。** 除 README 的 MP、MiniApp、Pay、CP、Open、Channel 映射外，明确追问： - 企业微信是自建应用还是第三方应用；开放平台是网站 OAuth 还是第三方平台代理；视频号是否已升级为 - 微信小店。后一个边界可链接 [视频号／微信小店 Wiki](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)。 -2. **把“SDK 是否已经覆盖”加入标准输出。** 先给主模块，再列“已在当前源码确认 / 需查 Issue / - 需用户自行调用底层接口”三种状态；[#4007](https://github.com/binarywang/WxJava/issues/4007)、 - [#4006](https://github.com/binarywang/WxJava/issues/4006)（MP OCR）展示了用户常把产品能力误认为 - SDK 已覆盖。 -3. **多账号不是附加项。** 有多个独立 appId、公众号或商户时，输出必须让用户确认隔离方式；Wiki 的 - [CP 多应用说明](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) - 明确提醒各应用共用 token、AES key 与 URL 有严重安全风险；[#3421](https://github.com/binarywang/WxJava/issues/3421) - 和 [#3556](https://github.com/binarywang/WxJava/issues/3556) 都是多实例需求的实际信号。 -4. **BOM 的推荐应带条件。** 同时使用多个 WxJava 模块时推荐 BOM；如同时依赖 Spring Boot 等上游 BOM， - 要在输出中附加 `mvn help:effective-pom` 和 `mvn dependency:tree` 检查。已关闭的 - [#4058](https://github.com/binarywang/WxJava/issues/4058) 记录过 BOM import 影响 Spring Data Redis - 版本和 scope 的实例，不能把“使用 BOM”输出成无条件操作。 -5. **允许真实的能力重叠。** 不能仅凭模块名称断言移动端 OAuth 能力归属：在 - [#3729](https://github.com/binarywang/WxJava/issues/3729) 中维护者明确 MP 和 Open 都实现了相关能力。 - 技能应按授权主体、微信官方 API 域和回调场景推荐，并在存在重叠时解释两个可选项。 - -### `wxjava-integration-guide` - -1. **接入输出按“依赖 → 配置 → 服务初始化 → 一条 API → 回调/验证”组织。** README 的 Maven 段和 - [Demo 入口](https://github.com/binarywang/WxJava/blob/develop/demo.md) 是依赖与示例的首选来源；不要用 - Wiki 的旧版本号直接生成 POM。 -2. **在单/多账号分流前先问四项：** 产品、框架、独立账号数、首个 API。没有这些信息时，不要臆造 - Starter 的前缀或配置键。反向代理、统一 token 服务等非默认部署，需要转到 - [代理与反向代理 Wiki](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) - 再从当前 Starter 源码核验属性。 -3. **支付最小示例必须有异步回调的验签和业务幂等。** - [支付 Wiki](https://github.com/binarywang/WxJava/wiki/%E5%BE%AE%E4%BF%A1%E6%94%AF%E4%BB%98) 指出回调应 - 校验签名、订单业务需避免重复处理；当前仓库的 - [新版商户转账用法](https://github.com/binarywang/WxJava/blob/develop/docs/NEW_TRANSFER_API_USAGE.md) - 还要求处理授权相关错误、转账状态和回调验签。技能应在产出中显式区分“示例可运行”和“生产安全”。 -4. **集群部署默认提示共享存储。** [MP 配置存储 Wiki](https://github.com/binarywang/WxJava/wiki/MP_WxMpConfigStorage) - 和 [CP 配置存储 Wiki](https://github.com/binarywang/WxJava/wiki/CP_WxCpConfigStorage) 都说明生产集群应提供 - 可共享 access token 的存储实现；这比让每个节点各自刷新 token 更可靠。 -5. **加入部署环境分支。** 对 Quarkus/GraalVM，转到仓库的 - [Quarkus 支持文档](https://github.com/binarywang/WxJava/blob/develop/docs/QUARKUS_SUPPORT.md)，确认 - 4.7.8.B+、Native Image 构建与反射限制，而非套用 Spring Boot 配置。 -6. **Starter 与 demo 配置必须分开。** [#2177](https://github.com/binarywang/WxJava/issues/2177) 是将 demo - 配置与 Starter 属性模型混用而产生空 key/NPE 的历史案例。技能要先判定自动装配还是手动初始化，随后 - 读取当前 Starter 的 `*Properties` 类核验属性；注入为空时先检查 profile、配置前缀和启动模块。 - -### `wxjava-troubleshooter` - -将诊断树固定为“版本与模块 → 最小堆栈/响应 → 配置与多账号选择 → 认证材料 → 依赖树 → -网络/回调”。每次输出要提出一个检查动作和预期结果，而不是笼统建议重试。 - -| 症状／证据 | 先做的检查 | 一手来源与应写入 SKILL 的规则 | -| --- | --- | --- | -| token 失效、集群间不一致 | 确认 config storage 类型、节点是否共享、是否不必要地强制刷新 | [MP 刷新 token](https://github.com/binarywang/WxJava/wiki/MP_%E5%88%B7%E6%96%B0access_token) 与 [CP 刷新 token](https://github.com/binarywang/WxJava/wiki/CP_%E5%88%B7%E6%96%B0access_token) 说明常规调用自动刷新；[#3354](https://github.com/binarywang/WxJava/issues/3354)、[#3742](https://github.com/binarywang/WxJava/issues/3742) 是并发/刷新类报告。禁止将 token、secret 贴入日志。 | -| 签名错误、支付回调验签失败 | 保存脱敏后的响应码、请求路径、timestamp/nonce 是否存在、证书/公钥来源；先验签，后执行业务 | [新版转账文档](https://github.com/binarywang/WxJava/blob/develop/docs/NEW_TRANSFER_API_USAGE.md) 的回调示例；[#3399](https://github.com/binarywang/WxJava/issues/3399)、[#3610](https://github.com/binarywang/WxJava/issues/3610)、[#3915](https://github.com/binarywang/WxJava/issues/3915) 表明头部、证书和字段规范是高频根因。绝不建议关闭验签或 TLS 校验。 | -| `NoClassDefFoundError` / `NoSuchMethodError` / 启动失败 | 执行 `mvn dependency:tree`，检查冲突库、BOM import 顺序和打包产物 | [Wiki 依赖异常页](https://github.com/binarywang/WxJava/wiki/NoClassDefFoundError%E3%80%81NoSuchMethodError%E6%88%96ClassNotFoundException%E7%AD%89%E5%BC%82%E5%B8%B8%E7%9A%84%E8%A7%A3%E5%86%B3%E5%8A%9E%E6%B3%95)；[#4058](https://github.com/binarywang/WxJava/issues/4058) 是 Spring Boot BOM 影响的具体复现。输出中必须区分 IDE classpath 与部署包。 | -| Boot 3 或依赖库升级后注入失败 | 记录 JDK、Boot、WxJava 组合；先升级到适配的当前 WxJava 发行版，并用 dependency tree 核对 Jedis/OkHttp 等 | [#3150](https://github.com/binarywang/WxJava/issues/3150)（历史 Boot 3 兼容性）与 [#3129](https://github.com/binarywang/WxJava/issues/3129)（Jedis 冲突）说明必须检查实际组合；[#2987](https://github.com/binarywang/WxJava/issues/2987) 是 OkHttp 版本不匹配导致 `NoSuchFieldError` 的案例。不要靠猜单一库版本修复。 | -| 升级到 4.8 后 HTTP 客户端异常 | 先确认 HTTP client 版本、代理 host/port/username/password 是否完整，再看当前升级指南 | [HttpClient 升级指南](https://github.com/binarywang/WxJava/blob/develop/docs/HTTPCLIENT_UPGRADE_GUIDE.md) 与 [#3836](https://github.com/binarywang/WxJava/issues/3836)；技能应特别要求检查可选代理密码的空值，而非让用户修改无关业务代码。 | -| CP 会话存档偶发 SIGSEGV/JVM 崩溃 | 立即检查是否还在调用旧 API 或手动 `Finance.DestroySdk()`；升级后改用框架管理生命周期的新 API | [会话存档生命周期重构](https://github.com/binarywang/WxJava/blob/develop/docs/CP_MSG_AUDIT_THREADLOCAL_LIFECYCLE_REFACTOR.md) 和 [安全使用迁移文档](https://github.com/binarywang/WxJava/blob/develop/docs/CP_MSG_AUDIT_SDK_SAFE_USAGE.md)；[#3670](https://github.com/binarywang/WxJava/issues/3670) 提供了旧 API + 手动销毁导致 native 崩溃的完整实例。此类问题不要建议“多重试”。 | -| 小程序用户数据解密 JSON 异常 | 核验 session key、encryptedData/iv、Base64 和微信端签名条件，保留脱敏异常 | [Wiki 首页](https://github.com/binarywang/WxJava/wiki/Home) 指向 [#359](https://github.com/binarywang/WxJava/issues/359)；技能应把它归入输入/签名契约，而非泛化为 Gson 故障。 | - -### `wxjava-api-contributor` - -1. **把“缺接口”和“实现错误”分开走。** 新接口先检索当前 Service、实现、Bean 和未关闭 Issue；已有 - [CP/MP 调用未支持接口 Wiki](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) - 可作为临时绕过线索（实际实现时需按目标模块选择对应 API），但不能替代 SDK 的正式扩展。 -2. **新增接口的 checklist 具体到仓库结构：** 官方契约 → 目标 `*Service` 方法 → `*ServiceImpl` - 的 URL/HTTP 执行 → 请求与响应 Bean 的 JSON/XML 映射 → Javadoc → TestNG 成功、错误和字段回归测试 - → 相邻 Starter/多账号/HTTP 实现是否受影响。这对应仓库 AGENTS 指南和 - [CONTRIBUTING.md](https://github.com/binarywang/WxJava/blob/develop/CONTRIBUTING.md) 的当前流程。 -3. **用近期 Issue 强制字段审查。** [#3999](https://github.com/binarywang/WxJava/issues/3999)、 - [#4000](https://github.com/binarywang/WxJava/issues/4000)、[#3917](https://github.com/binarywang/WxJava/issues/3917)、 - [#3941](https://github.com/binarywang/WxJava/issues/3941) 都是支付 Bean 漏字段或映射缺失。技能应该要求对 - 官方请求/响应字段逐项对照，尤其是 optional 字段、嵌套金额字段和 callback `change_type`。 -4. **提交前给出精确命令。** 默认 `mvn -pl -am test`；公共模块/BOM/多模块改动扩展范围，并总是 - 跑 `git diff --check`。要明确 PR 面向 `develop`，不混入格式化或依赖升级。 -5. **Issue 模板要足以落地实现。** 参考 [#3327](https://github.com/binarywang/WxJava/issues/3327) 和 - [#4008](https://github.com/binarywang/WxJava/issues/4008)，要求提供官方文档 URL、API 域/Base URL、认证 - 方式、请求/响应样例、与既有模块的边界和遗漏接口清单。新 API 不能仅因名称相近就塞进既有模块。 - 若是紧急生产需求，参考 [#3163](https://github.com/binarywang/WxJava/issues/3163)：使用已验证 commit - 或组织内构建物，同时仍以单主题、可合并的 PR 回馈上游。 - -### `wxjava-upgrade-guide` - -1. **升级前的基线收集必须可执行：** `mvn dependency:tree`、现用 WxJava artifact 与版本、JDK、 - Spring Boot/Solon 版本、是否 import BOM、代理配置、关键 API（尤其 token、回调、支付、会话存档）。 -2. **按升级类型分支，而不是只改版本号。** - - HTTP client 迁移：按 [HTTPCLIENT_UPGRADE_GUIDE.md](https://github.com/binarywang/WxJava/blob/develop/docs/HTTPCLIENT_UPGRADE_GUIDE.md) - 执行依赖、配置、应用测试；[#3836](https://github.com/binarywang/WxJava/issues/3836) 说明代理配置的空值路径也要回归。 - - CP 会话存档：4.8.0 后按 [ThreadLocal 生命周期迁移](https://github.com/binarywang/WxJava/blob/develop/docs/CP_MSG_AUDIT_THREADLOCAL_LIFECYCLE_REFACTOR.md) - 逐一替换旧 API，删除手动 SDK 生命周期管理，并进行并发/压力验证。 - - BOM 导入：根据 README 的 `4.8.3.B+` 前提，先验证 effective POM 和 dependency tree；[#4058](https://github.com/binarywang/WxJava/issues/4058) - 的已关闭报告意味着要在 Spring Boot 项目中专门回归 Redis 等受 Spring BOM 管理的依赖。 -3. **升级验证应分三层：** 编译与单测 → 非生产凭据下的 API 冒烟（token、回调验签、支付） → 灰度与可观测性。 - 支付与转账不能仅凭 HTTP 2xx 宣称成功；[#4050](https://github.com/binarywang/WxJava/issues/4050) 的 202 - 响应问题说明要核对该 API 的官方成功语义及业务后续状态。 -4. **回滚条件必须明确：** 保留上一个可用依赖锁定/构建物；若出现签名、证书、回调、依赖树或 native - 崩溃异常，停止扩大灰度，先以最小复现定位。不要把关闭校验、固定 token 或跳过验签当作回滚方案。 -5. **多账号回调是独立回归项。** [#2995](https://github.com/binarywang/WxJava/issues/2995) 的历史回归显示： - 回调处理应先由请求/消息确定 appId，显式切换服务上下文后再路由；异步任务也要显式传递 appId，不能 - 假定 ThreadLocal 自动继承。升级后需至少覆盖单账号和多账号的真实回调路径。 - -## 维护方式 - -每次细化某个 SKILL 时，优先把本文件列出的通用原则转成该 SKILL 的简短决策步骤，并把专题细节放入其 -自己的 `references/` 文件。新增事实必须附上当前仓库、Wiki 或 GitHub Issue 的精确 URL；若 Issue 已关闭， -只把它作为问题模式或历史复现，不作为当前行为的证明。 From a4b6276a3f951301b24e6f2497e557e788369f82 Mon Sep 17 00:00:00 2001 From: Binary Wang Date: Mon, 20 Jul 2026 10:42:11 +0800 Subject: [PATCH 7/7] =?UTF-8?q?=E5=AE=8C=E5=96=84=20WxJava=20=E6=8A=80?= =?UTF-8?q?=E8=83=BD=E5=AE=A1=E6=9F=A5=E5=BB=BA=E8=AE=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../references/contribution.md | 2 +- .../references/integration.md | 8 ++++---- skills/wxjava-module-selector/SKILL.md | 2 +- skills/wxjava-module-selector/references/modules.md | 12 +++++++++++- .../wxjava-troubleshooter/references/diagnostics.md | 2 +- skills/wxjava-upgrade-guide/references/migration.md | 6 ++++-- 6 files changed, 22 insertions(+), 10 deletions(-) diff --git a/skills/wxjava-api-contributor/references/contribution.md b/skills/wxjava-api-contributor/references/contribution.md index c5c5d3b3d..6b8571e28 100644 --- a/skills/wxjava-api-contributor/references/contribution.md +++ b/skills/wxjava-api-contributor/references/contribution.md @@ -10,7 +10,7 @@ 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. 按 [贡献指南](../../../CONTRIBUTING.md) 使用 `develop` 作为 PR 目标；说明 Issue、兼容性影响和验证命令。 +5. 按 [贡献指南](https://github.com/binarywang/WxJava/blob/develop/CONTRIBUTING.md) 使用 `develop` 作为 PR 目标；说明 Issue、兼容性影响和验证命令。 ## 一手资料入口 diff --git a/skills/wxjava-integration-guide/references/integration.md b/skills/wxjava-integration-guide/references/integration.md index 8b841538e..ae441cc27 100644 --- a/skills/wxjava-integration-guide/references/integration.md +++ b/skills/wxjava-integration-guide/references/integration.md @@ -1,8 +1,8 @@ # 接入约束 -优先通过 `wx-java-bom` 统一管理多个 WxJava 模块版本。核心 SDK 模块是 MP、MiniApp、Pay、CP、Open、Channel；框架集成模块位于 `spring-boot-starters` 与 `solon-plugins`。 +优先通过 `wx-java-bom` 统一管理多个 WxJava 模块版本。核心 SDK 模块是 MP、MiniApp、Pay、CP、Open、Channel、Qidian、Aispeech；框架集成模块位于 `spring-boot-starters` 与 `solon-plugins`。 -查阅相应模块 README 和 `demo/` 的相邻示例，确认配置属性与初始化模式。所有 `appId`、`secret`、商户私钥、API v3 密钥和证书均使用占位符，不得输出到日志。 +查阅相应模块 README、根目录 [demo.md](https://github.com/binarywang/WxJava/blob/develop/demo.md) 和目标模块测试中的示例，确认配置属性与初始化模式。所有 `appId`、`secret`、商户私钥、API v3 密钥和证书均使用占位符，不得输出到日志。 ## 实施检查表 @@ -12,11 +12,11 @@ 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 支持文档](../../../docs/QUARKUS_SUPPORT.md)，不要套用 Spring Boot Starter 配置。 +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 客户端升级指南](../../../docs/HTTPCLIENT_UPGRADE_GUIDE.md) +- [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 index 3ab354236..3d78c0ebf 100644 --- a/skills/wxjava-module-selector/SKILL.md +++ b/skills/wxjava-module-selector/SKILL.md @@ -1,6 +1,6 @@ --- name: wxjava-module-selector -description: 根据微信公众号、小程序、微信支付、企业微信、开放平台、视频号或微信小店等业务场景，为用户选择合适的 WxJava Maven 模块、BOM 和示例入口。适用于用户询问“该用哪个模块”、依赖坐标、产品边界或单/多账号 Starter 选择时。 +description: 根据微信公众号、小程序、微信支付、企业微信、开放平台、视频号或微信小店、腾讯企点和微信智能对话等业务场景，为用户选择合适的 WxJava Maven 模块、BOM 和示例入口。适用于用户询问“该用哪个模块”、依赖坐标、产品边界或单/多账号 Starter 选择时。 --- # WxJava 模块选择 diff --git a/skills/wxjava-module-selector/references/modules.md b/skills/wxjava-module-selector/references/modules.md index 7f3ea55c1..563cdbb95 100644 --- a/skills/wxjava-module-selector/references/modules.md +++ b/skills/wxjava-module-selector/references/modules.md @@ -8,8 +8,17 @@ | 企业微信 | `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` 的 Starter 或插件。 +多个模块并用时优先使用 `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。 ## 选择检查点 @@ -17,6 +26,7 @@ - 企业微信的多应用应使用独立的 `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 等依赖。 diff --git a/skills/wxjava-troubleshooter/references/diagnostics.md b/skills/wxjava-troubleshooter/references/diagnostics.md index e88411d99..acf115ae9 100644 --- a/skills/wxjava-troubleshooter/references/diagnostics.md +++ b/skills/wxjava-troubleshooter/references/diagnostics.md @@ -16,7 +16,7 @@ | `NoClassDefFoundError`、`NoSuchMethodError` | `mvn dependency:tree`、HttpClient/commons-lang/xstream 冲突及 BOM 是否统一版本 | Wiki 的异常排查页与 HTTP 客户端升级指南 | | 回调验签或重复处理 | 原始请求体、时间戳/nonce/签名、回调 URL、业务幂等键 | MP 合法性校验与支付回调说明 | | HTTP 连接、超时或代理问题 | 连接/读取超时、代理、TLS、正反向代理是否混用 | Wiki 的 HttpClient 参数与代理文档 | -| 企业微信会话存档崩溃 | 是否仍手动销毁旧 SDK 实例，是否已迁移安全 API | [会话存档安全使用指南](../../../docs/CP_MSG_AUDIT_SDK_SAFE_USAGE.md) | +| 企业微信会话存档崩溃 | 是否仍手动销毁旧 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) | ## 一手资料入口 diff --git a/skills/wxjava-upgrade-guide/references/migration.md b/skills/wxjava-upgrade-guide/references/migration.md index 947dfb2c6..443ac73a0 100644 --- a/skills/wxjava-upgrade-guide/references/migration.md +++ b/skills/wxjava-upgrade-guide/references/migration.md @@ -9,7 +9,7 @@ ### HTTP 客户端 -从 4.7.x 起，项目支持并推荐 Apache HttpClient 5.x，同时保留部分 4.x 兼容性。先按 [HTTP 客户端升级指南](../../../docs/HTTPCLIENT_UPGRADE_GUIDE.md) 核对模块、依赖与 `http-client-type`，再检查代理 host、port、username、password 的完整性。历史 [#3836](https://github.com/binarywang/WxJava/issues/3836) 表明可选代理配置也需要回归。 +从 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 与依赖冲突 @@ -24,7 +24,9 @@ mvn dependency:tree ### 企业微信会话存档 -升级到 4.8.0 或更高版本时，查找旧的 `getChatDatas`、`getDecryptData`、`getChatPlainText`、`getMediaFile` 和手动 `Finance.DestroySdk()`。按 [ThreadLocal 生命周期迁移文档](../../../docs/CP_MSG_AUDIT_THREADLOCAL_LIFECYCLE_REFACTOR.md) 切换至框架管理生命周期的新 API，并做并发验证。 +升级到 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()`。 ### 回调与支付