做IM这块结构体设计永远不是写好一两个struct那么简单。我这边维护的即时通讯服务端已经跑了两年多从最早的单机版到后来的分布式改造消息、会话、用户、连接每一类核心结构体都经历过不止一次重构踩过的坑比想象中多得多。这篇是“核心结构体设计”系列的第四篇重点聊一聊在真实IM项目里沉淀下来的消息结构、会话关系结构、连接管理结构以及序列化兼容这些特别容易翻车的地方。如果你正在写IM服务端或者准备做一个自己的即时通讯Demo这篇应该能帮你少走不少弯路。1. 整体设计思路为什么结构体是IM的骨架1.1 结构体设计的核心矛盾IM系统的复杂度主要体现在状态的维护和消息的流转上。一个最简单的发送消息动作背后可能涉及客户端构造消息、序列化、走网关、鉴权、投递、ACK确认、离线存储、多端同步。每一步都要在不同的系统模块之间传递数据而结构体就是这些模块之间的“共同语言”。刚开始做项目的时候我犯过一个典型的错误消息类型只用一个int字段表示消息内容直接塞进一个大的JSON字符串里。等后面需要支持图片、语音、视频、位置、自定义业务消息时整个解析逻辑开始变得混乱前端加一个字段后端就要跟着改一大堆判断分支。后来我才意识到结构体设计不是写几个类的问题它本质上是在定义一套长期演进的数据契约。结构体设计的核心矛盾其实是“变化”和“稳定”的矛盾。业务一定会在上线后持续变化今天加一个引用消息明天加一个表情回应后天可能又要加一个企业审批卡片。但如果结构体本身不稳定字段改来改去上层业务逻辑就会被拖垮。所以设计的时候既要有一组固定不变的核心字段作为骨架又要预留出足够的扩展空间让新业务不用伤筋动骨。1.2 分层模型与结构体划分我习惯把IM系统的结构体按层次去梳理不同层之间不混用。整体上是三层接入层、业务逻辑层、存储层。接入层处理的是客户端连接、心跳、断线重连它的结构体要轻量、快速比如连接Session、心跳包、上行下行Packet。业务逻辑层处理的是消息、会话、关系链、群组这些业务数据结构体更复杂字段也更完整。存储层关心的是数据怎么落到数据库或者缓存里结构体往往和数据库表的字段一一对应但也会做一些冗余设计来方便查询。三层之间的结构体不能互相嵌套太深。我见过有的同学把存储层的结构体直接当作接口返回值传给前端结果把数据库自增ID、内部状态位都暴露了出去既不安全后面想重构表结构的时候又不敢改。正确的做法是每一层定义自己需要的结构体层与层之间做字段映射。虽然会多写一些转换代码但换来的是模块之间的解耦。层次核心职责典型结构体接入层维持连接、心跳、链路状态Session, HeartbeatPacket, Packet业务逻辑层消息、会话、关系链、群组处理Message, Conversation, FriendRelation存储层持久化、缓存、离线数据OfflineMessage, MessageIndex, SyncCursor1.3 为什么坚持手写而不是ORM/自动生成现在的ORM和代码生成工具已经相当成熟很多数据库表结构能自动生成业务模型。但在IM这种高并发、长连接场景下我仍然坚持用手写结构体加手工定义序列化协议而不是完全依赖自动生成。原因有几个。第一IM的核心结构体不只是数据库表的映射它还承担着网络传输协议描述的任务。比如消息体里面的Content字段存到数据库时是一个Blob但在网络传输时可能是按消息类型做不同编码的。这种差异ORM很难优雅表达。第二手写结构体能让我精确控制字段命名、大小写、序列化标签避免Go语言里字段大写自动导出、JSON序列化时又需要特殊tag转换的问题。第三手写更利于做字段级的兼容性演进我想在哪个字段后面加一个optional扩展字段直接处理就是了用自动生成工具反而容易被覆盖。手写结构体还有一个隐性的好处倒逼自己思考每一个字段到底为什么不加不行。如果某一天你发现一个结构体里有一堆字段从来没人读过可能就是设计出了问题这是个值得关注的信号。2. 消息结构与内容载体2.1 基础消息结构体字段拆解消息是IM系统里最重要的数据载体几乎所有的功能都围绕消息展开。先看一下我在项目里使用的基础消息结构体我用的Go语言描述但概念上在其他语言同样适用。type Message struct { MsgID string json:msg_id ClientMsgID string json:client_msg_id ConversationID string json:conversation_id SenderID string json:sender_id ReceiverID string json:receiver_id MsgType int32 json:msg_type Content []byte json:content SendTime int64 json:send_time Status int32 json:status Ext map[string]string json:ext }这里几个字段很多人觉得是冗余实际各有用途。MsgID是服务端生成的消息全局唯一ID主要给客户端用来做幂等ClientMsgID是客户端生成的消息ID用于网络重试时判断同一条消息避免重复入库。这两个ID必须同时存在如果只信任客户端ID客户端有bug时会污染整个消息流如果只信任服务端ID在消息发到服务端之前客户端就没法本地去重。ConversationID是会话ID单聊时可以用双方用户ID排序后拼接群聊时用群的唯一ID。SenderID是发送者ReceiverID是接收者但如果会话类型是群聊ReceiverID就会存群ID而不是某个用户ID。这里要在业务层定清楚语义。Content的设计是重头戏。我不建议直接用string而是用[]byte。原因是后面的消息内容可能是文本、二进制图片缩略图、自定义加密数据string一旦被创建就会复制一份不可变数据在高并发消息转发时会带来不必要的内存分配。[]byte更贴近原始数据流的本质后面转成任何格式都更灵活。SendTime用int64毫秒时间戳统一单位很重要。我们曾经因为历史代码里一部分用秒、一部分用毫秒导致消息排序偶尔错乱排查了很久才找到问题。Status字段用于标记消息状态比如1正常、2已撤回、3已删除不要在业务里用魔法数字散落各处最好定义成常量枚举。2.2 消息内容payload的多格式设计消息内容不能是“一个大JSON套一切”。如果所有的业务数据都塞进一个JSON字符串里好处是开发快坏处是类型不安全、解析性能差、版本演进困难。我的做法是让MsgType决定Content的解析方式Content本身是二进制字节但里面是结构化的编码数据。文本消息的Content存储为JSON比如{ text: hello world }图片消息的Content{ url: https://cdn.example.com/img/xxx, width: 1080, height: 720, size: 204800, thumbnail_url: https://cdn.example.com/img/xxx_thumb }语音消息、视频消息、系统通知消息都类似各自定义自己的Content结构。每一个具体消息类型都应该有对应的解析函数比如TextContentFromBytes、ImageContentFromBytes。这样新增消息类型时不用修改Message主结构只增加一个类型枚举和对应的Content解析器即可。如果使用Protobuf可以进一步用oneof把不同消息体组织起来字段编号天然承载消息类型序列化效率更高。但要注意oneof在跨语言互操作时会有一些限制如果团队技术栈统一、协议文档管理规范强烈推荐。我之前在一个模拟项目X里就是从JSON切到Protobuf之后消息序列化耗时降低了大约40%效果非常明显。这里有个实操细节无论用哪种方式Content字段都要考虑大小上限。文本消息、图片消息、自定义消息的大小差异很大网关层要能根据MsgType做分档限制避免有人通过超大Content打爆内存。比如文本消息限制2KB图片消息原始链接、缩略图地址限制4KB自定义消息限制64KB超过直接返回错误码。2.3 消息扩展与已读回执结构体消息不是发出去就结束了IM里还有已读回执、批量已读、引用回复、表情回应这些“消息附属信息”。一开始我把这些字段直接塞进Message结构体里结果发现大部分消息都用不到白白浪费存储逻辑也越搅越乱。正确做法是把扩展信息单独拆成结构体。已读回执这块我设计了Receipt结构体type MessageReceipt struct { MsgID string json:msg_id ConversationID string json:conversation_id UserID string json:user_id ReadTime int64 json:read_time ReadCount int32 json:read_count TotalCount int32 json:total_count }其中UserID是读取者IDReadCount和TotalCount是冗余字段。你可能觉得这两个字段可以从会话成员表实时统计出来何必冗余但在高并发场景下用户点开群聊时界面要立刻显示“3人已读/10人”如果每次都要去数据库做一个COUNT查询压力非常大。把计数直接放在回执结构体里通过缓存更新展示时一次读取就能拿到。不过冗余也带来一致性问题。更新ReadCount时需要用乐观锁或原子操作不能简单先查后写否则并发多端登录时计数容易丢失。这个坑我在联调时就踩过两个设备同时标记已读最后ReadCount只加了一次后来又用Redis的INCR才解决。3. 会话与关系链结构体3.1 会话摘要与会话成员结构体IM里消息总是发生在某个会话里会话分为单聊和群聊。会话结构体既要描述会话本身又要描述每个用户在该会话里的个性化状态。会话本身可以设计为type Conversation struct { ConversationID string json:conversation_id ConversationType int32 json:conversation_type Name string json:name Avatar string json:avatar OwnerID string json:owner_id MaxMembers int32 json:max_members CreatedAt int64 json:created_at UpdatedAt int64 json:updated_at }ConversationType用1表示单聊2表示群聊。单聊的Name、Avatar往往不是真实名称而是要在展示时根据对方资料动态填充所以这两个字段在单聊会话里可以是空字符串查询接口返回时再补充。这是很多新手容易忽略的地方。会话成员结构体是另一个容易设计过重的点type ConversationMember struct { ConversationID string json:conversation_id UserID string json:user_id Role int32 json:role Mute bool json:mute UnreadCount int32 json:unread_count LastReadMsgID string json:last_read_msg_id JoinTime int64 json:join_time }这里的UnreadCount就是某个用户在这个会话里未读的消息数。LastReadMsgID是用户已读到的最后一条消息ID。为什么已经存了UnreadCount还要存LastReadMsgID因为未读数是可以重建的但实时计算的代价太高LastReadMsgID则用于增量拉取消息时定位起始点也用于多端同步已读位置。两者配合既能快速展示又能做数据校正。关于未读数我强烈建议不要只存一个总数而要把每个消息ID的状态也考虑进去。否则用户删除会话、清空消息、多端已读同步时未读数会经常出现“涨了降不回去”的问题。正确做法是未读数只是一个聚合展示真正的已读位置由LastReadMsgID决定增量消息再通过SenderID排除自己发送的消息。3.2 好友关系与用户资料结构体用户资料结构体看着简单但里面有一个隐患资料是高度变化的昵称、头像、签名经常改而消息记录里往往需要展示发送者信息。如果消息结构体里直接内嵌UserProfile那么历史消息里展示的就是最新的资料用户可能觉得“我当时发的昵称不是这个啊”。所以消息和用户资料不能耦合消息只存UserID展示时再单独拉取UserProfile。type UserProfile struct { UID string json:uid Nickname string json:nickname Avatar string json:avatar Signature string json:signature Gender int32 json:gender ProfileExt map[string]string json:profile_ext }ProfileExt是一个扩展map适合存生日、地区、个性标签这类非核心字段。这样新加资料字段时不需要改主结构体但不能滥用查询时如果需要按扩展字段过滤就会很痛苦。需要搜索的场景还是要把字段提升到独立列。好友关系结构体我这样设计type FriendRelation struct { OwnerUID string json:owner_uid FriendUID string json:friend_uid Remark string json:remark Source int32 json:source GroupIDs []string json:group_ids CreatedAt int64 json:created_at Status int32 json:status }Source表示好友来源比如搜索添加、扫码添加、群聊添加、通讯录匹配。GroupIDs表示这个好友被分在哪些好友分组里比如“同事”“家人”。Status是好友状态正常、删除、拉黑等。这里要注意好友关系是有方向的A和B是好友不代表B和A一定是好友除非你们的产品明确做双向确认。如果只存一条关系就会出现A能看到B、B看不到A的bug。3.3 群组角色与权限结构体群组角色和权限是整个IM里最容易设计失控的部分。早期我图省事直接在群成员结构体里放一个IsAdmin布尔字段结果产品后来要增加“群主”“管理员”“普通成员”“被禁言成员”“匿名成员”等一堆角色布尔字段根本不够用。后来我统一成角色结构体加权限位掩码type GroupRole struct { GroupID string json:group_id RoleID int32 json:role_id RoleName string json:role_name Permissions uint64 json:permissions }Permissions是一个uint64的位掩码每位对应一种权限。比如第0位表示是否可以发送消息第1位表示是否可以邀请成员第2位表示是否可以修改群公告第3位表示是否可以禁言。群主拥有全部权限管理员拥有部分权限普通成员只拥有基础权限。判断权限时用按位与即可if role.Permissions(13) ! 0 { // 允许禁言 }位掩码的好处是扩展方便新权限只需增加一个比特位不需要改数据库表结构。但要注意不要把所有权限都堆到同一个角色里否则以后角色组合爆炸。一个合理的做法是用户既属于群角色决定基础权限又可以在群成员表里单独记录“是否被禁言”“是否匿名”这种临时状态。群组成员设计时除了RoleID还应该在成员表里冗余一个IsMuted字段或者禁言到期时间方便高频的消息发送鉴权快速判断。去查角色表、再查权限表在高频消息场景下性能开销很大。4. 连接与会话管理结构体4.1 连接Session与心跳结构体长连接是IM的底座连接Session结构体描述“谁在哪台网关机器上保持着一条连接”。这个结构体对分布式IM尤其重要因为消息要投递到正确的网关节点才能触达用户。type Session struct { SessionID string json:session_id UserID string json:user_id DeviceID string json:device_id ConnID string json:conn_id GatewayID string json:gateway_id Status int32 json:status HeartbeatTime int64 json:heartbeat_time LoginTime int64 json:login_time RemoteIP string json:remote_ip }SessionID是连接的唯一标识每次客户端建立连接都会重新生成。ConnID是具体TCP连接在网关节点上的内部标识GatewayID则用于路由到具体网关节点。在分布式架构里Session通常会注册到Rediskey可以用UserIDvalue用Session结构体序列化后的字符串。这样逻辑层要发消息给某个用户时直接按UserID查Session就能知道该往哪个网关推送。心跳结构体相对简单type HeartbeatPacket struct { ClientTime int64 json:client_time ServerTime int64 json:server_time Seq int64 json:seq }Seq是客户端维护的自增序号用来匹配请求和响应。心跳最重要的作用是让网关能及时判断连接死活。超时时间不能太短否则弱网环境下用户频繁断线也不能太长否则网关积压已经死掉的连接。业界经验值一般是60秒到90秒没收到心跳就断开但具体要看你的用户网络环境。4.2 消息应答与可靠性结构体IM的消息投递默认是“至少一次”也就是可能会重复但不能丢。这就需要ACK机制。客户端发消息服务端收到后要返回一个Ack告诉客户端“我已经存下来了”。服务端推消息给客户端客户端也要返回Ack告诉服务端“我收到了可以移除离线消息了”。type Ack struct { MsgID string json:msg_id ClientMsgID string json:client_msg_id ConversationID string json:conversation_id Status int32 json:status ErrorCode int32 json:error_code ServerTime int64 json:server_time }Status标记成功还是失败ErrorCode在失败时说明原因比如消息过大、超时、权限不足、被禁言。这里有个细节Ack里的ClientMsgID必须原样返回不能只用服务端的MsgID因为客户端在超时重试时需要靠ClientMsgID知道自己之前发送的是哪条消息。消息发送的完整流程里Ack结构体每个环节都要参与。客户端把消息发给网关网关先返回一个“已收到”的临时Ack这并不表示消息已经成功存入数据库。之后逻辑层把消息真正落库、推送给接收端再返回一个“已成功”的最终Ack。如果客户端只是收到了临时Ack就不会重发但心里要清楚最终Ack只在目标端成功后才产生。这个区分很关键很多人把它混在一起导致消息重复或者丢失。4.3 离线消息与消息漫游结构体用户不在线的时候消息不能直接扔掉要存储为离线消息。等用户重新登录再从服务端拉取。type OfflineMessage struct { UserID string json:user_id MsgID string json:msg_id ConversationID string json:conversation_id Payload []byte json:payload CreateTime int64 json:create_time ExpireTime int64 json:expire_time }Payload存的是序列化后的消息内容可以和消息表里的Content保持一致。离线消息需要设置ExpireTime比如保留7天过期自动清理。如果用户长期不上线积压几万条离线消息会占用大量存储拉取时也容易超时。消息漫游指的是用户在任意设备登录都能拉历史消息。这里建议不要直接按ConversationID全量拉取而是维护一个同步游标type SyncCursor struct { UserID string json:user_id DeviceID string json:device_id LastMsgID string json:last_msg_id LastSyncTime int64 json:last_sync_time }每次增量同步时只拉取LastMsgID之后的消息同时用Limit限制条数。这样分页、断线续传都能处理。LastSyncTime用于兜底如果某些消息没有按照MsgID严格递增也可以作为辅助排序条件。离线消息和消息漫游在大多数IM里是一体化设计的在线推送失败的消息转为离线消息用户上线后通过同步接口一次性拉取。不要把它们拆成两套完全无关的存储逻辑否则会出现同一条消息在离线列表和历史记录里各存一份且ID对不上的情况。5. 序列化与版本兼容设计5.1 结构体的序列化标签与字段编号结构体最终要跨网络传输所以序列化方案必须提前定好。JSON、Protobuf、Thrift各有各的适用场景。我的建议是对外接口、调试场景可以用JSON便于排查核心的消息上下行链路用Protobuf或Thrift性能和类型安全性更好。如果使用Protobuf字段编号是头等大事。比如message Message { string msg_id 1; string client_msg_id 2; string conversation_id 3; string sender_id 4; string receiver_id 5; int32 msg_type 6; bytes content 7; int64 send_time 8; int32 status 9; mapstring, string ext 10; }这里从1开始编号这个编号一旦发布就永远不能变。字段编号是协议的一部分相当于数据库表的主键。如果某个字段在后续版本里挪动了用途老客户端解析时就会出错。我在项目里要求所有人改协议时都先在文档里备注字段编号任何人不准复用已废弃的编号。JSON格式则要注意字段名的序列化tag。Go里默认字段名首字母大写会被原样导出所以要用json标签统一成小写下划线风格。不同语言之间尤其要注意Java后端喜欢驼峰Go服务喜欢下划线客户端可能又用另一种风格。定一套统一的命名规范序列化标签严格遵循不要靠运气。5.2 兼容性演进新增/废弃字段策略IM系统升级是常态但客户端和服务端往往不是同时发布。我曾经因为删除一个旧字段导致老版本客户端崩溃。后来总结了非常严格的字段演进规则新增字段时必须保证是optional且默认值对旧客户端无影响。旧客户端解析一个未知字段时会直接忽略但前提是序列化框架支持未知字段保留或忽略所以千万不要在协议解析层上做“未知字段直接报错”的严格校验。废弃字段时不要把字段直接从结构体里删掉而是标记为reserved并且保留它的编号。Protobuf里有reserved关键字JSON没有那就只能在文档里记录“该字段已废弃不可复用编号”。如果有人复用废弃字段编号会导致老客户端把新数据解析成完全不同的含义这是最危险的兼容性事故。修改字段类型是绝对禁止的。int32改成int64看上去简单但对老客户端来说字节布局完全不同解析的数据会变成乱码。需要换类型的时候新增一个字段老字段保留原义或标记废弃。变更类型是否允许处理方式新增optional字段允许默认值要兼容旧端删除字段尽量避免标记reserved不删编号修改字段类型禁止新增字段替代修改枚举值含义禁止枚举只能追加修改包名/服务名谨慎做好全链路兼容测试枚举类型也需要小心枚举值一旦确定就不能修改含义只能追加。比如MsgType为3表示图片之后不能改成一个完全不同的业务消息。追加新枚举时旧版本客户端遇到不认识的枚举值要做好兜底处理比如显示“该消息类型版本过低无法查看”。5.3 常见问题与排查技巧实录聊几个我在实际联调和线上排查中遇到过的问题都是结构体设计引发的。第一个是int类型跨语言不一致。有个服务端同事在结构体里用了Go的int客户端用的是Java的int32。Go的int在64位机器上是8字节Java的int是4字节序列化后字段长度不一致导致客户端解析后字段错位。排查了很久才发现是类型长度不一致。从那时起所有跨网络传输的整数类型全部显式声明为int32或int64绝不用平台相关的int。第二个是时间戳单位不统一。消息结构体里SendTime有的地方是秒有的地方是毫秒排序和展示都会异常。后来我在结构体定义旁边写清楚注释所有时间戳统一使用毫秒存储层如果为了节省空间再转成秒必须在转换函数里单独处理。结构体字段注释不是可有可无的它就是在传递约束。第三个是Content字段误用string导致性能问题。在一次性能压测中发现消息转发时内存占用很高定位后发现是Content类型用了string每次复制消息内容都会产生一次深拷贝。改成[]byte之后字节切片在传递过程中只复制引用内存明显下降。第四个是Session覆盖问题。同一用户在不同设备登录如果不做device维度区分新连接会覆盖旧连接导致另一台设备收不到消息。Session结构体里必须带有DeviceID并且Redis的key要设计成UserID:DeviceID而不是只按UserID存储。踢人逻辑也要显式判断比如手机端登录时可以主动踢掉相同设备ID的旧连接但不同设备应该允许共存。第五个是消息体过大导致网关推送超时。结构体设计上内容类型是开放的但网关必须有大小限制。否则有人发一个几十MB的“文本消息”序列化后数据包很大网关内存被占满其他用户消息也跟着卡住。排查方法是在网关入口打印Packet大小分布超过阈值的请求直接拒绝。这些问题的共同点是它们不是代码逻辑难而是结构体设计阶段没有把约束和边界定义清楚。结构体不只是数据的容器它同时是协议、是契约、是系统各个模块之间的信任边界。最后说一个我自己的习惯。每次改完核心结构体我都会让客户端和服务端联调时专门跑一遍“新版发消息、旧版收消息”和“旧版发消息、新版收消息”的交叉测试不测一遍我是不敢上线的。IM这种系统的线上问题影响范围太大一条消息发不出去用户感知极其明显。结构体设计得再漂亮最终还是要经得住真实网络环境和客户端版本的考验。 
长河君 · 2026/10/24 3:34:03 · 阅读 1.2k IM服务端核心结构体设计：消息、会话、连接与序列化兼容实践
做IM这块结构体设计永远不是写好一两个struct那么简单。我这边维护的即时通讯服务端已经跑了两年多从最早的单机版到后来的分布式改造消息、会话、用户、连接每一类核心结构体都经历过不止一次重构踩过的坑比想象中多得多。这篇是“核心结构体设计”系列的第四篇重点聊一聊在真实IM项目里沉淀下来的消息结构、会话关系结构、连接管理结构以及序列化兼容这些特别容易翻车的地方。如果你正在写IM服务端或者准备做一个自己的即时通讯Demo这篇应该能帮你少走不少弯路。1. 整体设计思路为什么结构体是IM的骨架1.1 结构体设计的核心矛盾IM系统的复杂度主要体现在状态的维护和消息的流转上。一个最简单的发送消息动作背后可能涉及客户端构造消息、序列化、走网关、鉴权、投递、ACK确认、离线存储、多端同步。每一步都要在不同的系统模块之间传递数据而结构体就是这些模块之间的“共同语言”。刚开始做项目的时候我犯过一个典型的错误消息类型只用一个int字段表示消息内容直接塞进一个大的JSON字符串里。等后面需要支持图片、语音、视频、位置、自定义业务消息时整个解析逻辑开始变得混乱前端加一个字段后端就要跟着改一大堆判断分支。后来我才意识到结构体设计不是写几个类的问题它本质上是在定义一套长期演进的数据契约。结构体设计的核心矛盾其实是“变化”和“稳定”的矛盾。业务一定会在上线后持续变化今天加一个引用消息明天加一个表情回应后天可能又要加一个企业审批卡片。但如果结构体本身不稳定字段改来改去上层业务逻辑就会被拖垮。所以设计的时候既要有一组固定不变的核心字段作为骨架又要预留出足够的扩展空间让新业务不用伤筋动骨。1.2 分层模型与结构体划分我习惯把IM系统的结构体按层次去梳理不同层之间不混用。整体上是三层接入层、业务逻辑层、存储层。接入层处理的是客户端连接、心跳、断线重连它的结构体要轻量、快速比如连接Session、心跳包、上行下行Packet。业务逻辑层处理的是消息、会话、关系链、群组这些业务数据结构体更复杂字段也更完整。存储层关心的是数据怎么落到数据库或者缓存里结构体往往和数据库表的字段一一对应但也会做一些冗余设计来方便查询。三层之间的结构体不能互相嵌套太深。我见过有的同学把存储层的结构体直接当作接口返回值传给前端结果把数据库自增ID、内部状态位都暴露了出去既不安全后面想重构表结构的时候又不敢改。正确的做法是每一层定义自己需要的结构体层与层之间做字段映射。虽然会多写一些转换代码但换来的是模块之间的解耦。层次核心职责典型结构体接入层维持连接、心跳、链路状态Session, HeartbeatPacket, Packet业务逻辑层消息、会话、关系链、群组处理Message, Conversation, FriendRelation存储层持久化、缓存、离线数据OfflineMessage, MessageIndex, SyncCursor1.3 为什么坚持手写而不是ORM/自动生成现在的ORM和代码生成工具已经相当成熟很多数据库表结构能自动生成业务模型。但在IM这种高并发、长连接场景下我仍然坚持用手写结构体加手工定义序列化协议而不是完全依赖自动生成。原因有几个。第一IM的核心结构体不只是数据库表的映射它还承担着网络传输协议描述的任务。比如消息体里面的Content字段存到数据库时是一个Blob但在网络传输时可能是按消息类型做不同编码的。这种差异ORM很难优雅表达。第二手写结构体能让我精确控制字段命名、大小写、序列化标签避免Go语言里字段大写自动导出、JSON序列化时又需要特殊tag转换的问题。第三手写更利于做字段级的兼容性演进我想在哪个字段后面加一个optional扩展字段直接处理就是了用自动生成工具反而容易被覆盖。手写结构体还有一个隐性的好处倒逼自己思考每一个字段到底为什么不加不行。如果某一天你发现一个结构体里有一堆字段从来没人读过可能就是设计出了问题这是个值得关注的信号。2. 消息结构与内容载体2.1 基础消息结构体字段拆解消息是IM系统里最重要的数据载体几乎所有的功能都围绕消息展开。先看一下我在项目里使用的基础消息结构体我用的Go语言描述但概念上在其他语言同样适用。type Message struct { MsgID string json:msg_id ClientMsgID string json:client_msg_id ConversationID string json:conversation_id SenderID string json:sender_id ReceiverID string json:receiver_id MsgType int32 json:msg_type Content []byte json:content SendTime int64 json:send_time Status int32 json:status Ext map[string]string json:ext }这里几个字段很多人觉得是冗余实际各有用途。MsgID是服务端生成的消息全局唯一ID主要给客户端用来做幂等ClientMsgID是客户端生成的消息ID用于网络重试时判断同一条消息避免重复入库。这两个ID必须同时存在如果只信任客户端ID客户端有bug时会污染整个消息流如果只信任服务端ID在消息发到服务端之前客户端就没法本地去重。ConversationID是会话ID单聊时可以用双方用户ID排序后拼接群聊时用群的唯一ID。SenderID是发送者ReceiverID是接收者但如果会话类型是群聊ReceiverID就会存群ID而不是某个用户ID。这里要在业务层定清楚语义。Content的设计是重头戏。我不建议直接用string而是用[]byte。原因是后面的消息内容可能是文本、二进制图片缩略图、自定义加密数据string一旦被创建就会复制一份不可变数据在高并发消息转发时会带来不必要的内存分配。[]byte更贴近原始数据流的本质后面转成任何格式都更灵活。SendTime用int64毫秒时间戳统一单位很重要。我们曾经因为历史代码里一部分用秒、一部分用毫秒导致消息排序偶尔错乱排查了很久才找到问题。Status字段用于标记消息状态比如1正常、2已撤回、3已删除不要在业务里用魔法数字散落各处最好定义成常量枚举。2.2 消息内容payload的多格式设计消息内容不能是“一个大JSON套一切”。如果所有的业务数据都塞进一个JSON字符串里好处是开发快坏处是类型不安全、解析性能差、版本演进困难。我的做法是让MsgType决定Content的解析方式Content本身是二进制字节但里面是结构化的编码数据。文本消息的Content存储为JSON比如{ text: hello world }图片消息的Content{ url: https://cdn.example.com/img/xxx, width: 1080, height: 720, size: 204800, thumbnail_url: https://cdn.example.com/img/xxx_thumb }语音消息、视频消息、系统通知消息都类似各自定义自己的Content结构。每一个具体消息类型都应该有对应的解析函数比如TextContentFromBytes、ImageContentFromBytes。这样新增消息类型时不用修改Message主结构只增加一个类型枚举和对应的Content解析器即可。如果使用Protobuf可以进一步用oneof把不同消息体组织起来字段编号天然承载消息类型序列化效率更高。但要注意oneof在跨语言互操作时会有一些限制如果团队技术栈统一、协议文档管理规范强烈推荐。我之前在一个模拟项目X里就是从JSON切到Protobuf之后消息序列化耗时降低了大约40%效果非常明显。这里有个实操细节无论用哪种方式Content字段都要考虑大小上限。文本消息、图片消息、自定义消息的大小差异很大网关层要能根据MsgType做分档限制避免有人通过超大Content打爆内存。比如文本消息限制2KB图片消息原始链接、缩略图地址限制4KB自定义消息限制64KB超过直接返回错误码。2.3 消息扩展与已读回执结构体消息不是发出去就结束了IM里还有已读回执、批量已读、引用回复、表情回应这些“消息附属信息”。一开始我把这些字段直接塞进Message结构体里结果发现大部分消息都用不到白白浪费存储逻辑也越搅越乱。正确做法是把扩展信息单独拆成结构体。已读回执这块我设计了Receipt结构体type MessageReceipt struct { MsgID string json:msg_id ConversationID string json:conversation_id UserID string json:user_id ReadTime int64 json:read_time ReadCount int32 json:read_count TotalCount int32 json:total_count }其中UserID是读取者IDReadCount和TotalCount是冗余字段。你可能觉得这两个字段可以从会话成员表实时统计出来何必冗余但在高并发场景下用户点开群聊时界面要立刻显示“3人已读/10人”如果每次都要去数据库做一个COUNT查询压力非常大。把计数直接放在回执结构体里通过缓存更新展示时一次读取就能拿到。不过冗余也带来一致性问题。更新ReadCount时需要用乐观锁或原子操作不能简单先查后写否则并发多端登录时计数容易丢失。这个坑我在联调时就踩过两个设备同时标记已读最后ReadCount只加了一次后来又用Redis的INCR才解决。3. 会话与关系链结构体3.1 会话摘要与会话成员结构体IM里消息总是发生在某个会话里会话分为单聊和群聊。会话结构体既要描述会话本身又要描述每个用户在该会话里的个性化状态。会话本身可以设计为type Conversation struct { ConversationID string json:conversation_id ConversationType int32 json:conversation_type Name string json:name Avatar string json:avatar OwnerID string json:owner_id MaxMembers int32 json:max_members CreatedAt int64 json:created_at UpdatedAt int64 json:updated_at }ConversationType用1表示单聊2表示群聊。单聊的Name、Avatar往往不是真实名称而是要在展示时根据对方资料动态填充所以这两个字段在单聊会话里可以是空字符串查询接口返回时再补充。这是很多新手容易忽略的地方。会话成员结构体是另一个容易设计过重的点type ConversationMember struct { ConversationID string json:conversation_id UserID string json:user_id Role int32 json:role Mute bool json:mute UnreadCount int32 json:unread_count LastReadMsgID string json:last_read_msg_id JoinTime int64 json:join_time }这里的UnreadCount就是某个用户在这个会话里未读的消息数。LastReadMsgID是用户已读到的最后一条消息ID。为什么已经存了UnreadCount还要存LastReadMsgID因为未读数是可以重建的但实时计算的代价太高LastReadMsgID则用于增量拉取消息时定位起始点也用于多端同步已读位置。两者配合既能快速展示又能做数据校正。关于未读数我强烈建议不要只存一个总数而要把每个消息ID的状态也考虑进去。否则用户删除会话、清空消息、多端已读同步时未读数会经常出现“涨了降不回去”的问题。正确做法是未读数只是一个聚合展示真正的已读位置由LastReadMsgID决定增量消息再通过SenderID排除自己发送的消息。3.2 好友关系与用户资料结构体用户资料结构体看着简单但里面有一个隐患资料是高度变化的昵称、头像、签名经常改而消息记录里往往需要展示发送者信息。如果消息结构体里直接内嵌UserProfile那么历史消息里展示的就是最新的资料用户可能觉得“我当时发的昵称不是这个啊”。所以消息和用户资料不能耦合消息只存UserID展示时再单独拉取UserProfile。type UserProfile struct { UID string json:uid Nickname string json:nickname Avatar string json:avatar Signature string json:signature Gender int32 json:gender ProfileExt map[string]string json:profile_ext }ProfileExt是一个扩展map适合存生日、地区、个性标签这类非核心字段。这样新加资料字段时不需要改主结构体但不能滥用查询时如果需要按扩展字段过滤就会很痛苦。需要搜索的场景还是要把字段提升到独立列。好友关系结构体我这样设计type FriendRelation struct { OwnerUID string json:owner_uid FriendUID string json:friend_uid Remark string json:remark Source int32 json:source GroupIDs []string json:group_ids CreatedAt int64 json:created_at Status int32 json:status }Source表示好友来源比如搜索添加、扫码添加、群聊添加、通讯录匹配。GroupIDs表示这个好友被分在哪些好友分组里比如“同事”“家人”。Status是好友状态正常、删除、拉黑等。这里要注意好友关系是有方向的A和B是好友不代表B和A一定是好友除非你们的产品明确做双向确认。如果只存一条关系就会出现A能看到B、B看不到A的bug。3.3 群组角色与权限结构体群组角色和权限是整个IM里最容易设计失控的部分。早期我图省事直接在群成员结构体里放一个IsAdmin布尔字段结果产品后来要增加“群主”“管理员”“普通成员”“被禁言成员”“匿名成员”等一堆角色布尔字段根本不够用。后来我统一成角色结构体加权限位掩码type GroupRole struct { GroupID string json:group_id RoleID int32 json:role_id RoleName string json:role_name Permissions uint64 json:permissions }Permissions是一个uint64的位掩码每位对应一种权限。比如第0位表示是否可以发送消息第1位表示是否可以邀请成员第2位表示是否可以修改群公告第3位表示是否可以禁言。群主拥有全部权限管理员拥有部分权限普通成员只拥有基础权限。判断权限时用按位与即可if role.Permissions(13) ! 0 { // 允许禁言 }位掩码的好处是扩展方便新权限只需增加一个比特位不需要改数据库表结构。但要注意不要把所有权限都堆到同一个角色里否则以后角色组合爆炸。一个合理的做法是用户既属于群角色决定基础权限又可以在群成员表里单独记录“是否被禁言”“是否匿名”这种临时状态。群组成员设计时除了RoleID还应该在成员表里冗余一个IsMuted字段或者禁言到期时间方便高频的消息发送鉴权快速判断。去查角色表、再查权限表在高频消息场景下性能开销很大。4. 连接与会话管理结构体4.1 连接Session与心跳结构体长连接是IM的底座连接Session结构体描述“谁在哪台网关机器上保持着一条连接”。这个结构体对分布式IM尤其重要因为消息要投递到正确的网关节点才能触达用户。type Session struct { SessionID string json:session_id UserID string json:user_id DeviceID string json:device_id ConnID string json:conn_id GatewayID string json:gateway_id Status int32 json:status HeartbeatTime int64 json:heartbeat_time LoginTime int64 json:login_time RemoteIP string json:remote_ip }SessionID是连接的唯一标识每次客户端建立连接都会重新生成。ConnID是具体TCP连接在网关节点上的内部标识GatewayID则用于路由到具体网关节点。在分布式架构里Session通常会注册到Rediskey可以用UserIDvalue用Session结构体序列化后的字符串。这样逻辑层要发消息给某个用户时直接按UserID查Session就能知道该往哪个网关推送。心跳结构体相对简单type HeartbeatPacket struct { ClientTime int64 json:client_time ServerTime int64 json:server_time Seq int64 json:seq }Seq是客户端维护的自增序号用来匹配请求和响应。心跳最重要的作用是让网关能及时判断连接死活。超时时间不能太短否则弱网环境下用户频繁断线也不能太长否则网关积压已经死掉的连接。业界经验值一般是60秒到90秒没收到心跳就断开但具体要看你的用户网络环境。4.2 消息应答与可靠性结构体IM的消息投递默认是“至少一次”也就是可能会重复但不能丢。这就需要ACK机制。客户端发消息服务端收到后要返回一个Ack告诉客户端“我已经存下来了”。服务端推消息给客户端客户端也要返回Ack告诉服务端“我收到了可以移除离线消息了”。type Ack struct { MsgID string json:msg_id ClientMsgID string json:client_msg_id ConversationID string json:conversation_id Status int32 json:status ErrorCode int32 json:error_code ServerTime int64 json:server_time }Status标记成功还是失败ErrorCode在失败时说明原因比如消息过大、超时、权限不足、被禁言。这里有个细节Ack里的ClientMsgID必须原样返回不能只用服务端的MsgID因为客户端在超时重试时需要靠ClientMsgID知道自己之前发送的是哪条消息。消息发送的完整流程里Ack结构体每个环节都要参与。客户端把消息发给网关网关先返回一个“已收到”的临时Ack这并不表示消息已经成功存入数据库。之后逻辑层把消息真正落库、推送给接收端再返回一个“已成功”的最终Ack。如果客户端只是收到了临时Ack就不会重发但心里要清楚最终Ack只在目标端成功后才产生。这个区分很关键很多人把它混在一起导致消息重复或者丢失。4.3 离线消息与消息漫游结构体用户不在线的时候消息不能直接扔掉要存储为离线消息。等用户重新登录再从服务端拉取。type OfflineMessage struct { UserID string json:user_id MsgID string json:msg_id ConversationID string json:conversation_id Payload []byte json:payload CreateTime int64 json:create_time ExpireTime int64 json:expire_time }Payload存的是序列化后的消息内容可以和消息表里的Content保持一致。离线消息需要设置ExpireTime比如保留7天过期自动清理。如果用户长期不上线积压几万条离线消息会占用大量存储拉取时也容易超时。消息漫游指的是用户在任意设备登录都能拉历史消息。这里建议不要直接按ConversationID全量拉取而是维护一个同步游标type SyncCursor struct { UserID string json:user_id DeviceID string json:device_id LastMsgID string json:last_msg_id LastSyncTime int64 json:last_sync_time }每次增量同步时只拉取LastMsgID之后的消息同时用Limit限制条数。这样分页、断线续传都能处理。LastSyncTime用于兜底如果某些消息没有按照MsgID严格递增也可以作为辅助排序条件。离线消息和消息漫游在大多数IM里是一体化设计的在线推送失败的消息转为离线消息用户上线后通过同步接口一次性拉取。不要把它们拆成两套完全无关的存储逻辑否则会出现同一条消息在离线列表和历史记录里各存一份且ID对不上的情况。5. 序列化与版本兼容设计5.1 结构体的序列化标签与字段编号结构体最终要跨网络传输所以序列化方案必须提前定好。JSON、Protobuf、Thrift各有各的适用场景。我的建议是对外接口、调试场景可以用JSON便于排查核心的消息上下行链路用Protobuf或Thrift性能和类型安全性更好。如果使用Protobuf字段编号是头等大事。比如message Message { string msg_id 1; string client_msg_id 2; string conversation_id 3; string sender_id 4; string receiver_id 5; int32 msg_type 6; bytes content 7; int64 send_time 8; int32 status 9; mapstring, string ext 10; }这里从1开始编号这个编号一旦发布就永远不能变。字段编号是协议的一部分相当于数据库表的主键。如果某个字段在后续版本里挪动了用途老客户端解析时就会出错。我在项目里要求所有人改协议时都先在文档里备注字段编号任何人不准复用已废弃的编号。JSON格式则要注意字段名的序列化tag。Go里默认字段名首字母大写会被原样导出所以要用json标签统一成小写下划线风格。不同语言之间尤其要注意Java后端喜欢驼峰Go服务喜欢下划线客户端可能又用另一种风格。定一套统一的命名规范序列化标签严格遵循不要靠运气。5.2 兼容性演进新增/废弃字段策略IM系统升级是常态但客户端和服务端往往不是同时发布。我曾经因为删除一个旧字段导致老版本客户端崩溃。后来总结了非常严格的字段演进规则新增字段时必须保证是optional且默认值对旧客户端无影响。旧客户端解析一个未知字段时会直接忽略但前提是序列化框架支持未知字段保留或忽略所以千万不要在协议解析层上做“未知字段直接报错”的严格校验。废弃字段时不要把字段直接从结构体里删掉而是标记为reserved并且保留它的编号。Protobuf里有reserved关键字JSON没有那就只能在文档里记录“该字段已废弃不可复用编号”。如果有人复用废弃字段编号会导致老客户端把新数据解析成完全不同的含义这是最危险的兼容性事故。修改字段类型是绝对禁止的。int32改成int64看上去简单但对老客户端来说字节布局完全不同解析的数据会变成乱码。需要换类型的时候新增一个字段老字段保留原义或标记废弃。变更类型是否允许处理方式新增optional字段允许默认值要兼容旧端删除字段尽量避免标记reserved不删编号修改字段类型禁止新增字段替代修改枚举值含义禁止枚举只能追加修改包名/服务名谨慎做好全链路兼容测试枚举类型也需要小心枚举值一旦确定就不能修改含义只能追加。比如MsgType为3表示图片之后不能改成一个完全不同的业务消息。追加新枚举时旧版本客户端遇到不认识的枚举值要做好兜底处理比如显示“该消息类型版本过低无法查看”。5.3 常见问题与排查技巧实录聊几个我在实际联调和线上排查中遇到过的问题都是结构体设计引发的。第一个是int类型跨语言不一致。有个服务端同事在结构体里用了Go的int客户端用的是Java的int32。Go的int在64位机器上是8字节Java的int是4字节序列化后字段长度不一致导致客户端解析后字段错位。排查了很久才发现是类型长度不一致。从那时起所有跨网络传输的整数类型全部显式声明为int32或int64绝不用平台相关的int。第二个是时间戳单位不统一。消息结构体里SendTime有的地方是秒有的地方是毫秒排序和展示都会异常。后来我在结构体定义旁边写清楚注释所有时间戳统一使用毫秒存储层如果为了节省空间再转成秒必须在转换函数里单独处理。结构体字段注释不是可有可无的它就是在传递约束。第三个是Content字段误用string导致性能问题。在一次性能压测中发现消息转发时内存占用很高定位后发现是Content类型用了string每次复制消息内容都会产生一次深拷贝。改成[]byte之后字节切片在传递过程中只复制引用内存明显下降。第四个是Session覆盖问题。同一用户在不同设备登录如果不做device维度区分新连接会覆盖旧连接导致另一台设备收不到消息。Session结构体里必须带有DeviceID并且Redis的key要设计成UserID:DeviceID而不是只按UserID存储。踢人逻辑也要显式判断比如手机端登录时可以主动踢掉相同设备ID的旧连接但不同设备应该允许共存。第五个是消息体过大导致网关推送超时。结构体设计上内容类型是开放的但网关必须有大小限制。否则有人发一个几十MB的“文本消息”序列化后数据包很大网关内存被占满其他用户消息也跟着卡住。排查方法是在网关入口打印Packet大小分布超过阈值的请求直接拒绝。这些问题的共同点是它们不是代码逻辑难而是结构体设计阶段没有把约束和边界定义清楚。结构体不只是数据的容器它同时是协议、是契约、是系统各个模块之间的信任边界。最后说一个我自己的习惯。每次改完核心结构体我都会让客户端和服务端联调时专门跑一遍“新版发消息、旧版收消息”和“旧版发消息、新版收消息”的交叉测试不测一遍我是不敢上线的。IM这种系统的线上问题影响范围太大一条消息发不出去用户感知极其明显。结构体设计得再漂亮最终还是要经得住真实网络环境和客户端版本的考验。