企业微信客户 API 怎么用

先分清三种「人」，再决定用哪套读写

「客户」这个词在企业微信语境里至少压着三种对象，混着用是第一版最常见的返工来源。

• 内部成员：组织里的员工。生命周期跟着企业通讯录走，稳定、可枚举、变更低频。
• 外部联系人，也就是通常说的客户：由某个成员添加而来。关键在于它是「某个成员视角下的一个联系人」，同一个真人被三个成员各加过一次，就是三条互相独立的记录。
• 群成员：出现在某个外部群里的人。它和客户是两个集合，交集不完整 —— 群里的人未必是你的客户，你的客户也未必在任何群里。

判断很直接：这三者在数据模型里必须是三张表，中间靠映射关系连接，不要合并成一张「用户表」。合并的代价是每个查询都得带一个判别字段说明这行到底是什么，而且三者的可写字段、更新频率和失效语义完全不同，一张表意味着一套写入逻辑要同时伺候三种节奏。这一条和你走哪条接入路线无关，无论是官方开放平台还是 wecomapi 这类网关式接入，这三个集合的语义边界都一样。

读侧：分页是快照，翻页一定会漂

列表读取的本质，是对一个持续变化的集合做分页遍历。你翻到第 5 页时，第 1 页的内容可能已经变了：新客户插进来、老客户被移走、排序键被更新。结果是页间重复和页间漏读同时发生，而且数据量小的时候完全看不出来，等到客户上万才开始有人报「名单对不上」。

偏移量分页在这种场景下是最差的选择，任何一次插入或删除都会让后面所有页的边界整体位移。游标分页能挡掉大部分位移，但挡不住「游标指向的那条记录刚好被删了」这种情况。所以别指望换个分页方式就把问题解决掉，它只能把漂移的幅度压小。

工程上的取舍是明确的：宁可重复，不可漏读。前提是下游必须幂等 —— 同一个客户在一轮遍历里被处理两次不能产生任何副作用。做到这一条，分页漂移就从数据正确性问题降级成多花一点计算，这是能接受的代价；做不到，你的第一轮全量就会给一批人重复打标或重复发欢迎语。

还有一条容易忽略：不要边遍历边写入。翻页过程中给客户打标签会改变排序键，等于自己在推动漂移，而且这种自造的漂移比自然变更密集得多。正确顺序是先把整轮遍历跑完拿到完整名单，再统一进入写入阶段。多花一次内存，省掉一类查不出来的偶发问题。

写侧：写完立刻回读校验，是在给自己造 bug

第一版的经典写法是这样的：调写入接口，紧接着调读取接口，比对，不一致就重试。这段代码在演示环境百分之百通过，上生产之后会周期性地误判，而且失败率会随着并发量上升。

原因是写入路径和读取路径不保证在同一时刻看到同一份数据。写入返回成功只说明请求被受理，读侧看到新值可能要晚一点。你写的这段「校验」，实际测的是两条链路之间的时间差。

更麻烦的是它的失败方式：误判成失败，于是重试，于是同一个动作执行了两次。打标、改备注这类天然幂等的动作还好，「追加一条跟进记录」就是实打实的重复数据，而且这种重复不报错，只有一线看到两条一样的记录时才会有人发现。

正确的做法是把确认权交给事件：写入之后本地状态停在「已提交」，收到对应的变更事件才推进到「已确认」。回读不是不能做，是只能放在对账作业里做，并且允许一个明确的延迟窗口。

另外一条：写入尽量做成字段级的局部更新，不要拿一个完整对象整体覆盖。多个业务模块并发改同一个客户时，整体覆盖会用一份几秒前读出来的旧对象，把别人刚写进去的字段悄悄抹掉。这种覆盖不报错、不留痕，等发现时已经没法回溯是哪一次覆盖造成的。并发源往往不止你自己的服务：wecomapi 侧一个企业微信账号对应一个独立实例，工单系统、营销任务和人工后台常常共用同一个实例往同一批客户上写。所以串行化要做在自己的写入出口上 —— 按客户标识排队，比在几十个调用点上各加一把锁现实得多。

