指南
功能使用

企业IM集成

# 什么是 yt4j-im？

yt4j-im 是 yt4j 项目提供的企业即时通讯集成插件，用于统一对接各种企业 IM 平台，实现组织架构同步和消息推送功能。

# 设计理念

# 1. 接口抽象

通过定义统一的 IM 接口抽象，实现不同 IM 平台的解耦：

yt4j-im-api: 定义统一的 IM 接口规范
yt4j-feishu: 飞书 IM 的具体实现

# 2. 可插拔设计

通过 Spring 自动装配，按需引入 IM 实现
支持同时对接多个 IM 平台
便于扩展其他 IM 平台（钉钉、企业微信等）

# 模块结构

yt4j-plugin
└─ yt4j-im                  # 企业IM插件
   ├─ yt4j-im-api          # IM接口定义
   │  ├─ model             # 数据模型
   │  ├─ service           # 服务接口
   │  └─ constants         # 常量定义
   └─ yt4j-feishu          # 飞书IM实现
      ├─ config            # 配置类
      ├─ service           # 服务实现
      └─ client            # API客户端

# 核心功能

# 1. 部门同步

从 IM 平台同步部门组织架构
支持增量同步和全量同步
自动维护部门层级关系

# 2. 用户同步

从 IM 平台同步用户信息
关联部门关系
支持用户状态同步

# 3. 消息推送

发送文本消息
发送卡片消息
支持群消息和私消息

# 飞书集成

# 配置依赖

在 pom.xml 中添加飞书 IM 依赖：

<dependency>
    <groupId>cn.yt4j</groupId>
    <artifactId>yt4j-feishu</artifactId>
</dependency>

# 配置文件

在 application.yml 或 Nacos 配置中心添加配置：

yt4j:
  im:
    feishu:
      enabled: true                    # 是否启用飞书集成
      app-id: your_app_id             # 飞书应用ID
      app-secret: your_app_secret     # 飞书应用密钥
      encrypt-key: your_encrypt_key   # 加密Key（可选）
      verification-token: your_token  # 验证Token（可选）
      # API地址（可选，默认为官方地址）
      api-url: https://open.feishu.cn

# 获取飞书凭证

登录飞书开放平台 (opens new window)
创建企业自建应用
获取 App ID 和 App Secret
开启必要的权限：
- 获取部门基本信息
- 获取部门ID列表
- 获取部门直属成员
- 获取用户基本信息
- 发送消息

# 使用示例

# 1. 注入 IM 服务

@Service
public class UserService {

    @Autowired
    private ImService imService;  // 自动注入飞书实现

    public void syncUsers() {
        // 同步用户
    }
}

# 2. 同步部门

// 全量同步部门
List<ImDept> depts = imService.syncDepartments();

// 增量同步（需要支持增量查询的IM平台）
List<ImDept> depts = imService.syncDepartmentsIncremental(lastSyncTime);

# 3. 同步用户

// 同步所有用户
List<ImUser> users = imService.syncUsers();

// 按部门同步用户
List<ImUser> users = imService.syncUsersByDept(deptId);

# 4. 发送消息

// 发送文本消息
ImMessage message = ImMessage.builder()
    .msgType(ImMessageType.TEXT)
    .content("Hello, 飞书")
    .userId("ou_xxxx")  // 用户ID
    .build();
imService.sendMessage(message);

// 发送卡片消息（飞书卡片）
ImMessage cardMessage = ImMessage.builder()
    .msgType(ImMessageType.INTERACTIVE)
    .content(cardJson)
    .userId("ou_xxxx")
    .build();
imService.sendMessage(cardMessage);

# 数据模型

# ImDept（部门）

public class ImDept {
    private String deptId;      // 部门ID
    private String name;        // 部门名称
    private String parentId;    // 父部门ID
    private Integer level;      // 部门层级
    private Integer sort;       // 排序
    // ... 其他字段
}

# ImUser（用户）

