基于Golang的分布式即时通讯微服务系统设计与实现

POST /api/auth/register，入参：手机号/邮箱 + 密码 + 验证码；校验手机号格式/邮箱格式、密码长度≥8位含字母数字、验证码5分钟内有效；出参返回用户ID和JWT access token；错误码含参数校验失败、验证码错误/过期、账号已存在。

POST /api/auth/login，入参：账号（手机号/邮箱/用户名）+ 密码；校验账号存在且密码匹配（bcrypt验证）；出参返回JWT access_token（15min过期）+ refresh_token（7天过期）+ 用户基本信息；错误码含账号不存在、密码错误、账号被冻结。

POST /api/auth/refresh，入参：refresh_token；校验token有效且未过期、未列入黑名单；出参返回新的access_token和refresh_token（旧refresh_token立即失效）；错误码含token无效、token已过期、token已吊销。

GET /api/user/profile 查看个人信息（昵称、头像、手机号、邮箱、注册时间）；PUT /api/user/profile 修改昵称和头像（头像上传需限制≤2MB，支持jpg/png）；需携带有效access_token；错误码含未登录、文件过大、格式不支持。

客户端通过WebSocket发送消息帧：{type:"chat", to:目标用户ID, content:文本内容(≤5000字), msgId:客户端生成唯一ID}；服务端校验双方为好友关系、目标用户未被拉黑，校验通过后投递到消息队列异步处理；返回ACK确认帧含服务端msgId和时间戳。

服务端通过WebSocket向在线接收方推送消息帧：{type:"chat", from:发送者ID, content, msgId, timestamp}；若接收方不在线，消息进入离线队列；客户端收到后回执已读确认帧{type:"ack", msgId}，服务端标记消息已送达。

GET /api/chat/history?peerId=xxx&before=timestamp&limit=20，分页拉取与指定用户的历史消息；返回消息列表（msgId、发送方、内容、时间戳、已读状态）；limit最大50，默认20；支持按时间倒序；错误码含非好友关系、参数无效。

GET /api/contacts/search?q=xxx，按用户名/手机号/邮箱模糊匹配搜索用户；返回匹配用户列表（ID、昵称、头像），不返回已删除或已拉黑用户；支持分页，每页20条。

POST /api/contacts/request 发送好友申请（入参：目标用户ID + 验证消息，≤50字）；GET /api/contacts/requests 查看待处理申请列表；PUT /api/contacts/request/{id} 同意/拒绝申请；同一用户24h内不能重复发送申请；错误码含已是好友、申请已存在、对方拒绝接收申请。

GET /api/contacts/list 返回好友列表（好友ID、昵称、头像、在线状态、最后在线时间）；在线状态通过WebSocket实时推送变更（上线/离线/忙碌）；支持按在线状态排序（在线优先）。

POST /api/groups，入参：群名称（2-30字，必填）、群头像（可选）、初始成员ID列表（至少2人）；创建者自动成为群主；出参返回群组ID、群号（6位数字，全局唯一）；同一用户最多创建20个群组；错误码含群名重复、成员不足。

POST /api/groups/{id}/join 通过群号搜索并申请加入（群主/管理员审核后入群）；POST /api/groups/{id}/leave 主动退出群组（群主退出前需转让群主给其他成员）；群主退群若无可转让成员则群组解散；错误码含群组不存在、群已满员（上限200人）、已在群中。

客户端通过WebSocket发送群消息帧：{type:"group", groupId, content(≤5000字)}；服务端校验发送者为群成员，通过消息队列异步广播到群内所有在线成员；离线成员自动进入离线消息队列；支持@某人功能（@all 仅群主/管理员可用）。

GET /api/groups/{id}/members 查看群成员列表（昵称、头像、角色、入群时间）；PUT /api/groups/{id}/members/{uid}/role 群主设置/取消管理员；DELETE /api/groups/{id}/members/{uid} 群主/管理员踢出成员；以上操作仅群主或管理员可执行，错误码含无权限、目标用户不在群中。

