附录3：代码规范与最佳实践

附录3：代码规范与最佳实践

代码质量直接决定了项目的可维护性和团队协作效率，本附录将系统梳理现代JavaScript开发的规范体系和工程化实践。

一、基础编码规范

1. 变量与命名

命名规则矩阵：

标识符类型 命名规范 示例
类名 PascalCase class UserModel
构造函数 PascalCase function Database()
常量 UPPER_SNAKE_CASE const MAX_SIZE = 100
私有成员 _leadingUnderscore this._internalProp
布尔变量 is/has/can前缀 isLoading

禁止行为：

// 反例
let a = 5; // 无意义变量名
var DATA = []; // 可变"常量"

2. 模块化设计

ESM最佳实践：

// 正确示例
import { parseJSON } from './utils/helpers.js'; // 明确扩展名
export const PI = 3.14; // 命名导出优先
export default class Calculator {...} // 仅当模块单一功能时

// 避免
export default { // 匿名对象导出
  method1,
  method2
}

二、代码风格指南

3. 格式化规则

.eslintrc.js 推荐配置：

module.exports = {
  rules: {
    'indent': ['error', 2, { SwitchCase: 1 }],
    'quotes': ['error', 'single', { avoidEscape: true }],
    'semi': ['error', 'always'],
    'comma-dangle': ['error', 'always-multiline'],
    'object-curly-spacing': ['error', 'always'],
    'arrow-parens': ['error', 'as-needed']
  }
};

Prettier 配合使用：

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "singleQuote": true,
  "trailingComma": "es5"
}

4. 注释规范

JSDoc标准示例：

/**
 * 计算商品折扣价格
 * @param {number} originalPrice - 原始价格
 * @param {number} discount - 折扣率(0-1)
 * @returns {number} 折后价格
 * @throws {TypeError} 当参数不是数字时
 */
function applyDiscount(originalPrice, discount) {
  if (typeof originalPrice !== 'number') {
    throw new TypeError('价格必须是数字');
  }
  return originalPrice * (1 - discount);
}

三、安全实践

5. 前端安全清单

风险类型 防御措施 代码示例
XSS 内容安全策略(CSP) Content-Security-Policy: default-src 'self'
CSRF 同站Cookie+Token验证 SameSite=Lax; Secure
数据泄露 敏感数据脱敏 maskCreditCard(number)
原型污染 冻结原型对象 Object.freeze(Object.prototype)

6. 安全编码模式

危险操作防护：

// 动态代码执行替代方案
const actions = { // 策略模式替代eval
  add: (a, b) => a + b,
  subtract: (a, b) => a - b
};
function safeEval(action, ...args) {
  return actions[action]?.(...args) ?? null;
}

四、性能优化

7. 渲染性能准则

关键优化策略：

  1. CSS：
    .will-change {
  will-change: transform; /* 提前告知浏览器 */
  contain: strict; /* 限制渲染边界 */
}
  2. JavaScript：
    // 使用requestIdleCallback处理非关键任务
requestIdleCallback(() => {
  analytics.track('user-action');
});

8. 内存管理

常见内存泄漏场景：

  • 未清除的定时器
    // 错误示例
setInterval(() => {...}, 1000);

// 正确做法
const timer = setInterval(...);
componentWillUnmount() {
  clearInterval(timer);
}
  • DOM引用未释放
    // 危险代码
const elements = document.querySelectorAll('.item');

// 改进方案
function processAndRelease() {
  const elements = [...document.querySelectorAll('.item')];
  // 处理逻辑...
  elements.length = 0; // 显式释放
}

五、框架特定规范

9. React 最佳实践

组件设计原则：

// 受控组件模式
function SearchInput({ value, onChange }) {
  return (
    <input 
      type="text"
      value={value}
      onChange={(e) => onChange(e.target.value)}
    />
  );
}

// 状态提升示例
function Parent() {
  const [state, setState] = useState();
  return <Child value={state} onChange={setState} />;
}

10. Vue 代码风格

单文件组件规范：

<template>
  <!-- 组件根元素单节点 -->
  <div class="component-wrapper">
    <button @click="handleClick">Submit</button>
  </div>
</template>

<script>
// 选项顺序
export default {
  name: 'MyComponent',       // 组件名
  props: {},                 // 属性定义
  emits: [],                 // 事件定义
  setup() {},                // 组合式API
  data() { return {} },      // 响应式数据
  computed: {},              // 计算属性
  watch: {},                 // 监听器
  methods: {},               // 方法
  lifecycleHooks: {}         // 生命周期
}
</script>

六、工程化标准

11. Git提交规范

Angular Commit Message格式：

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

类型说明：

类型 适用场景
feat 新增功能
fix 修复bug
docs 文档变更
style 代码格式调整
refactor 代码重构（非功能变更）
perf 性能优化

12. 代码审查清单

CR重点检查项：

  1. 功能实现：

    • 是否完全实现需求？
    • 是否有未处理边界情况？

  2. 代码质量：

    • 是否存在重复逻辑？
    • 函数是否遵循单一职责？

  3. 测试覆盖：

    • 是否添加单元测试？
    • 测试用例是否覆盖主要场景？

七、测试规范

13. 单元测试准则

测试金字塔实践：

pie
    title 测试比例
    "单元测试" : 70
    "集成测试" : 20
    "E2E测试" : 10

Jest测试示例：

describe('购物车计算', () => {
  let cart;
  
  beforeEach(() => {
    cart = new ShoppingCart();
    cart.addItem({ id: 1, price: 100 });
  });

  test('应正确计算总价', () => {
    expect(cart.total).toBe(100);
    cart.addItem({ id: 2, price: 200 });
    expect(cart.total).toBe(300);
  });

  test('添加重复商品应合并数量', () => {
    cart.addItem({ id: 1, price: 100 });
    expect(cart.items).toHaveLength(1);
    expect(cart.items[0].quantity).toBe(2);
  });
});

14. E2E测试要点

Cypress最佳实践：

describe('结账流程', () => {
  it('应完成商品购买', () => {
    cy.visit('/products');
    cy.get('[data-testid="product-1"]').click();
    cy.contains('加入购物车').click();
    cy.visit('/cart');
    cy.contains('结算').click();
    cy.url().should('include', '/checkout');
  });
});

八、团队协作规范

15. Monorepo管理

项目结构示例：

packages/
  ├── shared/          # 公共工具
  ├── web-app/         # 前端应用
  ├── mobile-app/      # 移动端
  └── server/          # 后端服务

Lerna配置：

{
  "npmClient": "yarn",
  "useWorkspaces": true,
  "version": "independent",
  "packages": ["packages/*"]
}

16. 文档标准

组件文档模板：

## \<ComponentName>

### 功能描述
[说明组件的主要功能和适用场景]

### 属性说明
| 属性名 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|-----|-------|-----|
| prop1 | string | 是 | - | 描述... |

### 使用示例
```jsx
<ComponentName prop1="value" />

注意事项

[列出特殊使用限制或副作用]


本规范应结合团队实际情况调整使用，建议通过以下方式落地：
1. 将ESLint/Prettier配置纳入项目模板
2. 在CI流程中添加自动化检查
3. 定期进行代码评审和规范复盘
4. 维护团队知识库中的范例代码

优秀的代码规范应当如同呼吸般自然，既保证一致性又不妨碍开发效率。随着技术演进，规范也应定期迭代更新以适应新的最佳实践。
#前端开发 分享于 2025-03-25
上一篇：附录2：调试技巧与快捷键汇总
【 内容由 AI 共享，不代表本站观点，请谨慎参考 】