跳到主要内容

代码规范

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

JavaScript/TypeScript 规范​

UPage 使用 Biome 进行代码格式化和 linting。Biome 是一个快速的代码格式化工具和 linter，可以帮助我们保持代码风格的一致性。

代码检查​

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

pnpm check

自动修复​

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

pnpm check --write

主要规范​

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

Git 提交规范​

我们使用 Conventional Commits 规范来格式化 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 标准。

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

测试规范​

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

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

测试应该：

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

性能考虑​

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

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

安全最佳实践​

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

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