Pokerogue项目代码规范与质量检查指南

Pokerogue项目代码规范与质量检查指南

【免费下载链接】pokerogue 项目地址: https://gitcode.com/GitHub_Trending/po/pokerogue

概述

Pokerogue是一个基于TypeScript和Phaser构建的Pokemon Roguelike游戏项目。项目采用现代化的开发工具链，包括Biome作为代码格式化器和linter，Vitest作为测试框架，以及完善的Git hooks机制来确保代码质量。本指南将详细介绍项目的代码规范、质量检查流程和最佳实践。

技术栈与工具配置

核心工具

工具名称	版本	用途
Biome	2.0.0	代码格式化和静态分析
Vitest	3.2.4	单元测试框架
TypeScript	5.8.3	类型检查和编译
Lefthook	1.12.2	Git hooks管理

配置文件结构

Biome代码规范详解

格式化规则

// biome.jsonc 格式化配置示例
{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",      // 使用空格缩进
    "lineWidth": 120,           // 最大行宽120字符
    "quoteStyle": "double"      // 使用双引号
  }
}

Linting规则分类

Biome的linting规则分为多个类别，每个类别有不同的严格级别：

规则类别	默认级别	说明
Correctness	error	代码正确性相关规则
Style	error/warn	代码风格相关规则
Suspicious	error/warn	可疑代码模式检测
Complexity	info/error	代码复杂度控制
Performance	error	性能相关优化

重要的自定义规则

// 禁用模板字符串以提高性能
"useTemplate": "off"

// 强制使用const声明
"useConst": "error"

// 禁止使用var
"noVar": "error"

// 类型推断优化
"noInferrableTypes": "error"

// 导入类型优化
"useImportType": "error"

测试策略与覆盖率

Vitest测试配置

// vitest.config.ts 核心配置
export default defineProject({
  test: {
    environment: "jsdom",
    testTimeout: 20000,
    coverage: {
      provider: "istanbul",
      reportsDirectory: "coverage",
      reporters: ["text-summary", "html"]
    }
  }
})

测试目录结构

测试覆盖率目标

项目通过以下脚本命令管理测试覆盖率：

# 运行测试并生成覆盖率报告
pnpm test:cov

# 监控模式运行测试
pnpm test:watch

# 静默模式运行测试（仅显示失败）
pnpm test:silent

Git Hooks与自动化检查

Pre-commit自动化

# lefthook.yml 配置
pre-commit:
  commands:
    biome-lint:
      run: pnpm exec biome check --write --reporter=summary --staged
      stage_fixed: true
    ls-lint:
      run: pnpm exec ls-lint

提交前检查流程

代码质量最佳实践

1. 类型安全实践

// 推荐：使用明确的类型注解
interface PokemonBattleData {
  species: Species;
  level: number;
  ivs: StatsTable;
  evs: StatsTable;
}

// 避免：使用any类型
function processData(data: any) { // ❌ 不推荐
  // ...
}

// 推荐：使用具体类型或unknown
function processData(data: PokemonData) { // ✅ 推荐
  // ...
}

2. 错误处理规范

// 使用TypeScript的异常类型
class BattleError extends Error {
  constructor(message: string, public readonly code: BattleErrorCode) {
    super(message);
    this.name = 'BattleError';
  }
}

// 明确的错误处理
try {
  await executeBattleTurn();
} catch (error) {
  if (error instanceof BattleError) {
    handleBattleError(error);
  } else {
    logUnexpectedError(error);
  }
}

3. 性能优化实践

// 使用Map而不是对象字面量进行频繁查找
const abilityEffects = new Map<Ability, EffectHandler>();

// 避免在循环中创建函数
// ❌ 不推荐
pokemons.forEach(p => {
  setTimeout(() => processPokemon(p), 100);
});

// ✅ 推荐
const processWithDelay = (pokemon: Pokemon) => {
  setTimeout(() => processPokemon(pokemon), 100);
};
pokemons.forEach(processWithDelay);

开发工作流程

日常开发流程

代码审查清单

检查项	说明	重要性
Biome检查通过	无linting错误	高
测试覆盖率	新增代码有相应测试	高
类型安全	无any类型滥用	高
性能考虑	无明显的性能问题	中
代码可读性	命名清晰，结构合理	中

常见问题与解决方案

1. Biome规则冲突

# 临时禁用某条规则（需谨慎使用）
// biome-ignore lint/suspicious/noDoubleEquals: <解释原因>
if (value == null) {
  // 处理逻辑
}

2. 测试性能优化

// 使用Vitest的mock功能减少测试时间
vi.mock('../src/data/pokemon', () => ({
  getPokemonSpecies: vi.fn().mockReturnValue(mockSpecies)
}));

3. 类型定义管理

// 使用模块增强扩展全局类型
declare global {
  interface Window {
    gameData: GameData;
    battleScene: BattleScene;
  }
}

总结

Pokerogue项目通过完善的工具链和严格的代码规范，确保了代码质量和可维护性。开发者应该：

1. 遵循Biome规范：确保代码风格统一
2. 编写充分测试：维护高测试覆盖率
3. 利用类型系统：发挥TypeScript的优势
4. 参与代码审查：保持代码质量标准
5. 关注性能优化：提供流畅的游戏体验

通过遵循本指南，开发者可以高效地贡献高质量代码，共同维护这个优秀的开源项目。

【免费下载链接】pokerogue 项目地址: https://gitcode.com/GitHub_Trending/po/pokerogue