博客 / 詳情

返回

前端代碼開發與輸出規範

通用要求

  • 語言：思考過程與輸出內容一律使用中文。
  • 上下文引用：每次對話必須明確引用項目中的 README.md 相關內容，確保開發行為與項目目標一致。
  • 項目架構：基於Vue.js + ElementUI + Vue Router + Vuex + Axios的前端架構。
  • 文檔位置: 項目文檔統一存放在 /docs 目錄下，並使用 .md 格式編寫。
  • Git提交規範: 所有代碼提交必須遵循 GIT_COMMIT.md 中定義的提交規範，AI助手在生成提交信息時必須參考該文檔。

代碼風格

  • 保持統一的代碼風格（如縮進使用2個空格、分號使用、換行等）。
  • 遵循Vue.js官方風格指南和ESLint規範。
  • 優先保障代碼的可讀性，避免過度壓縮或炫技式寫法。

命名與註釋

命名規範

  • 變量名、函數名：採用小駝峯命名法（camelCase）
  • 組件名：採用大駝峯命名法（PascalCase），如 UserList.vue
  • 文件名：Vue組件使用大駝峯，其他文件使用小駝峯或短橫線分隔
  • 常量：使用全大寫加下劃線，如 API_BASE_URL
  • CSS類名：使用短橫線分隔，如 user-list-item

註釋規範

  • 所有函數、組件、關鍵邏輯塊必須附帶清晰、準確、簡潔的中文註釋
  • 註釋應説明"為什麼"而不僅是"做什麼"
  • @author 格式: username / useremail（從Git配置獲取）
  • @since 格式: yyyy-MM-dd HH:mm:ss（代碼生成時的時間戳）

Vue組件註釋示例

<template>
  <!-- 用户列表頁面 -->
  <div class="user-list">
    <!-- 搜索區域 -->
    <el-form :model="searchForm" inline>
      <el-form-item label="用户名">
        <el-input v-model="searchForm.username" placeholder="請輸入用户名"></el-input>
      </el-form-item>
    </el-form>
  </div>
</template>

<script>
/**
 * 用户列表組件
 * @author zhangsan / zhangsan@example.com
 * @since 2025-01-15 14:30:25
 */
export default {
  name: 'UserList',
  data() {
    return {
      searchForm: {
        username: ''
      }
    }
  },
  methods: {
    /**
     * 查詢用户列表
     * 根據搜索條件獲取用户數據並更新表格
     * @author zhangsan / zhangsan@example.com
     * @since 2025-01-15 14:30:25
     */
    getUserList() {
      // 實現邏輯
    }
  }
}
</script>

編碼規範

Vue組件規範

  • 單個函數長度不超過50行，超出時應考慮拆分或重構
  • 組件文件不超過300行，超出時應拆分為多個子組件
  • 禁止使用全局變量，優先使用Vuex狀態管理或props/emit傳遞數據
  • 模塊導入：使用ES6 import/export語法，避免require
  • 代碼格式：使用2個空格縮進，行尾加分號

JavaScript規範

  • 使用ES6+語法（箭頭函數、解構賦值、模板字符串等）
  • 優先使用const，其次let，避免使用var
  • 函數參數不超過3個，超出時使用對象參數
  • 避免深層嵌套，最多3層

Vue特定規範

  • 組件props必須定義類型和默認值
  • 使用computed處理複雜邏輯，避免在template中寫複雜表達式
  • 合理使用生命週期鈎子，避免在created中執行DOM操作
  • 組件銷燬時清理定時器和事件監聽器

樣式規範

CSS/SCSS規範

  • 使用SCSS預處理器，支持變量和嵌套
  • 類名使用短橫線分隔命名法（kebab-case）
  • 避免使用!important，通過提高選擇器權重解決
  • 合理使用CSS變量定義主題色彩

ElementUI使用規範

  • 優先使用ElementUI組件，避免重複造輪子
  • 自定義樣式時使用scoped避免全局污染
  • 主題定製通過variables.scss文件統一管理

響應式設計

  • 使用ElementUI的柵格系統實現響應式佈局
  • 移動端適配使用媒體查詢
  • 圖片使用相對單位，支持高分辨率屏幕

測試要求

單元測試

  • 為核心業務邏輯和工具函數編寫單元測試
  • 使用Jest + Vue Test Utils進行組件測試
  • 測試覆蓋率不低於70%（考慮前端項目特點）
  • 測試用例需覆蓋正常路徑、邊界條件和異常場景

