新人代码阅读指南

项目概述

ChatView 是一个端到端的即时通讯应用，使用 Ed25519 公钥作为用户标识。项目分为三部分：

Server — gRPC 服务端，Go 实现，PostgreSQL 存储
Client — 桌面客户端，Go + Fyne GUI，本地 SQLite 缓存
Proto — protobuf 协议定义，gRPC 通信协议

特性	实现方式
用户标识	Ed25519 公钥
认证	Challenge-Response 签名（私钥不离开客户端）
通信	gRPC + protobuf
服务端存储	PostgreSQL
客户端缓存	SQLite
GUI	Fyne (Go 原生跨平台 UI 库)

顺序	文件	说明
1	`proto/chatview/common/types.proto`	枚举定义 + 通用消息体（FriendInfo、Message、AdminStats）
2	`proto/chatview/auth.proto`	认证协议：Challenge-Response 流程
3	`proto/chatview/chat.proto`	聊天协议：好友、消息、历史、已读
4	`proto/chatview/events.proto`	事件流：新消息、好友状态、广播、强制下线
5	`proto/chatview/admin.proto`	管理员协议：封禁/解封、广播、面板轮询

顺序	文件	说明
6	`server/internal/contextx/auth.go`	Context 注入 Principal（25 行，极简）
7	`server/internal/db/db.go`	PostgreSQL 连接、事务、迁移、语义化错误分类
8	`server/internal/eventhub/hub.go`	发布/订阅事件总线（110 行）
9	`server/internal/interceptor/auth.go`	认证拦截器：从 metadata 提取 token 验证
10	`server/internal/interceptor/admin.go`	管理员权限拦截器
11	`server/internal/service/auth.go`	认证服务：RequestChallenge + Login
12	`server/internal/service/chat_send.go`	消息发送：幂等 + 串行化重试
13	`server/internal/service/chat_history.go`	消息历史：游标分页
14	`server/internal/service/events.go`	事件流订阅
15	`server/cmd/server/main.go`	入口：组装启动

顺序	文件	说明
16	`client/internal/domain/types.go`	客户端数据类型（LoginResult、Message、Event 等）
17	`client/internal/core/ports.go`	接口定义：authPort/chatPort/eventPort/adminPort
18	`client/internal/identity/store.go`	本地 Ed25519 密钥管理（PIN 加密存储）
19	`client/internal/core/auth.go`	登录编排：在线/离线双路径
20	`client/internal/core/messages.go`	消息发送：在线直发 vs outbox 异步
21	`client/internal/core/outbox.go`	离线消息队列：worker 重试机制
22	`client/internal/core/history.go`	消息历史 + 同步
23	`client/internal/core/service.go`	Service 结构体：依赖组装

顺序	文件	说明
24	`client/internal/rpcclient/client.go`	gRPC 连接管理
25	`client/internal/rpcclient/auth.go`	认证 RPC 映射
26	`client/internal/rpcclient/chat.go`	聊天 RPC 映射
27	`client/internal/rpcclient/events.go`	事件流 RPC 映射
28	`client/internal/storage/store.go`	SQLite 缓存（好友、消息、outbox）
29	`client/internal/storage/migrations.go`	SQLite schema 迁移

顺序	文件	说明
30	`client/internal/ui/app.go`	Application 结构体 + Run 入口
31	`client/internal/ui/auth_view.go`	登录/注册/导入 UI
32	`client/internal/ui/shell_view.go`	主界面布局：侧边栏 + 聊天面板
33	`client/internal/ui/sync.go`	数据同步：好友刷新、消息加载、发送
34	`client/internal/ui/state.go`	状态管理：消息合并、session 生命周期
35	`client/internal/ui/async.go`	结构化并发：sessionSnapshot + 泛型任务模板
36	`client/internal/ui/events.go`	实时事件处理 + 自动重连
37	`client/internal/ui/components.go`	可复用 UI 组件

关键路径跟踪

登录流程

┌─ UI: auth_view.go ────────────────────────────────────────────┐
│ 用户输入 PIN → Application.login(pin)                         │
└──────────────────────────┬────────────────────────────────────┘
                           │
