概述到这篇为止「用户体系集成」这个小系列正式收官。它解决的是项目接环信的第一个必答题自己的用户和环信的用户怎么对得上号。这个问题看起来简单实际却牵动注册、登录、鉴权、好友、消息五条链路任何一环没对齐用户就会遇到「能登录但收不到消息」「好友列表两边不一样」这类难以排查的故障。这篇不重复细节只做四件事把整条链路串成一张闭环图让读者一眼看清各环节的先后依赖把可复用的套路和踩过的坑沉淀成清单方便日后接其他第三方服务时直接照搬给出上线前的自检表把「感觉没问题」变成「逐项验证过」最后留几道课后练习把课程代码里没做完的补偿、幂等、对账补上。读完之后你应该能独立判断一个新接入的第三方用户体系该怎么映射、凭证该怎么下发、双写该怎么兜底。纲要系列回顾四块拼图组成的账号映射闭环知识地图Mermaid 全链路图各篇分工与代码落点表格可复用套路清单这里核心双体系账号映射前缀映射 vs 映射表凭证下发接口的三条铁律好友关系双写与一致性代价第三方能力四件套环信是第五次应用分层验证路径关键坑回顾10 条浓缩表常见误解澄清上线前自检清单可勾选练习建议每项改哪里 / 怎么验证下一章预告附近的人系列回顾一条账号映射闭环一句话概括整个系列把项目用户体系与环信打通形成正向注册userId → hxid 凭证下发App 登录环信 反向反查hxid → userId 好友双写MongoDB friend 集合 环信联系人的完整账号映射闭环。这四个环节不是并列关系而是有严格先后依赖的链条。少了任何一环聊天都跑不通没注册App 登不进环信SDK 连不上长连接没有凭证接口App 不知道用什么账号密码登录只能把凭证硬编码在客户端等于把安全边界交给用户没有反查收到消息只知道对方是hx1001却不知道对应项目里的哪个用户头像昵称都展示不出来没有双写本地好友列表和环信联系人各说各话A 看到 B 是好友、B 却看不到 A。理解这条依赖链的价值在于排障出问题时按链条顺序从上游往下游查先确认注册成功再确认凭证下发正确再确认反查能命中最后确认双写一致比盲目翻日志快得多。回调/通知场景补齐展示信息注册项目手机号验证码同步注册环信hxuserId凭证下发GET /huanxin/user 回库取App 环信登录SDK 长连接加好友双写MongoDB friend 集合 环信联系人聊天直达消息走环信通道反向反查hx_user → userId各环节的代码落点与本系列篇目对应关系环节代码落点对应篇目正向注册新用户UserService#loginVerification注册分支将新用户注册到环信正向注册存量用户HuanxinTest#register批量刷库环信后台发送消息测试凭证下发HuanXinControllerHuanXinService查询用户环信账号密码反向反查MessagesController#userinfoUserApi#findByHuanxin根据环信 ID 反查用户好友双写HuanXinTemplate#addContact 好友表联系人管理后一章衔接工程完成后的形态是User表新增hxUser/hxPassword两个字段Constants里落了两个常量这两个常量值得单独记住// mf-commons/.../Constants.javapublicstaticfinalStringINIT_PASSWORD123456;publicstaticfinalStringHX_USER_PREFIXhx;映射规则就一行环信 ID HX_USER_PREFIX userId即hx1001。所有正向、反向逻辑都锚定这一条规则这也是整个系列最值得记住的一句话。这条规则的好处是「无状态」不需要额外查表就能从 userId 推出环信 ID也能从环信 ID 反推出 userId正反两个方向都是纯计算。代价是规则一旦定下就不能随意改因为已经注册到环信的账号名是固定的改前缀意味着存量用户全部对不上号。所以前缀值要当成契约对待写进常量、禁止各处手写字符串拼接这也是坑表里第 8 条强调「统一走HX_USER_PREFIX id」的原因。可复用套路清单这一节是全系列真正能带走的东西。每个套路都标注了在本系列怎么用的、后续哪些地方还会遇到。套路本系列怎么用后续哪里用双体系账号映射自有 userId 与环信 username 的绑定用hx userId前缀规则 hxUser字段落库双保险接入任何第三方用户体系支付实名、推送、客服系统都会遇到同一问题凭证下发接口GET /huanxin/userJWT 鉴权后按UserHolder.getUserId()回库取只返当前用户自己的凭证OAuth 场景下发临时凭证、App 换取推送 token套路完全一致好友关系双写好友申请通过后本地 friend 集合和环信联系人各写一份任何「本地状态 第三方状态」的组合本地订单 物流平台、本地群组 IM 群第三方能力四件套环信是「配置类 → Properties → Template → 自动配置」的第五次应用前面OSS、OSS 阿里云、短信、百度人脸后续所有第三方组件MongoDB、青乌云透等继续复用分层验证Console 手工发消息 → REST 接口验证注册 → 业务消息端到端任何外部服务集成的排障路径双体系账号映射展开说一句。前缀映射hx userId和映射表独立表存userId ↔ thirdId是两种典型方案维度前缀映射映射表实现成本零成本规则即映射多一张表、多一组 CRUD可读性高看到 ID 就知道是谁需查表灵活性差第三方 ID 必须允许自定义且遵循规则好第三方自动生成 ID 也能接本系列的选择环信允许自定义 username选它—环信恰好允许自定义 username所以前缀映射是最省事的选型如果接的服务只给你返回一个不可控的 UUID就只能老老实实建映射表。选型前先确认对方的 ID 是否可控这一步问清楚能省掉后面大量返工。还有一个折中方案值得知道前缀映射 落库双保险。平时靠规则计算同时在User表里存一份hxUser字段反查时优先读字段、字段为空才回退到规则计算。这样既保留了零成本的优势又能在规则变更或历史数据异常时留一条退路本系列采用的正是这种写法。凭证下发接口的三条铁律HuanXinService的实现就是范本publicHuanXinUserVofindHuanXinUser(){LonguserIdUserHolder.getUserId();// 铁律一userId 只能从 token 解出绝不接收前端传参UseruseruserApi.findById(userId);if(usernull){returnnull;}returnnewHuanXinUserVo(user.getHxUser(),user.getHxPassword());// 铁律二只返当前用户自己的凭证// 铁律三生产环境密码不能这样明文直返应换成环信用户级 token}关于好友双写的一致性代价实际代码顺序是先环信addContact、后本地friendApi.save见「联系人管理」一节所以可能的不一致是「环信成功、本地save失败」——此时项目的处理只是记日志返回 false不回滚环信。这个取舍在课程项目里可接受但要想清楚双写意味着强一致换不回来只能靠对账兜底。后面的练习里有对应任务。为什么不能靠回滚解决因为环信是外部服务本地事务回滚管不到它而调用环信删除联系人又是一次可能失败的网络请求回滚本身也会失败最终还是要靠对账。所以双写场景的正确心态是接受短暂不一致用定时对账把差异收敛而不是追求写入瞬间的强一致。对账的方向也要定好本系列以本地为准发现环信缺失就补addContact反过来则不做自动删除避免误删用户手工添加的联系人。分层验证也值得复盘成套路环信 Console 手工发消息验证通道 → REST 调环信 API 验证注册 → App 端真实收发验证端到端。自下而上每层排除了下层的问题出问题才知道卡在哪一层。这套顺序的价值在于缩小排查范围如果 Console 都发不出消息说明是环信侧配置或网络问题根本不用看业务代码如果 Console 正常而 REST 注册失败问题就在服务端调用如果前两层都正常但 App 收不到才轮到客户端 SDK 和长连接。关键坑回顾整个系列浓缩成一张坑表每一条都在前面某篇里真实出现过#坑后果与成因规避1环信注册失败被吞createUsercatch 住只记日志返回 false项目注册成功、环信失败的不一致无人补偿该用户永远收不到消息失败入重试队列或惰性注册兜底见练习2重复 createUser 报「已存在」也返回 false异常被当成失败hxUser回写被跳过用户实际已存在但库里是空的已存在视为成功幂等处理见练习3INIT_PASSWORD 弱凭证全员123456拿到他人 hxUser 即可冒充登录生产换环信用户级 token 或随机密码4凭证接口不鉴权/huanxin/user若裸奔遍历 hxid 可拖走全员环信凭证JWT 必过拦截器userId 取自 token5环信 ID 大小写HuanXinTemplate里username.toLowerCase()项目侧若不统一大小写回查对不上两侧统一小写或都走hxUser字段不拼规则6好友双写不一致环信成功本地失败或反之好友列表两边对不齐对账任务 以本地为准做补偿7聊天记录在环信手里消息数据边界在第三方本地库没有聊天记录审计/检索受制于人需要留存就走环信回调落库8username 未加前缀测试代码里createUser(106,123456)漏了hx前缀环信侧出现游离账号反查永远失败统一走HX_USER_PREFIX id拼接禁止手写9响应式.block()的位置.block()封装在 Template 内部业务层拿到的是同步 Boolean若漏封业务线程会被响应式订阅卡住响应式 API 统一在组件层收口10双 token 体系混淆项目 JWT 与环信凭证各管各的拿 JWT 去登环信或拿环信凭证调项目接口都会失败记住各自通道REST 走 JWTSDK 走环信凭证常见误解澄清误解实际情况「环信会自动同步我的用户」不会。环信是独立账号体系项目用户必须显式调 API 注册一个都不能少「用户注册环信是登录时才做的」项目的设计是首次登录即注册新用户在loginVerification里落库后立刻注册环信存量用户靠批量脚本补「批量注册随便跑」测试账号环信侧最多 100 个用户超了会失败跑之前先清库清后台「凭证接口可以顺带查别人的环信账号」只能查自己的userId 从 JWT 解出这是安全边界不是功能限制「聊天记录存在项目数据库里」不在。消息收发与存储都在环信本地只有用户与好友关系「App 拿项目 token 也能登环信」两套凭证互不相认。JWT 登 REST环信凭证登 SDK缺一不可上线前自检清单发布前照着勾每项都给出验证方法新用户自动注册环信新手机号登录后查库hx_user非空环信 Console 能搜到该用户凭证接口带 JWT 返回正确GET /huanxin/user携带 token 返回当前用户凭证不带 token 返回 401无前缀/他人 ID 被拒绝接口不接收任何用户名参数传入他人 userId 无法获取其凭证加好友双写成功好友通过后本地 friend 集合有记录环信 Console 联系人列表同步出现聊天消息 App 可收Console 以对方身份发文本消息App 端长连接能收到环信 ID 反查正确GET /messages/userinfo?huanxinIdhx106返回 userId106 的用户详情失败可感知手工断网环信再注册新用户日志出现「创建环信用户失败」且后续有补偿路径依赖练习落地练习建议四个技术任务都比课程代码多走一步直接对着「改哪里 / 怎么验证」做环信注册失败的补偿改哪里createUser返回 false 时把userId写入 Redis 的重试队列或一张hx_register_retry表定时任务扫队列重新调huanXinTemplate.createUser再加一层「惰性注册」兜底凭证接口发现hxUser为空时现场补注册并回写。怎么验证手工把环信侧用户删掉、hxUser置空模拟注册失败后触发重试最终库里有hxUser、环信 Console 有账号。createUser 幂等处理改哪里HuanXinTemplate#createUser捕获异常时判断错误信息是否为「用户已存在」或先调service.user().get(username)探测已存在直接返回 true。怎么验证对同一hxid连调两次createUser第二次仍返回 truehxUser回写不被跳过。凭证接口改用户级 token 方案改哪里HuanXinService#findHuanXinUser不再返回密码改为调环信「获取用户 token」API服务端以管理员身份为指定用户换取 tokenHuanXinUserVo的password字段换成token 有效期App 端 SDK 改用 token 登录。怎么验证接口响应里不再出现123456App 用下发的 token 能正常登录环信并收发消息。好友双写的一致性对账改哪里写一个定时任务或测试类分页遍历本地 friend 集合对每对好友调环信 API 查询联系人关系缺失的调addContact补齐并记对账日志。怎么验证手工在环信 Console 删掉一条联系人关系跑对账任务后关系恢复日志输出修补明细。下一章预告用户体系打通之后IM 的地基就算打完了下一章转向「附近的人」用 MongoDB 的地理位置能力2dsphere索引 附近查询实现同城推荐。好消息是前面章节的movement动态表早就预留了经纬度字段到时候直接在其上建索引就能查不用改表。总结用户体系集成本质是账号映射一条hx userId规则贯穿正向注册、凭证下发、反向反查三个方向闭环缺一环聊天就不通。凭证下发接口的安全三铁律token 取 id、只返自己、生产换 token比接口本身更值得带走。双写带来的一致性问题课程代码没有解决补偿、幂等、对账是三个标准的补课方向练习里已给出落点。环信是「第三方能力四件套」的第五次应用这个装配套路此后每个新组件都在重复越用越熟。