🎯 项目概述

• Treasure Box 是一个基于 Clean Architecture (六边形架构) 设计的前端+后端工具应用，采用 Go-Kratos/React 框架构建。
• 当前以 Text-to-SQL 为核心业务，支持ReAct 模式（Reasoning + Acting）、ASR (Automatic Speech Recognition) 和 TTS (Text-to-Speech) 能力。
• 可以通过Spec coding 快速扩展业务功能，结合DDD的项目结构有效避免AI堆叠屎山。
  

核心特性

• ✅ Clean Architecture: 严格的分层架构，依赖倒置
• ✅ 微服务友好: 原生支持 gRPC + HTTP
• ✅ 类型安全: Protobuf 定义 API，编译期检查
• ✅ 依赖注入: Google Wire 编译期依赖注入
• ✅ 数据库安全: GORM Gen 代码生成，避免 SQL 注入
• ✅ 容器化部署: Docker + Docker Compose
• ✅ 自动化 CI/CD: GitHub Actions 自动构建部署

---

🛠️ 技术栈总览

后端技术栈

类别	技术选型	版本	选择理由
语言	Go	1.24	高性能、并发友好、部署简单
框架	Go-Kratos	v2.8.0	微服务架构、DDD 友好
数据库	MySQL	8.0	生态成熟、运维成本低
ORM	GORM + Gen	v1.31.1	类型安全、功能完善
依赖注入	Google Wire	v0.6.0	编译期检查、无反射
API 定义	Protobuf	v3	类型安全、跨语言

前端技术栈

类别	技术选型	版本	选择理由
语言	JavaScript	ES6+	快速开发、学习成本低
框架	React	18.2.0	生态丰富、社区活跃
构建工具	Vite	5.0.8	极速 HMR、开发体验好
样式	TailwindCSS	3.3.6	原子化 CSS、快速开发
图标	Lucide React	0.294.0	现代化图标库

基础设施

类别	技术选型	选择理由
网关	Nginx	性能极佳、成熟稳定
容器	Docker	标准化部署
编排	Docker Compose	简单易用
CI/CD	GitHub Actions	无缝集成、免费额度
镜像仓库	GHCR	GitHub 原生支持
云服务	阿里云	国内速度快、价格优

---

📁 项目结构

代码结构

• github地址：https://github.com/hanjg/treasure_box

treasure_box/
├── api/                    # Protobuf API 定义
├── cmd/                    # 应用入口
├── internal/               # 核心业务逻辑
│   ├── adapter/            # 适配器层
│   │   ├── driven/         # 被驱动适配器 (API)
│   │   └── driving/        # 驱动适配器 (数据访问)
│   ├── domain/             # 领域层
│   │   ├── entities/       # 实体
│   │   ├── interfaces/     # 接口 (端口)
│   │   └── services/       # 领域服务
│   └── usecases/           # 用例层
├── pkg/                    # 公共包
├── web/                    # 前端应用
├── configs/                # 配置文件
├── docker/                 # Docker 相关
├── scripts/                # 部署脚本
└── .github/                # CI/CD 配置

---

部署结构

阿里云 ECS
    ↓
Docker Compose Network
    ├── Frontend (Nginx) :80
    ├── Backend (Kratos) :8000
    ├── MySQL :3306
    └── Umami :3000 (Optional)

---

🔄 开发&部署流程

📊 核心业务时序

Text-to-SQL 转换流程

---

📝附录

1. 服务端语言：Go 1.24

对比方案

维度	Go	Java	Node.js	Python
性能	⭐⭐⭐⭐⭐ 编译型，高并发性能优秀	⭐⭐⭐⭐ JVM优化好，但启动慢	⭐⭐⭐ 单线程，I/O密集型好	⭐⭐ GIL限制，性能较弱
并发模型	Goroutine + Channel，轻量级	Thread Pool，重量级	Event Loop，异步回调	asyncio，复杂度高
开发效率	⭐⭐⭐⭐ 简洁，工具链完善	⭐⭐⭐ 生态成熟但冗长	⭐⭐⭐⭐⭐ 快速开发	⭐⭐⭐⭐⭐ 快速原型
类型安全	静态强类型	静态强类型	弱类型（需TypeScript）	动态类型（需类型提示）
部署	单一二进制，无依赖	需JVM，包体积大	需Node运行时	需Python环境
微服务	⭐⭐⭐⭐⭐ 天然适合	⭐⭐⭐⭐ Spring Cloud成熟	⭐⭐⭐ 轻量但缺乏规范	⭐⭐ 不适合高性能场景