当消息目标用户不在线时，消息服务将消息写入离线消息表（含msgId、发送方、接收方、内容、时间戳、消息类型）；单用户离线消息上限500条，超出后按FIFO淘汰旧消息；群聊离线消息同样存储且标注groupId。

用户WebSocket连接建立成功后，服务端自动拉取该用户所有离线消息（按时间升序），批量推送到客户端；推送完成后清空已推送的离线消息记录；单次拉取最多100条，超出的分批推送；客户端每收到一批回执确认。

客户端通过 ws://host/ws?token={JWT} 建立WebSocket连接；服务端在握手阶段校验JWT有效性，无效则关闭连接并返回4001状态码；认证通过后，将该连接注册到连接管理器（userId → conn映射），支持同一用户多端登录（最多3端）。

客户端每30秒发送Ping帧{type:"ping"}，服务端回复Pong帧{type:"pong"}；服务端超过90秒未收到Ping则判定连接断开，主动关闭连接并清理连接管理器；心跳超时后触发用户离线状态广播。

客户端检测到WebSocket断开后自动重连（指数退避：1s→2s→4s→8s，最大间隔30s，最多重试10次）；重连成功后携带上次最后收到的msgId，服务端推送断线期间遗漏的消息；重连超30秒未成功则提示用户手动刷新。

每个微服务编写Dockerfile（基于golang:1.21-alpine多阶段构建，最终镜像≤50MB）；使用docker-compose.yml编排所有服务：auth-service、contact-service、chat-service、group-service、message-router、api-gateway、etcd、kafka/zookeeper、mysql、redis；服务间通过容器网络通信。

MySQL 8.0存储用户、好友关系、群组、消息历史等结构化数据；Redis 7.x用于缓存用户在线状态、JWT黑名单、验证码（5分钟TTL）；消息历史按月分表（chat_message_YYYYMM），支持归档；数据库连接池最大50连接，超时30秒。

各微服务启动时向ETCD注册自身信息：服务名、实例ID（UUID）、IP:Port、健康检查端点、权重；注册TTL为30秒，需定期续约（每10秒续约一次）；注册信息以 /services/{serviceName}/{instanceId} 为Key存储。

API网关通过ETCD Watch机制监听服务实例变更；请求路由时从ETCD获取目标服务的所有健康实例列表，使用轮询（Round-Robin）策略分发请求；实例下线（TTL过期）后自动从路由表移除，30秒内生效。

每个微服务暴露 /health 端点返回200+{status:"UP"}；ETCD注册的健康检查端点由网关每10秒探测一次；连续3次探测失败（HTTP非200或超时2秒）则标记实例不健康，从路由表剔除；恢复后自动重新加入。

API网关统一监听80端口，根据请求路径前缀路由到对应微服务：/api/auth/* → auth-service，/api/contacts/* → contact-service，/api/chat/* → chat-service，/api/groups/* → group-service；支持路径参数透传和请求体转发。

网关对所有 /api/* 请求（除 /api/auth/login 和 /api/auth/register）进行JWT校验；从Authorization Header提取Bearer Token，验证签名和过期时间；校验失败返回401；校验通过后将userId注入请求上下文Header（X-User-Id）传递给下游服务。

网关对每个API路径配置令牌桶限流（默认100 req/s，可配置）；超限返回429 Too Many Requests；对下游服务调用配置熔断器：连续5次失败触发熔断，熔断期间直接返回503，30秒后半开探测；探测成功恢复，失败继续熔断。

消息服务作为生产者，将用户发送的消息序列化为JSON后投递到Kafka Topic（chat-message）；消息体含msgId、from、to、content、timestamp、type(single/group)；生产者配置acks=all确保消息不丢失。

消息路由服务作为消费者订阅chat-message Topic，消费消息后查询接收方在线状态：在线则通过WebSocket推送；离线则写入离线消息表；消费确认使用手动提交offset，确保消息被成功处理后才提交。

消息队列配置持久化存储（Kafka log.retention.hours=72或RabbitMQ durable queue）；生产者失败重试3次；消费者幂等处理（基于msgId去重）；死信队列兜底处理消费失败消息；全链路消息追踪使用msgId关联。