From b9b4f004387a644d665d33f2366c1b2b1982a3c3 Mon Sep 17 00:00:00 2001 From: Binary Wang Date: Thu, 23 Oct 2025 11:00:01 +0800 Subject: [PATCH] :memo: Revise development instructions with Chinese translations --- .github/copilot-instructions.md | 244 ++++++++++++++++---------------- 1 file changed, 124 insertions(+), 120 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index cec0d76c6..cad29d96d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -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 (`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 +### 测试结构 +- **测试框架**：TestNG（非 JUnit） +- **测试文件**：共有 298 个测试文件 +- **默认行为**：pom.xml 中默认禁用测试（`true`） +- **测试配置**：测试需要通过 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 com.github.binarywang - weixin-java-mp + 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 +### 常见开发区域 +- **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. \ No newline at end of file +注意：本项目为 SDK 库项目，而非可运行应用。修改应以 API 功能为主，不要改动应用级行为。