Getinge-web/docs/development/code-standards.md

代码规范文档

📋 文档信息

• 文档版本: v1.0.0
• 创建日期: 2024年
• 最后更新: 2024年
• 文档状态: 草稿
• 维护人员: 开发团队

🎯 代码规范概述

本规范旨在统一团队代码风格，提高代码质量，确保代码的可读性和可维护性。

📝 命名规范

文件命名

• Vue 组件: 使用 PascalCase，如 UserProfile.vue
• JavaScript 文件: 使用 camelCase，如 userService.js
• CSS/SCSS 文件: 使用 kebab-case，如 user-profile.scss
• 常量文件: 使用 UPPER_SNAKE_CASE，如 API_ENDPOINTS.js

变量命名

// 使用 camelCase
const userName = 'John';
const isActive = true;
const userList = [];

// 常量使用 UPPER_SNAKE_CASE
const API_BASE_URL = 'https://api.example.com';
const MAX_RETRY_COUNT = 3;

函数命名

// 使用 camelCase，动词开头
function getUserInfo() { }
function updateUserProfile() { }
function validateEmail() { }

// 布尔值函数使用 is/has/can 开头
function isValidUser() { }
function hasPermission() { }
function canEdit() { }

组件命名

<!-- 组件名使用 PascalCase -->
<template>
  <div class="user-profile">
    <UserAvatar />
    <UserInfo />
  </div>
</template>

<script>
export default {
  name: 'UserProfile',
  components: {
    UserAvatar,
    UserInfo
  }
}
</script>

🏗️ Vue 组件规范

组件结构

<template>
  <!-- 模板内容 -->
</template>

<script>
// 导入语句
import { mapState, mapActions } from 'vuex'
import UserService from '@/api/user'

// 组件定义
export default {
  name: 'ComponentName',
  components: {
    // 组件注册
  },
  props: {
    // 属性定义
  },
  data() {
    return {
      // 数据定义
    }
  },
  computed: {
    // 计算属性
  },
  watch: {
    // 监听器
  },
  created() {
    // 生命周期钩子
  },
  methods: {
    // 方法定义
  }
}
</script>

<style lang="scss" scoped>
/* 样式定义 */
</style>

Props 定义

props: {
  // 基础类型
  title: {
    type: String,
    required: true,
    default: ''
  },
  // 对象类型
  user: {
    type: Object,
    required: true,
    default: () => ({})
  },
  // 数组类型
  items: {
    type: Array,
    default: () => []
  }
}

事件命名

// 使用 kebab-case
this.$emit('user-updated', userData);
this.$emit('form-submitted', formData);

// 在模板中使用
<MyComponent @user-updated="handleUserUpdate" />

🎨 CSS/SCSS 规范

类名命名

// 使用 BEM 命名规范
.user-profile {
  &__header {
    // 元素
  }
  
  &--active {
    // 修饰符
  }
}

// 或者使用 kebab-case
.user-profile {
  .profile-header {
    // 嵌套元素
  }
  
  &.is-active {
    // 状态类
  }
}

样式组织

// 1. 布局相关
.layout-container {
  // 布局样式
}

// 2. 组件样式
.component-name {
  // 组件样式
}

// 3. 工具类
.text-center {
  text-align: center;
}

📊 JavaScript 规范

变量声明

// 优先使用 const，需要重新赋值时使用 let
const API_URL = 'https://api.example.com';
const userConfig = { theme: 'dark' };

let currentUser = null;
let isLoading = false;

// 避免使用 var
// var userName = 'John'; // ❌

函数定义

// 使用箭头函数
const fetchUser = async (userId) => {
  try {
    const response = await api.getUser(userId);
    return response.data;
  } catch (error) {
    console.error('Failed to fetch user:', error);
    throw error;
  }
};

// 对象方法简写
const userService = {
  async getUser(id) {
    // 方法实现
  },
  
  async updateUser(id, data) {
    // 方法实现
  }
};

异步处理

