u-desk/docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/编码规范.md

编码规范

状态：已确定
最后更新：2026-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. 代码简洁直接

   • 直接表达意图，避免过度抽象
   • 减少中间变量和临时状态
   • 使用明确的函数名和变量名

示例对比：

// ❌ 防御性编程（不推荐）
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个（硬性约束，不可违反）
• 超过限制：必须使用结构体/对象封装参数
• 设计美学：参数过多严重影响代码可读性和维护性，完全不可接受
• 示例：

  // ❌ 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 基础样式
• 避免过度自定义样式
• 事件参数使用对象格式
• 所有事件有类型定义

文档检查

• 文档内容精简准确
• 不创建过多报告文件
• 必要文档已创建