typescript-code-review

TypeScript 代码审查技能

对 TypeScript 代码进行全面、专业的审查，重点关注类型安全、最佳实践、性能、安全性和可维护性。

审查流程

审查 TypeScript 代码时，请遵循以下结构化方法：

1. 初步评估

• 了解代码的用途和上下文
• 确定审查范围（单个文件、模块、功能或整个代码库）
• 记录 TypeScript 版本和配置（检查 tsconfig.json）
• 查阅相关文档或注释

2. 核心审查类别

类型安全

• 严格模式合规性：确认 tsconfig.json 中的 strict: true，并检查代码是否遵循严格模式
• 类型注解：检查类型注解是否恰当，避免隐式 any
• 类型收窄：确保正确使用类型守卫和类型收窄
• 泛型类型：检查泛型的用法，确保灵活性，同时不牺牲安全性
• 联合类型和交叉类型：确认用法和处理方式正确
• 类型断言：指出不必要或危险的类型断言（as 关键字和非空断言运算符）
• null/undefined 处理：检查是否正确使用可选链（?.）和空值合并运算符（??）
• 返回类型：确保所有函数都有显式返回类型
• 可辨识联合：确认正确进行穷尽性检查

代码质量与最佳实践

• 命名规范：检查名称是否清晰且具有描述性（变量和函数使用 camelCase，类型和类使用 PascalCase）
• 函数长度：指出超过约 50 行或复杂度较高的函数
• 单一职责：确保函数和类各自只有一个明确用途
• DRY 原则：找出应抽取出来的重复代码
• 魔法数字/字符串：指出应改为常量的硬编码值
• 错误处理：审查 try-catch 的使用、错误类型和错误消息
• Async/await：检查异步处理是否恰当，避免混用回调和 Promise
• 不可变性：优先使用 const 而非 let，并检查数组/对象的变更操作
• 枚举与联合类型：适当情况下，建议使用 const 枚举或联合类型，而非常规枚举

TypeScript 现代特性

• 可选链：建议在嵌套属性访问时使用 ?.
• 空值合并：建议使用 ?? 而非 || 设置默认值
• 模板字面量类型：检查是否适合使用模板字面量类型
• 工具类型：适当时建议使用 Partial、Pick、Omit、Record 等
• 常量断言：建议对字面量类型使用 as const
• 类型谓词：用于自定义类型守卫
• satisfies 运算符：验证类型时，使用它替代类型断言

性能

• 不必要的重新渲染：在 React/框架中，检查 memo 的使用和依赖数组
• 大型导入：在可以进行 tree-shaking 时，指出导入整个库的问题
• 低效算法：当存在更优选择时，找出 O(n²) 或更差的算法
• 内存泄漏：检查事件监听器、订阅和计时器是否清理
• 懒加载：建议对大型模块使用动态导入
• 类型计算开销：指出会拖慢编译速度的极其复杂的类型计算

安全性

• 输入验证：确保对用户输入进行验证和清理
• XSS 漏洞：检查不安全的 HTML 渲染或 eval 用法
• 敏感数据：指出硬编码的密钥、令牌或密码
• 依赖项漏洞：建议运行 npm audit 或检查依赖项
• 将类型安全用于安全防护：确保类型能够防止安全问题（例如，通过带标签的模板防止 SQL 注入）

测试与可维护性

• 测试覆盖率：指出关键路径缺少测试的问题
• 仅类型导入：对仅用于类型的导入使用 import type
• 循环依赖：标记循环导入
• 聚合导出：检查 index 文件是否存在性能问题
• 文档：检查公共 API 是否有 JSDoc 注释
• 弃用通知：确保已正确标记弃用代码

3. 输出结构

将评审内容整理为清晰的章节：

## Summary
[High-level overview: overall code quality, main concerns, highlights]

## Critical Issues 🔴
[Issues that must be fixed: type errors, security vulnerabilities, breaking bugs]

## Important Improvements 🟡
[Significant issues affecting maintainability, performance, or best practices]

## Suggestions 🔵
[Nice-to-have improvements, style preferences, optimizations]

## Positive Observations ✅
[What the code does well, good patterns to reinforce]

## Detailed Findings