选择理由

• ✅ 高性能并发：Goroutine模型适合处理大量并发请求
• ✅ 部署简单：编译成单一二进制文件，无需运行时环境
• ✅ 内存占用低：相比JVM节省资源，适合容器化部署
• ✅ 强类型安全：编译期错误检查，减少运行时问题
• ✅ 云原生生态：Kubernetes、Docker等都是Go编写，生态契合

---

2. 服务端框架：Go-Kratos v2

对比方案

维度	Kratos	Gin	Echo	Go-Zero
架构风格	微服务框架，DDD友好	Web框架，轻量级	Web框架，性能优先	微服务框架，工具链强
gRPC支持	⭐⭐⭐⭐⭐ 原生支持	⭐⭐ 需手动集成	⭐⭐ 需手动集成	⭐⭐⭐⭐⭐ 原生支持
依赖注入	Wire集成	无	无	自动生成
配置管理	Protobuf配置	手动处理	手动处理	YAML配置
中间件生态	⭐⭐⭐⭐ 完善	⭐⭐⭐⭐⭐ 丰富	⭐⭐⭐⭐ 丰富	⭐⭐⭐ 自带常用
学习曲线	中等，需理解DDD	低	低	中等，工具多
社区活跃度	B站开源，国内活跃	最活跃	活跃	国内活跃

选择理由

• ✅ 微服务架构：天然支持gRPC + HTTP双协议
• ✅ Clean Architecture：强制分层，代码结构清晰
• ✅ Protobuf优先：API定义即文档，类型安全
• ✅ Wire依赖注入：编译期检查，无反射性能损耗
• ✅ 中间件完善：日志、链路追踪、限流等开箱即用
• ✅ 国内支持好：B站团队维护，文档和社区友好

---

3. 数据库：MySQL 8.0

对比方案

维度	MySQL	PostgreSQL	MongoDB	Redis
数据模型	关系型	关系型（更强）	文档型	KV存储
事务支持	⭐⭐⭐⭐ ACID	⭐⭐⭐⭐⭐ ACID强	⭐⭐⭐ 有限支持	⭐⭐ 简单事务
性能	⭐⭐⭐⭐ 读写均衡	⭐⭐⭐⭐ 复杂查询强	⭐⭐⭐⭐⭐ 写入快	⭐⭐⭐⭐⭐ 内存速度
JSON支持	⭐⭐⭐ 5.7+支持	⭐⭐⭐⭐⭐ 原生强大	⭐⭐⭐⭐⭐ 原生	⭐⭐ 字符串存储
生态成熟度	⭐⭐⭐⭐⭐ 最成熟	⭐⭐⭐⭐ 成熟	⭐⭐⭐⭐ 成熟	⭐⭐⭐⭐⭐ 成熟
运维成本	⭐⭐⭐⭐⭐ 低，工具多	⭐⭐⭐ 中等	⭐⭐⭐ 中等	⭐⭐⭐⭐ 低
云服务支持	⭐⭐⭐⭐⭐ 全面	⭐⭐⭐⭐ 全面	⭐⭐⭐⭐ 全面	⭐⭐⭐⭐⭐ 全面

选择理由

• ✅ 生态成熟：工具链完善，运维经验丰富
• ✅ GORM支持好：Go生态最佳ORM支持
• ✅ 性能稳定：8.0版本性能大幅提升
• ✅ 成本低：云服务价格相对PostgreSQL更低
• ✅ 团队熟悉：学习成本低，问题排查快

---

4. ORM：GORM + GORM Gen

对比方案

