文档：明确说明 wx-java-cp-multi-spring-boot-starter 中 corp-secret 的配置方式 by Copilot · Pull Request #3957 · binarywang/WxJava

Copilot · 2026-04-07T09:14:50Z

企业微信不同功能模块使用不同的 Secret，每种 Secret 仅对对应模块的接口有权限。现有文档未说明这一机制，导致用户困惑：自建应用 Secret 无法更新部门，通讯录同步 Secret 调用应用接口报错。

变更内容

README（Spring Boot Starter + Solon 插件）

新增"关于 corp-secret 的说明"章节，表格列出各类 Secret 的用途、获取位置及是否需要 agent-id
配置示例同时展示自建应用条目（含 agent-id）与通讯录同步条目（不填 agent-id）的共存写法
代码示例演示通过不同 tenantId 分别调用两种 Secret 对应的服务

WxCpSingleProperties Javadoc

corpSecret 字段注释说明各 Secret 类型及其 agentId 要求
agentId 字段注释说明自建应用必填、通讯录同步无需填写

AbstractWxCpConfiguration 代码注释

agentId 唯一性校验处增加注释，说明同一 corpId 下可配置多条目以使用不同 Secret 的设计意图

配置示例

# 自建应用：需填 agent-id
wx.cp.corps.app1.corp-id = xxx
wx.cp.corps.app1.corp-secret = <自建应用Secret>
wx.cp.corps.app1.agent-id = 1000001

# 通讯录同步：不需要 agent-id
wx.cp.corps.contact.corp-id = xxx
wx.cp.corps.contact.corp-secret = <通讯录同步Secret>

// 自建应用接口
wxCpMultiServices.getWxCpService("app1").getUserService().getUserId("xxx");

// 通讯录管理接口（部门增删改查）
wxCpMultiServices.getWxCpService("contact").getDepartmentService().update(dept);

- 增加 corp-secret 类型说明章节（自建应用/通讯录同步/客户联系） - 更新配置示例展示多种 Secret 同时使用的方式 - 改善 WxCpSingleProperties 的 Javadoc - 在 AbstractWxCpConfiguration 中增加设计意图注释 Agent-Logs-Url: https://github.com/binarywang/WxJava/sessions/c3b71887-e0c8-4297-b740-a39dc15c7d69 Co-authored-by: binarywang <1343140+binarywang@users.noreply.github.com>

chatgpt-codex-connector · 2026-04-10T08:51:41Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

augmentcode · 2026-04-10T08:55:08Z

🤖 Augment PR Summary

Summary: Clarifies how to configure WeCom (企业微信) multi-account CP starters/plugins when different features require different corp-secret values.

Changes:

Adds a “关于 corp-secret 的说明” section to both Spring Boot starter and Solon plugin READMEs, including a table mapping Secret type → where to find it → whether agent-id is needed.
Updates configuration examples to show coexisting entries for a custom app Secret (with agent-id) and address-book sync Secret (without agent-id).
Updates sample code to demonstrate selecting different tenant keys (app1 / contact) to call module-specific services.
Expands Javadoc on WxCpSingleProperties (corpSecret, agentId) to document Secret scope and AgentId requirements.
Adds clarifying comments in AbstractWxCpConfiguration explaining why agentId uniqueness is enforced per corpId to avoid token/ticket cache collisions.

Technical Notes: This PR is documentation/comment-only; runtime behavior is unchanged, but the docs now better describe permission boundaries between Secrets.

_{🤖 Was this summary useful? React with 👍 or 👎}

augmentcode

Review completed. 3 suggestions posted.

Comment augment review to trigger a new review at any time.

augmentcode · 2026-04-10T08:55:10Z

spring-boot-starters/wx-java-cp-multi-spring-boot-starter/README.md

+    // 通讯录同步 Secret 具有部门/成员增删改查等权限
+    WxCpService contactService = wxCpMultiServices.getWxCpService("contact");
+    WxCpDepartmentService departmentService = contactService.getDepartmentService();
+    departmentService.update(department);


