TypeScriptStrictModeGuardianSkill typescript-strict-guard

以下是TypeScript Strict Mode Guardian技能的中文翻译内容，保持原有格式不变。

TypeScript 严格模式守护者

你是TypeScript严格模式守护者。 你的任务是在所有TypeScript代码编写之前确保零类型错误。这项技能包含了针对每种TypeScript场景的全面模式和解决方案。

---

官方文档

始终参考这些官方资源：

• TypeScript 5.6 文档 - 官方TypeScript手册
• TypeScript 手册 - 完整的语言参考
• React TypeScript 速查表 - React特定模式
• React 19 TypeScript 指南 - 官方React TypeScript指南
• DefinitelyTyped - 类型定义仓库
• TypeScript 深入 - 高级TypeScript模式

---

快速参考 - 重要规则

永远不要做这些事情： ❌ 无明确理由使用any类型 ❌ 使用@ts-ignore注释（修复底层问题） ❌ 使用!非空断言（使用类型守卫或可选链） ❌ 在函数参数中留下隐式的any ❌ 省略函数的显式返回类型 ❌ 无运行时验证使用类型断言 ❌ 提交带有console.log语句的代码 ❌ 绕过严格模式检查

永远要做到这些事情： ✅ 为所有函数参数和返回值定义显式类型 ✅ 使用类型守卫来缩小unknown类型 ✅ 使用可选链（?.）和空值合并（??） ✅ 为对象形状创建接口 ✅ 使用区分联合用于变体类型 ✅ 使用类型守卫验证外部数据 ✅ 适当使用实用类型（Partial, Pick, Omit等） ✅ 为所有类型守卫和验证函数编写测试

---

完整指南索引

这项技能包含9个全面的指南，包含250+代码示例：

1. 严格模式违规

24个场景，带有前后示例

• 使用any类型（外部API，事件处理程序，动态键，数组方法）
• 使用@ts-ignore（第三方问题，复杂铸造）
• 非空断言（数组查找，DOM元素，可选链）
• 缺少返回类型（异步函数，回调）
• 隐式任何参数（解构对象）
• 无验证的类型断言
• 无界限的索引签名
• 枚举与联合类型
• 类型与接口选择
• 常量断言
• 满足操作符
• 模板字面量类型
• 条件类型
• 映射类型
• 交集与联合
• 从不类型使用
• 未知与任何

何时使用： 在编写任何TypeScript代码之前，查看此文件以获取所需的特定模式。

2. React TypeScript 模式

13个部分涵盖所有React模式

• 函数组件属性（基本，可选，带children）
• 事件处理程序类型（所有事件类型：点击，更改，提交，键盘，焦点，鼠标，拖动，滚动，触摸）
• useState钩子类型（基本状态，数组，对象，延迟初始化）
• useRef钩子类型（DOM元素，可变值，回调引用）
• useEffect和useLayoutEffect
• useContext钩子（类型化上下文，带有守卫的自定义钩子）
• 自定义钩子（基本，泛型，localStorage钩子）
• forwardRef类型
• 高阶组件（HOC）
• 渲染道具模式
• 组件组合（复合组件）
• 表单处理（受控表单，验证）
• 服务器组件（Next.js 15异步组件）

何时使用： 编写任何React组件，钩子或模式。

3. 第三方库类型

16个场景用于未类型化的库

• 安装类型定义（@types包）
• 创建声明文件（.d.ts）
• 增强现有类型（Window，ProcessEnv，Express Request）
• 为未类型化的NPM包类型化
• 为JavaScript库类型化
• 为CSS模块类型化
• 为JSON文件类型化
• 为图像导入类型化
• 为全局变量类型化
• 为实用程序库（Lodash）类型化
• 为浏览器API（实验性API）类型化
• 为Node.js模块类型化
• 创建包装函数
• 为GraphQL操作类型化
• tsconfig.json配置

何时使用： 集成任何没有类型的第三方库。

4. 类型守卫库

15个类别的可重用类型守卫

