copilot-instructions.md · diff
git:20250808.e61ad44 to git:20251023.b9b4f00
125 added, 120 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
- # WxJava - WeChat Java SDK Development Instructions
+ # Copilot Instruction
+ 请始终使用中文生成 Pull Request 的标题、描述和提交信息
- WxJava is a comprehensive WeChat Java SDK supporting multiple WeChat platforms including Official Accounts (公众号), Mini Programs (小程序), WeChat Pay (微信支付), Enterprise WeChat (企业微信), Open Platform (开放平台), and Channel/Video (视频号). This is a Maven multi-module project with Spring Boot and Solon framework integrations.
- **ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the information here.**
+ # WxJava - 微信 Java SDK 开发说明
- ## Working Effectively
+ WxJava 是一个支持多种微信平台的完整 Java SDK,包含公众号、小程序、微信支付、企业微信、开放平台、视频号、企点等多种功能模块。
- ### Prerequisites and Environment Setup
- - **Java Requirements**: JDK 8+ required (project uses Java 8 as minimum target)
- - **Maven**: Maven 3.6+ recommended (Maven 3.9.11 validated)
- - **IDE**: IntelliJ IDEA recommended (project optimized for IDEA)
+ **请始终优先参考本说明,只有在遇到与此内容不一致的意外信息时,才退而使用搜索或 bash 命令。**
- ### Bootstrap, Build, and Validate
- Execute these commands in sequence after cloning:
+ ## 高效开发指南
+ ### 前置条件与环境准备
+ - **Java 要求**:JDK 8+(项目最低目标为 Java 8)
+ - **Maven**:推荐 Maven 3.6+(已验证 Maven 3.9.11)
+ - **IDE**:推荐使用 IntelliJ IDEA(项目针对 IDEA 优化)
+
+ ### 引导、构建与校验
+ 克隆仓库后按顺序执行以下命令:
+
```bash
- # 1. Basic compilation (NEVER CANCEL - takes 4-5 minutes)
+ # 1. 基础编译(请勿中断 - 约需 4-5 分钟)
mvn clean compile -DskipTests=true --no-transfer-progress
- # Timeout: Set 8+ minutes. Actual time: ~4 minutes
+ # 超时时间:建议设置 8 分钟以上。实际时间:约 4 分钟
- # 2. Full package build (NEVER CANCEL - takes 2-3 minutes)
+ # 2. 完整打包(请勿中断 - 约需 2-3 分钟)
mvn clean package -DskipTests=true --no-transfer-progress
- # Timeout: Set 5+ minutes. Actual time: ~2 minutes
+ # 超时时间:建议设置 5 分钟以上。实际时间:约 2 分钟
- # 3. Code quality validation (NEVER CANCEL - takes 45-60 seconds)
+ # 3. 代码质量校验(请勿中断 - 约需 45-60 秒)
mvn checkstyle:check --no-transfer-progress
- # Timeout: Set 3+ minutes. Actual time: ~50 seconds
+ # 超时时间:建议设置 3 分钟以上。实际时间:约 50 秒
```
- **CRITICAL TIMING NOTES:**
- - **NEVER CANCEL** any Maven build command
- - Compilation phase takes longest (~4 minutes) due to 34 modules
- - Full builds are faster on subsequent runs due to incremental compilation
- - Always use `--no-transfer-progress` to reduce log noise
+ 重要时间说明:
+ - 绝对不要中断任意 Maven 构建命令
+ - 编译阶段耗时最长(约 4 分钟),原因是项目包含 34 个模块
+ - 后续构建会更快,因为存在增量编译
+ - 始终使用 `--no-transfer-progress` 以减少日志噪音
- ### Testing Structure
- - **Test Framework**: TestNG (not JUnit)
- - **Test Files**: 298 test files across all modules
- - **Default Behavior**: Tests are DISABLED by default in pom.xml (`<skip>true</skip>`)
- - **Test Configuration**: Tests require external WeChat API credentials via test-config.xml files
- - **DO NOT** attempt to run tests without proper WeChat API credentials as they will fail
+ ### 测试结构
+ - **测试框架**:TestNG(非 JUnit)
+ - **测试文件**:共有 298 个测试文件
+ - **默认行为**:pom.xml 中默认禁用测试(`<skip>true</skip>`)
+ - **测试配置**:测试需要通过 test-config.xml 提供真实的微信 API 凭据
+ - **注意**:没有真实微信 API 凭据请不要尝试运行测试,测试将会失败
- ## Project Structure and Navigation
+ ## 项目结构与导航
- ### Core SDK Modules (Main Development Areas)
- - `weixin-java-common/` - Common utilities and base classes (most important)
- - `weixin-java-mp/` - WeChat Official Account SDK (公众号)
- - `weixin-java-pay/` - WeChat Pay SDK (微信支付)
- - `weixin-java-miniapp/` - Mini Program SDK (小程序)
- - `weixin-java-cp/` - Enterprise WeChat SDK (企业微信)
- - `weixin-java-open/` - Open Platform SDK (开放平台)
- - `weixin-java-channel/` - Channel/Video SDK (视频号)
- - `weixin-java-qidian/` - Qidian SDK (企点)
+ ### 核心 SDK 模块(主要开发区)
+ - `weixin-java-common/` - 通用工具与基础类(最重要)
+ - `weixin-java-mp/` - 公众号 SDK
+ - `weixin-java-pay/` - 微信支付 SDK
+ - `weixin-java-miniapp/` - 小程序 SDK
+ - `weixin-java-cp/` - 企业微信 SDK
+ - `weixin-java-open/` - 开放平台 SDK
+ - `weixin-java-channel/` - 视频号 / Channel SDK
+ - `weixin-java-qidian/` - 企点 SDK
- ### Framework Integration Modules
- - `spring-boot-starters/` - Spring Boot auto-configuration starters
- - `solon-plugins/` - Solon framework plugins
- - `weixin-graal/` - GraalVM native image support
+ ### 框架集成模块
+ - `spring-boot-starters/` - Spring Boot 自动配置 starter
+ - `solon-plugins/` - Solon 框架插件
+ - `weixin-graal/` - GraalVM 本地镜像支持
- ### Configuration and Quality
- - `quality-checks/google_checks.xml` - Checkstyle configuration
- - `.editorconfig` - Code formatting rules (2 spaces = 1 tab)
- - `pom.xml` - Root Maven configuration
+ ### 配置与质量控制
+ - `quality-checks/google_checks.xml` - Checkstyle 配置
+ - `.editorconfig` - 代码格式规则(2 个空格等于 1 个制表)
+ - `pom.xml` - 根级 Maven 配置
- ## Development Workflow
+ ## 开发工作流
- ### Making Code Changes
- 1. **Always build first** to establish clean baseline:
+ ### 修改代码的流程
+ 1. 修改前务必先构建以建立干净基线:
```bash
mvn clean compile --no-transfer-progress
```
- 2. **Follow code style** (enforced by checkstyle):
- - Use 2 spaces for indentation (not tabs)
- - Follow Google Java Style Guide
- - Install EditorConfig plugin in your IDE
+ 2. 遵循代码风格(由 checkstyle 强制):
+ - 缩进使用 2 个空格(不要用制表符)
+ - 遵循 Google Java 风格指南
+ - 在 IDE 中安装 EditorConfig 插件
- 3. **Validate changes incrementally**:
+ 3. 增量验证修改:
```bash
- # After each change:
+ # 每次修改后运行:
mvn compile --no-transfer-progress
- mvn checkstyle:check --no-transfer-progress
+ mvn checkstyle:check --no-transfer-progress
```
- ### Before Submitting Changes
- **ALWAYS run these validation steps in sequence:**
+ ### 提交修改前的必须校验
+ 请务必按顺序完成以下校验步骤:
- 1. **Code Style Validation**:
+ 1. 代码风格校验:
```bash
mvn checkstyle:check --no-transfer-progress
- # Must pass - takes ~50 seconds
+ # 必须通过 - 约需 50 秒
```
- 2. **Full Clean Build**:
+ 2. 完整清理构建:
```bash
mvn clean package -DskipTests=true --no-transfer-progress
- # Must succeed - takes ~2 minutes
+ # 必须成功 - 约需 2 分钟
```
- 3. **Documentation**: Update javadoc for public methods and classes
- 4. **Contribution Guidelines**: Follow `CONTRIBUTING.md` - PRs must target `develop` branch
+ 3. 文档:为公共方法和类补充或更新 javadoc
+ 4. 贡献规范:遵循 `CONTRIBUTING.md`,Pull Request 必须以 `develop` 分支为目标
- ## Module Dependencies and Build Order
+ ## 模块依赖与构建顺序
- ### Core Module Dependencies (Build Order)
- 1. `weixin-graal` (GraalVM support)
- 2. `weixin-java-common` (foundation for all other modules)
- 3. Core SDK modules (mp, pay, miniapp, cp, open, channel, qidian)
- 4. Framework integrations (spring-boot-starters, solon-plugins)
+ ### 核心模块依赖(构建顺序)
+ 1. `weixin-graal`(GraalVM 支持)
+ 2. `weixin-java-common`(所有模块的基础)
+ 3. 核心 SDK 模块(mp、pay、miniapp、cp、open、channel、qidian)
+ 4. 框架集成(spring-boot-starters、solon-plugins)
- ### Key Relationship Patterns
- - All SDK modules depend on `weixin-java-common`
- - Spring Boot starters depend on corresponding SDK modules
- - Solon plugins follow same pattern as Spring Boot starters
- - Each module has both single and multi-account configurations
+ ### 主要关系模式
+ - 所有 SDK 模块都依赖于 `weixin-java-common`
+ - Spring Boot starters 依赖对应的 SDK 模块
+ - Solon 插件遵循与 Spring Boot starters 相同的依赖模式
+ - 每个模块都有单账号与多账号配置支持
- ## Common Tasks and Commands
+ ## 常见任务与命令
- ### Validate Specific Module
+ ### 验证指定模块
```bash
- # Build single module (replace 'weixin-java-mp' with target module):
+ # 构建单个模块(将 'weixin-java-mp' 替换为目标模块):
cd weixin-java-mp
mvn clean compile --no-transfer-progress
```
- ### Check Dependencies
+ ### 检查依赖
```bash
- # Analyze dependencies:
+ # 分析依赖树:
mvn dependency:tree --no-transfer-progress
- # Check for dependency updates:
+ # 检查依赖更新:
./others/check-dependency-updates.sh
```
- ### Release and Publishing
+ ### 发布与发布准备
```bash
- # Version check:
+ # 版本检查:
mvn versions:display-property-updates --no-transfer-progress
- # Deploy (requires credentials):
+ # 部署(需要凭据):
mvn clean deploy -P release --no-transfer-progress
```
- ## Important Files and Locations
+ ## 重要文件与位置
- ### Configuration Files
- - `pom.xml` - Root Maven configuration with dependency management
- - `quality-checks/google_checks.xml` - Checkstyle rules
- - `.editorconfig` - IDE formatting configuration
- - `.github/workflows/maven-publish.yml` - CI/CD pipeline
+ ### 配置文件
+ - `pom.xml` - 根级 Maven 配置与依赖管理
+ - `quality-checks/google_checks.xml` - Checkstyle 规则
+ - `.editorconfig` - IDE 格式化配置
+ - `.github/workflows/maven-publish.yml` - CI/CD 工作流
- ### Documentation
- - `README.md` - Project overview and usage (Chinese)
- - `CONTRIBUTING.md` - Development contribution guidelines
- - `demo.md` - Links to demo projects and examples
- - Each module has dedicated documentation and examples
+ ### 文档
+ - `README.md` - 项目概览与使用说明(中文)
+ - `CONTRIBUTING.md` - 贡献指南
+ - `demo.md` - 示例项目与演示链接
+ - 每个模块均有单独的文档与示例
- ### Test Resources
- - `*/src/test/resources/test-config.sample.xml` - Template for test configuration
- - Tests require real WeChat API credentials to run
+ ### 测试资源
+ - `*/src/test/resources/test-config.sample.xml` - 测试配置模板
+ - 测试运行需要真实的微信 API 凭据
- ## SDK Usage Patterns
+ ## SDK 使用模式
- ### Maven Dependency Usage
+ ### Maven 依赖示例
```xml
<dependency>
<groupId>com.github.binarywang</groupId>
- <artifactId>weixin-java-mp</artifactId> <!-- or other modules -->
+ <artifactId>weixin-java-mp</artifactId> <!-- 或其他模块 -->
<version>4.7.0</version>
</dependency>
```
- ### Common Development Areas
- - **API Client Implementation**: Located in `*/service/impl/` directories
- - **Model Classes**: Located in `*/bean/` directories
- - **Configuration**: Located in `*/config/` directories
- - **Utilities**: Located in `*/util/` directories in weixin-java-common
+ ### 常见开发区域
+ - **API 客户端实现**:位于 `*/service/impl/` 目录
+ - **模型类**:位于 `*/bean/` 目录
+ - **配置**:位于 `*/config/` 目录
+ - **工具类**:位于 `weixin-java-common` 的 `*/util/` 目录
- ## Troubleshooting
+ ## 故障排查
- ### Build Issues
- - **OutOfMemoryError**: Increase Maven memory: `export MAVEN_OPTS="-Xmx2g"`
- - **Compilation Failures**: Usually dependency issues - run `mvn clean` first
- - **Checkstyle Failures**: Check `.editorconfig` settings in IDE
+ ### 构建问题
+ - **OutOfMemoryError**:增加 Maven 内存:`export MAVEN_OPTS="-Xmx2g"`
+ - **编译失败**:通常为依赖问题 - 先执行 `mvn clean`
+ - **Checkstyle 失败**:检查 IDE 的 `.editorconfig` 设置
- ### Common Gotchas
- - **Tests Always Skip**: This is normal - tests require WeChat API credentials
- - **Multi-Module Changes**: Always build from root, not individual modules
- - **Branch Target**: PRs must target `develop` branch, not `master`/`release`
+ ### 常见陷阱
+ - **测试默认跳过**:这是正常现象 — 测试需要微信 API 凭据
+ - **多模块变更**:总是在仓库根目录构建,而不是单独模块
+ - **分支目标**:Pull Request 必须以 `develop` 分支为目标,而不是 `master` 或 `release`
- ## Performance Notes
- - **First Build**: Takes 4-5 minutes due to dependency downloads
- - **Incremental Builds**: Much faster (~30-60 seconds)
- - **Checkstyle**: Runs quickly (~50 seconds) and should be run frequently
- - **IDE Performance**: Project uses Lombok - ensure annotation processing is enabled
+ ## 性能说明
+ - **首次构建**:由于依赖下载,耗时 4-5 分钟
+ - **增量构建**:通常更快(约 30-60 秒)
+ - **Checkstyle**:运行迅速(约 50 秒),应当经常运行
+ - **IDE 性能**:项目使用 Lombok,请确保启用注解处理
- Remember: This is a SDK library project, not a runnable application. Changes should focus on API functionality, not application behavior.
+ 注意:本项目为 SDK 库项目,而非可运行应用。修改应以 API 功能为主,不要改动应用级行为。
+