157 lines
3.8 KiB
Markdown
157 lines
3.8 KiB
Markdown
---
|
||
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 注入
|
||
- 正确处理用户输入
|
||
- 保护敏感数据
|
||
- 实施适当的访问控制
|