// 使用 async/await
async function handleSubmit() {
  try {
    this.loading = true;
    const result = await this.submitForm();
    this.$message.success('提交成功');
    this.$router.push('/success');
  } catch (error) {
    this.$message.error('提交失败：' + error.message);
  } finally {
    this.loading = false;
  }
}

// 避免使用 .then() 链式调用
// ❌ 不推荐
this.submitForm()
  .then(result => {
    // 处理结果
  })
  .catch(error => {
    // 处理错误
  });

🔧 API 调用规范

接口定义

// api/user.js
import request from '@/utils/request'

export function getUserList(params) {
  return request({
    url: '/api/users',
    method: 'get',
    params
  })
}

export function createUser(data) {
  return request({
    url: '/api/users',
    method: 'post',
    data
  })
}

错误处理

// 统一的错误处理
try {
  const result = await api.getUserList(params);
  this.userList = result.data;
} catch (error) {
  // 根据错误类型处理
  if (error.response?.status === 401) {
    this.$router.push('/login');
  } else {
    this.$message.error(error.message || '操作失败');
  }
}

📁 文件组织规范

目录结构

src/
├── api/                    # API 接口
│   ├── user.js           # 用户相关接口
│   └── course.js         # 课程相关接口
├── components/            # 公共组件
│   ├── common/           # 通用组件
│   └── business/         # 业务组件
├── utils/                 # 工具函数
│   ├── request.js        # 请求封装
│   └── validate.js       # 验证工具
└── views/                 # 页面组件
    ├── user/             # 用户相关页面
    └── course/           # 课程相关页面

导入顺序

// 1. 第三方库
import Vue from 'vue'
import ElementUI from 'element-ui'

// 2. 项目内部模块
import { mapState } from 'vuex'
import UserService from '@/api/user'

// 3. 相对路径导入
import UserProfile from './UserProfile.vue'
import './styles/user.scss'

🧪 测试规范

测试文件命名

tests/
├── unit/                  # 单元测试
│   ├── components/       # 组件测试
│   └── utils/            # 工具函数测试
└── e2e/                  # 端到端测试
    └── specs/            # 测试规范

测试用例命名

describe('UserService', () => {
  describe('getUser', () => {
    it('should return user data when valid id provided', async () => {
      // 测试实现
    });
    
    it('should throw error when invalid id provided', async () => {
      // 测试实现
    });
  });
});

🔍 代码质量

ESLint 规则

项目使用 ESLint 进行代码质量检查，主要规则包括：

• 强制使用分号
• 强制使用单引号
• 强制使用 2 空格缩进
• 禁止未使用的变量
• 强制使用 === 比较

Prettier 配置

项目使用 Prettier 进行代码格式化，确保代码风格一致。

📝 注释规范

函数注释

/**
 * 获取用户信息
 * @param {string} userId - 用户ID
 * @param {Object} options - 请求选项
 * @returns {Promise<Object>} 用户信息对象
 */
async function getUserInfo(userId, options = {}) {
  // 函数实现
}

组件注释

<!--
  用户信息组件
  用于显示用户的基本信息和操作按钮
  
  @props {Object} user - 用户信息对象
  @props {Boolean} editable - 是否可编辑
  @emits {string} user-updated - 用户信息更新事件
-->
<template>
  <!-- 组件内容 -->
</template>

🚀 性能优化

组件优化

// 使用 v-show 替代频繁的 v-if
<div v-show="isVisible">内容</div>

// 使用 key 优化列表渲染
<li v-for="item in list" :key="item.id">
  {{ item.name }}
</li>

// 使用计算属性缓存结果
computed: {
  filteredList() {
    return this.list.filter(item => item.active);
  }
}

懒加载

// 路由懒加载
const UserList = () => import('@/views/user/UserList.vue');

// 组件懒加载
components: {
  UserDetail: () => import('./UserDetail.vue')
}

📝 变更记录

版本	日期	变更内容	变更人
v1.0.0	2024年	初始版本	开发团队

---

如有疑问，请联系开发团队