JPwise-Web 代码质量规范 - Claude Code

🎯 代码质量核心原则

可读性优先

命名清晰：变量、函数、组件名称必须见名知意
结构清晰：代码层次分明，逻辑流程易懂
注释恰当：复杂业务逻辑必须有注释说明
格式统一：严格遵循 ESLint 配置

可维护性保证

单一职责：每个函数、组件只做一件事
低耦合度：模块间依赖关系清晰简单
高内聚性：相关功能集中在同一模块
易于测试：代码结构支持单元测试

📏 代码复杂度控制标准

函数复杂度限制

javascript

// ✅ 好的函数设计
function validateUserInput(userData) {
  // 圈复杂度: 3 (推荐 ≤ 10)
  if (!userData.name) return { valid: false, error: '姓名不能为空' }
  if (!userData.email) return { valid: false, error: '邮箱不能为空' }
  if (!isValidEmail(userData.email)) return { valid: false, error: '邮箱格式不正确' }
  
  return { valid: true }
}

// ❌ 避免的复杂函数
function complexValidation(data) {
  // 圈复杂度过高，难以维护和测试
  if (data.type === 'user') {
    if (data.role === 'admin') {
      if (data.permissions && data.permissions.length > 0) {
        // 嵌套过深...
      }
    } else if (data.role === 'user') {
      // 更多嵌套...
    }
  }
  // 应该拆分成多个小函数
}

文件大小限制

javascript

// 文件行数控制标准
- Vue 组件文件：≤ 300 行
- JavaScript 工具文件：≤ 200 行
- 混入文件：≤ 150 行
- 常量定义文件：≤ 100 行

// 超过限制时的拆分策略
// ✅ 组件拆分示例
// 原文件：UserManagement.vue (400行)
// 拆分后：
// - UserManagement.vue (主组件，150行)
// - components/UserForm.vue (表单组件，100行)
// - components/UserList.vue (列表组件，120行)
// - mixins/userMixin.js (业务逻辑，80行)

嵌套深度控制

javascript

// ✅ 控制嵌套深度 ≤ 4 层
function processUserData(users) {
  return users.map(user => {
    if (user.active) {
      if (user.permissions) {
        return user.permissions.filter(p => p.enabled)
      }
    }
    return []
  })
}

// ✅ 优化后：提前返回，减少嵌套
function processUserDataOptimized(users) {
  return users.map(user => {
    if (!user.active) return []
    if (!user.permissions) return []
    return user.permissions.filter(p => p.enabled)
  })
}

// ✅ 进一步优化：抽取函数
function getActiveUserPermissions(user) {
  if (!user.active || !user.permissions) return []
  return user.permissions.filter(p => p.enabled)
}

function processUserDataBest(users) {
  return users.map(getActiveUserPermissions)
}

🏷️ 命名约定详细规范

变量命名规范

javascript

// ✅ 好的变量命名
const userList = []                    // 列表用复数
const isLoading = false               // 布尔值用 is/has/can 开头
const hasPermission = true
const canEdit = false
const pageSize = 20                   // 数值变量名词化
const maxRetryCount = 3
const API_BASE_URL = 'http://...'     // 常量全大写下划线

// ❌ 避免的命名
const list1 = []                      // 无意义数字后缀
const flag = false                    // 模糊的标识
const data = {}                       // 过于通用
const temp = ''                       // 临时变量应有具体意义
const a, b, c = ...                   // 单字母变量（除循环外）

函数命名规范

javascript

// ✅ 好的函数命名
function getUserById(id) {}           // 动词开头，明确动作
function validateEmail(email) {}      // 验证类函数
function formatDate(date) {}          // 格式化类函数
function handleClick() {}             // 事件处理函数
function calculateTotal() {}          // 计算类函数
function isValidUser(user) {}         // 判断类函数返回布尔值

// ❌ 避免的函数命名
function process() {}                 // 动作不明确
function doSomething() {}             // 过于通用
function func1() {}                   // 无意义命名
function getData() {}                 // 获取什么数据不明确

组件命名规范

javascript

// ✅ 组件命名遵循 PascalCase
export default {
  name: 'UserManagement',             // 业务组件名
  components: {
    UserForm: () => import('./UserForm.vue'),
    UserList: () => import('./UserList.vue'),
    JPWButton: () => import('@/components/JPWButton.vue')
  }
}

// ✅ 文件命名规范
UserManagement.vue                    // 组件文件 PascalCase
userManagement.js                     // JS 文件 camelCase
user-management.scss                  // 样式文件 kebab-case
USER_CONSTANTS.js                     // 常量文件 UPPER_CASE

📝 注释规范和文档要求

必须注释的情况

javascript

// ✅ 业务逻辑注释
/**
 * 计算用户工作时长
 * 按照公司规定，周末和节假日按1.5倍计算
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @param {Array} holidays 节假日列表
 * @returns {Object} {workDays: 工作日, overtime: 加班时长}
 */
function calculateWorkHours(startDate, endDate, holidays) {
  // 获取工作日天数（排除周末）
  const workDays = getWorkDays(startDate, endDate)
  
  // 计算节假日加班（按1.5倍计算）
  const overtimeHours = holidays.reduce((total, holiday) => {
    return total + (holiday.hours * 1.5)
  }, 0)
  
  return { workDays, overtime: overtimeHours }
}