E2E測試

  • 關鍵業務流程編寫端到端測試
  • 使用Cypress或Playwright進行自動化測試
  • 覆蓋主要用户操作路徑

手動測試

  • 新功能開發完成後進行瀏覽器兼容性測試
  • 測試不同屏幕尺寸的響應式效果
  • 驗證無障礙訪問性（a11y）

代碼優化

  • 優化需基於性能瓶頸或可維護性問題，避免無意義的"提前優化"。
  • 任何優化後必須通過完整測試驗證，確保功能正確性。
  • 在性能與可讀性之間優先保障可讀性，除非性能是明確瓶頸。

代碼重構

  • 重構前需明確目標（如提升可讀性、消除重複、改善結構等）。
  • 重構後必須通過全部現有測試，並補充必要新測試。
  • 重構不得降低代碼可讀性或引入隱式複雜度。

文檔要求

  • 所有模塊、接口、關鍵算法必須配套詳細的技術文檔。
  • 文檔應包含：功能説明、使用示例、輸入/輸出定義、依賴關係等。
  • 文檔需與代碼同步更新，避免"文檔腐化"。

開發工具與腳本

代碼生成信息獲取腳本

項目提供了自動獲取代碼生成信息的腳本，用於生成規範的@author和@since註釋。

腳本位置:

  • Windows: scripts/get-code-info.bat
  • Linux/macOS: scripts/get-code-info.sh

使用場景:

  • 生成新的Vue組件時
  • 添加新的工具函數時
  • 需要標註作者和時間信息時

開發工具配置

ESLint配置

  • 使用Vue官方ESLint配置
  • 自定義規則適配項目需求
  • 保存時自動格式化代碼

Prettier配置

  • 統一代碼格式化規則
  • 配置文件：.prettierrc
  • 與ESLint集成避免衝突

VS Code配置

推薦安裝插件：

  • Vetur（Vue語法高亮）
  • ESLint（代碼檢查）
  • Prettier（代碼格式化）
  • Auto Rename Tag（標籤自動重命名）

Git提交規範

規範文檔引用

完整的Git提交規範請參考：GIT_COMMIT.md

AI助手職責

當開發人員請求生成Git提交信息時，AI助手必須：

  1. 自動分析代碼變更

    • 執行 git status 查看變更文件
    • 執行 git diff 分析具體變更內容
    • 識別變更類型（新功能、修復、重構等）

  2. 生成規範提交信息

    • 格式：[no] [type] [subject]
    • 使用當前周任務編號（需開發人員提供）
    • 選擇正確的type類型
    • subject不超過50字符
    • body列出所有關鍵變更（使用 - 標識）

  3. 質量保證

    • ✅ 包含任務編號
    • ✅ 正確的type類型
    • ✅ 簡潔的subject
    • ✅ 完整的body
    • ✅ 格式規範

提交類型速查

type 説明 使用場景
feat 新功能 新增頁面、組件、業務功能
fix 缺陷修復 修復Bug、樣式問題、邏輯錯誤
refactor 代碼重構 重構組件、優化代碼結構
docs 文檔變更 修改README、註釋、開發文檔
style 樣式調整 CSS樣式修改、UI調整
perf 性能優化 優化加載速度、減少包體積
test 測試代碼 新增或修改單元測試、E2E測試
build 構建調整 webpack配置、依賴管理、打包優化
chore 其他變更 配置文件、開發工具配置

使用示例

[sop-72] feat 新增用户管理頁面

- 新增UserList.vue用户列表組件
- 實現用户查詢、新增、編輯功能
- 添加用户狀態管理和權限控制
- 集成ElementUI表格和分頁組件

任務編號管理

  • 開發人員每週提供一次任務編號
  • AI助手自動記錄到GIT_COMMIT.md文檔中
  • 生成提交信息時自動使用當前任務編號

觸發場景

AI助手應在以下場景主動提供Git提交信息生成服務：

  • 開發人員明確請求生成提交信息
  • 完成代碼開發任務後
  • 開發人員詢問如何提交代碼時

自動執行Git操作

重要：AI主動詢問機制

  • 生成提交信息後，AI必須主動詢問：“是否需要我直接執行git提交併推送到遠程倉庫？”
  • 開發人員無需主動説明，AI會自動提示
  • 開發人員確認後，AI自動執行：
    • git add 添加文件
    • git commit 提交到本地
    • git push 推送到遠程倉庫
    • 提供詳細的執行結果反饋
AI
user avatar
0 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.