| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 5 | 11 | 6% |
| Commands | 0 | 7 | 9 | 0% |
| Section tags | 2 | 2 | 0 | 50% |
What each file covers
Sections
1 shared · 5 only in A · 11 only in B- − WxJava Agent 指南
- − API 与实现约定
- − Git 与 Pull Request 规范
- − Review 指南
- − Agent 完成检查清单
- + Copilot Instruction
- + WxJava - 微信 Java SDK 开发说明
- + 1. 基础编译（请勿中断 - 约需 4-5 分钟）
- + 超时时间：建议设置 8 分钟以上。实际时间：约 4 分钟
- + 2. 完整打包（请勿中断 - 约需 2-3 分钟）
- + 超时时间：建议设置 5 分钟以上。实际时间：约 2 分钟
- + 3. 代码质量校验（请勿中断 - 约需 45-60 秒）
- + 超时时间：建议设置 3 分钟以上。实际时间：约 50 秒
- + SDK 使用模式
- + 构建单个模块（将 'weixin-java-mp' 替换为目标模块）：
- + Maven 依赖示例
- 安全与敏感数据
Commands
0 shared · 7 only in A · 9 only in B- − mvn -pl <module> -am test
- − mvn -pl <module> -am -Dtest=<TestClass> -Dsurefire.failIfNoSpecifiedTests=false test
- − mvn test
- − git diff --check
- − git diff
- − git push
- − git reset --hard
- + mvn clean compile -DskipTests=true --no-transfer-progress
- + mvn clean package -DskipTests=true --no-transfer-progress
- + mvn checkstyle:check --no-transfer-progress
- + mvn clean compile --no-transfer-progress
- + mvn compile --no-transfer-progress
- + mvn dependency:tree --no-transfer-progress
- + mvn versions:display-property-updates --no-transfer-progress
- + mvn clean deploy -P release --no-transfer-progress
- + mvn clean
Section tags
2 shared · 2 only in A · 0 only in B- − testing-strategy
- − api
- git-pr
- agent-behaviour
Line diff
binarywang/WxJava · AGENTS.md
@@ −1 @@
1# WxJava Agent 指南
2
3## 适用范围与指令优先级
4
5- 本文件适用于整个仓库，供本地编码 Agent、自动化 Agent 和 Pull Request Review Agent 使用。
6- 开始工作前先阅读与任务直接相关的 `README.md`、`CONTRIBUTING.md`、模块 `pom.xml`、现有实现和测试；不要仅凭通用经验推断项目约定。
7- 若子目录存在更具体的 `AGENTS.md`，处理该目录文件时优先遵循距离目标文件最近的说明。
8- 用户的明确要求优先于本文件；若要求与兼容性、安全性或仓库约定冲突，应先说明风险，不要静默偏离。
9- 只修改完成任务所必需的文件，不处理无关格式、重构或历史遗留问题。
10
11## 项目概览
12
13- WxJava 是面向微信生态的 Java SDK，采用 Maven 多模块结构。
14- 当前根项目要求 Java 8（`maven.compiler.source` 和 `maven.compiler.target` 均为 `1.8`）。除非任务明确要求升级，否则新增代码、依赖和 API 必须保持 Java 8 兼容。
15- 主要 SDK 模块包括：
16 - `weixin-java-common`：各模块共用的基础类型、工具、异常、HTTP 与配置能力。
17 - `weixin-java-mp`：微信公众号。
18 - `weixin-java-miniapp`：微信小程序。
19 - `weixin-java-pay`：微信支付。
20 - `weixin-java-cp`：企业微信。
21 - `weixin-java-open`：微信开放平台。
22 - `weixin-java-channel`：微信视频号、微信小店。
23 - `weixin-java-qidian`：微信客服相关能力。
24 - `weixin-java-aispeech`：微信智能语音。
25 - `weixin-graal`：GraalVM 相关支持。
26- 集成模块主要位于：
27 - `spring-boot-starters`：Spring Boot Starter 及多账号 Starter。
28 - `solon-plugins`：Solon 插件及多账号插件。
29 - `wx-java-bom`：统一管理对外模块版本的 BOM。
30- `README.md` 说明整体能力和使用方式，`CONTRIBUTING.md` 规定代码贡献要求，`docs` 保存补充文档。
31
32## 开发流程
33
341. 确认任务涉及的微信产品和 Maven 模块，先查找同模块中的相似接口、Bean、实现类和测试。
352. 阅读目标模块及其父级 `pom.xml`，确认依赖、测试框架和已有实现方式。
363. 优先沿用现有的包结构、命名、序列化、HTTP 执行器、异常处理及配置模式。
374. 以最小变更完成任务；不要在功能修改中夹带依赖升级、全局格式化或无关重构。
385. 为修复或新增行为添加有针对性的测试，并先运行受影响模块的验证。
396. 交付前检查 diff、测试结果、兼容性和文档影响，明确报告未执行或无法执行的验证。
40
41## 代码风格与兼容性
42
43- 遵循 `.editorconfig`：使用空格缩进、缩进宽度为 2、UTF-8、LF、文件末尾保留换行，并清除非 Markdown 文件的行尾空格。
44- 保持目标文件现有代码风格；避免仅为个人偏好调整 import、换行、注释或成员顺序。
45- 不使用 Java 9 及以上语言特性或仅在新版本 JDK 中存在的 API。
46- 项目使用 Lombok；新增或修改 Lombok 用法时遵循相邻代码模式，不要在同一变更中无理由改写为手工样板代码。
47- 公共 API、序列化字段、枚举值、常量、默认实现和依赖范围都可能影响下游用户，修改时优先保持源码、二进制和行为兼容。
48- 不要随意改变已有异常类型、空值语义、默认 HTTP 客户端、JSON/XML 映射或配置加载行为。
49- 新增依赖前先确认现有依赖能否满足需求；依赖版本应在合适的父 POM 或 BOM 中统一管理，避免模块间版本漂移。
50
51## API 与实现约定
52
53- 对接微信接口时，以对应产品的官方接口定义和仓库内现有同类实现为依据，核对请求路径、HTTP 方法、字段名、必填项和返回结构。
54- Java 字段名可以符合项目命名习惯，但传输层字段名必须与微信接口保持一致；需要时使用项目现有的 Gson、Jackson 或 XStream 映射方式。
55- 新增 Service API 时同步检查接口、实现类、请求/响应 Bean、URL 常量、序列化适配器和测试是否都需要更新。
56- 涉及多个 HTTP 客户端实现时，保持 Apache HttpClient、HttpComponents、OkHttp 和 Jodd 等现有实现的能力一致；不要只修复其中一种而遗漏其他可选实现。
57- 涉及 Starter 或插件时，检查单账号与多账号版本以及自动配置、配置属性和示例测试是否需要同步。
58- 公共方法需要清晰的 Javadoc，至少准确描述参数、返回值、异常和必要约束；不要编写与实现不一致的模板化注释。
59- 不吞掉异常，不使用空 `catch`，不在日志中泄露 token、secret、密钥、签名原文或用户敏感数据。
60
61## 测试与验证
62
63- 项目测试主要使用 TestNG；沿用目标模块已有测试基类、数据提供器、Mock 方式和资源布局。
64- 修复 bug 时应添加能够复现旧行为并验证修复结果的回归测试；新增公共方法必须配套单元测试。
65- 优先执行受影响模块及其依赖的测试：
66
67```shell
68mvn -pl <module> -am test
69```
70
71- 运行单个测试类时，可在对应模块范围内执行：
72
73```shell
74mvn -pl <module> -am -Dtest=<TestClass> -Dsurefire.failIfNoSpecifiedTests=false test
75```
76
77- 跨公共模块、父 POM、BOM 或多个产品模块的变更应扩大验证范围；条件允许时执行：
78
79```shell
80mvn test
81```
82
83- 对仅需确认编译且测试依赖外部凭据的场景，可执行模块级编译或打包，但不得把跳过测试的构建描述为“测试通过”。
84- 部分测试可能依赖微信凭据、网络或本地配置。不得提交真实凭据；无法运行时应说明原因以及已完成的替代验证。
85- 完成前至少运行 `git diff --check`，并人工检查 `git diff`，确认没有意外文件、调试代码、生成物或敏感信息。
86
87## 文档与依赖变更
88
89- 用户可见的 API、配置项、模块使用方式或兼容性发生变化时，同步更新相关 Javadoc、README 或 `docs` 文档。
90- 示例中的版本号、模块名和配置键应与当前项目保持一致；不要复制未经验证的外部示例。
91- 修改根 POM、父 POM 或 `wx-java-bom` 时，检查所有子模块和对外依赖管理的影响。
92- 不提交构建输出、IDE 临时文件、测试报告、真实配置文件或本地备份文件。
93
94## Git 与 Pull Request 规范
95
96- 贡献目标分支为 `develop`；`release` 用于正式版本发布，不应作为常规 Pull Request 的目标分支。
97- 提交前保持工作区变更聚焦，不覆盖或回退用户已有的无关修改。
98- Commit 和 Pull Request 应说明变更动机、影响模块、兼容性风险和验证方式；关联已有 Issue 时写明编号。
99- 不得在未经用户明确授权的情况下执行 `git push`、创建或合并 Pull Request、改写历史或执行破坏性 Git 操作。
100- 不要使用 `git reset --hard`、强制 checkout 等方式清理不属于当前任务的改动。
101
102## 安全与敏感数据
103
104- 禁止提交 AppID 对应的 secret、access token、API v3 密钥、商户私钥、证书私钥、用户数据或其他真实凭据。
105- 测试和文档使用明显的占位值或脱敏数据；日志应避免输出查询串、请求体或响应体中的敏感字段。
106- 涉及签名、验签、加解密、证书、回调通知和支付金额时，重点检查字符编码、字段排序、精度、时区、重放风险和资源关闭。
107- 涉及网络请求、文件或流时，检查超时、异常路径、资源释放、响应关闭和大数据量下的内存行为。
108
109## Review 指南
110
111- 重点检查空指针、并发、资源释放、兼容性问题。
112- 不要只做代码风格建议，优先指出真实 bug 和回归风险。
113- 所有 Pull Request Review 的总结、结论和行内评论必须使用简体中文。
114- 技术标识符、类名、方法名、变量名、日志、错误信息及代码片段保持原文，不要翻译。
115- 严重程度标识可以保留 `P0`、`P1`、`P2` 等英文缩写。
116- 如果没有发现需要阻止合并的问题，也必须使用简体中文给出结论。
117- Review 结论必须基于当前 diff 和仓库中可验证的行为；不确定时明确说明假设，不要把推测写成确定缺陷。
118- 仅报告由本次变更引入或暴露、且作者可以采取行动的问题，并指出具体文件、位置、触发条件和影响。
119- 重点关注微信接口契约、Java 8 兼容性、公共 API 兼容性、序列化字段、HTTP 客户端实现一致性、Starter 多账号场景及敏感信息泄露。
120- 不要仅因缺少全仓库测试、个人风格偏好或与本次变更无关的历史代码而阻止合并。
121
122## Agent 完成检查清单
123
124- 已确认并遵循相关模块、相邻代码和更具体的 `AGENTS.md`。
125- 变更范围与任务直接相关，没有覆盖用户的无关修改。
126- 新增代码保持 Java 8、公共 API 和序列化兼容性。
127- 必要的测试与文档已经更新。
128- 已执行与风险匹配的构建或测试，并如实记录结果。
129- 已检查完整 diff、格式、生成物和敏感信息。
130- 最终回复使用简体中文，简要列出修改内容、验证结果和任何剩余风险。
131
binarywang/WxJava · .github/copilot-instructions.md
@@ +1 @@
1# Copilot Instruction
2请始终使用中文生成 Pull Request 的标题、描述和提交信息
3
4
5# WxJava - 微信 Java SDK 开发说明
6
7WxJava 是一个支持多种微信平台的完整 Java SDK，包含公众号、小程序、微信支付、企业微信、开放平台、视频号、企点等多种功能模块。
8
9**请始终优先参考本说明，只有在遇到与此内容不一致的意外信息时，才退而使用搜索或 bash 命令。**
10
11## 高效开发指南
12
13### 前置条件与环境准备
14- **Java 要求**：JDK 8+（项目最低目标为 Java 8）
15- **Maven**：推荐 Maven 3.6+（已验证 Maven 3.9.11）
16- **IDE**：推荐使用 IntelliJ IDEA（项目针对 IDEA 优化）
17
18### 引导、构建与校验
19克隆仓库后按顺序执行以下命令：
20
21```bash
22# 1. 基础编译（请勿中断 - 约需 4-5 分钟）
23mvn clean compile -DskipTests=true --no-transfer-progress
24# 超时时间：建议设置 8 分钟以上。实际时间：约 4 分钟
25
26# 2. 完整打包（请勿中断 - 约需 2-3 分钟）
27mvn clean package -DskipTests=true --no-transfer-progress
28# 超时时间：建议设置 5 分钟以上。实际时间：约 2 分钟
29
30# 3. 代码质量校验（请勿中断 - 约需 45-60 秒）
31mvn checkstyle:check --no-transfer-progress
32# 超时时间：建议设置 3 分钟以上。实际时间：约 50 秒
33```
34
35重要时间说明：
36- 绝对不要中断任意 Maven 构建命令
37- 编译阶段耗时最长（约 4 分钟），原因是项目包含 34 个模块
38- 后续构建会更快，因为存在增量编译
39- 始终使用 `--no-transfer-progress` 以减少日志噪音
40
41### 测试结构
42- **测试框架**：TestNG（非 JUnit）
43- **测试文件**：共有 298 个测试文件
44- **默认行为**：pom.xml 中默认禁用测试（`<skip>true</skip>`）
45- **测试配置**：测试需要通过 test-config.xml 提供真实的微信 API 凭据
46- **注意**：没有真实微信 API 凭据请不要尝试运行测试，测试将会失败
47
48## 项目结构与导航
49
50### 核心 SDK 模块（主要开发区）
51- `weixin-java-common/` - 通用工具与基础类（最重要）
52- `weixin-java-mp/` - 公众号 SDK
53- `weixin-java-pay/` - 微信支付 SDK
54- `weixin-java-miniapp/` - 小程序 SDK
55- `weixin-java-cp/` - 企业微信 SDK
56- `weixin-java-open/` - 开放平台 SDK
57- `weixin-java-channel/` - 视频号 / Channel SDK
58- `weixin-java-qidian/` - 企点 SDK
59
60### 框架集成模块
61- `spring-boot-starters/` - Spring Boot 自动配置 starter
62- `solon-plugins/` - Solon 框架插件
63- `weixin-graal/` - GraalVM 本地镜像支持
64
65### 配置与质量控制
66- `quality-checks/google_checks.xml` - Checkstyle 配置
67- `.editorconfig` - 代码格式规则（2 个空格等于 1 个制表）
68- `pom.xml` - 根级 Maven 配置
69
70## 开发工作流
71
72### 修改代码的流程
731. 修改前务必先构建以建立干净基线：
74 ```bash
75 mvn clean compile --no-transfer-progress
76 ```
77
782. 遵循代码风格（由 checkstyle 强制）：
79 - 缩进使用 2 个空格（不要用制表符）
80 - 遵循 Google Java 风格指南
81 - 在 IDE 中安装 EditorConfig 插件
82
833. 增量验证修改：
84 ```bash
85 # 每次修改后运行：
86 mvn compile --no-transfer-progress
87 mvn checkstyle:check --no-transfer-progress
88 ```
89
90### 提交修改前的必须校验
91请务必按顺序完成以下校验步骤：
92
931. 代码风格校验：
94 ```bash
95 mvn checkstyle:check --no-transfer-progress
96 # 必须通过 - 约需 50 秒
97 ```
98
992. 完整清理构建：
100 ```bash
101 mvn clean package -DskipTests=true --no-transfer-progress
102 # 必须成功 - 约需 2 分钟
103 ```
104
1053. 文档：为公共方法和类补充或更新 javadoc
1064. 贡献规范：遵循 `CONTRIBUTING.md`，Pull Request 必须以 `develop` 分支为目标
107
108## 模块依赖与构建顺序
109
110### 核心模块依赖（构建顺序）
1111. `weixin-graal`（GraalVM 支持）
1122. `weixin-java-common`（所有模块的基础）
1133. 核心 SDK 模块（mp、pay、miniapp、cp、open、channel、qidian）
1144. 框架集成（spring-boot-starters、solon-plugins）
115
116### 主要关系模式
117- 所有 SDK 模块都依赖于 `weixin-java-common`
118- Spring Boot starters 依赖对应的 SDK 模块
119- Solon 插件遵循与 Spring Boot starters 相同的依赖模式
120- 每个模块都有单账号与多账号配置支持
121
122## 常见任务与命令
123
124### 验证指定模块
125```bash
126# 构建单个模块（将 'weixin-java-mp' 替换为目标模块）：
127cd weixin-java-mp
128mvn clean compile --no-transfer-progress
129```
130
131### 检查依赖
132```bash
133# 分析依赖树：
134mvn dependency:tree --no-transfer-progress
135
136# 检查依赖更新：
137./others/check-dependency-updates.sh
138```
139
140### 发布与发布准备
141```bash
142# 版本检查：
143mvn versions:display-property-updates --no-transfer-progress
144
145# 部署（需要凭据）：
146mvn clean deploy -P release --no-transfer-progress
147```
148
149## 重要文件与位置
150
151### 配置文件
152- `pom.xml` - 根级 Maven 配置与依赖管理
153- `quality-checks/google_checks.xml` - Checkstyle 规则
154- `.editorconfig` - IDE 格式化配置
155- `.github/workflows/maven-publish.yml` - CI/CD 工作流
156
157### 文档
158- `README.md` - 项目概览与使用说明（中文）
159- `CONTRIBUTING.md` - 贡献指南
160- `demo.md` - 示例项目与演示链接
161- 每个模块均有单独的文档与示例
162
163### 测试资源
164- `*/src/test/resources/test-config.sample.xml` - 测试配置模板
165- 测试运行需要真实的微信 API 凭据
166
167## SDK 使用模式
168
169### Maven 依赖示例
170```xml
171<dependency>
172 <groupId>com.github.binarywang</groupId>
173 <artifactId>weixin-java-mp</artifactId> <!-- 或其他模块 -->
174 <version>4.7.0</version>
175</dependency>
176```
177
178### 常见开发区域
179- **API 客户端实现**：位于 `*/service/impl/` 目录
180- **模型类**：位于 `*/bean/` 目录
181- **配置**：位于 `*/config/` 目录
182- **工具类**：位于 `weixin-java-common` 的 `*/util/` 目录
183
184## 故障排查
185
186### 构建问题
187- **OutOfMemoryError**：增加 Maven 内存：`export MAVEN_OPTS="-Xmx2g"`
188- **编译失败**：通常为依赖问题 - 先执行 `mvn clean`
189- **Checkstyle 失败**：检查 IDE 的 `.editorconfig` 设置
190
191### 常见陷阱
192- **测试默认跳过**：这是正常现象 — 测试需要微信 API 凭据
193- **多模块变更**：总是在仓库根目录构建，而不是单独模块
194- **分支目标**：Pull Request 必须以 `develop` 分支为目标，而不是 `master` 或 `release`
195
196## 性能说明
197- **首次构建**：由于依赖下载，耗时 4-5 分钟
198- **增量构建**：通常更快（约 30-60 秒）
199- **Checkstyle**：运行迅速（约 50 秒），应当经常运行
200- **IDE 性能**：项目使用 Lombok，请确保启用注解处理
201
202注意：本项目为 SDK 库项目，而非可运行应用。修改应以 API 功能为主，不要改动应用级行为。
203
@@ −1 +1 @@
1−# WxJava Agent 指南
1+# Copilot Instruction
2+请始终使用中文生成 Pull Request 的标题、描述和提交信息
23
3−## 适用范围与指令优先级
44
5−- 本文件适用于整个仓库，供本地编码 Agent、自动化 Agent 和 Pull Request Review Agent 使用。
6−- 开始工作前先阅读与任务直接相关的 `README.md`、`CONTRIBUTING.md`、模块 `pom.xml`、现有实现和测试；不要仅凭通用经验推断项目约定。
7−- 若子目录存在更具体的 `AGENTS.md`，处理该目录文件时优先遵循距离目标文件最近的说明。
8−- 用户的明确要求优先于本文件；若要求与兼容性、安全性或仓库约定冲突，应先说明风险，不要静默偏离。
9−- 只修改完成任务所必需的文件，不处理无关格式、重构或历史遗留问题。
5+# WxJava - 微信 Java SDK 开发说明
106
11−## 项目概览
7+WxJava 是一个支持多种微信平台的完整 Java SDK，包含公众号、小程序、微信支付、企业微信、开放平台、视频号、企点等多种功能模块。
128
13−- WxJava 是面向微信生态的 Java SDK，采用 Maven 多模块结构。
14−- 当前根项目要求 Java 8（`maven.compiler.source` 和 `maven.compiler.target` 均为 `1.8`）。除非任务明确要求升级，否则新增代码、依赖和 API 必须保持 Java 8 兼容。
15−- 主要 SDK 模块包括：
16− - `weixin-java-common`：各模块共用的基础类型、工具、异常、HTTP 与配置能力。
17− - `weixin-java-mp`：微信公众号。
18− - `weixin-java-miniapp`：微信小程序。
19− - `weixin-java-pay`：微信支付。
20− - `weixin-java-cp`：企业微信。
21− - `weixin-java-open`：微信开放平台。
22− - `weixin-java-channel`：微信视频号、微信小店。
23− - `weixin-java-qidian`：微信客服相关能力。
24− - `weixin-java-aispeech`：微信智能语音。
25− - `weixin-graal`：GraalVM 相关支持。
26−- 集成模块主要位于：
27− - `spring-boot-starters`：Spring Boot Starter 及多账号 Starter。
28− - `solon-plugins`：Solon 插件及多账号插件。
29− - `wx-java-bom`：统一管理对外模块版本的 BOM。
30−- `README.md` 说明整体能力和使用方式，`CONTRIBUTING.md` 规定代码贡献要求，`docs` 保存补充文档。
9+**请始终优先参考本说明，只有在遇到与此内容不一致的意外信息时，才退而使用搜索或 bash 命令。**
3110
32−## 开发流程
11+## 高效开发指南
3312
34−1. 确认任务涉及的微信产品和 Maven 模块，先查找同模块中的相似接口、Bean、实现类和测试。
35−2. 阅读目标模块及其父级 `pom.xml`，确认依赖、测试框架和已有实现方式。
36−3. 优先沿用现有的包结构、命名、序列化、HTTP 执行器、异常处理及配置模式。
37−4. 以最小变更完成任务；不要在功能修改中夹带依赖升级、全局格式化或无关重构。
38−5. 为修复或新增行为添加有针对性的测试，并先运行受影响模块的验证。
39−6. 交付前检查 diff、测试结果、兼容性和文档影响，明确报告未执行或无法执行的验证。
13+### 前置条件与环境准备
14+- **Java 要求**：JDK 8+（项目最低目标为 Java 8）
15+- **Maven**：推荐 Maven 3.6+（已验证 Maven 3.9.11）
16+- **IDE**：推荐使用 IntelliJ IDEA（项目针对 IDEA 优化）
4017
41−## 代码风格与兼容性
18+### 引导、构建与校验
19+克隆仓库后按顺序执行以下命令：
4220
43−- 遵循 `.editorconfig`：使用空格缩进、缩进宽度为 2、UTF-8、LF、文件末尾保留换行，并清除非 Markdown 文件的行尾空格。
44−- 保持目标文件现有代码风格；避免仅为个人偏好调整 import、换行、注释或成员顺序。
45−- 不使用 Java 9 及以上语言特性或仅在新版本 JDK 中存在的 API。
46−- 项目使用 Lombok；新增或修改 Lombok 用法时遵循相邻代码模式，不要在同一变更中无理由改写为手工样板代码。
47−- 公共 API、序列化字段、枚举值、常量、默认实现和依赖范围都可能影响下游用户，修改时优先保持源码、二进制和行为兼容。
48−- 不要随意改变已有异常类型、空值语义、默认 HTTP 客户端、JSON/XML 映射或配置加载行为。
49−- 新增依赖前先确认现有依赖能否满足需求；依赖版本应在合适的父 POM 或 BOM 中统一管理，避免模块间版本漂移。
21+```bash
22+# 1. 基础编译（请勿中断 - 约需 4-5 分钟）
23+mvn clean compile -DskipTests=true --no-transfer-progress
24+# 超时时间：建议设置 8 分钟以上。实际时间：约 4 分钟
5025
51−## API 与实现约定
26+# 2. 完整打包（请勿中断 - 约需 2-3 分钟）
27+mvn clean package -DskipTests=true --no-transfer-progress
28+# 超时时间：建议设置 5 分钟以上。实际时间：约 2 分钟
5229
53−- 对接微信接口时，以对应产品的官方接口定义和仓库内现有同类实现为依据，核对请求路径、HTTP 方法、字段名、必填项和返回结构。
54−- Java 字段名可以符合项目命名习惯，但传输层字段名必须与微信接口保持一致；需要时使用项目现有的 Gson、Jackson 或 XStream 映射方式。
55−- 新增 Service API 时同步检查接口、实现类、请求/响应 Bean、URL 常量、序列化适配器和测试是否都需要更新。
56−- 涉及多个 HTTP 客户端实现时，保持 Apache HttpClient、HttpComponents、OkHttp 和 Jodd 等现有实现的能力一致；不要只修复其中一种而遗漏其他可选实现。
57−- 涉及 Starter 或插件时，检查单账号与多账号版本以及自动配置、配置属性和示例测试是否需要同步。
58−- 公共方法需要清晰的 Javadoc，至少准确描述参数、返回值、异常和必要约束；不要编写与实现不一致的模板化注释。
59−- 不吞掉异常，不使用空 `catch`，不在日志中泄露 token、secret、密钥、签名原文或用户敏感数据。
30+# 3. 代码质量校验（请勿中断 - 约需 45-60 秒）
31+mvn checkstyle:check --no-transfer-progress
32+# 超时时间：建议设置 3 分钟以上。实际时间：约 50 秒
33+```
6034
61−## 测试与验证
35+重要时间说明：
36+- 绝对不要中断任意 Maven 构建命令
37+- 编译阶段耗时最长（约 4 分钟），原因是项目包含 34 个模块
38+- 后续构建会更快，因为存在增量编译
39+- 始终使用 `--no-transfer-progress` 以减少日志噪音
6240
63−- 项目测试主要使用 TestNG；沿用目标模块已有测试基类、数据提供器、Mock 方式和资源布局。
64−- 修复 bug 时应添加能够复现旧行为并验证修复结果的回归测试；新增公共方法必须配套单元测试。
65−- 优先执行受影响模块及其依赖的测试：
41+### 测试结构
42+- **测试框架**：TestNG（非 JUnit）
43+- **测试文件**：共有 298 个测试文件
44+- **默认行为**：pom.xml 中默认禁用测试（`<skip>true</skip>`）
45+- **测试配置**：测试需要通过 test-config.xml 提供真实的微信 API 凭据
46+- **注意**：没有真实微信 API 凭据请不要尝试运行测试，测试将会失败
6647
67−```shell
68−mvn -pl <module> -am test
48+## 项目结构与导航
49+
50+### 核心 SDK 模块（主要开发区）
51+- `weixin-java-common/` - 通用工具与基础类（最重要）
52+- `weixin-java-mp/` - 公众号 SDK
53+- `weixin-java-pay/` - 微信支付 SDK
54+- `weixin-java-miniapp/` - 小程序 SDK
55+- `weixin-java-cp/` - 企业微信 SDK
56+- `weixin-java-open/` - 开放平台 SDK
57+- `weixin-java-channel/` - 视频号 / Channel SDK
58+- `weixin-java-qidian/` - 企点 SDK
59+
60+### 框架集成模块
61+- `spring-boot-starters/` - Spring Boot 自动配置 starter
62+- `solon-plugins/` - Solon 框架插件
63+- `weixin-graal/` - GraalVM 本地镜像支持
64+
65+### 配置与质量控制
66+- `quality-checks/google_checks.xml` - Checkstyle 配置
67+- `.editorconfig` - 代码格式规则（2 个空格等于 1 个制表）
68+- `pom.xml` - 根级 Maven 配置
69+
70+## 开发工作流
71+
72+### 修改代码的流程
73+1. 修改前务必先构建以建立干净基线：
74+ ```bash
75+ mvn clean compile --no-transfer-progress
76+ ```
77+
78+2. 遵循代码风格（由 checkstyle 强制）：
79+ - 缩进使用 2 个空格（不要用制表符）
80+ - 遵循 Google Java 风格指南
81+ - 在 IDE 中安装 EditorConfig 插件
82+
83+3. 增量验证修改：
84+ ```bash
85+ # 每次修改后运行：
86+ mvn compile --no-transfer-progress
87+ mvn checkstyle:check --no-transfer-progress
88+ ```
89+
90+### 提交修改前的必须校验
91+请务必按顺序完成以下校验步骤：
92+
93+1. 代码风格校验：
94+ ```bash
95+ mvn checkstyle:check --no-transfer-progress
96+ # 必须通过 - 约需 50 秒
97+ ```
98+
99+2. 完整清理构建：
100+ ```bash
101+ mvn clean package -DskipTests=true --no-transfer-progress
102+ # 必须成功 - 约需 2 分钟
103+ ```
104+
105+3. 文档：为公共方法和类补充或更新 javadoc
106+4. 贡献规范：遵循 `CONTRIBUTING.md`，Pull Request 必须以 `develop` 分支为目标
107+
108+## 模块依赖与构建顺序
109+
110+### 核心模块依赖（构建顺序）
111+1. `weixin-graal`（GraalVM 支持）
112+2. `weixin-java-common`（所有模块的基础）
113+3. 核心 SDK 模块（mp、pay、miniapp、cp、open、channel、qidian）
114+4. 框架集成（spring-boot-starters、solon-plugins）
115+
116+### 主要关系模式
117+- 所有 SDK 模块都依赖于 `weixin-java-common`
118+- Spring Boot starters 依赖对应的 SDK 模块
119+- Solon 插件遵循与 Spring Boot starters 相同的依赖模式
120+- 每个模块都有单账号与多账号配置支持
121+
122+## 常见任务与命令
123+
124+### 验证指定模块
125+```bash
126+# 构建单个模块（将 'weixin-java-mp' 替换为目标模块）：
127+cd weixin-java-mp
128+mvn clean compile --no-transfer-progress
69129 ```
70130
71−- 运行单个测试类时，可在对应模块范围内执行：
131+### 检查依赖
132+```bash
133+# 分析依赖树：
134+mvn dependency:tree --no-transfer-progress
72135
73−```shell
74−mvn -pl <module> -am -Dtest=<TestClass> -Dsurefire.failIfNoSpecifiedTests=false test
136+# 检查依赖更新：
137+./others/check-dependency-updates.sh
75138 ```
76139
77−- 跨公共模块、父 POM、BOM 或多个产品模块的变更应扩大验证范围；条件允许时执行：
140+### 发布与发布准备
141+```bash
142+# 版本检查：
143+mvn versions:display-property-updates --no-transfer-progress
78144
79−```shell
80−mvn test
145+# 部署（需要凭据）：
146+mvn clean deploy -P release --no-transfer-progress
81147 ```
82148
83−- 对仅需确认编译且测试依赖外部凭据的场景，可执行模块级编译或打包，但不得把跳过测试的构建描述为“测试通过”。
84−- 部分测试可能依赖微信凭据、网络或本地配置。不得提交真实凭据；无法运行时应说明原因以及已完成的替代验证。
85−- 完成前至少运行 `git diff --check`，并人工检查 `git diff`，确认没有意外文件、调试代码、生成物或敏感信息。
149+## 重要文件与位置
86150
87−## 文档与依赖变更
151+### 配置文件
152+- `pom.xml` - 根级 Maven 配置与依赖管理
153+- `quality-checks/google_checks.xml` - Checkstyle 规则
154+- `.editorconfig` - IDE 格式化配置
155+- `.github/workflows/maven-publish.yml` - CI/CD 工作流
88156
89−- 用户可见的 API、配置项、模块使用方式或兼容性发生变化时，同步更新相关 Javadoc、README 或 `docs` 文档。
90−- 示例中的版本号、模块名和配置键应与当前项目保持一致；不要复制未经验证的外部示例。
91−- 修改根 POM、父 POM 或 `wx-java-bom` 时，检查所有子模块和对外依赖管理的影响。
92−- 不提交构建输出、IDE 临时文件、测试报告、真实配置文件或本地备份文件。
157+### 文档
158+- `README.md` - 项目概览与使用说明（中文）
159+- `CONTRIBUTING.md` - 贡献指南
160+- `demo.md` - 示例项目与演示链接
161+- 每个模块均有单独的文档与示例
93162
94−## Git 与 Pull Request 规范
163+### 测试资源
164+- `*/src/test/resources/test-config.sample.xml` - 测试配置模板
165+- 测试运行需要真实的微信 API 凭据
95166
96−- 贡献目标分支为 `develop`；`release` 用于正式版本发布，不应作为常规 Pull Request 的目标分支。
97−- 提交前保持工作区变更聚焦，不覆盖或回退用户已有的无关修改。
98−- Commit 和 Pull Request 应说明变更动机、影响模块、兼容性风险和验证方式；关联已有 Issue 时写明编号。
99−- 不得在未经用户明确授权的情况下执行 `git push`、创建或合并 Pull Request、改写历史或执行破坏性 Git 操作。
100−- 不要使用 `git reset --hard`、强制 checkout 等方式清理不属于当前任务的改动。
167+## SDK 使用模式
101168
102−## 安全与敏感数据
169+### Maven 依赖示例
170+```xml
171+<dependency>
172+ <groupId>com.github.binarywang</groupId>
173+ <artifactId>weixin-java-mp</artifactId> <!-- 或其他模块 -->
174+ <version>4.7.0</version>
175+</dependency>
176+```
103177
104−- 禁止提交 AppID 对应的 secret、access token、API v3 密钥、商户私钥、证书私钥、用户数据或其他真实凭据。
105−- 测试和文档使用明显的占位值或脱敏数据；日志应避免输出查询串、请求体或响应体中的敏感字段。
106−- 涉及签名、验签、加解密、证书、回调通知和支付金额时，重点检查字符编码、字段排序、精度、时区、重放风险和资源关闭。
107−- 涉及网络请求、文件或流时，检查超时、异常路径、资源释放、响应关闭和大数据量下的内存行为。
178+### 常见开发区域
179+- **API 客户端实现**：位于 `*/service/impl/` 目录
180+- **模型类**：位于 `*/bean/` 目录
181+- **配置**：位于 `*/config/` 目录
182+- **工具类**：位于 `weixin-java-common` 的 `*/util/` 目录
108183
109−## Review 指南
184+## 故障排查
110185
111−- 重点检查空指针、并发、资源释放、兼容性问题。
112−- 不要只做代码风格建议，优先指出真实 bug 和回归风险。
113−- 所有 Pull Request Review 的总结、结论和行内评论必须使用简体中文。
114−- 技术标识符、类名、方法名、变量名、日志、错误信息及代码片段保持原文，不要翻译。
115−- 严重程度标识可以保留 `P0`、`P1`、`P2` 等英文缩写。
116−- 如果没有发现需要阻止合并的问题，也必须使用简体中文给出结论。
117−- Review 结论必须基于当前 diff 和仓库中可验证的行为；不确定时明确说明假设，不要把推测写成确定缺陷。
118−- 仅报告由本次变更引入或暴露、且作者可以采取行动的问题，并指出具体文件、位置、触发条件和影响。
119−- 重点关注微信接口契约、Java 8 兼容性、公共 API 兼容性、序列化字段、HTTP 客户端实现一致性、Starter 多账号场景及敏感信息泄露。
120−- 不要仅因缺少全仓库测试、个人风格偏好或与本次变更无关的历史代码而阻止合并。
186+### 构建问题
187+- **OutOfMemoryError**：增加 Maven 内存：`export MAVEN_OPTS="-Xmx2g"`
188+- **编译失败**：通常为依赖问题 - 先执行 `mvn clean`
189+- **Checkstyle 失败**：检查 IDE 的 `.editorconfig` 设置
121190
122−## Agent 完成检查清单
191+### 常见陷阱
192+- **测试默认跳过**：这是正常现象 — 测试需要微信 API 凭据
193+- **多模块变更**：总是在仓库根目录构建，而不是单独模块
194+- **分支目标**：Pull Request 必须以 `develop` 分支为目标，而不是 `master` 或 `release`
123195
124−- 已确认并遵循相关模块、相邻代码和更具体的 `AGENTS.md`。
125−- 变更范围与任务直接相关，没有覆盖用户的无关修改。
126−- 新增代码保持 Java 8、公共 API 和序列化兼容性。
127−- 必要的测试与文档已经更新。
128−- 已执行与风险匹配的构建或测试，并如实记录结果。
129−- 已检查完整 diff、格式、生成物和敏感信息。
130−- 最终回复使用简体中文，简要列出修改内容、验证结果和任何剩余风险。
196+## 性能说明
197+- **首次构建**：由于依赖下载，耗时 4-5 分钟
198+- **增量构建**：通常更快（约 30-60 秒）
199+- **Checkstyle**：运行迅速（约 50 秒），应当经常运行
200+- **IDE 性能**：项目使用 Lombok，请确保启用注解处理
201+
202+注意：本项目为 SDK 库项目，而非可运行应用。修改应以 API 功能为主，不要改动应用级行为。
131203