### [Category 1: e.g., Type Safety]
**File**: `path/to/file.ts:line_number`
- **Issue**: [Description]
- **Current code**:
  ```typescript
  [code snippet]

• 建议：

  [improved code]
  

• 原因：[说明这为何重要]

[对每项发现重复以上格式]

### 4. Code Review Guidelines

**Tone and Style**:
- Be constructive and specific, not vague or critical
- Explain the "why" behind recommendations
- Provide code examples for suggested changes
- Acknowledge good practices when present
- Use severity indicators (🔴 critical, 🟡 important, 🔵 suggestion)

**Prioritization**:
1. Critical: Security issues, type errors, runtime bugs
2. Important: Performance problems, maintainability issues, anti-patterns
3. Suggestions: Style improvements, modern syntax, optimizations

**Context Awareness**:
- Consider the project's maturity (prototype vs production)
- Respect existing patterns if consistent across codebase
- Note tradeoffs (e.g., performance vs readability)
- Reference the project's TypeScript configuration

### 5. Reference Files

For detailed guidance on specific topics, consult the reference files:

- `references/type-safety-checklist.md` - Comprehensive type safety review points
- `references/common-antipatterns.md` - TypeScript anti-patterns to avoid
- `references/security-checklist.md` - Security considerations for TypeScript
- `references/performance-tips.md` - Performance optimization strategies

Search references using Grep when encountering specific issues. For example:
- Type guard issues: grep "type guard" in `references/type-safety-checklist.md`
- Performance concerns: grep "performance" in `references/performance-tips.md`

### 6. TypeScript Configuration Review

When reviewing `tsconfig.json`, check for:

**Recommended strict settings**:
```json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "exactOptionalPropertyTypes": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitReturns": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

7. 特定框架的注意事项

React + TypeScript：

• 使用接口定义组件属性类型
• 为钩子（useState、useEffect、useCallback 等）正确指定类型
• 指定事件处理器类型（例如，React.MouseEvent<HTMLButtonElement>）
• 指定 ref 类型（useRef<HTMLDivElement>(null)）
• 为 children 指定类型（React.ReactNode 与 React.ReactElement）

Node.js + TypeScript：

• 为 Express/Fastify 处理器正确指定类型
• 在中间件中处理异步错误
• 为环境变量指定类型
• 为数据库查询结果指定类型

测试：

• 使用类型安全的模拟对象和桩对象
• 为测试工具（Jest、Vitest 等）正确指定类型
• 在测试中使用类型断言

8. 建议执行的自动化检查

如果尚未使用，请建议运行以下工具：

• TypeScript 编译器：使用 tsc --noEmit 进行类型检查
• ESLint：搭配 @typescript-eslint/parser 和推荐规则
• Prettier：确保格式一致
• ts-prune：查找未使用的导出
• depcheck：查找未使用的依赖项
• madge：检测循环依赖

9. 评审工作流

1. 首先扫描严重问题：类型错误、安全问题、明显的 Bug
2. 评审架构：文件结构、模块边界、关注点分离
3. 深入检查逻辑：算法正确性、边界情况、错误处理
4. 全面检查类型：准确性、安全性、TypeScript 特性的恰当使用
5. 评审性能：识别瓶颈、不必要的工作和优化机会
6. 检查风格与一致性：命名、格式、模式遵循情况
7. 检查测试与文档：覆盖率、清晰度、可维护性

10. 交互示例

用户：“评审这个 TypeScript 文件并指出问题”

响应流程：

1. 阅读提供的文件
2. 检查项目中是否有任何 tsconfig.json
3. 对所有类别进行系统评审
4. 按严重级别整理发现
5. 提供具体、可执行的建议和代码示例
6. 指出良好的实践
7. 建议后续步骤（运行特定工具、添加测试、重构特定部分）

最佳实践

• 全面但务实：聚焦重要问题
• 提供背景：说明问题所在以及可能造成的后果
• 展示胜于空谈：为建议提供代码示例
• 考虑受众：根据团队的 TypeScript 经验调整细节程度
• 保持与时俱进：参考现代 TypeScript 特性（4.9+、5.0+）
• 兼顾权衡：不要因追求完美而影响实际进展——承认取舍

适用场景

当用户出现以下情况时，启用此技能：

• 明确要求评审 TypeScript 代码
• 请求对 TypeScript 实现提供反馈
• 要求检查代码中的问题、Bug 或改进点
• 希望确保遵循 TypeScript 最佳实践
• 需要帮助提升代码质量或类型安全性
• 请求对 TypeScript 代码进行安全或性能审计