// ✅ 复杂算法注释
function optimizeRouteCalculation(points) {
  // 使用贪心算法计算最短路径
  // 时间复杂度：O(n²)，空间复杂度：O(n)
  const visited = new Set()
  const path = []
  
  // 从起点开始，每次选择距离最近的未访问点
  let current = points[0]
  visited.add(current.id)
  
  while (visited.size < points.length) {
    // 计算到所有未访问点的距离
    let nearest = findNearestUnvisited(current, points, visited)
    path.push(nearest)
    visited.add(nearest.id)
    current = nearest
  }
  
  return path
}

⚡ 性能基准和优化标准

性能指标要求

javascript

// 性能基准标准
- 首屏加载时间：≤ 2秒
- 页面切换时间：≤ 500ms
- API 响应处理：≤ 100ms
- 内存使用增长：≤ 50MB/小时
- 包大小：≤ 2MB (gzip压缩后)

性能优化检查要点

javascript

// ✅ 必须检查的性能问题
- 大数据列表 (>100条) 启用虚拟滚动或分页
- 图片大小控制在 500KB 以内，启用懒加载
- 及时清理定时器、事件监听器，避免内存泄漏
- API 请求合并，避免重复调用
- 组件按需加载，路由懒加载

🔍 代码审查检查清单

自动化检查工具

json

// .eslintrc.js 配置
{
  "extends": [
    "eslint:recommended",
    "@vue/standard"
  ],
  "rules": {
    "complexity": ["error", 10],           // 圈复杂度限制
    "max-depth": ["error", 4],             // 嵌套深度限制
    "max-lines": ["error", 300],           // 文件行数限制
    "max-lines-per-function": ["error", 50], // 函数行数限制
    "max-params": ["error", 4],            // 参数个数限制
    "no-console": "warn",                  // 控制台输出警告
    "no-debugger": "error",                // 禁止 debugger
    "no-magic-numbers": ["warn", {         // 魔法数字检查
      "ignore": [0, 1, -1]
    }]
  }
}

人工审查要点

markdown

## 代码审查检查清单

### 功能正确性
- [ ] 功能实现是否符合需求
- [ ] 边界条件是否处理
- [ ] 错误情况是否有适当处理
- [ ] 数据验证是否充分

### 代码质量
- [ ] 命名是否清晰易懂
- [ ] 函数职责是否单一
- [ ] 代码复杂度是否合理
- [ ] 是否有重复代码

### 性能考虑
- [ ] 是否有性能瓶颈
- [ ] 大数据量处理是否优化
- [ ] 是否存在内存泄漏风险
- [ ] API 调用是否合理

### 安全性
- [ ] 用户输入是否验证
- [ ] 敏感信息是否保护
- [ ] 权限检查是否完整
- [ ] XSS/CSRF 防护是否到位

### 可维护性
- [ ] 代码结构是否清晰
- [ ] 注释是否充分
- [ ] 测试用例是否完整
- [ ] 文档是否更新

✅ 代码质量检查清单

提交前检查

[ ] 代码通过 ESLint 检查
[ ] 单元测试全部通过
[ ] 测试覆盖率达到要求
[ ] 性能指标符合标准
[ ] 安全检查通过

发布前检查

[ ] 代码审查完成
[ ] 集成测试通过
[ ] 文档更新完成
[ ] 性能测试通过
[ ] 安全扫描通过

持续监控

[ ] 代码质量趋势监控
[ ] 技术债务跟踪
[ ] 性能指标监控
[ ] 用户反馈收集
[ ] 缺陷密度统计

代码质量控制核心：规范约束 + 自动检查 + 人工审查 + 持续改进

主项目-前端

配置标准

开发指南

最佳实践

参考文档

开发标准

开发指南

部署手册

开发指南

参考文档

开发标准

故障排除

文件预览

JPwise-Web 代码质量规范 - Claude Code

🎯 代码质量核心原则

可读性优先

可维护性保证

📏 代码复杂度控制标准

函数复杂度限制

文件大小限制

嵌套深度控制

🏷️ 命名约定详细规范

变量命名规范

函数命名规范

组件命名规范

📝 注释规范和文档要求

必须注释的情况

⚡ 性能基准和优化标准

性能指标要求

性能优化检查要点

🔍 代码审查检查清单

自动化检查工具

人工审查要点

✅ 代码质量检查清单

提交前检查

发布前检查

持续监控

JPwise-Web 代码质量规范 - Claude Code ​

🎯 代码质量核心原则 ​

可读性优先 ​

可维护性保证 ​

📏 代码复杂度控制标准 ​

函数复杂度限制 ​

文件大小限制 ​

嵌套深度控制 ​

🏷️ 命名约定详细规范 ​

变量命名规范 ​

函数命名规范 ​

组件命名规范 ​

📝 注释规范和文档要求 ​

必须注释的情况 ​

⚡ 性能基准和优化标准 ​

性能指标要求 ​

性能优化检查要点 ​

🔍 代码审查检查清单 ​

自动化检查工具 ​

人工审查要点 ​

✅ 代码质量检查清单 ​

提交前检查 ​

发布前检查 ​

持续监控 ​

JPwise-Web 代码质量规范 - Claude Code

🎯 代码质量核心原则

可读性优先

可维护性保证

📏 代码复杂度控制标准

函数复杂度限制

文件大小限制

嵌套深度控制

🏷️ 命名约定详细规范

变量命名规范

函数命名规范

组件命名规范

📝 注释规范和文档要求

必须注释的情况

⚡ 性能基准和优化标准

性能指标要求

性能优化检查要点

🔍 代码审查检查清单

自动化检查工具

人工审查要点

✅ 代码质量检查清单

提交前检查

发布前检查

持续监控