• 原始类型守卫（字符串，数字，布尔值，函数，符号，大整数）
• 对象类型守卫（基本对象，纯对象，有键，有属性）
• 数组类型守卫（isArray，isArrayOf，非空数组，元组）
• 可空类型守卫（isNotNull，isNotUndefined，isNotNullish，isDefined）
• 实例类型守卫（Error，Date，RegExp，Promise，Map，Set）
• 接口类型守卫（用户，通用接口守卫构建器）
• 区分联合守卫（结果类型，操作类型）
• JSON类型守卫（isJSONValue，安全解析JSON）
• 断言函数（assertString，assertNumber，assertNotNull，通用断言）
• 属性存在守卫（hasProperty，hasMethod）
• 范围和验证守卫（isInRange，isEmail，isURL，isUUID，isISODateString）
• 品牌类型守卫（名义类型与品牌类型）
• 异步类型守卫（异步验证）
• 组合守卫（isOneOf，isAllOf，可选）

何时使用： 验证任何外部数据或缩小类型。

5. 通用模式

12个高级通用模式

• 基本通用函数（单个通用，多个通用）
• 通用约束（HasId，keyof约束，原始约束）
• 通用类（栈，带有约束的存储库）
• 通用类型推断（参数推断，返回类型推断，默认参数）
• 条件类型（ElementType，Awaited，Exclude，Extract，NonNullable，ReturnType，Parameters）
• 映射类型（Partial，Required，Readonly，Pick，Omit，Record，深度类型）
• 模板字面量类型（字符串操作，事件处理程序，getter/setter，API路由，CSS值）
• 递归通用类型（Flatten，DeepReadonly，PathTo，获取嵌套属性）
• 可变元组类型（Prepend，Append，Concat，Reverse，curry）
• 品牌类型（名义类型，UserId，Email，PositiveNumber）
• 带有泛型的构建器模式（类型安全的流畅API）
• 高阶类型模拟（Functor模式）

何时使用： 创建任何可重用的函数或数据结构。

6. 实用类型指南

16个内置实用类型与决策树

• Partial<T>（更新操作，带有默认值的配置）
• Required<T>（确保所有字段提供）
• Readonly<T>（防止变异，不可变数据）
• Pick<T, K>（API DTOs，表单子集，查询投影）
• Omit<T, K>（移除敏感字段，创建输入，移除计算）
• Record<K, T>（字典，查找表，按键分组）
• Exclude<T, U>（过滤联合类型，移除值）
• Extract<T, U>（从联合中提取匹配类型）
• NonNullable<T>（移除null/undefined）
• ReturnType<T>（推断返回类型）
• Parameters<T>（提取函数参数）
• ConstructorParameters<T>（提取构造函数参数）
• InstanceType<T>（获取类的实例类型）
• Awaited<T>（解包Promise类型）
• ThisParameterType<T>（提取’this’参数）
• OmitThisParameter<T>（移除’this’参数）

包含用于选择正确实用类型的决策树。

何时使用： 转换任何现有类型。

7. 异步类型模式

13个异步模式

• 基本Promise类型（显式Promise<T>，异步函数）
• Promise.all类型（元组结果，同质数组）
• Promise.race和Promise.any
• 错误处理类型（结果类型，选项类型，要么类型）
• 异步生成器（分页获取，处理返回值）
• 异步迭代器（自定义异步可迭代）
• 延迟/延迟承诺
• 重试逻辑（指数退避，带条件重试）
• 超时工具（withTimeout，超时清理）
• 并行执行与并发限制（parallelLimit，AsyncQueue）
• 异步缓存（缓存异步函数，TTL缓存）
• 异步事件发射器（类型安全的事件）
• AbortController集成（可取消的fetch，可取消的操作）

何时使用： 编写任何异步代码。

8. 错误处理类型

10个错误处理模式

• 基本错误类型（ApplicationError，ValidationError，NotFoundError，UnauthorizedError）
• 结果类型模式（Ok/Err构造函数，map，flatMap，解包实用程序）
• 选项/也许类型模式（Some/None，isSome，isNone，map，getOrElse）
• 要么类型模式（Left/Right，类型守卫，实用程序，fold）
• 带有类型安全的Try-Catch（tryCatch，tryCatchAsync，错误转换）
• 验证与错误累积（多个错误，特定字段错误）
• 错误边界（React错误边界与类型）
• 异步错误处理（异步结果，异步要么）
• 错误恢复策略（带退避的重试，回退链）
• 穷尽错误处理（区分联合错误，错误处理程序映射）

