reviewing-typescript-code

TypeScript 代码质量模式

概述

针对 Saleor Configurator 代码库的项目专属代码质量检查清单。涵盖类型安全约定、错误处理模式，以及本项目特有的架构标准。

使用场景

• 添加实体类型、服务、仓库、比较器、格式化器
• 实现部署阶段或引导方法
• 创建 Zod 模式或错误类
• 在提交或合并 PR 前审查代码

快速参考

约定	规则
不使用 any	仅适用于生产代码；测试模拟中允许使用
品牌类型	对领域值使用 EntitySlug、EntityName
错误类	使用错误代码扩展 BaseError
GraphQL 错误	使用 GraphQLError.fromCombinedError() 包装
Zod 错误	使用 ZodValidationError.fromZodError() 包装
函数	10-50 行为理想长度，最多约 100 行
风格	优先使用函数式写法（map/filter/flatMap），而非循环

质量检查清单

类型安全

• 生产代码中不使用 any 类型
• 不使用不安全的类型断言（as unknown as T）
• 不使用没有说明理由的非空断言（!）
• 对领域值使用品牌类型（EntitySlug、EntityName）
• 优先使用判别联合类型，而非继承
• 使用 satisfies 验证类型，同时保留字面量类型
• 对不可变数据使用 readonly

代码整洁

• 每个函数只承担一项职责
• 函数尽量少于 50 行
• 使用有意义、声明式的名称
• 布尔值名称使用 is/has/should/can 前缀
• 使用有名称的常量，而非魔法数字
• 对较长的条件链使用注册表/策略模式
• 为保持一致性使用箭头函数

函数式模式

• 不直接修改数组/对象
• 优先使用 map/filter/flatMap，而非 for/forEach 循环
• 不在 reduce 中累积扩展运算符（改用 Map）

错误处理

• 自定义错误使用错误代码扩展 BaseError
• GraphQL 错误：GraphQLError.fromCombinedError()
• Zod 错误：ZodValidationError.fromZodError()
• 错误消息应提供可执行的恢复建议
• 错误中应包含相关上下文

审查输出格式

按以下结构整理审查结果：

严重问题

合并前必须修复的问题。

重要改进

应该处理，但不会阻碍合并的问题。

建议

可在未来考虑的改进项。

正面观察

值得指出的优秀实现模式。

项目专属约定

• 实体标识：类别、商品使用 Slug；productTypes、pageTypes 使用 Name
• 服务模式：通过构造函数注入 validator、repository、logger
• 仓库模式：封装 GraphQL 操作，并将响应映射为领域模型
• 测试模式：使用 vi.fn() 模拟，并通过模式生成测试数据
• Zod 优先：先定义模式，再实现逻辑；使用 z.infer<> 获取类型

常见错误

错误	修正方法
在生产代码中使用 any	使用 unknown 和类型守卫
将 GraphQL 类型暴露给服务	在仓库中映射为领域类型
GraphQL 调用缺少错误上下文	在错误中包含操作名称
较长的 if-else 链	重构为注册表/策略模式
在 reduce 中累积扩展运算符	使用 Map 或 Object.fromEntries
在循环中修改数据（push）	使用 map/filter/flatMap

参考资料

Skill 参考文件

• 反模式 - 常见反模式的代码示例及修正方法
• 类型安全示例 - 品牌类型、类型守卫、判别联合类型

项目资源

• docs/CODE_QUALITY.md - 完整的编码标准
• docs/ARCHITECTURE.md - 服务模式
• biome.json - 代码检查规则

相关技能

• 完整实体工作流：架构模式请参阅 adding-entity-types
• Zod 标准：架构审核标准请参阅 designing-zod-schemas
• 提交前检查：质量门禁命令请参阅 validating-pre-commit

快速参考规则

如需精简的快速参考，请参阅 .claude/rules/code-quality.md（编辑 src/**/*.ts 文件时会自动加载）。