Skip to content

技术文档.md

Latest commit

 

History

History
203 lines (147 loc) · 7.87 KB

技术文档.md

File metadata and controls

203 lines (147 loc) · 7.87 KB

IM-Chat 技术文档（当前版）

  • 更新时间：2026-02-08
  • 代码分支：dev（HEAD：d61d34b）
  • 评估范围：IMChat/（iOS SwiftUI）+ backend/（Go + Gin + GORM）
  • 当前结论：项目已进入“可持续迭代”阶段，课程演示/内部联调可用；若要生产上线，需先补齐配置治理、CORS、响应统一、测试与可观测性。

1. 当前状态快照

1.1 已稳定能力（已闭环）

  1. 架构分层已落地
  • 前端采用 App / Core / Features / Shared 分层，核心依赖通过 AppContainer 装配。
  • 后端采用 router -> handler -> service -> model 主路径，WS 由独立 Hub 管理。
  1. HTTP/WS 鉴权链路已打通
  • HTTP：backend/internal/middleware/auth.go 统一校验 Authorization: Bearer <token> 并注入 userID。
  • WS：/ws 复用同一鉴权中间件，不再信任 query 参数中的用户身份。
  1. 聊天主链路可用
  • 历史消息分页：/api/messages 已支持 page/pageSize。
  • 实时消息确认：WS 支持 clientMessageId + messageId 回执，前端可替换乐观消息。
  • 弱网可用性：WebSocketService 支持重连、心跳、离线发送队列。
  1. 个人资料链路可用
  • 头像更新已形成两段式闭环：/api/upload -> /api/user/avatar。
  • 前端成功后会同步更新会话中的当前用户头像。

1.2 当前工作区变更（未提交）

  1. 聊天页滚动留白优化
  • 文件：IMChat/IMChat/Features/Chat/Presentation/ChatRoomView.swift
  • 现状：根据消息数量动态调整顶部留白，减少“少量消息时被头部遮挡”和“消息多时顶部黑边过大”。
  1. 个人页统计卡片宽度微调
  • 文件：IMChat/IMChat/Features/Profile/Presentation/ProfileView.swift
  • 现状：统计卡容器 maxWidth 从 420 调整为 380，改善小屏展示。
  1. 文档文件调整
  • Architecture_Review_Frontend_Backend_2026-02-07.md 已删除（工作区状态）。
  • 当前文档以 技术文档.md 为主。

2. 当前架构概览

2.1 前端（SwiftUI）

目录职责：

  • 应用壳层：IMChat/IMChat/App/
  • 基础能力层：IMChat/IMChat/Core/
  • 业务模块层：IMChat/IMChat/Features/
  • 共享层：IMChat/IMChat/Shared/

关键入口：

  • 依赖装配：IMChat/IMChat/Core/DI/AppContainer.swift
  • 路由切换：IMChat/IMChat/App/ContentView.swift
  • 会话状态：IMChat/IMChat/Core/Session/AppSessionStore.swift
  • 网络层：IMChat/IMChat/Core/Networking/APIClient.swift
  • 实时层：IMChat/IMChat/Core/Realtime/WebSocketService.swift

2.2 后端（Go）

目录职责：

  • 启动入口：backend/cmd/server/main.go
  • 路由层：backend/internal/router/router.go
  • 处理层：backend/internal/handlers/
  • 业务层：backend/internal/service/
  • 数据层：backend/internal/models/
  • 实时层：backend/internal/ws/

关键入口：

  • 配置加载：backend/internal/config/config.go
  • 鉴权中间件：backend/internal/middleware/auth.go
  • WS 主循环：backend/internal/ws/hub.go
  • 统一响应：backend/pkg/response/response.go

2.3 前后端契约对齐现状

  1. 已对齐
  • 鉴权：Bearer token（HTTP + WS）。
  • 历史消息：receiverId/page/pageSize。
  • 消息确认：clientMessageId/messageId。
  1. 未完全对齐
  • 上传接口仍为 raw JSON（{"url":"..."}），其他接口为 code/msg/data 包装。

3. 核心链路现状

3.1 登录与会话恢复

  • 登录/注册后前端保存 token 和 user，并立即建立 WS。
  • 启动时 restoreSession() 会恢复本地会话并尝试重连 WS。

对应文件：

  • IMChat/IMChat/Features/Auth/Presentation/AuthViewModel.swift
  • IMChat/IMChat/Core/Session/AppSessionStore.swift
  • IMChat/IMChat/Core/Session/SessionStorage.swift

