web前端开发规范文档

前端开发规范文档

版本：V1.0
适用范围：Web 前端开发（HTML/CSS/JS/TS/Vue/React）
目的：统一团队编码风格、提升代码可读性与可维护性、降低协作成本、减少线上 Bug、保障项目质量与性能

---

一、通用原则

1. 可读性优先：代码首先给人看，其次给机器执行
2. 语义化：优先使用标准、有含义的写法，拒绝“能跑就行”
3. 可维护性：结构清晰、命名规范、注释得当、便于迭代
4. 一致性：团队内风格统一，不随意个人化写法
5. 性能与安全：编码时兼顾加载速度、运行效率、安全风险

---

二、文件与目录命名规范

2.1 文件夹命名

• 统一使用 小写字母 + 短横线（kebab-case）
• 禁止中文、空格、特殊字符、驼峰、下划线

  src/
  ├── assets/           # 静态资源
  ├── components/       # 公共组件
  ├── views/            # 页面组件
  ├── utils/            # 工具函数
  ├── api/              # 接口请求
  ├── styles/           # 全局样式
  ├── router/           # 路由
  └── store/            # 状态管理

2.2 文件命名

1. 页面/视图文件：kebab-case.vue / kebab-case.jsx

   views/
   ├── home.vue
   ├── user-center.vue
   └── login.vue

2. 公共组件：大驼峰（PascalCase）

   components/
   ├── HeaderBar.vue
   ├── UserTable.vue
   └── FormItem.vue

3. 工具/JS/TS 文件：kebab-case.js / camelCase.js

   utils/
   ├── request.js
   ├── date-utils.js
   └── validator.js

4. 样式文件：kebab-case.scss / kebab-case.css
5. 图片/静态资源：小写、语义化，禁止 1.png、test.jpg

   logo.png、user-avatar-default.jpg、bg-banner.png

---

三、HTML 开发规范

3.1 基础语法

• 统一使用 2 空格缩进，禁止 Tab
• 标签名、属性名全小写
• 自闭合标签必须加 /（Vue/JSX 规范）

  <img src="logo.png" alt="logo" />
  <input type="text" />

• 属性使用 双引号，禁止单引号
• 禁止冗余闭合、空属性

3.2 语义化优先

• 优先使用 HTML5 语义标签：

  <header> <nav> <main> <section> <article> <footer>

• 禁止通篇 div + span 堆砌
• 图片必须加 alt，a 标签禁止空 href

3.3 结构规范

• 一个页面只允许一个 <h1>
• 结构层级清晰：head 只放元信息，body 只放内容
• 禁止行内样式、行内事件（特殊场景除外）

  <!-- 不推荐 -->
  <div style="color:red" onclick="login()"></div>

---

四、CSS / SCSS 开发规范

4.1 基础规范

• 统一 2 空格缩进
• 属性末尾必须加分号
• 选择器、属性之间空一行
• 禁止使用 !important（公共覆盖除外）

4.2 命名规范（BEM 推荐）

• 块（Block）：user-card
• 元素（Element）：user-card__name
• 修饰符（Modifier）：user-card--active
• 禁止无意义命名：a1、box2、tt

4.3 属性书写顺序（统一风格）

1. 定位 / 显示
2. 盒模型
3. 文本样式
4. 视觉样式（背景、阴影等）

   .box {
     /* 定位 */
     position: absolute;
     top: 0;
     left: 0;
     display: flex;
     /* 盒模型 */
     width: 100px;
     height: 100px;
     padding: 10px;
     margin: 0;
     border: 1px solid #ccc;
     /* 文本 */
     font-size: 14px;
     color: #333;
     text-align: center;
     /* 视觉 */
     background: #fff;
     border-radius: 4px;
   }

4.4 预处理器（SCSS）规范

• 嵌套层级不超过 3 层
• 公共变量统一管理：$color-primary、$font-size-base
• 公共混合宏（mixin）统一放在 styles/mixins.scss
• 禁止嵌套过深导致样式冗余

---

五、JavaScript / TypeScript 规范

5.1 变量命名

• 普通变量：小驼峰（camelCase）

  const userName = '张三'
  const userList = []

