H5 移动端、管理系统 开发规范文档

开发规范的目的是保证统一项目成员的编码风格，并使代码美观，易于项目维护。

1.命名规范

1.1 项目文件命名

• 项目名：
  全部采用小写方式，优先选择单个单词命名， 以短横线分隔。例：my-project-name。
• 目录名:
  参照项目命名规则，有复数结构时，要采用复数命名法。例：assets、components、utils、views等。
• 图像文件名:
  全部采用小写方式，优先选择单个单词命名，短横线分隔。例pic-people.jpg。
• HTML 文件名:
  全部采用小写方式，优先选择单个单词命名， 以短横线分隔。例：home-page.html。
• CSS 文件:
  全部采用小写方式，优先选择单个单词命名， 以短横线分隔。例：home-page.css。
• JavaScript 文件名:
  全部采用小写方式，优先选择单个单词命名， 以短横线分隔。例：home-page.js。

1.2 Vue 组件命名

• 组件名：
  文件扩展名为 .vue。应该始终是单词大写开头。例：MyComponent.vue。
• 紧密耦合的组件名:

和父组件紧密耦合的子组件应该以父组件名作为前缀命名。 因为编辑器通常会按字母顺序组织文件，所以这样做可以把相关联的文件排在一起。例：
|-TodoList.vue
|-TodoListItem.vue
|-TodoListItemButton.vue

• 组件名中单词顺序:
  组件名应该以高级别的 (通常是一般化描述的) 单词开头，以描述性的修饰词结尾。 因为编辑器通常会按字母顺序组织文件，所以现在组件之间的重要关系一目了然。如组件主要是用于搜索和设置功能。例：SearchButtonClear.vue

1.3 代码参数命名

• router
  Vue Router Path 命名采用 kebab-case 格式。 用camelCase（如：/userInfo)的单词会被当成一个单词，搜索引擎无法区分语义。
  component 采用懒加载写法引入。

 {
    path: '/my-router',
    name: 'MyRouter',
    component: () => import("@/views/home/index.vue"),
    meta: {
      title: '标题',
      desc: '描述'
    }
  }

• 模板中组件
  对于绝大多数项目来说，在单文件组件和字符串模板中组件名应该总是 PascalCase 的，但是在 DOM 模板中总是 kebab-case 的。
  在单文件组件和字符串模板中：

<MyComponent/>

在所有地方：

<my-component></my-component>

• 变量

命名方法：camelCase
命名规范：类型 + 对象描述或属性的方式

• 常量

命名方法：全部大写下划线分割
命名规范：使用大写字母和下划线来组合命名，下划线用以分割单词

• 方法

  命名方法：camelCase
  命名规范：统一使用动词或者形容词 + 名词形式

• 自定义事件

  命名方法：camelCase
  命名规范：统一使用动词或者形容词 + 名词形式

• 事件方法

  命名方法：camelCase
  命名规范：handle + 名称（可选）+ 动词

2.代码规范

• Vue

1. 代码结构

<template></template>
<script></script>
<style></style>

2. 为 v-for 设置键值

 在组件上必须用 key 搭配 v-for，以便维护内部组件及其子树的状态。

3. v-if 和 v-for 互斥

 永远不要把 v-if 和 v-for 同时用在同一个元素上。

3.注释规范

• HTML 文件注释

1.单行注释

一般用于简单的描述，如某些状态描述、属性描述等。
注释内容前后各一个空格字符，注释位于要注释代码的上面，单独占一行。

<!-- Comment Text -->
<div>...</div>

2.模块注释

一般用于描述模块的名称以及模块开始与结束的位置。
注释内容前后各一个空格字符，模块与模块之间相隔一行。

<!-- S Comment Text A --> 
<div class="mod_a">
  ...
</div>
<!-- E Comment Text A -->

3.CSS 文件注释

3.1 单行注释:
注释内容第一个字符和最后一个字符都是一个空格字符，单独占一行，行与行之间相隔一行。

/* Comment Text */ 
.jdc {} 

3.2 模块注释:
注释内容第一个字符和最后一个字符都是一个空格字符，/ 与 模块信息描述占一行，多个横线分隔符 - 与 / 占一行，行与行之间相隔两行。
推荐：

/* Module A  
---------------------------------------------------------------- */
.mod_a {}


/* Module B 
---------------------------------------------------------------- */
.mod_b {}

• JavaScript 文件注释:

1.单行注释

单行注释使用 //，注释应单独一行写在被注释对象的上方，不要追加在某条语句的后面。

// is current tab
const active = true

2.多行注释

多行注释使用 /* … /，而不是多行的 //。

/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make (tag) {
  // ...
 return element
}

3.注释空格

注释内容和注释符之间需要有一个空格，以增加可读性。eslint: spaced-comment。

// is current tab
const active = true

4.特殊标记

有时我们发现某个可能的 bug，但因为一些原因还没法修复；或者某个地方还有一些待完成的功能，这时我们需要使用相应的特殊标记注释来告知未来的自己或合作者。常用的特殊标记有两种：

// FIXME : 说明问题是什么
// TODO : 说明还要做什么或者问题的解决方案

5.文档类注释

文档类注释，如函数、类、文件、事件等；都使用 jsdoc 规范。

/**
 * Book类，代表一个书本.
 * @constructor
 * @param {string} title - 书本的标题.
 * @param {string} author - 书本的作者.
 */
function Book (title, author) {
 this.title = title
 this.author = author
}

4.版本管理

• 主分支（master）
  代码合并到正式分支之前现将正式分支代码合并到主分支，始终落后正式分支一个版本。
• 正式分支（prod）
  用于对外发布版本，任何时候在这个分支获得的代码都是线上最新版本。
• 预生产分支（pre）
  用于发布预生产环境。
• 测试分支（test）
  用于发布测试环境。
• 功能分支（按照功能描述命名）
  开发某项特定功能，从prod分支上面分出来的；开发完成后，合并到test分支进行测试。
• 补丁分支（按照Bug描述命名）
  修复正式环境bug分支，从prod上分支出来；开发完成后，再合并到test分支上进行测试。

5.其它

• Node.js版本 v16+。
• Vue版本 v3+。
• UI组件库 移动端：vant；管理系统：element-plus；
• 状态管理使用 Vuex 或 Pinia。
• 遵循 ESLint + Prettier 的代码规范。
• 使用 Axios 进行网络请求，封装请求模块，统一错误处理和loading状态管理。
• 根据业务需求合理使用缓存策略。
• 路由配置清晰,区分动态路由和静态路由。
• 部署流程自动化,使用 Jenkins/Git 工具，找运维人员部署正式环境。