何时使用： 处理任何错误或失败。

9. 验证脚本

可执行Python脚本用于预验证

检查：

• any类型使用
• @ts-ignore注释
• !非空断言
• 生产代码中的console.log
• 函数缺少返回类型
• 参数中的隐式任何

提交前运行：

python .claude/skills/typescript-strict-guard/validate-types.py --dir src/

---

工作流程 - 使用这项技能

编写新代码时

步骤1：确定模式

编写代码前，问：

• 这是一个React组件吗？→ React TypeScript 模式
• 这是异步代码吗？→ 异步类型模式
• 这验证外部数据吗？→ 类型守卫库
• 这处理错误吗？→ 错误处理类型
• 这使用泛型吗？→ 通用模式
• 这转换类型吗？→ 实用类型指南
• 这使用第三方库吗？→ 第三方库类型

步骤2：阅读相关部分

打开指南，找到你需要的确切模式。每个指南都有20+示例代码。

步骤3：按照模式编写代码

复制模式结构，适应你的用例，确保到处都有显式类型。

步骤4：验证

运行验证脚本：

python .claude/skills/typescript-strict-guard/validate-types.py --file src/path/to/file.ts

步骤5：编写测试

每个类型守卫，验证函数和自定义类型都需要测试。

---

代码审查时

步骤1：运行验证脚本

python .claude/skills/typescript-strict-guard/validate-types.py --dir src/

步骤2：检查常见违规

参考严格模式违规以找到发现的具体违规。

步骤3：建议正确的模式

引用适当的指南部分与正确的模式。

步骤4：验证测试存在

所有类型守卫和验证逻辑必须有测试。

---

决策树

当你看到未知数据时

数据来自外部源（API，用户输入，JSON）吗？
├─ 是 → 在[类型守卫库](type-guards-library.md)中创建类型守卫
│        示例：isUser(data: unknown): data is User
│        然后：使用前验证
└─ 否 → 你能在编译时定义类型吗？
         └─ 是 → 使用显式类型
         └─ 否 → 使用unknown与类型缩小

当你需要转换类型时

你需要什么转换？
├─ 使属性可选 → Partial<T>
├─ 使属性必需 → Required<T>
├─ 使属性只读 → Readonly<T>
├─ 选择特定属性 → Pick<T, K>
├─ 移除特定属性 → Omit<T, K>
├─ 创建带有键的对象 → Record<K, T>
├─ 从联合中移除类型 → Exclude<T, U>
├─ 从联合中提取类型 → Extract<T, U>
├─ 移除null/undefined → NonNullable<T>
├─ 获取函数返回类型 → ReturnType<T>
├─ 获取函数参数 → Parameters<T>
└─ 解包Promise → Awaited<T>

见：[实用类型指南](utility-types-guide.md)

当你有一个错误时

你需要什么样的错误处理？
├─ 作为返回值的显式错误 → 结果<T, E>模式
├─ 可空值 → 选项<T>模式
├─ 两个不同的结果 → 要么<L, R>模式
├─ 带有元数据的自定义错误 → 扩展ApplicationError类
├─ 多个验证错误 → ValidationResult<T>带有错误数组
├─ React组件错误 → 错误边界
└─ 异步错误处理 → 异步结果<T, E>

见：[错误处理类型](error-handling-types.md)

---

示例：完整的功能实现

场景： 从API获取用户，验证数据，处理错误，显示在React组件中。

步骤1：类型守卫（类型守卫库）

interface User {
  id: string
  name: string
  email: string
}

function isUser(obj: unknown): obj is User {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    'id' in obj && typeof obj.id === 'string' &&
    'name' in obj && typeof obj.name === 'string' &&
    'email' in obj && typeof obj.email === 'string'
  )
}

步骤2：异步函数与错误处理（异步类型 + 错误处理）

type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E }

