企业微信通讯录同步服务的增量更新与冲突解决算法

同步场景与核心挑战

在 SaaS 系统对接企业微信时，需将外部 HR 系统（如本地数据库）的组织架构、员工信息同步至企业微信。全量同步效率低、API 调用成本高。增量同步通过比对变更记录，仅同步差异数据。但面临两大问题：

双向修改冲突：HR 系统修改了员工姓名，同时管理员在企业微信后台也做了修改；
时序不一致 ：本地记录的更新时间戳与企业微信 update_time 存在偏差。

因此，需设计基于版本向量（Version Vector） 与最后写入胜出（LWW） 的冲突解决机制。

数据模型与版本控制

为用户实体增加版本字段：

java 复制代码

package wlkankan.cn.model;

import java.time.Instant;

public class Employee {
    private String userId;          // 企业微信 userid
    private String name;
    private String mobile;
    private Long departmentId;
    private Instant localUpdateTime; // 本地最后修改时间
    private Long wecomVersion;       // 企业微信返回的 version（整型递增）
    
    // standard getters/setters
}

企业微信用户接口返回 version 字段（如 "version": 1709234567），每次变更递增，可作为乐观锁依据。

增量比对算法

同步流程分三步：拉取企业微信最新状态 → 比对本地变更 → 执行合并或覆盖。

java 复制代码

package wlkankan.cn.sync;

import wlkankan.cn.model.Employee;
import wlkankan.cn.repo.EmployeeRepository;
import wlkankan.cn.wecom.WecomClient;

import java.util.*;

public class IncrementalSyncService {

    public void syncDepartmentAndUsers(String corpId) {
        // 1. 获取企业微信当前全量用户（带 version）
        List<WecomUser> wecomUsers = WecomClient.listAllUsers(corpId);
        Map<String, WecomUser> wecomMap = wecomUsers.stream()
            .collect(Collectors.toMap(WecomUser::getUserId, u -> u));

        // 2. 获取本地所有员工
        List<Employee> localEmployees = EmployeeRepository.findByCorpId(corpId);
        Map<String, Employee> localMap = localEmployees.stream()
            .collect(Collectors.toMap(Employee::getUserId, e -> e));

        // 3. 合并处理
        for (String userId : unionKeys(wecomMap.keySet(), localMap.keySet())) {
            WecomUser remote = wecomMap.get(userId);
            Employee local = localMap.get(userId);

            if (local == null) {
                // 企业微信有，本地无 → 新增
                handleNewUser(remote);
            } else if (remote == null) {
                // 本地有，企业微信无 → 删除（或标记离职）
                handleDeletedUser(local);
            } else {
                // 双方存在 → 冲突检测
                resolveConflict(local, remote);
            }
        }
    }

    private Set<String> unionKeys(Set<String> a, Set<String> b) {
        Set<String> union = new HashSet<>(a);
        union.addAll(b);
        return union;
    }
}

冲突解决策略：LWW + 版本优先

采用以下规则：

若本地 localUpdateTime > 企业微信 update_time，且本地 version 未落后，则推送本地变更；
若企业微信 version > 本地记录的 wecomVersion，则拉取远程覆盖本地；
若双方同时变更（版本均更新），以HR 系统为权威源，强制覆盖企业微信。

java 复制代码

private void resolveConflict(Employee local, WecomUser remote) {
    // 场景1: 本地未变更，远程已更新 → 拉取
    if (local.getWecomVersion() != null && remote.getVersion() > local.getWecomVersion()) {
        if (!isLocalModifiedAfter(local, remote.getUpdateTime())) {
            updateLocalFromRemote(local, remote);
            return;
        }
    }

    // 场景2: 本地已变更，远程未变（或版本未增）→ 推送
    if (isLocalModifiedAfter(local, remote.getUpdateTime())) {
        pushLocalToWecom(local);
        return;
    }

    // 场景3: 双方同时变更 → 以本地 HR 为准（业务策略）
    if (local.getWecomVersion() != null && remote.getVersion() > local.getWecomVersion()
        && isLocalModifiedAfter(local, remote.getUpdateTime())) {
        wlkankan.cn.log.Logger.warn("Conflict detected for user {}, overriding WeCom with HR data", local.getUserId());
        pushLocalToWecom(local);
    }
}

private boolean isLocalModifiedAfter(Employee local, Long remoteUpdateTime) {
    if (local.getLocalUpdateTime() == null) return false;
    return local.getLocalUpdateTime().toEpochMilli() > remoteUpdateTime * 1000L;
}

原子化同步与幂等保障

为避免部分失败导致状态不一致，每个用户操作需幂等：

java 复制代码

private void pushLocalToWecom(Employee emp) {
    try {
        WecomClient.updateUser(emp.getCorpId(), buildWecomUpdateRequest(emp));
        // 成功后更新本地 version 和时间
        emp.setWecomVersion(WecomClient.getUser(emp.getCorpId(), emp.getUserId()).getVersion());
        emp.setLocalUpdateTime(Instant.now());
        EmployeeRepository.save(emp);
    } catch (WecomApiException e) {
        if (e.getErrorCode() == 60104) { // userid 不存在
            WecomClient.createUser(emp.getCorpId(), buildWecomCreateRequest(emp));
            // 重新获取 version
            Long newVer = WecomClient.getUser(emp.getCorpId(), emp.getUserId()).getVersion();
            emp.setWecomVersion(newVer);
            EmployeeRepository.save(emp);
        } else {
            throw e;
        }
    }
}

性能优化：分页与并发

企业微信 API 限制单次最多 1000 用户，需分页拉取；同时可按部门并发同步：

java 复制代码

public List<WecomUser> listAllUsers(String corpId) {
    List<WecomUser> all = new ArrayList<>();
    String nextCursor = "";
    do {
        WecomUserListResponse resp = WecomClient.getUsersPage(corpId, nextCursor, 1000);
        all.addAll(resp.getUsers());
        nextCursor = resp.getNextCursor();
    } while (nextCursor != null && !nextCursor.isEmpty());
    return all;
}

配合 CompletableFuture 实现多部门并行同步：

java 复制代码

List<CompletableFuture<Void>> futures = deptIds.stream()
    .map(deptId -> CompletableFuture.runAsync(() -> syncDepartment(deptId), executor))
    .collect(Collectors.toList());
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();

该方案通过精确的版本比对 与明确的冲突仲裁规则，实现高效、可靠的企业微信通讯录增量同步，适用于大规模多租户 SaaS 场景。