重构：文件系统模块化架构，优化应用启动流程
This commit is contained in:
58
docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/README.md
Normal file
58
docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/README.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# 知识库
|
||||
|
||||
## 目录说明
|
||||
|
||||
知识库用于存储**已确定的知识**，包括规范、参考、最佳实践。
|
||||
|
||||
### 核心原则
|
||||
|
||||
1. **确定性**：只有已确定、已验证的知识才能进入知识库
|
||||
2. **可引用**：知识库内容可以被其他文档引用
|
||||
3. **可维护**：知识库内容需要定期更新和维护
|
||||
|
||||
---
|
||||
|
||||
## 📐 规范
|
||||
|
||||
**位置**：`规范/`
|
||||
**用途**：编码规范、命名规范、架构规范等约束条件
|
||||
|
||||
### 内容分类
|
||||
- `编码规范.md` - 代码编写规范
|
||||
- `命名规范.md` - 命名约定
|
||||
- `架构规范.md` - 架构约束
|
||||
- `API规范.md` - API设计规范
|
||||
|
||||
---
|
||||
|
||||
## 📚 参考
|
||||
|
||||
**位置**：`参考/`
|
||||
**用途**：技术参考、API参考、模式参考
|
||||
|
||||
### 内容分类
|
||||
- `技术栈.md` - 使用的技术栈和版本
|
||||
- `API参考.md` - 后端API接口参考
|
||||
- `组件参考.md` - 前端组件使用参考
|
||||
- `模式参考.md` - 设计模式参考
|
||||
|
||||
---
|
||||
|
||||
## ✨ 最佳实践
|
||||
|
||||
**位置**：`最佳实践/`
|
||||
**用途**：已验证的最佳实践、经验总结
|
||||
|
||||
### 内容分类
|
||||
- `前端最佳实践.md` - 前端开发最佳实践
|
||||
- `后端最佳实践.md` - 后端开发最佳实践
|
||||
- `数据库最佳实践.md` - 数据库操作最佳实践
|
||||
|
||||
---
|
||||
|
||||
## 🔄 维护规范
|
||||
|
||||
1. **新增知识**：需要经过验证和确认才能加入
|
||||
2. **更新知识**：更新时需要记录变更原因
|
||||
3. **废弃知识**：废弃的知识需要标记并说明原因
|
||||
|
||||
90
docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/参考/技术栈.md
Normal file
90
docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/参考/技术栈.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# 技术栈参考
|
||||
|
||||
**状态**：已确定
|
||||
**最后更新**：2025-01-28
|
||||
|
||||
---
|
||||
|
||||
## 一、后端技术栈
|
||||
|
||||
### 1.1 核心框架
|
||||
- **语言**：Go 1.25+
|
||||
- **Web框架**：Wails v2
|
||||
- **ORM**：GORM
|
||||
- **数据库**：SQLite（本地存储）
|
||||
|
||||
### 1.2 数据库驱动
|
||||
- **MySQL**：`github.com/go-sql-driver/mysql`
|
||||
- **Redis**：`github.com/redis/go-redis/v9`
|
||||
- **MongoDB**：`go.mongodb.org/mongo-driver`
|
||||
- **SQLite**：`github.com/glebarez/sqlite`
|
||||
|
||||
### 1.3 加密
|
||||
- **密码加密**：AES-256 加密
|
||||
|
||||
---
|
||||
|
||||
## 二、前端技术栈
|
||||
|
||||
### 2.1 核心框架
|
||||
- **框架**：Vue 3 (Composition API)
|
||||
- **构建工具**：Vite
|
||||
- **UI框架**：Arco Design Vue
|
||||
- **编辑器**：CodeMirror 6
|
||||
|
||||
### 2.2 编辑器
|
||||
- **SQL编辑器**：CodeMirror 6
|
||||
- **语法高亮**：`@codemirror/lang-sql`
|
||||
- **JavaScript支持**：`@codemirror/lang-javascript`
|
||||
|
||||
### 2.3 类型系统
|
||||
- **类型检查**：TypeScript
|
||||
- **类型定义**：集中管理在 `types/` 目录
|
||||
|
||||
---
|
||||
|
||||
## 三、开发工具
|
||||
|
||||
### 3.1 代码规范
|
||||
- **Go格式化**：gofmt
|
||||
- **Go检查**：golangci-lint
|
||||
- **前端检查**：ESLint
|
||||
|
||||
### 3.2 构建工具
|
||||
- **后端构建**：go build
|
||||
- **前端构建**：Vite
|
||||
- **打包工具**：Wails
|
||||
|
||||
---
|
||||
|
||||
## 四、版本要求
|
||||
|
||||
### 4.1 Go版本
|
||||
- **最低版本**：Go 1.21
|
||||
- **推荐版本**：Go 1.22+
|
||||
|
||||
### 4.2 Node版本
|
||||
- **最低版本**：Node 18
|
||||
- **推荐版本**：Node 20+
|
||||
|
||||
---
|
||||
|
||||
## 五、依赖管理
|
||||
|
||||
### 5.1 Go依赖
|
||||
- **管理工具**：go mod
|
||||
- **模块文件**：`go.mod`
|
||||
|
||||
### 5.2 前端依赖
|
||||
- **管理工具**：npm
|
||||
- **配置文件**：`package.json`
|
||||
|
||||
---
|
||||
|
||||
## 六、参考链接
|
||||
|
||||
- [Wails文档](https://wails.io/)
|
||||
- [Arco Design Vue](https://arco.design/vue/docs/start)
|
||||
- [CodeMirror 6](https://codemirror.net/)
|
||||
- [GORM文档](https://gorm.io/)
|
||||
|
||||
29
docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/最佳实践/README.md
Normal file
29
docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/最佳实践/README.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# 最佳实践
|
||||
|
||||
## 目录说明
|
||||
|
||||
本目录用于存储已验证的最佳实践和经验总结。
|
||||
|
||||
## 核心原则
|
||||
|
||||
1. **已验证**：只有经过验证的最佳实践才能加入
|
||||
2. **可复用**：最佳实践应该可以在类似场景中复用
|
||||
3. **可维护**：最佳实践需要定期更新
|
||||
|
||||
## 内容分类
|
||||
|
||||
### 前端最佳实践
|
||||
- （待补充）
|
||||
|
||||
### 后端最佳实践
|
||||
- （待补充）
|
||||
|
||||
### 数据库最佳实践
|
||||
- （待补充）
|
||||
|
||||
## 维护规范
|
||||
|
||||
1. **新增实践**：需要经过验证和确认
|
||||
2. **更新实践**：更新时需要记录变更原因
|
||||
3. **废弃实践**：废弃的实践需要标记并说明原因
|
||||
|
||||
146
docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/AI协作检查清单.md
Normal file
146
docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/AI协作检查清单.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# AI协作检查清单
|
||||
|
||||
**状态**：已确定
|
||||
**最后更新**：2025-01-28
|
||||
|
||||
---
|
||||
|
||||
## 一、开始任务前检查
|
||||
|
||||
### 1.1 读取约束
|
||||
- [ ] 已读取 [编码规范.md](./编码规范.md)
|
||||
- [ ] 已读取 [架构规范.md](./架构规范.md)
|
||||
- [ ] 已读取 [技术栈.md](../参考/技术栈.md)
|
||||
|
||||
### 1.2 检查决策
|
||||
- [ ] 已检查 [决策记录/](../决策记录/) 中相关决策
|
||||
- [ ] 已理解相关决策的约束和影响
|
||||
|
||||
### 1.3 检查问题
|
||||
- [ ] 已检查 [问题追踪/](../../问题追踪/) 中相关问题
|
||||
- [ ] 已理解待解决问题和待实现功能
|
||||
|
||||
---
|
||||
|
||||
## 二、设计阶段检查
|
||||
|
||||
### 2.1 设计文档
|
||||
- [ ] 设计文档符合模板格式
|
||||
- [ ] 引用了相关的知识库规范
|
||||
- [ ] 关联了相关的决策记录（ADR）
|
||||
- [ ] 列出了待讨论问题
|
||||
|
||||
### 2.2 决策记录
|
||||
- [ ] 重要决策已创建ADR
|
||||
- [ ] ADR格式符合标准模板
|
||||
- [ ] 决策理由清晰明确
|
||||
|
||||
---
|
||||
|
||||
## 三、实现阶段检查
|
||||
|
||||
### 3.1 代码规范
|
||||
- [ ] 方法参数不超过3个
|
||||
- [ ] 不返回 `RetResult<Void>` 类型
|
||||
- [ ] 代码简洁，易于维护
|
||||
- [ ] 必要注释已添加
|
||||
|
||||
### 3.2 架构规范
|
||||
- [ ] 符合分层架构
|
||||
- [ ] 职责分离明确
|
||||
- [ ] 事件参数使用对象格式
|
||||
- [ ] 所有事件有类型定义
|
||||
|
||||
### 3.3 样式规范
|
||||
- [ ] 使用Arco基础样式
|
||||
- [ ] 避免过度自定义样式
|
||||
- [ ] 确保主题兼容
|
||||
|
||||
---
|
||||
|
||||
## 四、文档更新检查
|
||||
|
||||
### 4.1 知识库更新
|
||||
- [ ] 新确定的知识已加入知识库
|
||||
- [ ] 知识库内容已验证
|
||||
|
||||
### 4.2 问题追踪更新
|
||||
- [ ] 已解决问题已关闭
|
||||
- [ ] 新问题已创建
|
||||
- [ ] 问题状态已更新
|
||||
|
||||
### 4.3 决策记录更新
|
||||
- [ ] 新决策已创建ADR
|
||||
- [ ] 相关ADR已更新
|
||||
|
||||
---
|
||||
|
||||
## 五、完成检查
|
||||
|
||||
### 5.1 代码检查
|
||||
- [ ] 编译通过
|
||||
- [ ] 无Linter错误
|
||||
- [ ] 符合编码规范
|
||||
|
||||
### 5.2 文档检查
|
||||
- [ ] 设计文档已更新
|
||||
- [ ] 决策记录已更新
|
||||
- [ ] 问题追踪已更新
|
||||
|
||||
### 5.3 测试检查
|
||||
- [ ] 功能测试通过
|
||||
- [ ] 测试用例已更新
|
||||
|
||||
---
|
||||
|
||||
## 六、常见错误避免
|
||||
|
||||
### 6.1 代码错误
|
||||
- ❌ 方法参数超过3个
|
||||
- ❌ 返回 `RetResult<Void>` 类型
|
||||
- ❌ 过度设计，增加不必要复杂度
|
||||
|
||||
### 6.2 架构错误
|
||||
- ❌ 违反分层架构
|
||||
- ❌ 事件参数使用多个参数
|
||||
- ❌ 缺少类型定义
|
||||
|
||||
### 6.3 文档错误
|
||||
- ❌ 问题与知识混淆
|
||||
- ❌ 决策未记录
|
||||
- ❌ 约束未明确
|
||||
|
||||
---
|
||||
|
||||
## 七、引用规范
|
||||
|
||||
### 7.1 引用格式
|
||||
- 知识库：`[知识库/规范/编码规范.md](../../知识库/规范/编码规范.md)`
|
||||
- 决策记录：`[ADR-001](../决策记录/ADR-001-事件系统设计.md)`
|
||||
- 问题追踪：`[问题-001](../../问题追踪/待讨论/问题-001-右键菜单实现方式.md)`
|
||||
- 设计文档：`[设计文档/架构设计/事件系统设计.md](../../设计文档/架构设计/事件系统设计.md)`
|
||||
|
||||
### 7.2 引用原则
|
||||
- 引用要准确，使用相对路径
|
||||
- 引用要明确，说明引用内容
|
||||
- 引用要完整，包含路径和说明
|
||||
|
||||
---
|
||||
|
||||
## 八、协作流程
|
||||
|
||||
### 8.1 开始任务
|
||||
1. 读取约束（知识库/规范）
|
||||
2. 检查决策（决策记录）
|
||||
3. 检查问题（问题追踪）
|
||||
|
||||
### 8.2 执行任务
|
||||
1. 遵循约束
|
||||
2. 记录决策
|
||||
3. 更新问题
|
||||
|
||||
### 8.3 完成任务
|
||||
1. 更新文档
|
||||
2. 创建检查报告
|
||||
3. 更新任务状态
|
||||
|
||||
190
docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/文档编写规范.md
Normal file
190
docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/文档编写规范.md
Normal file
@@ -0,0 +1,190 @@
|
||||
# 文档编写规范
|
||||
|
||||
**状态**：已确定
|
||||
**最后更新**：2025-01-28
|
||||
|
||||
---
|
||||
|
||||
## 一、核心原则
|
||||
|
||||
### 1.1 抽象与实现分离
|
||||
- **设计文档**：描述"做什么"和"为什么"，不描述"怎么做"
|
||||
- **实现细节**：在代码中体现，不在设计文档中详细描述
|
||||
|
||||
### 1.2 问题与知识分离
|
||||
- **问题**：待讨论、待解决的问题 → [问题追踪/](../../问题追踪/)
|
||||
- **知识**：已确定、已验证的知识 → [知识库/](./)
|
||||
|
||||
### 1.3 确定性先行
|
||||
- **约束优先**：先明确约束和规则，再讨论具体实现
|
||||
- **决策记录**：所有重要决策都要记录在 [决策记录/](../../决策记录/)
|
||||
|
||||
---
|
||||
|
||||
## 二、文档分类
|
||||
|
||||
### 2.1 知识库文档
|
||||
**位置**：`知识库/`
|
||||
**特点**：
|
||||
- 已确定、已验证的内容
|
||||
- 可被其他文档引用
|
||||
- 需要定期维护
|
||||
|
||||
**分类**：
|
||||
- `规范/` - 约束和规则
|
||||
- `参考/` - 技术参考
|
||||
- `最佳实践/` - 已验证的最佳实践
|
||||
|
||||
### 2.2 设计文档
|
||||
**位置**：`设计文档/`
|
||||
**特点**：
|
||||
- 描述"做什么"和"为什么"
|
||||
- 引用知识库中的规范
|
||||
- 关联相关的决策记录
|
||||
|
||||
**分类**：
|
||||
- `需求设计/` - 功能需求
|
||||
- `架构设计/` - 系统架构
|
||||
- `功能设计/` - 具体功能设计
|
||||
|
||||
### 2.3 决策记录（ADR）
|
||||
**位置**：`决策记录/`
|
||||
**特点**：
|
||||
- 记录所有重要决策
|
||||
- 包含决策背景、选项、理由
|
||||
- 格式标准化
|
||||
|
||||
### 2.4 问题追踪
|
||||
**位置**：`问题追踪/`
|
||||
**特点**：
|
||||
- 管理待解决问题
|
||||
- 状态明确（待讨论/进行中/已解决）
|
||||
- 可追溯
|
||||
|
||||
---
|
||||
|
||||
## 三、文档模板
|
||||
|
||||
### 3.1 设计文档模板
|
||||
|
||||
```markdown
|
||||
# {功能名称}设计
|
||||
|
||||
**状态**：{设计中|已完成|已废弃}
|
||||
**创建日期**：YYYY-MM-DD
|
||||
**最后更新**：YYYY-MM-DD
|
||||
|
||||
## 一、设计目标
|
||||
|
||||
功能要解决什么问题？
|
||||
|
||||
## 二、设计约束
|
||||
|
||||
引用：[知识库/规范/编码规范.md](../../知识库/规范/编码规范.md)
|
||||
|
||||
## 三、设计方案
|
||||
|
||||
### 3.1 方案概述
|
||||
|
||||
### 3.2 详细设计
|
||||
|
||||
## 四、相关决策
|
||||
|
||||
- [ADR-{序号}](../../决策记录/ADR-{序号}.md)
|
||||
|
||||
## 五、待讨论问题
|
||||
|
||||
- [问题追踪/待讨论/{问题}.md](../../问题追踪/待讨论/{问题}.md)
|
||||
|
||||
## 六、实现计划
|
||||
|
||||
1. 步骤1
|
||||
2. 步骤2
|
||||
```
|
||||
|
||||
### 3.2 ADR模板
|
||||
|
||||
```markdown
|
||||
# ADR-{序号}: {决策标题}
|
||||
|
||||
**状态**：{已采纳|已拒绝|已替代|待定}
|
||||
**日期**：YYYY-MM-DD
|
||||
**决策者**：{姓名/角色}
|
||||
|
||||
## 上下文
|
||||
|
||||
为什么需要做这个决策？
|
||||
|
||||
## 考虑的选项
|
||||
|
||||
### 选项1：{选项名称}
|
||||
- 优点：
|
||||
- 缺点：
|
||||
|
||||
## 决策
|
||||
|
||||
选择的方案：{选项名称}
|
||||
|
||||
## 理由
|
||||
|
||||
为什么选择这个方案？
|
||||
|
||||
## 后果
|
||||
|
||||
### 正面影响
|
||||
-
|
||||
|
||||
### 负面影响
|
||||
-
|
||||
|
||||
### 约束
|
||||
-
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、引用规范
|
||||
|
||||
### 4.1 引用格式
|
||||
- 知识库：`[知识库/规范/编码规范.md](../../知识库/规范/编码规范.md)`
|
||||
- 决策记录：`[ADR-001](../决策记录/ADR-001-事件系统设计.md)`
|
||||
- 问题追踪：`[问题-001](../../问题追踪/待讨论/问题-001-右键菜单实现方式.md)`
|
||||
- 设计文档：`[设计文档/架构设计/事件系统设计.md](../../设计文档/架构设计/事件系统设计.md)`
|
||||
|
||||
### 4.2 引用原则
|
||||
- **准确性**：引用路径要准确
|
||||
- **明确性**：引用要说明引用内容
|
||||
- **完整性**：引用要包含路径和说明
|
||||
|
||||
---
|
||||
|
||||
## 五、内容要求
|
||||
|
||||
### 5.1 精简准确
|
||||
- 内容要精简，避免冗余
|
||||
- 描述要准确，避免歧义
|
||||
- 避免AI幻觉，确保内容真实
|
||||
|
||||
### 5.2 结构清晰
|
||||
- 使用清晰的标题层级
|
||||
- 使用列表和表格组织内容
|
||||
- 使用代码块展示代码
|
||||
|
||||
### 5.3 可维护性
|
||||
- 文档要易于更新
|
||||
- 使用模板保持一致性
|
||||
- 定期检查和更新
|
||||
|
||||
---
|
||||
|
||||
## 六、检查清单
|
||||
|
||||
### 文档检查
|
||||
- [ ] 符合文档分类
|
||||
- [ ] 使用了正确的模板
|
||||
- [ ] 引用了相关的知识库
|
||||
- [ ] 关联了相关的决策记录
|
||||
- [ ] 列出了待讨论问题
|
||||
- [ ] 内容精简准确
|
||||
- [ ] 结构清晰
|
||||
|
||||
400
docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/架构规范.md
Normal file
400
docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/架构规范.md
Normal file
@@ -0,0 +1,400 @@
|
||||
# 架构规范
|
||||
|
||||
**状态**：已确定
|
||||
**最后更新**：2025-01-28
|
||||
|
||||
---
|
||||
|
||||
## 一、后端架构规范
|
||||
|
||||
### 1.1 分层架构
|
||||
```
|
||||
API层 (internal/api/)
|
||||
↓
|
||||
Service层 (internal/service/)
|
||||
↓
|
||||
Repository层 (internal/storage/repository/)
|
||||
↓
|
||||
Infrastructure层 (internal/dbclient/)
|
||||
```
|
||||
|
||||
### 1.2 职责划分
|
||||
|
||||
#### API层
|
||||
- **职责**：暴露给前端的接口
|
||||
- **约束**：只负责参数验证和调用Service
|
||||
- **文件命名**：`{功能}_api.go`
|
||||
|
||||
#### Service层
|
||||
- **职责**：业务逻辑处理
|
||||
- **约束**：不直接访问数据库，通过Repository
|
||||
- **文件命名**：`{功能}_service.go`
|
||||
|
||||
#### Repository层
|
||||
- **职责**：数据访问
|
||||
- **约束**：只负责CRUD操作，不包含业务逻辑
|
||||
- **文件命名**：`{模型}_repo.go`
|
||||
|
||||
#### Infrastructure层
|
||||
- **职责**：基础设施（数据库客户端、连接池等）
|
||||
- **约束**：提供统一的接口，隐藏实现细节
|
||||
|
||||
---
|
||||
|
||||
## 二、前端架构规范
|
||||
|
||||
### 2.1 组件结构
|
||||
```
|
||||
Views (views/db-cli/)
|
||||
↓
|
||||
Components (components/)
|
||||
↓
|
||||
Composables (composables/)
|
||||
↓
|
||||
Types (types/)
|
||||
```
|
||||
|
||||
### 2.2 职责划分
|
||||
|
||||
#### Views
|
||||
- **职责**：页面级组件，负责布局和状态协调
|
||||
- **约束**：不包含具体业务逻辑
|
||||
|
||||
#### Components
|
||||
- **职责**：可复用组件
|
||||
- **约束**：组件应该是无状态的（通过props接收数据）
|
||||
|
||||
#### Composables
|
||||
- **职责**：状态管理和业务逻辑
|
||||
- **约束**：可复用的逻辑封装
|
||||
|
||||
#### Types
|
||||
- **职责**：TypeScript类型定义
|
||||
- **约束**：所有类型定义集中管理
|
||||
|
||||
---
|
||||
|
||||
## 三、事件系统规范
|
||||
|
||||
### 3.1 事件命名
|
||||
- **格式**：`<组件>-<动作>` 或 `<功能>-<动作>`
|
||||
- **示例**：`connection-select`、`table-structure`
|
||||
|
||||
### 3.2 事件参数
|
||||
- **格式**：对象格式，不使用多个参数
|
||||
- **类型**：所有事件都有TypeScript类型定义
|
||||
- **位置**：`types/events.ts`
|
||||
|
||||
### 3.3 事件处理
|
||||
- **位置**：在父组件中处理
|
||||
- **职责**：调用相应的composable方法
|
||||
|
||||
---
|
||||
|
||||
## 四、架构设计美学原则
|
||||
|
||||
### 4.1 参数数量约束（最高优先级）
|
||||
|
||||
**原则**：方法参数不得超过 3 个，超过必须使用结构体/对象封装。
|
||||
|
||||
**违反示例**（不可接受）：
|
||||
```go
|
||||
// ❌ 9个参数，完全不可接受
|
||||
func SaveDbConnection(id uint, name, dbType, host string, port int, username, password, database, options string) error
|
||||
```
|
||||
|
||||
**正确示例**：
|
||||
```go
|
||||
// ✅ 使用结构体封装
|
||||
type SaveConnectionRequest struct {
|
||||
ID uint
|
||||
Name string
|
||||
Type string
|
||||
Host string
|
||||
Port int
|
||||
Username string
|
||||
Password string
|
||||
Database string
|
||||
Options string
|
||||
}
|
||||
func SaveDbConnection(req SaveConnectionRequest) error
|
||||
```
|
||||
|
||||
**前端同理**：
|
||||
```typescript
|
||||
// ❌ 参数过多
|
||||
function saveConnection(id: number, name: string, type: string, host: string, port: number, username: string, password: string, database: string, options: string)
|
||||
|
||||
// ✅ 使用对象封装
|
||||
interface SaveConnectionRequest {
|
||||
id: number
|
||||
name: string
|
||||
type: string
|
||||
host: string
|
||||
port: number
|
||||
username: string
|
||||
password: string
|
||||
database: string
|
||||
options: string
|
||||
}
|
||||
function saveConnection(req: SaveConnectionRequest)
|
||||
```
|
||||
|
||||
### 4.2 依赖注入美学
|
||||
|
||||
**原则**：减少手动依赖注入，优先使用自动依赖获取。
|
||||
|
||||
**当前问题**：
|
||||
```typescript
|
||||
// 需要手动注入依赖
|
||||
const { executeSQL } = useSqlExecution(resultState, messageLog)
|
||||
```
|
||||
|
||||
**优化方向**：
|
||||
```typescript
|
||||
// 内部自动获取依赖（通过 provide/inject 或全局状态）
|
||||
const { executeSQL } = useSqlExecution()
|
||||
```
|
||||
|
||||
### 4.3 代码简洁性
|
||||
|
||||
**原则**：代码应该简洁、直接、易于理解。
|
||||
|
||||
**要求**：
|
||||
- 避免过度抽象
|
||||
- 减少中间层
|
||||
- 直接表达意图
|
||||
- 移除不必要的包装
|
||||
|
||||
### 4.4 一致性原则
|
||||
|
||||
**原则**：相同功能在不同实现中保持一致的命名和结构。
|
||||
|
||||
**要求**：
|
||||
- 统一的错误处理方式
|
||||
- 统一的命名规范
|
||||
- 统一的数据结构
|
||||
- 统一的接口风格
|
||||
|
||||
### 4.5 可组合性
|
||||
|
||||
**原则**：Composables 应该可以独立使用，也可以组合使用。
|
||||
|
||||
**要求**：
|
||||
- Composables 之间依赖关系清晰
|
||||
- 支持按需组合
|
||||
- 避免循环依赖
|
||||
- 提供清晰的组合模式
|
||||
|
||||
---
|
||||
|
||||
## 五、架构优化建议
|
||||
|
||||
### 5.1 后端 API 层优化（高优先级）
|
||||
|
||||
**问题**：API 方法参数过多，违反设计美学。
|
||||
|
||||
**优化方案**：
|
||||
1. 所有 API 方法参数超过 3 个时，必须使用请求结构体
|
||||
2. 统一请求/响应结构体命名：`{Action}Request` / `{Action}Response`
|
||||
3. 结构体定义放在对应的 API 文件中
|
||||
|
||||
**示例**：
|
||||
```go
|
||||
// connection_api.go
|
||||
type SaveConnectionRequest struct {
|
||||
ID uint `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Type string `json:"type"`
|
||||
Host string `json:"host"`
|
||||
Port int `json:"port"`
|
||||
Username string `json:"username"`
|
||||
Password string `json:"password"`
|
||||
Database string `json:"database"`
|
||||
Options string `json:"options"`
|
||||
}
|
||||
|
||||
func (api *ConnectionAPI) SaveDbConnection(req SaveConnectionRequest) error {
|
||||
conn := &models.DbConnection{
|
||||
ID: req.ID,
|
||||
Name: req.Name,
|
||||
Type: req.Type,
|
||||
Host: req.Host,
|
||||
Port: req.Port,
|
||||
Username: req.Username,
|
||||
Password: req.Password,
|
||||
Database: req.Database,
|
||||
Options: req.Options,
|
||||
}
|
||||
return api.connService.SaveConnection(conn)
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 前端 Composables 依赖优化（中优先级）
|
||||
|
||||
**问题**：需要手动注入依赖，使用不够优雅。
|
||||
|
||||
**优化方案**：
|
||||
1. 使用 `provide/inject` 或全局状态管理依赖
|
||||
2. Composables 内部自动获取依赖
|
||||
3. 保持向后兼容，支持手动注入
|
||||
|
||||
**示例**：
|
||||
```typescript
|
||||
// 使用 provide/inject
|
||||
const resultState = useResultState()
|
||||
const messageLog = useMessageLog()
|
||||
|
||||
provide('resultState', resultState)
|
||||
provide('messageLog', messageLog)
|
||||
|
||||
// useSqlExecution 内部自动获取
|
||||
export function useSqlExecution() {
|
||||
const resultState = inject<ReturnType<typeof useResultState>>('resultState')
|
||||
const messageLog = inject<ReturnType<typeof useMessageLog>>('messageLog')
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 Service 层验证逻辑提取（中优先级）
|
||||
|
||||
**问题**：验证逻辑分散在 Service 方法中，代码重复。
|
||||
|
||||
**优化方案**：
|
||||
1. 创建独立的验证器（Validator）
|
||||
2. 统一验证错误格式
|
||||
3. 可复用的验证规则
|
||||
|
||||
**示例**：
|
||||
```go
|
||||
// validator/connection_validator.go
|
||||
type ConnectionValidator struct{}
|
||||
|
||||
func (v *ConnectionValidator) ValidateSave(conn *models.DbConnection) error {
|
||||
if conn.Name == "" {
|
||||
return fmt.Errorf("连接名称不能为空")
|
||||
}
|
||||
if conn.Type == "" {
|
||||
return fmt.Errorf("数据库类型不能为空")
|
||||
}
|
||||
if conn.Host == "" {
|
||||
return fmt.Errorf("主机地址不能为空")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### 5.4 Composables 组合优化（低优先级）
|
||||
|
||||
**问题**：`index.vue` 中 composables 较多，可以进一步抽象。
|
||||
|
||||
**优化方案**：
|
||||
1. 创建 `useDbCli` composable 作为统一入口
|
||||
2. 内部组合所有相关 composables
|
||||
3. 提供简洁的 API
|
||||
|
||||
**示例**：
|
||||
```typescript
|
||||
// composables/useDbCli.ts
|
||||
export function useDbCli() {
|
||||
const connection = useDbConnection()
|
||||
const editor = useEditorState()
|
||||
const result = useResultState()
|
||||
const message = useMessageLog()
|
||||
const sql = useSqlExecution(result, message)
|
||||
const structure = useStructureState()
|
||||
const structureEdit = useStructureEdit()
|
||||
|
||||
return {
|
||||
connection,
|
||||
editor,
|
||||
result,
|
||||
message,
|
||||
sql,
|
||||
structure,
|
||||
structureEdit
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、架构检查清单
|
||||
|
||||
### 开发优先原则检查
|
||||
- [ ] 是否使用了 Vue 的响应式系统管理状态？
|
||||
- [ ] 是否使用了模板引用而非 DOM 查询？
|
||||
- [ ] 是否在正确的时机执行操作（通过 `nextTick`、`requestAnimationFrame` 等）？
|
||||
- [ ] 是否移除了不必要的重试循环？
|
||||
- [ ] 是否移除了过多的条件检查和兜底逻辑？
|
||||
- [ ] 代码是否简洁直接，易于理解？
|
||||
- [ ] 是否避免了防御性编程模式？
|
||||
|
||||
### 后端检查
|
||||
- [ ] API 方法参数不超过 3 个，超过使用结构体封装
|
||||
- [ ] 所有请求/响应结构体命名统一
|
||||
- [ ] Service 层验证逻辑清晰
|
||||
- [ ] 错误处理统一
|
||||
|
||||
### 前端检查
|
||||
- [ ] Composables 依赖关系清晰
|
||||
- [ ] 减少手动依赖注入
|
||||
- [ ] 代码简洁直接
|
||||
- [ ] 类型定义完善
|
||||
|
||||
### 设计美学检查
|
||||
- [ ] 参数数量符合约束（≤3）
|
||||
- [ ] 代码简洁易读
|
||||
- [ ] 命名一致统一
|
||||
- [ ] 结构清晰优雅
|
||||
|
||||
---
|
||||
|
||||
## 四、数据流规范
|
||||
|
||||
### 4.1 数据流向
|
||||
```
|
||||
用户操作
|
||||
↓
|
||||
组件事件
|
||||
↓
|
||||
Composable方法
|
||||
↓
|
||||
API调用
|
||||
↓
|
||||
后端Service
|
||||
↓
|
||||
Repository
|
||||
↓
|
||||
数据库
|
||||
```
|
||||
|
||||
### 4.2 状态管理
|
||||
- **原则**：使用Composables管理状态
|
||||
- **位置**：`composables/` 目录
|
||||
- **命名**：`use{功能}State.ts`
|
||||
|
||||
---
|
||||
|
||||
## 五、约束条件
|
||||
|
||||
### 5.1 后端约束
|
||||
- 方法参数不超过3个
|
||||
- 不返回 `RetResult<Void>` 类型
|
||||
- 使用分层架构，职责分离
|
||||
|
||||
### 5.2 前端约束
|
||||
- 使用Arco基础样式
|
||||
- 事件参数使用对象格式
|
||||
- 所有事件有类型定义
|
||||
|
||||
---
|
||||
|
||||
## 六、检查清单
|
||||
|
||||
### 架构检查
|
||||
- [ ] 分层架构清晰
|
||||
- [ ] 职责分离明确
|
||||
- [ ] 依赖方向正确
|
||||
- [ ] 符合架构规范
|
||||
|
||||
194
docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/编码规范.md
Normal file
194
docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/编码规范.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# 编码规范
|
||||
|
||||
**状态**：已确定
|
||||
**最后更新**：2025-01-28
|
||||
|
||||
---
|
||||
|
||||
## 一、通用规范
|
||||
|
||||
### 1.1 开发优先原则（最高优先级）
|
||||
|
||||
#### 1.1.1 主动性确定性编程
|
||||
|
||||
**原则**：主动控制执行时机和状态，确保在确定的状态下执行操作，而非通过防御性检查和重试来弥补时机问题。
|
||||
|
||||
**具体要求**：
|
||||
|
||||
1. **使用 Vue 响应式系统确保状态一致性**
|
||||
- 优先使用 `ref`、`reactive`、`computed` 管理状态
|
||||
- 通过 `watch` 和 `nextTick` 确保在正确时机执行
|
||||
- 避免手动同步状态，依赖 Vue 的响应式机制
|
||||
|
||||
2. **使用模板引用（Template Refs）直接获取 DOM**
|
||||
- 优先使用 `:ref` 绑定获取 DOM 元素
|
||||
- 避免通过 `querySelector` 等 DOM 查询方式
|
||||
- 通过 ref Map 管理多个元素引用
|
||||
|
||||
3. **确保执行时机正确**
|
||||
- 使用 `nextTick` 等待 DOM 更新完成
|
||||
- 使用 `requestAnimationFrame` 等待渲染完成
|
||||
- 在正确的生命周期钩子中执行操作
|
||||
|
||||
4. **减少防御性编程**
|
||||
- 移除不必要的重试循环
|
||||
- 移除过多的条件检查和兜底逻辑
|
||||
- 确保数据在操作前已准备好，而非通过检查来避免错误
|
||||
|
||||
5. **代码简洁直接**
|
||||
- 直接表达意图，避免过度抽象
|
||||
- 减少中间变量和临时状态
|
||||
- 使用明确的函数名和变量名
|
||||
|
||||
**示例对比**：
|
||||
|
||||
```typescript
|
||||
// ❌ 防御性编程（不推荐）
|
||||
const findContainer = async (tabKey, retryCount = 8) => {
|
||||
for (let i = 0; i < retryCount; i++) {
|
||||
await new Promise(resolve => setTimeout(resolve, 250))
|
||||
const container = document.querySelector(`.code-editor[data-tab-key="${tabKey}"]`)
|
||||
if (container) {
|
||||
const rect = container.getBoundingClientRect()
|
||||
if (rect.width > 0 && rect.height > 0) {
|
||||
return container
|
||||
}
|
||||
}
|
||||
}
|
||||
return null
|
||||
}
|
||||
|
||||
// ✅ 主动性确定性编程（推荐）
|
||||
const editorContainers = ref(new Map())
|
||||
|
||||
// 在模板中直接绑定
|
||||
<div :ref="el => setEditorContainerRef(el, tab.key)"></div>
|
||||
|
||||
const findContainer = async (tabKey) => {
|
||||
await nextTick()
|
||||
await new Promise(resolve => requestAnimationFrame(resolve))
|
||||
const containerInfo = editorContainers.value.get(tabKey)
|
||||
return containerInfo?.container || null
|
||||
}
|
||||
```
|
||||
|
||||
#### 1.1.2 其他优先原则
|
||||
|
||||
- **简洁优先**：代码要简洁，避免过度设计；优先使用简单方案，避免不必要的高级特性
|
||||
- **易于维护**：代码结构清晰，便于维护；减少中间层和抽象，直接表达意图
|
||||
- **减少AI味**：避免明显的AI生成代码特征；避免过度注释和文档
|
||||
- **降低幻觉**：避免不必要的高级特性；优先使用简单、直接的方案
|
||||
|
||||
### 1.2 注释规范
|
||||
- **必要注释**：只保留必要的注释，便于维护
|
||||
- **中文注释**：使用中文编写注释
|
||||
- **避免冗余**：不写显而易见的注释
|
||||
|
||||
---
|
||||
|
||||
## 二、Go后端规范
|
||||
|
||||
### 2.1 方法参数（设计美学约束）
|
||||
- **参数限制**：方法参数不得超过3个（硬性约束，不可违反）
|
||||
- **超过限制**：必须使用结构体/对象封装参数
|
||||
- **设计美学**：参数过多严重影响代码可读性和维护性，完全不可接受
|
||||
- **示例**：
|
||||
```go
|
||||
// ❌ 9个参数，完全不可接受
|
||||
func SaveDbConnection(id uint, name, dbType, host string, port int, username, password, database, options string) error
|
||||
|
||||
// ✅ 使用结构体封装
|
||||
type SaveConnectionRequest struct {
|
||||
ID uint
|
||||
Name string
|
||||
Type string
|
||||
Host string
|
||||
Port int
|
||||
Username string
|
||||
Password string
|
||||
Database string
|
||||
Options string
|
||||
}
|
||||
func SaveDbConnection(req SaveConnectionRequest) error
|
||||
```
|
||||
|
||||
### 2.2 返回值
|
||||
- **禁止类型**：不返回 `RetResult<Void>` 类型
|
||||
- **错误处理**：统一使用 error 返回错误
|
||||
|
||||
### 2.3 代码签名
|
||||
- **作者标识**：新增文件使用 `JueChen` 作为代码签名
|
||||
|
||||
### 2.4 架构约束
|
||||
- **分层架构**：API → Service → Repository → Infrastructure
|
||||
- **职责分离**：每层只负责自己的职责
|
||||
- **依赖方向**：只能依赖下层，不能依赖上层
|
||||
|
||||
---
|
||||
|
||||
## 三、前端规范
|
||||
|
||||
### 3.1 样式规范
|
||||
- **Arco基础样式**：优先使用 Arco Design 提供的基样式
|
||||
- **避免自定义**：避免过度自定义样式和硬编码样式
|
||||
- **主题兼容**：确保切换主题时样式正常
|
||||
|
||||
### 3.2 组件规范
|
||||
- **不包含title**：`<a-card>` 元素不包含 title 属性
|
||||
- **简洁设计**：组件设计要简洁，避免过度复杂
|
||||
|
||||
### 3.3 事件规范
|
||||
- **统一格式**：事件参数使用对象格式
|
||||
- **类型定义**：所有事件都有 TypeScript 类型定义
|
||||
- **命名规范**：事件名称使用 kebab-case
|
||||
|
||||
---
|
||||
|
||||
## 四、文档规范
|
||||
|
||||
### 4.1 文档编写
|
||||
- **精简准确**：文档内容要精简、准确、无幻觉
|
||||
- **直接回复**：优先直接回复，不创建过多报告文件
|
||||
- **必要文档**：只创建必要性和长久性文档
|
||||
|
||||
### 4.2 代码签名
|
||||
- **文档签名**：文档使用 `JueChen` 作为签名（本地新增文件）
|
||||
|
||||
---
|
||||
|
||||
## 五、工具使用
|
||||
|
||||
### 5.1 命令行优先
|
||||
- **文件操作**：文件更名、复制等优先使用命令行
|
||||
- **Git Bash**：执行类似命令时使用 Git Bash
|
||||
|
||||
---
|
||||
|
||||
## 六、检查清单
|
||||
|
||||
### 开发优先原则检查
|
||||
- [ ] 是否使用了 Vue 的响应式系统管理状态？
|
||||
- [ ] 是否使用了模板引用而非 DOM 查询？
|
||||
- [ ] 是否在正确的时机执行操作（通过 `nextTick`、`requestAnimationFrame` 等）？
|
||||
- [ ] 是否移除了不必要的重试循环？
|
||||
- [ ] 是否移除了过多的条件检查和兜底逻辑？
|
||||
- [ ] 代码是否简洁直接，易于理解？
|
||||
- [ ] 是否避免了防御性编程模式？
|
||||
|
||||
### 代码检查
|
||||
- [ ] 方法参数不超过3个
|
||||
- [ ] 不返回 `RetResult<Void>` 类型
|
||||
- [ ] 代码风格简洁，易于维护
|
||||
- [ ] 必要注释已添加
|
||||
|
||||
### 前端检查
|
||||
- [ ] 使用 Arco 基础样式
|
||||
- [ ] 避免过度自定义样式
|
||||
- [ ] 事件参数使用对象格式
|
||||
- [ ] 所有事件有类型定义
|
||||
|
||||
### 文档检查
|
||||
- [ ] 文档内容精简准确
|
||||
- [ ] 不创建过多报告文件
|
||||
- [ ] 必要文档已创建
|
||||
|
||||
Reference in New Issue
Block a user