diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..cec0d76c6 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,198 @@ +# 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: + +```bash +# 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 (`true`) +- **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: + ```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 + +3. **Validate changes incrementally**: + ```bash + # 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**: + ```bash + mvn checkstyle:check --no-transfer-progress + # Must pass - takes ~50 seconds + ``` + +2. **Full Clean Build**: + ```bash + 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 +```bash +# Build single module (replace 'weixin-java-mp' with target module): +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 + +### 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 +```xml + + com.github.binarywang + weixin-java-mp + 4.7.0 + +``` + +### 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. \ No newline at end of file diff --git a/others/mvnw b/others/mvnw old mode 100644 new mode 100755