137 lines
5.0 KiB
Markdown
137 lines
5.0 KiB
Markdown
# 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
|
||
|
||
## 循环依赖检查
|
||
|
||
```bash
|
||
# 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 结构化 |