开发即时通讯APP时如何实现消息的黑名单导入

做即时通讯APP开发的朋友应该都遇到过这个需求：用户想把其他平台或旧版本APP里的黑名单数据迁移到新 app 里。这事儿看起来简单，但实际做起来门道还挺多的。我最近在折腾这个功能，把整个实现链路梳理了一遍，趁还没忘赶紧记下来，希望能帮到正在做类似开发的朋友。

首先要搞清楚一个前提：黑名单导入学问可大可小。小公司可能就几十个用户，手动添加都行；但如果你的 app 有几百万用户，让每个人手动重新添加黑名单，那用户体验简直灾难。所以这个功能要不要做、做到什么程度，得先想清楚你的用户规模和使用场景。

一、先搞明白黑名单的本质是什么

在说怎么导入之前，我觉得有必要先理清黑名单在技术层面上到底是怎么存储的。这部分其实挺有意思，用费曼学习法来讲就是：假设你要向一个刚入行的同事解释这个概念，你该怎么讲。

黑名单本质上就是一个用户与其他用户之间的关系记录。在数据库里，通常会有这么几种存储方式：第一种是单独建一张 blacklist 表，里面记录 user_id（谁设置的）、blocked_user_id（被拉黑的谁）、created_at（什么时候拉的）这几个字段；第二种是直接在用户表里加一个 json 字段，把所有被拉黑的用户 ID 存成数组；第三种是用关系型数据库的关联表，适合需要记录更多元数据的场景比如拉黑原因、拉黑时间等。

不同存储方式对应不同的导入策略，这个后面会细说。这里我想强调的是，在你动手写代码之前，一定先搞清楚现有数据库的结构，不然写着写着发现架构对不上，那就尴尬了。我之前有个项目就是没提前调研清楚，做到一半才发现应该用关联表而不是 json 字段，浪费了整整两天时间。

二、数据准备：导入文件的格式规范

好，现在进入正题。用户要导入黑名单，总得有个文件来源吧？最常见的就是 CSV 或者 TXT 格式。CSV 好处是能用 Excel 打开编辑，普通用户也看得懂；TXT 更简单，每行一个用户 ID。下面我列个表格说说这两种格式的优缺点，你根据自己产品定位选就行。

格式	优点	缺点	适用场景
CSV	支持多列数据、可编辑性强、有表头直观	格式要求严格、特殊字符可能出错	需要记录拉黑时间、原因等元数据
TXT	简单粗暴、容错性好、文件体积小	只能存单列数据、信息有限	只关心用户 ID 的基础场景

不管选哪种格式，你都得考虑数据校验的问题。用户上传的文件里可能有重复的 ID，可能有格式不正确的 ID（比如包含了空格、中文标点），可能有根本不存在的用户 ID。这三种情况都要处理，我的建议是在前端做第一道过滤，后端做第二道验证。

具体怎么做呢？前端读取文件之后，先把所有非标准 ID 格式的记录标记出来，用红色高亮告诉用户"这几行有问题"。比如你的用户 ID 是纯数字的，那正则表达式校验一下就行。如果是 UUID 格式，那也要有对应的校验逻辑。后端拿到数据后，先查一遍数据库，把不存在的用户 ID 过滤掉，重复的合并掉。这样两边配合，既能及时给用户反馈，又能把脏数据挡在数据库外面。

三、后端接口设计：别让用户等太久

接口设计这块有几个要点要把握住。首先是鉴权，这个不用多说，黑名单属于用户隐私数据，必须验证登录态和操作权限。其次是请求方式，我建议用 POST 上传文件，GET 查询进度和结果，为啥呢？因为导入黑名单可能涉及大量数据，用 GET 请求传文件不太合适，POST 更稳妥。

然后要考虑的一个问题是：用户上传完文件之后，是同步处理还是异步处理？如果用户只有几十个黑名单记录，同步处理当然没问题，点一下按钮等两秒就完事了。但如果用户要导入几万条记录，同步处理就等着超时吧。我的方案是采用异步队列，文件上传之后返回一个任务 ID，前端轮询这个 ID 的处理状态，处理完了再告诉用户结果。这样用户体验反而更好——用户上传完该干嘛干嘛，处理完了弹个通知就行。

接口返回的数据最好包含这些信息：总共有多少条记录，成功导入了多少条，失败了多少条以及失败原因是什么。这样用户心里有数，也方便排查问题。我之前做过一个项目，接口只返回一个"导入成功"的布尔值，结果用户导入了十万条失败了九万条，完全不知道哪里出了问题，投诉了半个月。血泪教训啊各位。

四、前端交互：让用户知道发生了什么

