一、引言

新年伊始，万象更新。

又到了一年一度立Flag的时候了。

过去一年，我阅读了众多技术书籍，但是，纸上得来终觉浅，所以我一直纠结如何将看到的转化为用到的，并能沉淀成可传播的。

新的一年，与其纠结过去，不如行在当下。

「前端使用技巧」，这个系列是必不可少的。

顺应时代浪潮，我还准备在朝着智能化方向迈进，同时探索如何利用新兴技术构建更流畅、更智能、更具吸引力的用户界面。

最近正在整理前端的规范，除了常规的开发规范和组件设计规范，其实安全规范同样重要。

二、基础开发规范

1. 命名规范

1.1 语义化命名

// Bad
<Button click={() => {}} txt="Submit" />

// Good 
<Button onClick={handleSubmit} label="Submit" />

1.2 布尔类型命名

// 使用 is/has/should 前缀
<Modal isOpen={true} hasFooter={false} shouldCloseOnEsc />

1.3 事件处理命名

// 使用 on + 动词 形式
<Input onChange={handleChange} onFocus={handleFocus} />

2. 类型设计规范

2.1 类型声明强制化

// TypeScript 类型定义
type ButtonProps = {
  size?: 'small' | 'medium' | 'large';
  variant?: 'primary' | 'secondary';
  disabled?: boolean;
  onClick?: (event: React.MouseEvent) => void;
};

2.2 复杂类型结构化

// Bad：多个独立props
<Calendar startDate={...} endDate={...} holidays={...} />

// Good：结构化对象 
<Calendar 
  range={{ start: startDate, end: endDate }}
  specialDates={{ holidays }}
/>

3. 默认值规范

3.1 默认值定义

// 使用 defaultProps（类组件）
class Button extends React.Component {
  static defaultProps = {
    size: 'medium',
    disabled: false
  };
}

// 函数组件解构默认值
const Button = ({ size = 'medium', disabled = false }) => {...}

3.2 默认值优化技巧

// 使用空对象兜底
const UserCard = ({ user = {} }) => {
  const { name = 'Anonymous', avatar = defaultAvatar } = user;
  // ...
}

4. 性能优化规范

4.1 避免内联对象

// Bad：每次渲染创建新对象
<Chart options={{ width: 100, height: 100 }} />

// Good：记忆化对象
const chartOptions = useMemo(() => ({ width: 100, height: 100 }), []);

<Chart options={chartOptions} />

4.2 函数Prop优化

// Bad：内联函数
<Button onClick={() => handleClick(id)} />

// Good：记忆化函数
const handleClick = useCallback(() => {
  // 处理逻辑
}, [id]);

<Button onClick={handleClick} />

5. 特殊场景规范

5.1 样式透传方案

// 使用 className + style 组合
type BaseProps = {
  className?: string;
  style?: React.CSSProperties;
};

const Card: React.FC<BaseProps> = ({ className, style, children }) => (
  <div className={`base-card ${className}`} style={style}>
    {children}
  </div>
);

5.2 多主题支持

// 主题相关 props 设计
type ThemeProviderProps = {
  theme?: 'light' | 'dark';
  primaryColor?: string;
  secondaryColor?: string;
};

const App = () => (
  <ThemeProvider theme="dark" primaryColor="#1890ff">
    {/* 子组件 */}
  </ThemeProvider>
);

6.小结

1. 文档规范：使用 Storybook 或 Docz 编写可视化文档

2. 代码检查：配置 ESLint 规则

{
  "react/jsx-pascal-case": "error",
  "react/no-unused-prop-types": "error",
  "react/require-default-props": "off"
}

3. 性能监测：使用 React Profiler 检测 props 变更

4. 设计系统集成：与 Figma 变量保持命名一致

ApplyFigma Token -> JS Constant -> Component Prop

典型错误 vs 正确示范

通过遵循这些规范，可使组件库的维护成本降低 40%（根据阿里妈妈数据），团队协作效率提升 30%（腾讯统计数据）。

三、组件设计规范

1.设计原则

1.1 单一职责原则

• 每个组件只专注解决一个问题（如Button只处理点击交互）
• 复杂组件按功能拆分为：容器组件（逻辑） + 展示组件（UI）

1.2 原子化设计

• 遵循原子设计方法论：原子（基础元素）→ 分子（基础组件）→ 组织（复合组件）→ 模板 → 页面
• 基础组件库保持零业务耦合度

1.3 可复用性

• 通过props控制组件行为而非直接修改组件代码
• 使用组合模式（Compound Components）增强灵活性

1.4 可维护性

• 组件文件包含：.jsx + .scss + .test.js + README.md
• 使用TypeScript定义清晰接口

2.开发规范

1. 目录结构