维度	GORM	XORM	sqlx	ent
类型安全	⭐⭐⭐ 反射	⭐⭐⭐ 反射	⭐⭐⭐⭐⭐ 原生SQL	⭐⭐⭐⭐⭐ 代码生成
性能	⭐⭐⭐ 中等	⭐⭐⭐ 中等	⭐⭐⭐⭐⭐ 接近原生	⭐⭐⭐⭐ 好
功能丰富度	⭐⭐⭐⭐⭐ 最全	⭐⭐⭐⭐ 全面	⭐⭐ 基础	⭐⭐⭐⭐ 现代化
关联查询	⭐⭐⭐⭐⭐ 强大	⭐⭐⭐⭐ 支持	⭐⭐ 手动	⭐⭐⭐⭐⭐ 图查询
迁移支持	⭐⭐⭐⭐ AutoMigrate	⭐⭐⭐ 支持	❌ 无	⭐⭐⭐⭐⭐ Schema优先
学习曲线	⭐⭐⭐⭐ 低	⭐⭐⭐⭐ 低	⭐⭐⭐⭐⭐ 最低	⭐⭐⭐ 中等
社区	⭐⭐⭐⭐⭐ 最活跃	⭐⭐⭐ 活跃	⭐⭐⭐⭐ 活跃	⭐⭐⭐⭐ Facebook

选择理由

• ✅ GORM Gen：代码生成，类型安全，避免反射性能损耗
• ✅ 功能完善：Hooks、事务、软删除、关联查询等开箱即用
• ✅ 插件生态：dbresolver支持读写分离
• ✅ 社区最大：问题解决快，文档丰富
• ✅ 迁移工具：配合golang-migrate实现版本化迁移

---

5. 前端语言：JavaScript (ES6+)

对比方案

维度	JavaScript	TypeScript
类型安全	❌ 弱类型	✅ 强类型
开发效率	⭐⭐⭐⭐⭐ 快速	⭐⭐⭐⭐ 需类型定义
重构友好	⭐⭐ 困难	⭐⭐⭐⭐⭐ 编译器支持
学习曲线	⭐⭐⭐⭐⭐ 低	⭐⭐⭐ 需学习类型系统
生态兼容	⭐⭐⭐⭐⭐ 原生	⭐⭐⭐⭐ 需编译
错误检测	运行时	编译期

选择理由

• ✅ 快速开发：小型项目，开发效率优先
• ✅ 无编译负担：减少构建复杂度
• ✅ 团队熟悉：学习成本低
• ⚠️ 未来考虑：项目规模扩大后可迁移到TypeScript

---

6. 前端框架：React 18 + Vite

对比方案

维度	React + Vite	Vue 3 + Vite	Svelte + Vite	Next.js
性能	⭐⭐⭐⭐ 虚拟DOM	⭐⭐⭐⭐ 响应式	⭐⭐⭐⭐⭐ 编译优化	⭐⭐⭐⭐ SSR
生态	⭐⭐⭐⭐⭐ 最丰富	⭐⭐⭐⭐ 丰富	⭐⭐⭐ 成长中	⭐⭐⭐⭐⭐ React生态
学习曲线	⭐⭐⭐ 中等	⭐⭐⭐⭐ 低	⭐⭐⭐⭐⭐ 最低	⭐⭐ 复杂
开发体验	⭐⭐⭐⭐ Hooks	⭐⭐⭐⭐⭐ Composition	⭐⭐⭐⭐ 简洁	⭐⭐⭐⭐ 全栈
构建速度	⭐⭐⭐⭐⭐ Vite极快	⭐⭐⭐⭐⭐ Vite极快	⭐⭐⭐⭐⭐ Vite极快	⭐⭐⭐ Webpack
UI组件库	⭐⭐⭐⭐⭐ 最多	⭐⭐⭐⭐ 多	⭐⭐⭐ 较少	⭐⭐⭐⭐⭐ React生态

选择理由

• ✅ React生态：组件库丰富（Lucide React图标库）
• ✅ Vite构建：开发体验极佳，HMR秒级响应
• ✅ TailwindCSS：原子化CSS，快速构建现代UI
• ✅ 社区最大：问题解决方案多，招聘容易
• ✅ 灵活性高：适合快速迭代的产品

---

7. 网关：Nginx

对比方案