public class ImUser {
    private String userId;      // 用户ID
    private String name;        // 姓名
    private String email;       // 邮箱
    private String mobile;      // 手机号
    private String deptId;      // 部门ID
    private String avatar;      // 头像
    private Integer status;     // 状态：1-激活，2-禁用
    // ... 其他字段
}

# ImMessage（消息）

public class ImMessage {
    private String msgId;       // 消息ID
    private ImMessageType type; // 消息类型
    private String content;     // 消息内容
    private String userId;      // 接收用户ID
    private String chatId;      // 群聊ID
    // ... 其他字段
}

# 定时同步

配置定时任务，定期同步组织架构：

@Component
public class ImSyncJob {

    @Autowired
    private ImService imService;

    @Autowired
    private UserService userService;

    @Autowired
    private DeptService deptService;

    // 每天凌晨2点执行
    @Scheduled(cron = "0 0 2 * * ?")
    public void syncFromIm() {
        log.info("开始同步IM组织架构");

        try {
            // 1. 同步部门
            List<ImDept> depts = imService.syncDepartments();
            deptService.syncImDepts(depts);

            // 2. 同步用户
            List<ImUser> users = imService.syncUsers();
            userService.syncImUsers(users);

            log.info("IM组织架构同步完成");
        } catch (Exception e) {
            log.error("IM组织架构同步失败", e);
        }
    }
}

# 扩展其他 IM 平台

# 1. 创建实现模块

在 yt4j-plugin 下创建新模块，如 yt4j-dingtalk（钉钉）：

<dependency>
    <groupId>cn.yt4j</groupId>
    <artifactId>yt4j-im-api</artifactId>
</dependency>

# 2. 实现接口

@Service
@ConditionalOnProperty(name = "yt4j.im.dingtalk.enabled", havingValue = "true")
public class DingtalkImServiceImpl implements ImService {

    @Autowired
    private DingtalkProperties properties;

    @Override
    public List<ImDept> syncDepartments() {
        // 调用钉钉API同步部门
        return dingtalkClient.getDepartments();
    }

    @Override
    public List<ImUser> syncUsers() {
        // 调用钉钉API同步用户
        return dingtalkClient.getUsers();
    }

    @Override
    public void sendMessage(ImMessage message) {
        // 调用钉钉API发送消息
        dingtalkClient.send(message);
    }
}

# 3. 配置类

@Configuration
@ConfigurationProperties(prefix = "yt4j.im.dingtalk")
public class DingtalkProperties {
    private Boolean enabled = false;
    private String appKey;
    private String appSecret;
    private String agentId;
    // getters and setters
}

# 4. 配置文件

yt4j:
  im:
    dingtalk:
      enabled: true
      app-key: your_app_key
      app-secret: your_app_secret
      agent-id: your_agent_id

# 计划支持的平台

[ ] 钉钉
[ ] 企业微信
[ ] Slack
[ ] Microsoft Teams
[ ] Lark（飞书国际版）

# 最佳实践

# 1. 分离 IM 用户和系统用户

// IM用户和系统用户分开存储，通过映射表关联
public class User {
    private Long id;           // 系统用户ID
    private String imUserId;   // IM用户ID
    private String imType;     // IM类型：feishu、dingtalk等
    // ...
}

# 2. 同步策略

全量同步: 适用于初始化或定期全量更新
增量同步: 适用于高频同步，减少数据传输
手动触发: 适用于临时需求

# 3. 错误处理

try {
    imService.syncDepartments();
} catch (ImApiException e) {
    // API调用失败
    log.error("同步部门失败，错误码：{}，错误信息：{}", e.getCode(), e.getMessage());
} catch (ImDataException e) {
    // 数据处理失败
    log.error("处理部门数据失败", e);
}

# 4. 缓存优化

@Cacheable(value = "im:dept", key = "'tree'")
public List<ImDept> getDeptTree() {
    return imService.syncDepartments();
}

# 参考资料

上次更新: 2026/01/04, 09:28:19

← 流程编排