async function fetchUser(id: string): Promise<Result<User>> {
  try {
    const response = await fetch(`/api/users/${id}`)

    if (!response.ok) {
      return {
        success: false,
        error: new Error(`HTTP ${response.status}`)
      }
    }

    const data: unknown = await response.json()

    if (!isUser(data)) {
      return {
        success: false,
        error: new Error('Invalid user data from API')
      }
    }

    return { success: true, data }
  } catch (error) {
    return {
      success: false,
      error: error instanceof Error ? error : new Error('Unknown error')
    }
  }
}

步骤3：React组件（React TypeScript 模式）

interface UserProfileProps {
  userId: string
}

function UserProfile({ userId }: UserProfileProps): React.ReactElement {
  const [user, setUser] = useState<User | null>(null)
  const [error, setError] = useState<string | null>(null)
  const [loading, setLoading] = useState<boolean>(true)

  useEffect(() => {
    async function loadUser(): Promise<void> {
      setLoading(true)
      const result = await fetchUser(userId)

      if (result.success) {
        setUser(result.data)
        setError(null)
      } else {
        setError(result.error.message)
        setUser(null)
      }

      setLoading(false)
    }

    loadUser()
  }, [userId])

  if (loading) return <div>Loading...</div>
  if (error) return <div>Error: {error}</div>
  if (!user) return <div>User not found</div>

  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  )
}

步骤4：测试

describe('fetchUser', () => {
  it('should fetch user successfully', async () => {
    const result = await fetchUser('1')
    expect(result.success).toBe(true)
    if (result.success) {
      expect(result.data.id).toBe('1')
    }
  })

  it('should handle invalid data', async () => {
    // Mock returns invalid data
    const result = await fetchUser('invalid')
    expect(result.success).toBe(false)
    if (!result.success) {
      expect(result.error.message).toContain('Invalid user data')
    }
  })
})

describe('isUser', () => {
  it('should validate correct user object', () => {
    expect(isUser({ id: '1', name: 'Alice', email: 'alice@example.com' })).toBe(true)
  })

  it('should reject invalid object', () => {
    expect(isUser({ id: 123 })).toBe(false)
    expect(isUser(null)).toBe(false)
  })
})

步骤5：验证

python .claude/skills/typescript-strict-guard/validate-types.py --file src/components/UserProfile.tsx

✅ 结果： 零类型错误，全面错误处理，完整测试覆盖。

---

提交前验证

在提交任何TypeScript代码之前：

# 验证所有TypeScript文件
python .claude/skills/typescript-strict-guard/validate-types.py --dir src/

# 运行TypeScript编译器
npx tsc --noEmit

# 运行测试
npm test

# 运行linter
npm run lint

所有检查必须在代码提交前通过。

---

常见违规 - 快速修复

违规	快速修复	指南部分
any类型	使用显式类型或unknown与类型守卫	严格模式违规 #1-4
@ts-ignore	修复底层问题或创建适当类型	严格模式违规 #5-6
!断言	使用?.可选链或类型守卫	严格模式违规 #7-9
缺少返回类型	向函数添加: ReturnType	严格模式违规 #10-11
隐式any	向参数添加类型	严格模式违规 #12
未类型化事件	使用React.XEvent<HTMLElement>	React TypeScript 模式 #2
外部数据	创建类型守卫	类型守卫库 #6
异步错误	使用Result<T, E>模式	错误处理类型 #8

---

成功指标

这项技能工作时： ✅ 生产代码中零any类型 ✅ 零@ts-ignore注释 ✅ 零!非空断言 ✅ 100%显式函数返回类型 ✅ 所有外部数据使用类型守卫验证 ✅ 所有类型守卫都有测试 ✅ TypeScript编译器通过零错误 ✅ 验证脚本通过零违规

---

文件统计

• 总文件数： 10
• 总行数： 3,200+
• 代码示例： 250+
• 覆盖模式： 100+
• 官方文档链接： 15+

---

何时使用这项技能

始终使用时：

• 编写任何TypeScript代码
• 审查任何TypeScript代码
• 调试类型错误
• 集成第三方库
• 处理外部数据
• 编写React组件
• 创建异步函数
• 处理错误
• 创建通用实用程序

这项技能在编写代码之前预防99%的TypeScript错误。

---

记住： TypeScript严格模式不是负担 - 它是一种超能力。使用这项技能第一次就写出完美的TypeScript代码，每次都这样。