📝 Revise development instructions with Chinese translations
This commit is contained in:
Binary Wang
GitHub
242
.github/copilot-instructions.md
vendored
242
.github/copilot-instructions.md
vendored
@@ -1,198 +1,202 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
### 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 功能为主，不要改动应用级行为。
|
||||
|
||||
Reference in New Issue
Block a user