增量同步：事件优先，定时兜底

同步模式就三种，按客户规模选，别一上来就上最复杂的那个。

1. 1定时全量：几千客户以内完全能跑，最简单，也最不容易写错。缺点是调用量随规模线性增长，而且同步周期就是你的数据延迟下限。
2. 2纯事件增量：延迟低、调用量小，但它一定会漏 —— 事件会丢、会乱序，也会在你服务重启的那几分钟里投递失败。把它当唯一来源，缺口只会越攒越大，而且你不会知道缺了什么。
3. 3增量为主加低频对账：生产上唯一能长期跑的组合。事件负责让数据及时，对账负责让数据最终正确，两者目标不同，谁也别想替代谁。

触发上建议事件优先、定时兜底：用 wecomapi 的事件回调拿到客户侧的变更通知就立刻更新，定时任务只负责补漏。这比纯定时轮询省一大截调用量，延迟也从分钟级降到秒级，而定时任务的频率反而可以调低 —— 它的职责从「发现变更」变成了「确认没漏」。

水位线怎么定 —— 为什么不能用「上次同步完成的时刻」、为什么要往回退一个重叠窗口、为什么整轮成功才推进 —— 站内讲数据同步的那篇已经按通用形态拆过，这里不重复。客户这块只多一个前提：重叠窗口每轮都会重新带回一批已经处理过的记录，所以前面说的幂等必须先成立，否则重叠窗口本身就是一台重复打标、重复发欢迎语的机器。

对账的排期做法 —— 按最后确认时间排序、每轮只滚固定条数、频控吃紧时整体让路 —— 和外部群那边是同一套，站内讲外部群开发的那篇讲得更细，这里不展开。客户这块的差别只在分母：客户数通常比群数大一个量级，所以对账必须做成调用量恒定的滚动作业，否则它会先把留给业务触达的额度吃光。这里的「额度」说的是频控与公平使用策略下的速率预算，不是账单 —— wecomapi 按账号订阅、订阅内可无限次调用接口、不按调用次数计费，对账跑得密一点不会多花钱，但它和业务触达抢的是同一条速率，所以恒定比省着调更重要。

客户不会消失，只会改状态

某个客户从这一轮的列表里不见了，可能的原因有好几种：对方把成员删了、成员离职、企业侧做了归属调整，或者仅仅是这一轮同步漏读了。这几种情况在数据上长得几乎一样，业务含义却完全不同。

所以有一条硬规则：同步任务永远不许物理删除本地客户记录。「先标记、观察一个窗口、再软删」这套通用处理在站内讲数据同步的那篇里；客户这块要多一级 —— 列表差集只能把状态改成「本轮未出现」，连续若干轮未出现才升级为「疑似流失」，「已确认流失」只能由明确的事件或人工给出，差集本身永远不构成流失证据。

这不是数据洁癖。渠道归因、历史会话、成交记录全都挂在客户标识上，物理删一次这些数据立刻变成孤儿；更常见的是下一轮同步他又出现了，于是一个跟了半年的老客户被当成新客重新走一遍欢迎流程。这类事故的根因往往只是一次网络抖动导致的漏读，代价却要一线去承担。

状态字段建议至少四个值：活跃、静默、本轮未出现、已确认流失。前三个由程序写，最后一个只允许事件或人工写。写入方分开这件事，比状态取几个值重要得多。

上线前的六条自查

1. 1全量遍历过程中不做写入，写入统一挪到遍历结束之后。
2. 2下游对同一客户的重复处理必须无副作用 —— 这是分页漂移和重叠窗口共同的前提，不成立的话后面两条都不能用。
3. 3写入确认走事件，不走回读；回读只出现在对账作业里，并且允许延迟窗口。
4. 4水位整轮成功才推进，中途失败整轮重来，不要记「处理到第几条」这种断点，它在乱序面前没有意义。
5. 5同步差集只改状态，不删记录；流失结论由事件或人工给出。
6. 6所有客户相关的读写和日志都带账号维度。同一个真人在不同成员名下是不同记录，日志里少了这一维，出问题时根本对不上号。