维度	Nginx	Traefik	Caddy	Envoy
性能	⭐⭐⭐⭐⭐ C语言，极快	⭐⭐⭐⭐ Go	⭐⭐⭐⭐ Go	⭐⭐⭐⭐⭐ C++
配置复杂度	⭐⭐⭐ 中等	⭐⭐⭐⭐ 自动发现	⭐⭐⭐⭐⭐ 最简单	⭐⭐ 复杂
HTTPS	⭐⭐⭐ 手动配置	⭐⭐⭐⭐⭐ 自动证书	⭐⭐⭐⭐⭐ 自动证书	⭐⭐⭐ 需配置
动态配置	❌ 需重载	✅ 支持	✅ 支持	✅ 支持
生态成熟度	⭐⭐⭐⭐⭐ 最成熟	⭐⭐⭐⭐ 云原生	⭐⭐⭐ 新兴	⭐⭐⭐⭐ 服务网格

选择理由

• ✅ 成熟稳定：生产环境验证充分
• ✅ 性能极佳：C语言实现，资源占用低
• ✅ 功能全面：反向代理、负载均衡、静态文件服务
• ✅ 运维熟悉：团队经验丰富，问题排查快
• ✅ Docker集成：官方镜像稳定，配置灵活

---

8. DevOps：GitHub Actions

对比方案

维度	GitHub Actions	GitLab CI	Jenkins	CircleCI
集成度	⭐⭐⭐⭐⭐ GitHub原生	⭐⭐⭐⭐⭐ GitLab原生	⭐⭐ 需配置	⭐⭐⭐ 第三方
配置复杂度	⭐⭐⭐⭐ YAML简单	⭐⭐⭐⭐ YAML	⭐⭐ Groovy复杂	⭐⭐⭐⭐ YAML
免费额度	⭐⭐⭐⭐ 公开仓库无限	⭐⭐⭐⭐ 慷慨	⭐⭐⭐⭐⭐ 自托管免费	⭐⭐⭐ 有限
生态	⭐⭐⭐⭐⭐ Marketplace丰富	⭐⭐⭐⭐ 丰富	⭐⭐⭐⭐⭐ 插件最多	⭐⭐⭐ 中等
性能	⭐⭐⭐⭐ 云端快	⭐⭐⭐⭐ 云端快	⭐⭐⭐ 自托管	⭐⭐⭐⭐ 云端

选择理由

• ✅ 无缝集成：代码托管和CI/CD在同一平台
• ✅ 配置简单：YAML配置，学习成本低
• ✅ Marketplace：丰富的预制Actions，开箱即用
• ✅ GHCR集成：GitHub Container Registry原生支持
• ✅ 免费额度：公开仓库无限制，私有仓库2000分钟/月
• ✅ 并行构建：支持矩阵构建，加速CI流程

---

9. 云服务：阿里云

对比方案

维度	阿里云	腾讯云	AWS	Azure
国内速度	⭐⭐⭐⭐⭐ 最快	⭐⭐⭐⭐⭐ 快	⭐⭐⭐ 海外节点	⭐⭐⭐ 海外节点
价格	⭐⭐⭐⭐ 竞争力强	⭐⭐⭐⭐ 相近	⭐⭐ 较贵	⭐⭐ 较贵
生态	⭐⭐⭐⭐⭐ 国内最全	⭐⭐⭐⭐ 全面	⭐⭐⭐⭐⭐ 全球最全	⭐⭐⭐⭐ 企业级
文档	⭐⭐⭐⭐ 中文友好	⭐⭐⭐⭐ 中文友好	⭐⭐⭐ 英文为主	⭐⭐⭐ 英文为主
备案	✅ 支持	✅ 支持	❌ 不支持	❌ 不支持
技术支持	⭐⭐⭐⭐ 响应快	⭐⭐⭐⭐ 响应快	⭐⭐⭐ 时差	⭐⭐⭐ 时差

选择理由

• ✅ 国内优势：CDN节点多，访问速度快
• ✅ 备案支持：提供完整的ICP备案流程
• ✅ 价格优势：学生优惠、新用户优惠力度大
• ✅ 生态完善：ECS、RDS、OSS等产品线齐全
• ✅ 中文文档：学习成本低，问题排查快