fix(synchronizer-feishu): 用户同步 NPE 因 status 字段缺失，需判空保护

[float0108]

问题描述

MaxKey 管理端「同步器 → 飞书」点击“同步”时：

• 部门能正常同步，但成员（用户）全部同步失败；
• 前端提示“操作失败”，控制台报 Cannot read properties of undefined (reading 'refresh')；
• 后端日志：

java.lang.NullPointerException: Cannot invoke "org.dromara.maxkey.synchronizer.feishu.entity.FeishuUserStatus.isIs_activated()"
because the return value of "org.dromara.maxkey.synchronizer.feishu.entity.FeishuUsers.getStatus()" is null
    at org.dromara.maxkey.synchronizer.feishu.FeishuUsersService.buildUserInfoByFieldMapper(FeishuUsersService.java:153)
    at org.dromara.maxkey.synchronizer.feishu.FeishuUsersService.sync(FeishuUsersService.java:70)

复现步骤

1. 飞书开放平台创建应用，配置 contact:user.base:readonly（及所需通讯录权限）并发布上线；
2. 在 MaxKey 飞书同步器中填写 App ID / Secret；
3. 执行“立即同步”。Token 获取正常，部门可拉到，执行到用户同步时 NPE。

根因

MaxKey 4.1.12 同步用户调用的是：

GET https://open.feishu.cn/open-apis/contact/v3/users/find_by_department?department_id=<open_department_id>&page_size=50

该 v3 接口当前返回的用户对象不包含 status 字段，实际返回形如：

{
  "code": 0,
  "data": {
    "items": [
      {
        "name": "...",
        "email": "...",
        "employee_no": "...",
        "open_id": "...",
        "union_id": "...",
        "user_id": "..."
      }
    ]
  }
}

而 FeishuUsersService.buildUserInfoByFieldMapper（第 153 行）直接解引用了 status，未判空：

if (user.getStatus().isIs_activated()) {
    userInfo.setStatus(1);   // 在职
} else {
    userInfo.setStatus(2);   // 离职/未激活
}

getStatus() 返回 null → isIs_activated() NPE → 用户同步中断。

建议修复

请官方对用户对象做空值保护，例如：

FeishuUserStatus status = user.getStatus();
boolean activated = (status != null && status.isIs_activated());
userInfo.setStatus(activated ? 1 : 2);

并明确 status 缺失（该接口不返回）时的默认值——当前我们按“未激活”（status=2）处理。

影响范围 / 备注

• 版本：maxkey-mgt + maxkey-synchronizer-feishu 4.1.12（maxkeytop/maxkey-mgt:latest）；
• 仅在 users/find_by_department 这种“精简字段”接口下触发；若改用含 status 的完整用户接口（如 users/{user_id}）则不会 NPE；
• 因为要验证能否仅依赖该接口配置，是否应同步该精简接口回归更多字段（status）也可一并评估。

[float0108]

临时规避方案（字节码补丁）——供维护者复现验证

说明：运行时字节码补丁（工作区规避方案），不改动上游源码。现象复现依赖飞书线上 API，以下给出可完整复现/审查的构造过程。

---

1. 素材

从 maxkeytop/maxkey-mgt:latest 容器取出：

• 启动 jar：/maxkey-mgt/maxkey-mgt-boot.jar
• 目标类（位于 BOOT-INF/lib/maxkey-synchronizer-feishu-4.1.12.jar）：

  org/dromara/maxkey/synchronizer/feishu/FeishuUsersService
  

• 目标方法：buildUserInfoByFieldMapper（第 153 行，NPE 点）

原始逻辑：

if (user.getStatus().isIs_activated()) {   // getStatus() 可能为 null → NPE
    userInfo.setStatus(1);
} else {
    userInfo.setStatus(2);
}

---

2. 补丁逻辑（ASM 注入）

注入后等效：

FeishuUserStatus st = user.getStatus();
if (st == null) {
    userInfo.setStatus(2);   // 缺省未激活
} else {
    userInfo.setStatus(st.isIs_activated() ? 1 : 2);
}

关键踩坑点：

• ClassWriter 必须启用 COMPUTE_FRAMES，且需重写 getCommonSuperClass 用真实类加载器（加载全部依赖 jar），否则生成的 StackMapFrame 会导致 VerifyError，Spring 启动失败。
• 用 -Xverify:all + 真实依赖 classpath 加载补丁类，确认输出 LOAD_OK 再使用。
• 不可在 classpath* 扫描层替换，否则 FeishuSynchronizerService 等 @Service bean 会重复注册/丢失。

---

3. 部署：Java Agent（免改 jar）

不重打包 BOOT-INF/lib（会破坏 Spring Boot 嵌套 jar 的 classpath 扫描），改用 -javaagent 在类加载时整体替换。

Agent 核心代码：

import java.lang.instrument.*;
import java.security.ProtectionDomain;

public class FeishuPatchAgent {
    public static void premain(String args, Instrumentation inst) throws Exception {
        final byte[] patched = FeishuPatchAgent.class
                .getResourceAsStream("/patch/feishu-users-service.bin").readAllBytes();
        inst.addTransformer(new ClassFileTransformer() {
            public byte[] transform(ClassLoader ld, String cn, Class<?> c,
                                    ProtectionDomain d, byte[] buf) {
                return "org/dromara/maxkey/synchronizer/feishu/FeishuUsersService".equals(cn) ? patched : null;
            }
        });
    }
}

⚠️ 补丁字节必须打包为 .bin（非 .class）存放，否则会被系统类加载器提前加载，依赖的 ISynchronizerService 在嵌套 jar 内解析不到 → NoClassDefFoundError。

MANIFEST.MF：

Premain-Class: FeishuPatchAgent
Can-Redefine-Classes: true
Can-Retransform-Classes: true

---

4. 镜像改动

FROM maxkeytop/maxkey-mgt:latest
COPY FeishuPatchAgent.jar /patch/FeishuPatchAgent.jar
CMD ["/bin/sh","-c","sleep 60; java -javaagent:/patch/FeishuPatchAgent.jar -jar maxkey-mgt-boot.jar $JAVA_OPTS"]

验证结果： 补丁后 buildUserInfoByFieldMapper 对 status 为 null 的用户改走未激活分支，飞书成员可正常入库，同步不再中断。

---

产出物清单

组件	说明
PatchFeishu2.java	ASM 注入器（生成补丁字节）
FeishuPatchAgent.java / .jar	Java Agent 载体
maxkey-mgt:feishu-fix-agent	补丁后镜像（可选）

---

若官方计划在下个版本修复，此 Agent 方案仅作临时规避参考；修复后即可移除。

---