3.2 聊天历史与实时消息

  • 首屏加载第 1 页历史。
  • 顶部触发增量分页。
  • 发送时先本地乐观插入，再由 WS 回执替换。

对应文件：

  • IMChat/IMChat/Features/Chat/Presentation/ChatViewModel.swift
  • IMChat/IMChat/Features/Chat/Data/ChatRepository.swift
  • backend/internal/handlers/message.go
  • backend/internal/ws/hub.go

3.3 头像上传

  • 第一步：文件上传，返回可访问 URL。
  • 第二步：写入用户头像字段并同步前端会话。

对应文件：

  • IMChat/IMChat/Features/Profile/Data/ProfileRepository.swift
  • backend/internal/handlers/upload.go
  • backend/internal/handlers/user.go

4. 问题与风险（按优先级）

P0（上线前必须处理）

  1. 配置治理未闭环
  • 现状：backend/.env、backend/config.yaml 存在本地明文配置。
  • 缺口：未提供可提交模板 backend/.env.example、backend/config.example.yaml。
  • 风险：协作环境不一致、敏感信息误用或误传。
  1. CORS 配置冲突
  • 文件：backend/internal/router/router.go
  • 问题：Access-Control-Allow-Origin: * 与 Allow-Credentials: true 同时存在。
  • 风险：浏览器行为不确定，生产跨域策略不可控。

P1（建议本周处理）

  1. 响应风格不统一
  • 文件：backend/internal/handlers/upload.go
  • 问题：上传接口返回 raw JSON，其他接口返回统一包装体。
  • 影响：前端网络层被迫维护 wrapped/raw 双解析路径。
  1. 分层边界未完全收敛
  • 文件：backend/internal/handlers/user.go、backend/internal/handlers/user_list.go、backend/internal/ws/client.go
  • 问题：handler/WS 仍直接访问 model/DB。
  • 影响：业务逻辑分散，测试与维护成本升高。
  1. 前端环境配置硬编码
  • 文件：IMChat/IMChat/App/Config/Constants.swift
  • 问题：serverIP 为固定值。
  • 影响：切换网络环境需要改代码重编译，联调成本高。

P2（中期优化）

  1. 自动化测试缺失
  • 现状：未发现后端 _test.go；未发现前端 *Tests.swift。
  • 风险：重构回归无法快速发现。
  1. 可观测性不足
  • 现状：缺 request_id/user_id/latency 等结构化日志字段和基础指标。
  • 风险：线上问题定位慢。

5. 下一阶段建议（基于你当前进度）

Phase A：安全与配置（优先）

  1. 补模板配置文件
  • 新增：backend/.env.example、backend/config.example.yaml。
  • 验收标准：新机器仅按模板即可启动后端。
  1. 修复 CORS
  • 改为按环境白名单 origin，不使用 * + credentials 组合。
  • 验收标准：浏览器跨域行为稳定，可明确限制来源。

Phase B：契约统一

  1. 统一上传接口响应
  • /api/upload 改为 response.Success(c, gin.H{"url": url}) 同风格返回。
  • 验收标准：前端 APIClient 可移除 raw 分支（或显著收敛）。
  1. 细化业务错误码
  • 针对鉴权、参数、资源冲突等常见错误补细粒度业务码。
  • 验收标准：前端可按业务码做稳定提示与兜底逻辑。

Phase C：工程质量

  1. 增加基础测试
  • 后端先覆盖 auth middleware、message pagination、upload handler。
  • 前端先覆盖 AuthViewModel、ChatViewModel 核心状态流。
  1. 增加关键日志字段
  • 至少覆盖 request_id、user_id、latency_ms、path。

6. 总体判断

  1. 以“课程/演示/内部联调”为目标：当前版本已可稳定推进，且架构方向正确。
  2. 以“生产上线”为目标：先完成 P0 + P1，再评估灰度发布。
  3. 当前最值得优先做的两件事：配置治理模板化 + CORS/响应契约统一。

7. 快速阅读顺序（给后续维护）

  1. 先读入口：IMChat/IMChat/App/IMChatApp.swift、backend/cmd/server/main.go
  2. 再读状态与通信骨架：IMChat/IMChat/Core/DI/AppContainer.swift、IMChat/IMChat/Core/Realtime/WebSocketService.swift、backend/internal/ws/hub.go
  3. 再读核心业务：IMChat/IMChat/Features/Chat/Presentation/ChatViewModel.swift、backend/internal/handlers/message.go
  4. 最后读风险点：backend/internal/router/router.go、backend/internal/handlers/upload.go、IMChat/IMChat/App/Config/Constants.swift