Copilot instructions

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