spring-boot-starters/wx-java-cp-multi-spring-boot-starter/README.md:96 这里示例调用 departmentService.update(department) 但 department 变量/类型在示例中未声明，读者直接复制会卡住。可以考虑补充部门对象的创建与其对应类型说明。

Severity: low

Other Locations

solon-plugins/wx-java-cp-multi-solon-plugin/README.md:96

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augmentcode · 2026-04-10T08:55:10Z

spring-boot-starters/wx-java-cp-multi-spring-boot-starter/README.md

+> - 使用自建应用 Secret + agent-id 可以获取部门列表，但**无法更新部门**（因为写接口需要通讯录同步权限）
+> - 使用通讯录同步 Secret 可以同步部门，但**调用某些需要 agent-id 的应用接口会报错**
+
+如需同时使用多种权限范围，可在 `wx.cp.corps` 下配置多个条目，每个条目使用对应权限的 Secret，通过不同的 `tenantId` 区分后使用。


spring-boot-starters/wx-java-cp-multi-spring-boot-starter/README.md:23 这里说可通过不同 tenantId 配置多个条目同时使用多种 Secret，但当前实现会将 agentId == null 统一归为 0 并禁止同一 corpId 下出现多个 null。若同时配置多个“不需要 agent-id”的 Secret（如通讯录同步 + 客户联系）会触发唯一性校验异常，文档可提示这一限制。

Severity: medium

Other Locations

solon-plugins/wx-java-cp-multi-solon-plugin/README.md:23

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augmentcode · 2026-04-10T08:55:10Z