components/
├─ base/            # 基础组件（无业务耦合）
│  ├─ Button/
│  │  ├─ index.tsx
│  │  ├─ style.module.scss
│  │  └─ __tests__/
├─ business/        # 业务组件
│  ├─ PaymentFlow/
│  │  ├─ hooks/     # 自定义hooks
│  │  ├─ types.ts   # 类型定义
│  │  └─ context/   # 上下文管理
└─ shared/          # 公共工具方法

2. 命名规范

• 组件名：大驼峰（PaymentDialog）
• 方法名：小驼峰（handleSubmit）
• 事件处理：前缀+名词（on{Action}，如onAmountChange）
• 布尔类型props使用is/has前缀（isLoading）

3. Props设计

interface PaymentProps {
  /** 支付金额（必填）*/
  amount: number;
  /** 支付状态 */
  status?: 'pending' | 'success';
  /** 支付完成回调 */
  onComplete?: (receipt: string) => void;
}

4. 状态管理

• 优先使用本地状态（useState）
• 复杂状态逻辑使用useReducer
• 跨组件状态使用Context API
• 全局状态管理使用Redux Toolkit

3.代码质量

1. 样式方案

// 使用CSS Modules
.buttonWrapper {
  :global(.ant-btn) { // 覆盖第三方库样式
    padding: 8px 12px;
  }
}

2. 性能优化

// 使用React.memo优化渲染
const MemoizedComponent = React.memo(({ data }) => {
  /* render */
});

// 复杂计算使用useMemo
const sortedList = useMemo(() => 
  data.sort((a,b) => a.id - b.id), 
  [data]
);

3. 异常处理

const fetchData = async () => {
  try {
    const res = await api.getData();
    if (res.code !== 0) throw new Error(res.msg);
    return res.data;
  } catch (err) {
    showErrorToast(err.message);
    Sentry.captureException(err);
    return fallbackData;
  }
}

4.测试规范

1. 单元测试

describe('PaymentButton', () => {
  it('should trigger payment flow when clicked', () => {
    const mockFn = jest.fn();
    render(<PaymentButton onClick={mockFn} />);
    fireEvent.click(screen.getByRole('button'));
    expect(mockFn).toHaveBeenCalledTimes(1);
  });
});

2. E2E测试

cy.visit('/payment')
  .get('[data-testid="amount-input"]')
  .type('100')
  .get('[data-testid="submit-button"]')
  .click()
  .url()
  .should('include', '/payment-success');

四、安全规范

1.基础安全原则

1.1 最小权限原则

• 所有请求必须遵循最小权限原则，API接口需设置细粒度权限控制
• 前端不应存储任何非必要敏感信息（如密码明文、身份证号等）

1.2 零信任机制

• 默认不信任所有输入数据，包括：URL参数、Cookie、LocalStorage、第三方SDK数据等
• 关键操作必须进行二次验证（如短信验证码、生物识别）

2.代码安全规范

2.1 XSS防御

// 错误示例：直接插入未处理内容
document.getElementById("content").innerHTML = userInput;

// 正确做法：使用安全API
React：自动转义（默认行为）  
Vue：使用 {{ }} 插值表达式  
原生JS：使用textContent代替innerHTML

• 启用CSP（内容安全策略）：

Content-Security-Policy: 
  default-src 'self';
  script-src 'self' 'unsafe-inline' 'unsafe-eval';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data:;

2.2 CSRF防御

// 所有敏感请求必须：
// 1. 使用POST/PUT/DELETE方法
// 2. 携带CSRF Token（推荐SameSite Cookie + 请求头双重验证）
axios.defaults.headers.common['X-CSRF-Token'] = getCSRFToken();

2.3 点击劫持防护

<!-- 设置X-Frame-Options -->
<meta http-equiv="X-Frame-Options" content="DENY">

2.4 敏感数据处理

// 禁止明文存储敏感信息
// 错误示例
localStorage.setItem('token', '明文token');

// 正确做法：使用加密存储
import { encrypt } from '@security/crypto';
sessionStorage.setItem('encryptedData', encrypt(data));

3.第三方依赖管理

3.1 组件安全

• 使用npm audit或Snyk进行依赖扫描
• 禁止引入未经安全审核的第三方SDK

3.2 CDN资源校验

<!-- 使用SRI校验 -->
<script 
  src="https://cdn.example.com/jquery.js"
  integrity="sha384-xxxx"
  crossorigin="anonymous">
</script>

4.数据安全规范

4.1 加密传输

• 全站强制HTTPS（HSTS配置）
• 敏感接口启用HTTP/2 + TLS 1.3

4.2 日志脱敏

// 日志处理中间件示例
app.use((req, res, next) => {
  console.log(maskSensitiveData(req.body));
  next();
});

五、总结

实际工作中，开发规范虽然起到约束作用，但是如果想要真正做到效率提升，还需要配合双周规范评审会动态优化，从而促使新老成员协作效率得到有效提升。