WxJava AGENTS.md

WxJava Agent 指南

适用范围与指令优先级

• 本文件适用于整个仓库，供本地编码 Agent、自动化 Agent 和 Pull Request Review Agent 使用。
• 开始工作前先阅读与任务直接相关的 README.md、CONTRIBUTING.md、模块 pom.xml、现有实现和测试；不要仅凭通用经验推断项目约定。
• 若子目录存在更具体的 AGENTS.md，处理该目录文件时优先遵循距离目标文件最近的说明。
• 用户的明确要求优先于本文件；若要求与兼容性、安全性或仓库约定冲突，应先说明风险，不要静默偏离。
• 只修改完成任务所必需的文件，不处理无关格式、重构或历史遗留问题。

项目概览

• WxJava 是面向微信生态的 Java SDK，采用 Maven 多模块结构。
• 当前根项目要求 Java 8（maven.compiler.source 和 maven.compiler.target 均为 1.8）。除非任务明确要求升级，否则新增代码、依赖和 API 必须保持 Java 8 兼容。
• 主要 SDK 模块包括：
  • weixin-java-common：各模块共用的基础类型、工具、异常、HTTP 与配置能力。
  • weixin-java-mp：微信公众号。
  • weixin-java-miniapp：微信小程序。
  • weixin-java-pay：微信支付。
  • weixin-java-cp：企业微信。
  • weixin-java-open：微信开放平台。
  • weixin-java-channel：微信视频号、微信小店。
  • weixin-java-qidian：微信客服相关能力。
  • weixin-java-aispeech：微信智能语音。
  • weixin-graal：GraalVM 相关支持。
• 集成模块主要位于：
  • spring-boot-starters：Spring Boot Starter 及多账号 Starter。
  • solon-plugins：Solon 插件及多账号插件。
  • wx-java-bom：统一管理对外模块版本的 BOM。
• README.md 说明整体能力和使用方式，CONTRIBUTING.md 规定代码贡献要求，docs 保存补充文档。

开发流程

1. 确认任务涉及的微信产品和 Maven 模块，先查找同模块中的相似接口、Bean、实现类和测试。
2. 阅读目标模块及其父级 pom.xml，确认依赖、测试框架和已有实现方式。
3. 优先沿用现有的包结构、命名、序列化、HTTP 执行器、异常处理及配置模式。
4. 以最小变更完成任务；不要在功能修改中夹带依赖升级、全局格式化或无关重构。
5. 为修复或新增行为添加有针对性的测试，并先运行受影响模块的验证。
6. 交付前检查 diff、测试结果、兼容性和文档影响，明确报告未执行或无法执行的验证。

代码风格与兼容性

• 遵循 .editorconfig：使用空格缩进、缩进宽度为 2、UTF-8、LF、文件末尾保留换行，并清除非 Markdown 文件的行尾空格。
• 保持目标文件现有代码风格；避免仅为个人偏好调整 import、换行、注释或成员顺序。
• 不使用 Java 9 及以上语言特性或仅在新版本 JDK 中存在的 API。
• 项目使用 Lombok；新增或修改 Lombok 用法时遵循相邻代码模式，不要在同一变更中无理由改写为手工样板代码。
• 公共 API、序列化字段、枚举值、常量、默认实现和依赖范围都可能影响下游用户，修改时优先保持源码、二进制和行为兼容。
• 不要随意改变已有异常类型、空值语义、默认 HTTP 客户端、JSON/XML 映射或配置加载行为。
• 新增依赖前先确认现有依赖能否满足需求；依赖版本应在合适的父 POM 或 BOM 中统一管理，避免模块间版本漂移。

API 与实现约定

• 对接微信接口时，以对应产品的官方接口定义和仓库内现有同类实现为依据，核对请求路径、HTTP 方法、字段名、必填项和返回结构。
• Java 字段名可以符合项目命名习惯，但传输层字段名必须与微信接口保持一致；需要时使用项目现有的 Gson、Jackson 或 XStream 映射方式。
• 新增 Service API 时同步检查接口、实现类、请求/响应 Bean、URL 常量、序列化适配器和测试是否都需要更新。
• 涉及多个 HTTP 客户端实现时，保持 Apache HttpClient、HttpComponents、OkHttp 和 Jodd 等现有实现的能力一致；不要只修复其中一种而遗漏其他可选实现。
• 涉及 Starter 或插件时，检查单账号与多账号版本以及自动配置、配置属性和示例测试是否需要同步。
• 公共方法需要清晰的 Javadoc，至少准确描述参数、返回值、异常和必要约束；不要编写与实现不一致的模板化注释。
• 不吞掉异常，不使用空 catch，不在日志中泄露 token、secret、密钥、签名原文或用户敏感数据。