• 常量：全大写 + 下划线

  const MAX_COUNT = 100
  const BASE_URL = 'https://xxx.com'

• 布尔值：以 is / has / can 开头

  const isLoading = true
  const hasPermission = false

5.2 函数命名

• 小驼峰，动词 + 名词

  function getUserInfo() {}
  function handleSubmit() {}
  function formatDate() {}

• 事件处理函数：handle + 动作

  handleClick、handleChange、handleSubmit

5.3 语法规范

• 优先使用 **ES6+**：let/const 替代 var
• 箭头函数、解构赋值、模板字符串优先
• 异步优先：async/await 替代回调地狱
• 禁止隐式全局变量
• 禁止 ==，统一使用 ===

5.4 禁止写法

• 禁止 eval()
• 禁止 with(){}
• 禁止修改原生对象原型
• 禁止超长函数（单个函数不超过 80 行）

---

六、Vue 开发规范（团队通用）

6.1 组件命名

• 单文件组件：PascalCase
• 组件使用：kebab-case

  <UserList />

6.2 代码顺序（强制统一）

<script>
export default {
  name: 'UserPage',
  components: {},    // 组件
  props: {},         // 属性
  data() {},         // 数据
  computed: {},      // 计算属性
  watch: {},         // 监听
  created() {},      // 生命周期
  mounted() {},
  methods: {}        // 方法
}
</script>

6.3 Props 规范

• 必须类型校验 + 默认值
• 禁止裸写 props

  props: {
    userName: {
      type: String,
      default: '',
      required: true
    }
  }

6.4 其他规范

• 禁止在 template 写复杂表达式
• 事件名使用 kebab-case：@user-change
• 计算属性优先，避免 methods 做纯计算
• 禁止 v-if 和 v-for 同节点使用

---

七、Git 规范

7.1 分支命名

• main / master：生产分支
• dev：开发分支
• feature/xxx：功能分支
• bugfix/xxx：修复分支
• release/x.x.x：发布分支

7.2 提交信息（Angular 规范）

类型(模块): 描述

• feat: 新功能
• fix: 修复 Bug
• style: 格式调整
• refactor: 重构
• docs: 文档
• perf: 性能优化
• chore: 构建/工具

  feat(user): 新增用户列表页
  fix(login): 修复登录密码错误提示

---

八、注释规范

8.1 文件注释

每个文件顶部必须标注：用途、作者、创建时间

/**
 * @description 用户相关工具函数
 * @author 张三
 * @date 2025-01-01
 */

8.2 函数注释

/**
 * 获取用户信息
 * @param {number} userId - 用户ID
 * @returns {Promise<Object>} 用户信息
 */
async function getUserInfo(userId) {}

8.3 业务注释

• 复杂逻辑必须加注释
• 禁止无用注释：// 这是变量
• 注释使用中文，简洁明确

---

九、性能规范

1. 图片必须压缩，使用 WebP/AVIF
2. 路由懒加载、组件懒加载
3. 防抖节流处理高频事件
4. 避免频繁操作 DOM
5. 合理使用虚拟列表（长列表）
6. 开启 Gzip，配置缓存
7. 减少包体积，剔除无用代码

---

十、安全规范

1. 防止 XSS：对用户输入转义，不直接渲染 HTML
2. 防止 CSRF：请求带 Token
3. 敏感信息不放在 localStorage
4. 接口请求统一错误处理
5. 禁止前端硬编码密钥、Token

---

十一、工具与编码环境

1. 编辑器：VS Code
2. 格式化：Prettier（统一配置）
3. 代码检查：ESLint
4. Git 工具：GitLens
5. 保存时自动格式化、自动修复 ESLint

---

十二、异常与兼容性

1. 接口请求必须 try/catch
2. 边界值处理：空、0、undefined、数组越界
3. 兼容主流浏览器：Chrome、Edge、Firefox
4. 移动端兼容微信、支付宝、App Webview

---

附则

• 本规范为团队基础规范，可根据项目类型微调
• 新成员必须遵守，代码合并前需符合规范
• 规范定期迭代更新，保持实用性与先进性