weixin-java-tools/.github/copilot-instructions.md

WxJava - WeChat Java SDK Development Instructions

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.

Working Effectively

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)

Bootstrap, Build, and Validate

Execute these commands in sequence after cloning:

# 1. Basic compilation (NEVER CANCEL - takes 4-5 minutes)
mvn clean compile -DskipTests=true --no-transfer-progress
# Timeout: Set 8+ minutes. Actual time: ~4 minutes

# 2. Full package build (NEVER CANCEL - takes 2-3 minutes)  
mvn clean package -DskipTests=true --no-transfer-progress
# Timeout: Set 5+ minutes. Actual time: ~2 minutes

# 3. Code quality validation (NEVER CANCEL - takes 45-60 seconds)
mvn checkstyle:check --no-transfer-progress
# Timeout: Set 3+ minutes. Actual time: ~50 seconds

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

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

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 (企点)

Framework Integration Modules

• spring-boot-starters/ - Spring Boot auto-configuration starters
• solon-plugins/ - Solon framework plugins
• weixin-graal/ - GraalVM native image support

Configuration and Quality

• quality-checks/google_checks.xml - Checkstyle configuration
• .editorconfig - Code formatting rules (2 spaces = 1 tab)
• pom.xml - Root Maven configuration

Development Workflow

Making Code Changes

1. Always build first to establish clean baseline:

   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

3. Validate changes incrementally:

   # After each change:
   mvn compile --no-transfer-progress
   mvn checkstyle:check --no-transfer-progress  
   

Before Submitting Changes

ALWAYS run these validation steps in sequence:

1. Code Style Validation:

   mvn checkstyle:check --no-transfer-progress
   # Must pass - takes ~50 seconds
   

2. Full Clean Build:

   mvn clean package -DskipTests=true --no-transfer-progress  
   # Must succeed - takes ~2 minutes
   

3. Documentation: Update javadoc for public methods and classes

4. Contribution Guidelines: Follow CONTRIBUTING.md - PRs must target develop branch

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)

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

Common Tasks and Commands

Validate Specific Module

# Build single module (replace 'weixin-java-mp' with target module):
cd weixin-java-mp
mvn clean compile --no-transfer-progress

Check Dependencies

# Analyze dependencies:
mvn dependency:tree --no-transfer-progress

# Check for dependency updates:  
./others/check-dependency-updates.sh

Release and Publishing

# 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

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

Test Resources

• */src/test/resources/test-config.sample.xml - Template for test configuration
• Tests require real WeChat API credentials to run

SDK Usage Patterns

Maven Dependency Usage

<dependency>
  <groupId>com.github.binarywang</groupId>
  <artifactId>weixin-java-mp</artifactId>  <!-- or other modules -->
  <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

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

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

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

Remember: This is a SDK library project, not a runnable application. Changes should focus on API functionality, not application behavior.