┌─ Core: auth.go ───────────────────────────────────────────────┐
│ Service.Login(ctx, pin)                                       │
│   1. identity.Load(pin)   → 解密本地 Ed25519 私钥              │
│   2. rpc.Login(ctx, pubKey, sign)                             │
│      ├─ 在线成功 → setSession(pubKey, role, offline=false)     │
│      └─ 网络故障 → setSession(pubKey, 0, offline=true)         │
└──────────────────────────┬────────────────────────────────────┘
                           │
┌─ RPC: rpcclient/auth.go ──────────────────────────────────────┐
│ Client.Login()                                                │
│   1. RequestChallenge(publicKey)   → 获得随机 challenge        │
│   2. ed25519.Sign(privateKey, challenge)                       │
│   3. Login(publicKey, signature)   → 获得 sessionToken         │
│   4. 保存 token 到 client metadata                             │
└──────────────────────────┬────────────────────────────────────┘
                           │ gRPC
┌─ Server: service/auth.go ─────────────────────────────────────┐
│ AuthService.Login()                                           │
│   1. 验证 Ed25519 签名                                         │
│   2. 检查用户状态（是否被封禁）                                  │
│   3. 生成 session token → 写入 sessions 表                     │
│   4. 返回 sessionToken + role + publicKey                      │
└───────────────────────────────────────────────────────────────┘

消息发送流程

┌─ UI: sync.go ────────────────────────────────────────────────┐
│ Application.sendMessage()                                    │
│   1. 清空输入框                                                │
│   2. core.Service.SendMessage(ctx, receiver, text)            │
└──────────────────────────┬────────────────────────────────────┘
                           │
┌─ Core: messages.go ──────────────────────────────────────────┐
│ Service.SendMessage()                                        │
│   1. 生成 clientMessageID（UUIDv7，幂等键）                    │
│   2. 创建 pending 状态 message                                │
│   3. cache == nil？                                           │
│      ├─ 是 → 直接 rpc.SendMessageWithID()                    │
│      └─ 否 → cache.EnqueueOutbox() + sendOutboxItem()        │
└──────────────────────────┬────────────────────────────────────┘
                           │ gRPC
┌─ Server: service/chat_send.go ───────────────────────────────┐
│ ChatService.SendMessage()                                    │
│   1. 串行化重试（最多 3 次）                                    │
│   2. clientMessageID 去重检查                                   │
│   3. 验证接收者存在                                            │
│   4. 事务内：EnsureConversation → next_seq++ → INSERT message │
│   5. 事件推送 → Hub.Push(receiver, NewMessageEvent)           │
│   6. 返回 messageId + serverSeq                               │
└───────────────────────────────────────────────────────────────┘

实时事件流

┌─ UI: events.go ──────────────────────────────────────────────┐
│ Application.watchEvents()                                    │
│   1. core.Service.Subscribe(ctx)                             │
│   2. 循环读取 event channel                                   │
│   3. 根据 event.Kind 分发：                                    │
│      new_message → syncConversation + refreshFriends         │
│      friend_status → refreshFriends                           │
│      system_broadcast → notify                                │
│      force_offline → logout + showAuth                        │
│      admin_update → refreshAdmin                              │
│   4. 连接断开时 exponential backoff 自动重连                   │
└──────────────────────────┬────────────────────────────────────┘
                           │
┌─ Server: eventhub/hub.go ────────────────────────────────────┐
│ Hub                                                          │
│   Register(pubKey, clientID, chan)                           │
│   Unregister(pubKey, clientID)                               │
│   Push(pubKey, event)         → 广播给指定用户的所有连接       │
│   Broadcast(event)            → 广播给所有在线用户             │
│   PushAdmins(ctx, store, e)   → 仅广播给管理员                 │
└───────────────────────────────────────────────────────────────┘

