typescript-skills

LlamaFarm 的 TypeScript 技能

适用于 Designer（React）和 Electron App 子系统的通用 TypeScript 最佳实践。

概述

此技能介绍了适用于 LlamaFarm 前端应用的惯用 TypeScript 模式：

• designer/：React 18 + TanStack Query + TailwindCSS + Radix UI
• electron-app/：Electron 28 + Electron Vite

技术栈

子系统	框架	构建工具	主要库
designer	React 18	Vite	TanStack Query、Radix UI、axios、react-router-dom
electron-app	Electron 28	electron-vite	electron-updater、axios

配置

两个项目都使用严格的 TypeScript：

{
  "strict": true,
  "noUnusedLocals": true,
  "noUnusedParameters": true,
  "noFallthroughCasesInSwitch": true
}

核心原则

1. 始终启用严格模式 - 没有明确理由时，切勿使用 any
2. 优先使用接口 - 对象结构使用 interface，联合类型和交叉类型使用 type
3. 明确指定返回类型 - 始终为公共函数的返回值指定类型
4. 不可变性 - 在适用时使用 readonly 和 as const
5. 空值安全 - 显式处理 null/undefined，避免使用非空断言

相关文档

• patterns.md - 惯用 TypeScript 模式
• typing.md - 严格类型、泛型、工具类型
• testing.md - Vitest 和测试模式
• security.md - XSS 防护、输入验证

快速参考

React 组件模式

interface Props {
  readonly title: string
  readonly onAction?: () => void
}

function MyComponent({ title, onAction }: Props): JSX.Element {
  return <button onClick={onAction}>{title}</button>
}

TanStack Query Hook 模式

export const projectKeys = {
  all: ['projects'] as const,
  lists: () => [...projectKeys.all, 'list'] as const,
  detail: (id: string) => [...projectKeys.all, 'detail', id] as const,
}

export function useProject(id: string) {
  return useQuery({
    queryKey: projectKeys.detail(id),
    queryFn: () => fetchProject(id),
    enabled: !!id,
  })
}

错误类模式

export class ApiError extends Error {
  constructor(
    message: string,
    public readonly status: number,
    public readonly response?: unknown
  ) {
    super(message)
    this.name = 'ApiError'
  }
}

检查清单摘要

类别	严重	高	中	低
类型	3	4	2	1
模式	2	3	3	2
测试	2	3	2	1
安全	4	2	1	0