# 代码规范文档

## 📋 文档信息

- **文档版本**: 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`

### 变量命名
```javascript
// 使用 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;
```

### 函数命名
```javascript
// 使用 camelCase，动词开头
function getUserInfo() { }
function updateUserProfile() { }
function validateEmail() { }

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

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

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

## 🏗️ Vue 组件规范

### 组件结构
```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 定义
```javascript
props: {
  // 基础类型
  title: {
    type: String,
    required: true,
    default: ''
  },
  // 对象类型
  user: {
    type: Object,
    required: true,
    default: () => ({})
  },
  // 数组类型
  items: {
    type: Array,
    default: () => []
  }
}
```

### 事件命名
```javascript
// 使用 kebab-case
this.$emit('user-updated', userData);
this.$emit('form-submitted', formData);

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

## 🎨 CSS/SCSS 规范

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

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

### 样式组织
```scss
// 1. 布局相关
.layout-container {
  // 布局样式
}

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

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

## 📊 JavaScript 规范

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

let currentUser = null;
let isLoading = false;

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

### 函数定义
```javascript
// 使用箭头函数
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) {
    // 方法实现
  }
};
```

### 异步处理
```javascript
// 使用 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 调用规范

### 接口定义
```javascript
// 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
  })
}
```

### 错误处理
```javascript
// 统一的错误处理
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/           # 课程相关页面
```

### 导入顺序
```javascript
// 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/            # 测试规范
```

### 测试用例命名
```javascript
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 进行代码格式化，确保代码风格一致。

## 📝 注释规范

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

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

## 🚀 性能优化

### 组件优化
```javascript
// 使用 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);
  }
}
```

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

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

## 📝 变更记录

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

---

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