数据流图

                    ┌──────────┐
                    │   Proto  │  协议定义
                    │  定义文件  │  (5 files)
                    └────┬─────┘
                         │ protoc 生成
                    ┌────▼─────┐
                    │ api/gen/ │  生成代码
                    │   (排除)   │  (9 files)
                    └────┬─────┘
                         │ import
          ┌──────────────┼──────────────┐
          │              │              │
    ┌─────▼─────┐  ┌─────▼─────┐        │
    │  Server   │  │  Client   │        │
    │  gRPC 服务 │◄─┤  Fyne 桌面 │        │
    └─────┬─────┘  └─────┬─────┘        │
          │              │              │
    ┌─────▼─────┐  ┌─────▼─────┐        │
    │PostgreSQL │  │  SQLite   │        │
    │ 服务端存储 │  │  本地缓存  │        │
    └───────────┘  └───────────┘        │

技术要点速览

Ed25519 认证

用户创建身份时生成 Ed25519 密钥对
私钥用 PIN + NaCl secretbox 加密存储在本地
登录时客户端用私钥签名服务端的随机 challenge
服务端用公钥验证签名，私钥不离开客户端
位置：client/internal/identity/store.go、server/internal/service/auth.go

幂等消息发送

客户端发送消息时生成 clientMessageID（UUIDv7）
服务端收到后检查此 ID 是否已写入，已写则直接返回原始响应
配合 serialization failure 自动重试，保证 exactly-once 语义
位置：server/internal/service/chat_send.go、server/internal/service/chat_dedupe.go

离线 Outbox

客户端发送消息时同时写入本地 SQLite outbox 表
网络不通时消息停留在 pending 状态
后台 worker 定期重试，成功后更新本地状态为 sent
位置：client/internal/core/outbox.go、client/internal/storage/outbox.go

事件推送

服务端 Hub 维护 pubKey → [client channel] 映射
消息发送成功后，服务端 Push 事件到接收者的所有连接
客户端通过 gRPC server-streaming 订阅事件流
位置：server/internal/eventhub/hub.go、client/internal/ui/events.go

结构化并发 — Context 树

项目使用 Go context 构建 goroutine 生命周期树，实现级联取消——取消根节点自动传播到所有子 goroutine，不会泄漏。

Session Context（会话根节点）

client/internal/ui/state.go:66-84 — 每次登录创建新的 context.WithCancel，登出时取消：

func (a *Application) startSessionContext() {
    a.sessionCtx, a.sessionCancel = context.WithCancel(context.Background())
}
func (a *Application) stopSessionContext() {
    a.sessionCancel()   // ← 这一行会级联取消所有子 goroutine
}

SessionSnapshot — 并发安全的上下文快照

client/internal/ui/async.go — goroutine 启动时捕获当前 session 的 context + 版本号：

type sessionSnapshot struct {
    ctx     context.Context
    version int
}

func runSessionTask[T any](a *Application, work func(context.Context) (T, error), apply func(T, error)) {
    snapshot := a.currentSessionSnapshot()       // 捕获快照
    go func() {
        result, err := work(snapshot.ctx)        // 后台工作感知 ctx 取消
        a.doInSession(snapshot, func() {         // 回到 UI 线程时二次校验
            apply(result, err)
        })
    }()
}

doInSession 双重保护：先检查 ctx.Err()（context 是否已取消），再检查 sessionVersion（是否已登出再登入）。

goroutine 树结构

startSessionContext()                         ← 根 context
  │
  ├─ startOutboxWorker(ctx)                   ← ctx, cancel = WithCancel(parent)
  │     └─ processOutbox(ctx) → ctx.Done()
  │
  ├─ watchEvents(ctx)                         ← ctx, cancel = WithCancel(sessionCtx)
  │     └─ select { event, err, ctx.Done() }
  │
  ├─ runSessionTask(snapshot)                 ← snapshot.ctx = sessionCtx
  │     └─ work(snapshot.ctx) → ctx 取消则提前返回
  │
  └─ startOutboxPoller(ctx)                   ← ctx, cancel = WithCancel(sessionCtx)
        └─ ticker → ctx.Done()

服务端同理

server/cmd/server/main.go — OS 信号转为 context：

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
go store.RunCleanup(ctx, cfg.CleanupInterval)       // 后台清理感知 ctx
go eventhub.RunPresenceHealer(ctx, store, hub, ...) // 在线修复感知 ctx
// Ctrl+C → stop() → ctx.Done() → 所有后台 goroutine 优雅退出

设计要点

