gochat/docs/ARCHITECTURE_REVIEW.md

GoChat Architecture Review

项目概览

GoChat 是 Chatwoot 的 1:1 Go 语言重写，旨在提供高性能、可扩展的全功能客服平台。

指标	数值
源代码行数	32,228
测试代码行数	8,746
源文件数	209
测试文件数	30
API路由数	104
模型结构体	28
Handler方法	~150

分层架构

cmd/main.go                  ← 入口
internal/app/bootstrap.go    ← DI 编排（repos→services→handlers→router）
internal/router/router.go    ← 104 路由注册
internal/handler/api/v1/     ← HTTP 处理层（15个handler文件）
internal/service/            ← 业务逻辑层（DI via 接口）
internal/repository/         ← 数据访问层（GORM + BaseRepository泛型）
internal/model/              ← 领域模型（28 个 struct）
internal/auth/               ← 认证+RBAC+MFA+SAML+OAuth
internal/channel/provider/   ← 渠道抽象（Telegram/WebWidget/API）
internal/llm/                ← AI集成（Captain/Copilot）
internal/middleware/         ← 11 个中间件（安全/限流/XSS/上传等）
internal/security/           ← 加密/Webhook签名/SQL安全
internal/ws/                 ← WebSocket hub + authenticator
internal/pubsub/             ← Watermill 事件驱动
internal/reporting/          ← 报表+指标注册
pkg/crypto/                  ← JWT + 加密工具

模块代码量分布

模块	行数	占比
channel (Telegram/WebWidget/API)	6,448	20.0%
handler (HTTP)	5,044	15.6%
service (业务逻辑)	4,426	13.8%
auth (认证/RBAC/MFA)	1,691	5.2%
middleware (安全中间件)	1,879	5.8%
security (加密/签名)	1,570	4.9%
ws (WebSocket)	1,221	3.8%
repository (数据访问)	1,820	5.6%
model (领域模型)	1,392	4.3%
reporting (报表)	477	1.5%
llm (AI)	579	1.8%
config	243	0.7%
pubsub	239	0.7%

关键设计决策

1. 依赖注入（DI）

• Bootstrap 函数按顺序编排：repos → services → handlers → router
• Services 依赖 repo 接口（不直接依赖 app.DB）
• Handlers 依赖 service 接口（不依赖 app.App struct）
• ✅ 优点：可测试、松耦合
• ⚠️ 缺点：无 DI 容器，手动编排复杂度随模块增长

2. 泛型 BaseRepository

• BaseRepository[T any] 提供通用 CRUD
• 具体 Repo 通过组合 BaseRepository + 自定义方法实现
• ✅ 减少重复代码
• ⚠️ 泛型错误处理需要关注 RowsAffected 检查

3. 渠道抽象（Channel Provider）

• ChannelProvider 接口：SendMessage/ReceiveMessage/ValidateWebhookToken
• Provider 工厂模式：GetProvider(channelType)
• 支持 Telegram、WebWidget、API Channel
• ✅ 新渠道只需实现接口 + 注册工厂

4. Watermill PubSub

• 替代 Chatwoot 的 Sidekiq/asynq
• 内存实现（可扩展到 Redis/NATS）
• 事件：message.created, conversation.updated, notification.created 等
• ✅ Go 生态标准选择，可插拔

5. 安全层

• JWT + RefreshToken + MFA (TOTP) + SAML + OAuth
• RBAC: PermissionMatrix → PolicyContext.Can(action, resource)
• SSRF 防护、Rate Limiting、XSS、上传安全、加密
• Webhook HMAC-SHA256 签名验证 + 防重放

6. AI 集成（Captain/Copilot）

• LLM provider 接口：Generate/Stream/Embed
• 多提供商支持（OpenAI/Anthropic/本地模型）
• Captain: assistant + scenario + document + custom_tool
• Copilot: message suggestion + thread analysis

循环依赖检查

# Go 模块依赖拓扑无循环
go build ./... → PASS
go vet ./... → PASS

各包 import 关系：

• handler → service → repository → model（单向）
• auth → config, crypto
• middleware → auth, config
• channel → model, pubsub, service（事件发布）
• ws → auth, crypto
• security → 独立（无外部依赖）

✅ 无循环依赖，依赖方向全部单向向下。

分层合规性评估

规则	状态	说明
Handler 不依赖 DB	✅	仅注入 Service 接口
Service 不依赖 app.App	✅	仅注入 Repo 接口
Repo 不依赖 Service	✅	仅依赖 GORM + model
Model 独立无业务逻辑	✅	纯数据结构 + GORM hooks
跨层通过接口通信	✅	全部 DI via 接口

改进建议

高优先级

1. 引入 DI 容器（wire/dig）— 减少 bootstrap 手动编排复杂度
2. Service 层测试覆盖率（0.2%→50%）— 关键业务逻辑需要验证
3. Repository 层测试覆盖率（6.3%→40%）— 数据访问层需保证正确性

中优先级

4. PubSub 扩展到 Redis/NATS — 生产环境需要持久化消息队列
5. 配置热加载 — 当前配置只在启动时加载
6. API 文档生成（Swagger/OpenAPI）— 104 个路由需要自动文档

低优先级

7. 性能优化 — Conversation List (468μs) 和 Message List (440μs) 有优化空间
8. 结构化日志 — applogger 当前简化版，生产需要 JSON 结构化