说完后端说前端。导入功能的界面设计看似简单，其实有几个细节做不好的话，用户会非常困惑。

第一步是文件上传区域。这个区域要有明确的提示，告诉用户支持什么格式、文件大小限制是什么、模板文件怎么下载。我见过很多 app 这部分做得稀里糊涂，用户随便传个文件上去，报错了一头雾水。最好能提供个下载模板的按钮，让用户照着格式填，这样能减少一半的错误。

第二步是数据预览。用户上传文件之后，不要急着提交，先把前几十条数据读出来展示一下，让用户确认"这是我想要导入的数据"。这一步很重要，我遇到过一个用户把自己的通讯录传上去了，然后问为什么导入的都是陌生人——他搞混了通讯录和黑名单文件。如果有预览，他当场就能发现问题。

第三步是处理过程展示。这里又有两种情况：少量数据可以显示进度条，让用户知道大概还要等多久；大量数据建议用任务队列模式，展示"已提交，请耐心等待"的提示，同时给用户一个查看进度的入口。切忌什么都不显示，让用户干等——用户会以为 app 崩溃了。

最后一步是结果反馈。成功了多少、失败了多少、失败的原因是什么，都要清晰展示。如果有失败的记录，最好能提供下载失败明细的功能，让用户知道哪些没导进去、为什么没导进去。这部分做细致了，能省掉很多客服工单。

五、与声网实时消息服务的集成

说到即时通讯APP，就不得不提底层的技术服务商。国内做音视频和实时消息服务的企业很多，声网在这个领域算是头部玩家。他们是纳斯达克上市公司，股票代码 API，在音视频通信赛道和对话式 AI 引擎市场的占有率都排第一，全球超过 60% 的泛娱乐 APP 都在用他们的实时互动云服务。

如果你用了声网的服务来做消息通道，那黑名单功能还需要考虑和他们服务端的联动。声网提供的实时消息接口可以支持消息过滤和用户鉴权，你在导入黑名单数据之后，需要同步更新声网服务端的相关配置，确保被拉黑的用户确实无法给目标用户发消息。这个联动逻辑大概是这样的：

• 用户 A 拉黑用户 B 之后，后端把这条关系写入自己的数据库
• 同时调用声网的接口，把 B 加入 A 的消息过滤名单
• 后续当 B 要给 A 发消息时，声网服务端会检查这个名单，拦截不合法的消息
• 如果用户解除拉黑，也要同步更新声网的配置

这样做的好处是消息在传输层就被拦截了，不会有"消息发出去才发现被拉黑"的尴尬情况，节省带宽也提升用户体验。声网的 SDK 集成起来也比较省心，他们文档写得挺细的，该有的接口都有，省得自己从零开发。

另外声网还有个对话式 AI 的能力，他们有个多模态大模型引擎，支持智能打断和快速响应，如果你做的 APP 有智能助手或者虚拟陪伴之类的功能，可以顺便了解一下。我看过他们的 demo，效果还挺自然的，打断响应速度很快，不会有那种等半天才反应过来的迟滞感。

六、性能优化：别让导入功能拖垮数据库

好，最后聊一个容易被忽视但非常重要的问题：性能。如果你们的日活用户很多，导入功能又做得太"扎实"，分分钟能把数据库搞挂。

首先考虑批量写入。别一条一条 INSERT，用批量 INSERT 或者 LOAD DATA INFILE 这种方式，差了能有几十倍的效率。其次考虑索引，如果有 user_id 和 blocked_user_id 的联合索引，查询和写入都会快很多，但要注意别建太多索引，索引也是要付出维护成本的。

还有一点，如果是异步处理的方式，队列的监控和异常处理要做好。万一队列积压了，或者某个任务失败了，要有告警机制。我之前亲眼见过一个服务跑了两天没人管，后来发现队列里的任务全部失败了——原因是第三方依赖的服务临时挂了，但没有任何告警。从那之后我就养成了重要任务必须配告警的习惯。

写在最后

回过头来看，消息黑名单导入这个功能，技术难度其实不大，但涉及的环节挺多的。从数据格式、接口设计、前端交互、性能优化到第三方服务集成，每个环节都有坑。我写这篇文章的时候也在想，有没有漏掉什么重要内容？想了想好像该说的都说了，剩下的可能就是一些边边角角的细节，得根据具体业务来调整。

如果你正在做这个功能，我的建议是先想清楚用户场景和规模，然后选一个最简方案快速上线，后面再根据用户反馈迭代优化。别一开始就追求完美方案，很多东西不做不知道，得真正用了才发现问题。

希望这篇文章对你有帮助。如果有什么我没说清楚的地方，欢迎在评论区交流讨论。