机制	作用	位置
`context.WithCancel`	创建可取消子树	`startOutboxWorker`、`watchEvents`、`startOutboxPoller`
`ctx.Done()`	goroutine 退出信号	所有后台 select 语句
`sessionSnapshot`	捕获 context + version，防止竞态	`async.go`
`doInSession`	UI 回调前二次确认 session 有效性	`async.go:27-31`
`sessionVersion`	整数版本号，context 之外的兜底保护	`state.go`

本地开发

前置条件

# PostgreSQL（服务端需要）
# Go 1.21+
# protoc（可选，仅修改 proto 时需要）

启动服务端

cd server

# 创建数据库
createdb chatview

# 启动（使用示例配置）
go run ./cmd/server -config config.example.yaml

启动客户端

cd client

# 启动（连接本地服务端）
go run ./cmd/client

# Wayland 下建议
go run -tags wayland ./cmd/client

运行测试

cd server && go test ./...
cd client && go test ./...

修改 Proto 后重新生成

./scripts/gen-proto

详情见 PROTO_GUIDE.md。

目录结构速查

chatview/
├── proto/                    # protobuf 协议定义
│   └── chatview/
│       ├── common/types.proto
│       ├── auth.proto
│       ├── chat.proto
│       ├── events.proto
│       └── admin.proto
├── api/                      # Go module（生成 + 手写）
│   ├── go.mod
│   └── gen/chatview/         # protoc 生成代码（不手动修改）
├── server/
│   ├── cmd/server/main.go    # 服务端入口
│   ├── config.example.yaml
│   ├── configuration.md
│   ├── migrations/           # PostgreSQL DDL 迁移
│   └── internal/
│       ├── auth/             # Ed25519 加密工具
│       ├── config/           # 配置加载
│       ├── contextx/         # Context Principal 注入
│       ├── db/               # PostgreSQL 数据层
│       ├── eventhub/         # 事件总线
│       ├── interceptor/      # gRPC 拦截器（认证/权限/日志）
│       └── service/          # gRPC 服务实现
├── client/
│   ├── cmd/client/main.go    # 客户端入口
│   ├── client.example.yaml
│   ├── configuration.md
│   └── internal/
│       ├── config/           # 配置加载
│       ├── core/             # 业务编排（ports 接口 + 实现）
│       ├── domain/           # 纯数据类型
│       ├── identity/         # Ed25519 密钥管理
│       ├── rpcclient/        # gRPC 传输适配
│       ├── storage/          # SQLite 本地缓存
│       └── ui/               # Fyne 桌面 UI
├── scripts/gen-proto         # Proto 代码生成脚本
└── tools/protoc-*/           # protoc 工具链

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

新人代码阅读指南

项目概述

推荐阅读顺序

第一阶段：理解协议和数据结构（约 400 行，15 分钟）

第二阶段：理解服务端（约 800 行，30 分钟）

第三阶段：理解客户端核心层（约 600 行，25 分钟）

第四阶段：理解客户端传输与存储（约 400 行，15 分钟）

第五阶段：理解客户端 UI（约 600 行核心，20 分钟）

关键路径跟踪

登录流程

消息发送流程

实时事件流

数据流图

技术要点速览

Ed25519 认证

幂等消息发送

离线 Outbox

事件推送

结构化并发 — Context 树

本地开发

前置条件

启动服务端

启动客户端

运行测试

修改 Proto 后重新生成

目录结构速查

FilesExpand file tree

CODE_GUIDE.md

Latest commit

History

CODE_GUIDE.md

File metadata and controls

新人代码阅读指南

项目概述

推荐阅读顺序

第一阶段：理解协议和数据结构（约 400 行，15 分钟）

第二阶段：理解服务端（约 800 行，30 分钟）

第三阶段：理解客户端核心层（约 600 行，25 分钟）

第四阶段：理解客户端传输与存储（约 400 行，15 分钟）

第五阶段：理解客户端 UI（约 600 行核心，20 分钟）

关键路径跟踪

登录流程

消息发送流程

实时事件流

数据流图

技术要点速览

Ed25519 认证

幂等消息发送

离线 Outbox

事件推送

结构化并发 — Context 树

本地开发

前置条件

启动服务端

启动客户端

运行测试

修改 Proto 后重新生成

目录结构速查