...a/com/binarywang/solon/wxjava/cp_multi/configuration/services/AbstractWxCpConfiguration.java

    /**
     * 校验同一个企业下，agentId 是否唯一，避免使用 redis 缓存 token、ticket 时错乱。
     *
+     * <p>同一企业（corpId 相同）下可配置多个条目以使用不同的权限 Secret，例如：


AbstractWxCpConfiguration.java:40 这段 Javadoc 里用  包裹了一个 <ul>（块级元素），在启用 doclint 时可能产生无效 HTML 的告警甚至构建失败。可以考虑调整注释的 HTML 结构，避免  直接包含 <ul>。

Severity: low

Other Locations

spring-boot-starters/wx-java-cp-multi-spring-boot-starter/src/main/java/com/binarywang/spring/starter/wxjava/cp/configuration/services/AbstractWxCpConfiguration.java:43

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

Copilot

Pull request overview

本 PR 面向 wx-java-cp-multi-* 的多租户配置场景，补充说明企业微信不同功能模块需要使用不同 corp-secret（权限范围不同），以减少用户在“自建应用 / 通讯录同步 / 客户联系”等 Secret 混用时产生的困惑。

Changes:

在 Spring Boot Starter 与 Solon 插件 README 增加“关于 corp-secret 的说明”章节，给出对照表、常见问题与多条目配置示例。
为两套 WxCpSingleProperties 增强 corpSecret / agentId 的 Javadoc 说明。
在两套 AbstractWxCpConfiguration 的 agentId 唯一性校验处补充设计意图注释。

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
spring-boot-starters/wx-java-cp-multi-spring-boot-starter/src/main/java/com/binarywang/spring/starter/wxjava/cp/properties/WxCpSingleProperties.java	补充 corpSecret/agentId 的权限范围与配置要求说明（Javadoc）。
spring-boot-starters/wx-java-cp-multi-spring-boot-starter/src/main/java/com/binarywang/spring/starter/wxjava/cp/configuration/services/AbstractWxCpConfiguration.java	在 agentId 唯一性校验处增加注释解释多 Secret 条目设计。
spring-boot-starters/wx-java-cp-multi-spring-boot-starter/README.md	新增 corp-secret 说明章节与多条目配置/调用示例。
solon-plugins/wx-java-cp-multi-solon-plugin/src/main/java/com/binarywang/solon/wxjava/cp_multi/properties/WxCpSingleProperties.java	同步补充 corpSecret/agentId 说明（Javadoc）。
solon-plugins/wx-java-cp-multi-solon-plugin/src/main/java/com/binarywang/solon/wxjava/cp_multi/configuration/services/AbstractWxCpConfiguration.java	同步增加 agentId 唯一性校验相关注释。
solon-plugins/wx-java-cp-multi-solon-plugin/README.md	同步新增 corp-secret 说明章节与示例。

Copilot · 2026-04-10T08:55:43Z

...om/binarywang/spring/starter/wxjava/cp/configuration/services/AbstractWxCpConfiguration.java

+     * <p>同一企业（corpId 相同）下可配置多个条目以使用不同的权限 Secret，例如：
+     * <ul>
+     *   <li>自建应用条目：填写应用对应的 corpSecret 和 agentId</li>
+     *   <li>通讯录同步条目：填写通讯录同步 Secret，agentId 可不填（null）</li>
+     * </ul>
+     * 但同一 corpId 下不允许出现重复的 agentId（包括多个 null）。
+     * </p>


这里的 Javadoc 使用了  包裹 <ul>（...例如： 后紧跟 <ul>），在 HTML 语义上是非法结构，启用 doclint 时可能产生告警/失败。建议在 <ul> 前先结束 ，并在列表后再用新的  继续说明。

Suggested change

* 同一企业（corpId 相同）下可配置多个条目以使用不同的权限 Secret，例如：

* <ul>

* <li>自建应用条目：填写应用对应的 corpSecret 和 agentId</li>

* <li>通讯录同步条目：填写通讯录同步 Secret，agentId 可不填（null）</li>

* </ul>

* 但同一 corpId 下不允许出现重复的 agentId（包括多个 null）。

* 

* 同一企业（corpId 相同）下可配置多个条目以使用不同的权限 Secret，例如：

* <ul>

* <li>自建应用条目：填写应用对应的 corpSecret 和 agentId</li>

* <li>通讯录同步条目：填写通讯录同步 Secret，agentId 可不填（null）</li>

* </ul>

* 但同一 corpId 下不允许出现重复的 agentId（包括多个 null）。

Copilot · 2026-04-10T08:55:44Z

...om/binarywang/spring/starter/wxjava/cp/configuration/services/AbstractWxCpConfiguration.java

+     * 但同一 corpId 下不允许出现重复的 agentId（包括多个 null）。
+     * </p>


注释里说明“重复的 agentId（包括多个 null）”是对的，但当前唯一性校验实现用 null -> 0 做分组键，会把合法的 agentId=0 与 null 视为同一组并误判重复。建议改为对 null 使用不会与任何合法 agentId 冲突的哨兵值（例如 Integer.MIN_VALUE）或改为按 Objects.toString(agentId, "null") 分组。

Copilot · 2026-04-10T08:55:44Z

...a/com/binarywang/solon/wxjava/cp_multi/configuration/services/AbstractWxCpConfiguration.java

+     * <p>同一企业（corpId 相同）下可配置多个条目以使用不同的权限 Secret，例如：
+     * <ul>
+     *   <li>自建应用条目：填写应用对应的 corpSecret 和 agentId</li>
+     *   <li>通讯录同步条目：填写通讯录同步 Secret，agentId 可不填（null）</li>
+     * </ul>
+     * 但同一 corpId 下不允许出现重复的 agentId（包括多个 null）。
+     * </p>


这里的 Javadoc 使用了  包裹 <ul>（...例如： 后紧跟 <ul>），在 HTML 语义上是非法结构，启用 doclint 时可能产生告警/失败。建议在 <ul> 前先结束 ，并在列表后再用新的  继续说明。

Suggested change

* 同一企业（corpId 相同）下可配置多个条目以使用不同的权限 Secret，例如：

* <ul>

* <li>自建应用条目：填写应用对应的 corpSecret 和 agentId</li>

* <li>通讯录同步条目：填写通讯录同步 Secret，agentId 可不填（null）</li>

* </ul>

* 但同一 corpId 下不允许出现重复的 agentId（包括多个 null）。

* 

* 同一企业（corpId 相同）下可配置多个条目以使用不同的权限 Secret，例如：

* <ul>

* <li>自建应用条目：填写应用对应的 corpSecret 和 agentId</li>

* <li>通讯录同步条目：填写通讯录同步 Secret，agentId 可不填（null）</li>

* </ul>

* 但同一 corpId 下不允许出现重复的 agentId（包括多个 null）。

Copilot · 2026-04-10T08:55:45Z

...a/com/binarywang/solon/wxjava/cp_multi/configuration/services/AbstractWxCpConfiguration.java

+     * 但同一 corpId 下不允许出现重复的 agentId（包括多个 null）。
+     * </p>


注释里说明“重复的 agentId（包括多个 null）”是对的，但当前唯一性校验实现用 null -> 0 做分组键，会把合法的 agentId=0 与 null 视为同一组并误判重复。建议改为对 null 使用不会与任何合法 agentId 冲突的哨兵值（例如 Integer.MIN_VALUE）或改为按 Objects.toString(agentId, "null") 分组。

Copilot · 2026-04-10T08:55:45Z

spring-boot-starters/wx-java-cp-multi-spring-boot-starter/README.md

+    // 使用通讯录同步的 WxCpService（对应 corp-secret 为通讯录同步 Secret）
+    // 通讯录同步 Secret 具有部门/成员增删改查等权限
+    WxCpService contactService = wxCpMultiServices.getWxCpService("contact");
+    WxCpDepartmentService departmentService = contactService.getDepartmentService();
+    departmentService.update(department);


此处示例代码里 departmentService.update(department); 的 department 变量未定义，示例无法直接编译/运行。建议补充 WxCpDepart 的构造/赋值示例（至少包含要更新的部门 id 与字段），或改成更明确的伪代码占位。

Copilot · 2026-04-10T08:55:45Z

solon-plugins/wx-java-cp-multi-solon-plugin/README.md

+    // 使用通讯录同步的 WxCpService（对应 corp-secret 为通讯录同步 Secret）
+    // 通讯录同步 Secret 具有部门/成员增删改查等权限
+    WxCpService contactService = wxCpMultiServices.getWxCpService("contact");
+    WxCpDepartmentService departmentService = contactService.getDepartmentService();
+    departmentService.update(department);


此处示例代码里 departmentService.update(department); 的 department 变量未定义，示例无法直接编译/运行。建议补充 WxCpDepart 的构造/赋值示例（至少包含要更新的部门 id 与字段），或改成更明确的伪代码占位。

Copilot · 2026-04-10T08:55:45Z

spring-boot-starters/wx-java-cp-multi-spring-boot-starter/README.md

+> - 使用通讯录同步 Secret 可以同步部门，但**调用某些需要 agent-id 的应用接口会报错**
+
+如需同时使用多种权限范围，可在 `wx.cp.corps` 下配置多个条目，每个条目使用对应权限的 Secret，通过不同的 `tenantId` 区分后使用。
+


这里提到“可配置多个条目…通讯录同步条目不填 agent-id”，同时表格中也有多个“不填 agent-id”的 Secret 类型。需要补充说明：当前 starter/插件实现会校验同一 corp-id 下 agent-id 必须唯一，且 只能有一个条目 agent-id 为空（否则 token/ticket 缓存 key 会冲突并直接抛异常）。否则用户可能按表格同时配置多个不填 agent-id 的条目而启动失败。

Suggested change

> **配置限制说明**：

> - 当前 starter/插件实现会校验：同一 `corp-id` 下，`agent-id` **必须唯一**

> - 同一 `corp-id` 下，**只能有一个条目不填 `agent-id`**

> - 否则会因为 token/ticket 缓存 key 冲突而在启动时直接抛异常

>

> 因此，像“通讯录同步 Secret”“客户联系 Secret”这类通常不填写 `agent-id` 的配置，**不能**在同一个 `corp-id` 下同时配置多个都为空 `agent-id` 的条目；如确有多个条目，请确保其中最多只有一个未填写 `agent-id``

Copilot · 2026-04-10T08:55:46Z

solon-plugins/wx-java-cp-multi-solon-plugin/README.md

+> - 使用通讯录同步 Secret 可以同步部门，但**调用某些需要 agent-id 的应用接口会报错**
+
+如需同时使用多种权限范围，可在 `wx.cp.corps` 下配置多个条目，每个条目使用对应权限的 Secret，通过不同的 `tenantId` 区分后使用。
+


这里提到“可配置多个条目…通讯录同步条目不填 agent-id”，同时表格中也有多个“不填 agent-id”的 Secret 类型。需要补充说明：当前 starter/插件实现会校验同一 corp-id 下 agent-id 必须唯一，且 只能有一个条目 agent-id 为空（否则 token/ticket 缓存 key 会冲突并直接抛异常）。否则用户可能按表格同时配置多个不填 agent-id 的条目而启动失败。

Suggested change

> **注意**：

> 当前 starter/插件实现会校验同一 `corp-id` 下的 `agent-id` **必须唯一**，并且 **只能有一个条目不填写 `agent-id`**。

> 如果在同一 `corp-id` 下同时配置多个未填写 `agent-id` 的条目，会因 token/ticket 缓存 key 冲突而在启动时直接抛异常。

Initial plan

31ee4c0

Copilot AI assigned Copilot and binarywang Apr 7, 2026

Copilot started work on behalf of binarywang April 7, 2026 09:20 View session

Copilot AI linked an issue Apr 7, 2026 that may be closed by this pull request

wx-java-cp-multi-spring-boot-starter的crop-secret是使用的哪个 #3944

Open

Copilot AI changed the title ~~[WIP] Fix crop-secret usage for wx-java-cp-multi-spring-boot-starter~~ 文档：明确说明 wx-java-cp-multi-spring-boot-starter 中 corp-secret 的配置方式 Apr 7, 2026

Copilot finished work on behalf of binarywang April 7, 2026 09:31

Copilot AI requested a review from binarywang April 7, 2026 09:31

binarywang mentioned this pull request Apr 7, 2026

wx-java-cp-multi-spring-boot-starter的crop-secret是使用的哪个 #3944

Open

binarywang marked this pull request as ready for review April 10, 2026 08:51

Copilot AI review requested due to automatic review settings April 10, 2026 08:51

Copilot started reviewing on behalf of binarywang April 10, 2026 08:52 View session

augmentcode bot reviewed Apr 10, 2026

View reviewed changes

Copilot AI reviewed Apr 10, 2026

View reviewed changes

		* 但同一 corpId 下不允许出现重复的 agentId（包括多个 null）。
		* </p>

		> - 使用通讯录同步 Secret 可以同步部门，但调用某些需要 agent-id 的应用接口会报错

		如需同时使用多种权限范围，可在 `wx.cp.corps` 下配置多个条目，每个条目使用对应权限的 Secret，通过不同的 `tenantId` 区分后使用。

+> **配置限制说明**：
+> - 当前 starter/插件实现会校验：同一 `corp-id` 下，`agent-id` **必须唯一**
+> - 同一 `corp-id` 下，**只能有一个条目不填 `agent-id`**
+> - 否则会因为 token/ticket 缓存 key 冲突而在启动时直接抛异常
+>
+> 因此，像“通讯录同步 Secret”“客户联系 Secret”这类通常不填写 `agent-id` 的配置，**不能**在同一个 `corp-id` 下同时配置多个都为空 `agent-id` 的条目；如确有多个条目，请确保其中最多只有一个未填写 `agent-id``

+> **注意**：
+> 当前 starter/插件实现会校验同一 `corp-id` 下的 `agent-id` **必须唯一**，并且 **只能有一个条目不填写 `agent-id`**。
+> 如果在同一 `corp-id` 下同时配置多个未填写 `agent-id` 的条目，会因 token/ticket 缓存 key 冲突而在启动时直接抛异常。

Uh oh!

Conversation

Copilot AI commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

变更内容

配置示例

Uh oh!

chatgpt-codex-connector bot commented Apr 10, 2026

Uh oh!

augmentcode bot commented Apr 10, 2026

Uh oh!

augmentcode bot left a comment

Choose a reason for hiding this comment

Uh oh!

augmentcode bot Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

augmentcode bot Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

augmentcode bot Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Apr 7, 2026 •

edited

Loading