---
id: code-standards
title: 代码规范
---

# 代码规范

UPage 项目遵循严格的代码规范和最佳实践，以确保代码质量和一致性。本文档概述了这些规范，所有贡献者在提交代码前应确保遵循这些规范。

## JavaScript/TypeScript 规范

UPage 使用 [Biome](https://biomejs.dev/) 进行代码格式化和 linting。Biome 是一个快速的代码格式化工具和 linter，可以帮助我们保持代码风格的一致性。

### 代码检查

在提交代码前，请确保您的代码符合项目的代码规范：

```bash
pnpm check
```

### 自动修复

您也可以使用以下命令自动修复格式问题：

```bash
pnpm check --write
```

### 主要规范

- **缩进**: 使用 2 个空格
- **分号**: 必须使用分号
- **引号**: 使用单引号
- **命名约定**: 
  - 变量和函数使用 camelCase
  - 类和接口使用 PascalCase
  - 常量使用 UPPER_SNAKE_CASE
- **类型注解**: 尽可能使用类型注解提高代码可读性和类型安全性
- **注释**: 对复杂逻辑和公共 API 添加适当的注释

## Git 提交规范

我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范来格式化 Git 提交信息。提交信息应遵循以下格式：

```
<type>(<scope>): <description>

[optional body]

[optional footer(s)]
```

### 类型 (Type)

提交类型必须是以下之一：

- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码风格更改（不影响代码功能）
- `refactor`: 代码重构（既不是新功能，也不是修复 bug）
- `perf`: 性能优化
- `test`: 添加或修改测试
- `chore`: 构建过程或辅助工具的变动
- `ci`: CI 配置文件和脚本的更改
- `revert`: 回滚之前的提交

### 范围 (Scope)

范围是可选的，用于指定更改的范围（例如组件或文件名）。

### 描述 (Description)

描述是对更改的简短摘要：

- 使用现在时态（"change"，而不是"changed"或"changes"）
- 不要首字母大写
- 不要以句号结尾

### 示例

```
feat(editor): 添加拖拽调整组件大小功能

添加了一个新的拖拽句柄，允许用户直接调整组件的大小。
同时优化了调整过程中的性能。

Closes #123
```

```
fix: 修复用户认证失败问题

修复了当用户凭证包含特殊字符时认证失败的问题。

Fixes #456
```

## CSS/SCSS 规范

UPage 使用 SCSS 和 CSS Modules 来组织样式代码。

### 命名约定

- 使用 kebab-case 命名 CSS 类和 ID
- 使用有意义的名称，避免过于简短或抽象的名称
- 使用 BEM（Block Element Modifier）命名方法论

### 组织结构

- 将全局样式放在 `app/styles` 目录下
- 将组件特定样式放在组件同级目录下的 `.scss` 或 `.module.scss` 文件中

## 可访问性标准

UPage 致力于创建可访问的 Web 应用程序。所有贡献的代码应遵循 [WCAG 2.1 AA](https://www.w3.org/WAI/WCAG21/quickref/) 标准。

- 确保适当的颜色对比度
- 提供替代文本和 ARIA 标签
- 确保键盘导航功能
- 支持屏幕阅读器

## 测试规范

所有新功能和 bug 修复应包含适当的测试：

- **单元测试**: 测试单个函数和组件
- **集成测试**: 测试多个组件或功能的交互
- **端到端测试**: 测试完整的用户流程

测试应该：

- 覆盖正常和边缘情况
- 清晰描述测试的目的
- 保持独立性，不依赖于其他测试的状态

## 性能考虑

贡献的代码应考虑性能影响：

- 避免不必要的重新渲染
- 优化大型列表和表格
- 懒加载大型资源
- 减少网络请求
- 优化打包大小

## 安全最佳实践

所有代码应遵循安全最佳实践：

- 防止 XSS 攻击
- 避免 SQL 注入
- 正确处理用户输入
- 保护敏感数据
- 实施适当的访问控制