React 全栈类型安全：组件类型、事件类型与前后端契约

type UserCardProps = {
  user: User
  onSelect: (user: User) => void      // 回调类型化
  variant?: 'default' | 'compact'     // 字面量联合限制取值
}

export function UserCard({ user, onSelect, variant = 'default' }: UserCardProps) {
  return <button onClick={() => onSelect(user)} className={variant}>
    {user.name}
  </button>
}

// 1. ReactNode：任意可渲染内容（最宽）
import type { ReactNode } from 'react'
type CardProps = { children: ReactNode }

// 2. 特定类型：限制 children 必须是某个组件
type MenuProps = { children: ReactElement<MenuItemProps>[] }
// 3. 函数子组件（Render Props）
type ListProps<T> = { items: T[]; render: (item: T) => ReactNode }

1. 必填 vs 可选：默认值给可选 + 解构默认
2. 用字面量联合限制「枚举型」props（variant/size）
3. 事件回调带完整参数类型（不只 any）
4. 只读：props 本身不可变（React 保证，TS 也标记）

// 泛型组件：列表项类型由调用方决定
type ListProps<T> = {
  items: T[]
  keyOf: (item: T) => string
  render: (item: T) => ReactNode
}

export function List<T>({ items, keyOf, render }: ListProps<T>) {
  return <ul>{items.map(item => <li key={keyOf(item)}>{render(item)}</li>)}</ul>
}

// 使用：T 自动推断
<List items={users} keyOf={u => u.id} render={u => <span>{u.name}</span>} />

type HasId = { id: string }

// 约束 T 必须带 id
export function EntityList<T extends HasId>({ items }: { items: T[] }) {
  return <ul>{items.map(i => <li key={i.id}>{JSON.stringify(i)}</li>)}</ul>
}

import { forwardRef, type Ref } from 'react'

// 泛型 ref：外部拿到正确的实例类型
const FancyInput = forwardRef<HTMLInputElement, FancyInputProps>(
  function FancyInput(props, ref) {
    return <input ref={ref} {...props} />
  }
)
// 使用：const ref = useRef<HTMLInputElement>(null)

import type { ChangeEvent, FormEvent, MouseEvent, KeyboardEvent } from 'react'

// 不用手写，利用组件元素的推断
<input onChange={e => {
  // e 自动推断为 ChangeEvent<HTMLInputElement>
  const value: string = e.target.value
}} />

// 显式标注的场景
function handleKeyDown(e: KeyboardEvent<HTMLInputElement>) {
  if (e.key === 'Enter') submit()
}

type FormState = { email: string; password: string; remember: boolean }

const [form, setForm] = useState<FormState>({ email: '', password: '', remember: false })

function update<K extends keyof FormState>(key: K, value: FormState[K]) {
  setForm(prev => ({ ...prev, [key]: value }))
}
// K extends keyof → update('email', 123) 报错（值类型不匹配）

type Errors<T> = Partial<Record<keyof T, string>>

function validate(form: FormState): Errors<FormState> {
  const errors: Errors<FormState> = {}
  if (!form.email.includes('@')) errors.email = '邮箱格式错误'
  return errors
}

// 显式泛型（initial 为 null 时必须）
const [user, setUser] = useState<User | null>(null)
// 推导（有初始值）
const [count, setCount] = useState(0)      // number

// 函数式更新保持类型
setCount(c => c + 1)

// 判别联合 Action —— 状态机的核心
type State =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: User }
  | { status: 'error'; message: string }

type Action =
  | { type: 'FETCH_START' }
  | { type: 'FETCH_SUCCESS'; data: User }
  | { type: 'FETCH_ERROR'; message: string }

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case 'FETCH_START':  return { status: 'loading' }
    case 'FETCH_SUCCESS': return { status: 'success', data: action.data }
    case 'FETCH_ERROR':  return { status: 'error', message: action.message }
  }
}

const [state, dispatch] = useReducer(reducer, { status: 'idle' })

// 使用：判别联合自动收窄
if (state.status === 'success') {
  state.data.name  // ✅ 只有 success 分支才有 data
}

1. 所有状态迁移集中（可预测）
2. 判别联合让「每个状态只暴露该状态的数据」
3. Action 类型化 → dispatch 的写法被编译检查
4. 状态机心智模型清晰

type AuthContextValue = {
  user: User | null
  login: (email: string, pwd: string) => Promise<void>
  logout: () => void
}

// 关键：默认值绝不能是「假值」——否则下游拿到的是假类型
const AuthContext = createContext<AuthContextValue | null>(null)

export function useAuth(): AuthContextValue {
  const ctx = useContext(AuthContext)
  if (!ctx) throw new Error('useAuth must be used within AuthProvider')
  return ctx   // 收窄后保证非空
}

// 返回元组（类似 useState）——返回类型元组要 as const 或显式
function useToggle(initial = false) {
  const [on, setOn] = useState(initial)
  const toggle = useCallback(() => setOn(v => !v), [])
  return [on, toggle] as const    // 推断为 readonly [boolean, () => void]
}
// 使用：const [on, toggle] = useToggle() 类型正确

1. Context 用 null + 守卫 Hook（useAuth 抛错）防「假默认值」
2. Hooks 返回值尽量显式类型或 as const
3. 参数用泛型/联合保持灵活
4. 用 useCallback/useMemo 时类型自动推导

把 DTO（数据传输对象）放进共享包 packages/types
后端（Nest/Fastify）与前端（React）都 import 同一份类型
→ 改一个字段，全栈编译报错，契约同步

// packages/types/src/api.ts
export type UserDTO = { id: string; name: string; email: string }
export type ApiResponse<T> = { data: T; code: number }

// 前端
import type { UserDTO } from '@repo/types'
// 后端
import type { UserDTO } from '@repo/types'

// 封装 fetch：请求/响应都有类型
async function api<T>(path: string, init?: RequestInit): Promise<T> {
  const res = await fetch(path, init)
  if (!res.ok) throw new Error(`API ${res.status}`)
  return res.json() as Promise<T>
}

// 具体接口
async function getUser(id: string): Promise<UserDTO> {
  return api<UserDTO>(`/api/users/${id}`)
}

import { z } from 'zod'

// 运行时验证：类型契约 + 运行时守卫
const UserSchema = z.object({ id: z.string(), name: z.string() })
type UserDTO = z.infer<typeof UserSchema>

async function getUser(id: string): Promise<UserDTO> {
  const data = await api<unknown>(`/api/users/${id}`)
  return UserSchema.parse(data)    // 校验不过就抛错，而非静默
}

// 用判别联合建模「异步数据」状态
type LoadState<T> =
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; message: string }

function Profile() {
  const state = useProfileData()   // 返回 LoadState<User>
  switch (state.status) {
    case 'loading': return <Spinner />
    case 'error':   return <ErrorMsg message={state.message} />
    case 'success': return <UserCard user={state.data} />
  }
}

1. 每个分支只访问「该状态存在的数据」→ 编译期保证
2. switch 穷尽所有分支 → 新增状态会强制补分支（exhaustive check）
3. 消除了「data 可能是 null」的运行时判断

// 缺一个分支编译报错？用 never 兜底
function assertNever(x: never): never { throw new Error('unreachable: ' + x) }

function render(state: LoadState<User>) {
  switch (state.status) {
    case 'loading': return ...
    case 'success': return ...
    case 'error':   return ...
    default: return assertNever(state)   // 新增状态未处理 → 编译错误
  }
}

// 坏：useState(() => '') 推导 string，但其实是固定字面量
// 好：需要固定取值用 as const 或显式联合
const [tab, setTab] = useState<'overview' | 'details'>('overview')

// 坏：onChange={e => setX(e.target.value)} 若 e 是 any，一切失控
// 好：让 React 推断，或显式 ChangeEvent<HTMLInputElement>

// 坏：createContext<AuthContextValue>({} as AuthContextValue) —— 假值
// 好：createContext<AuthContextValue | null>(null) + 守卫 Hook

// 过窄：children: ReactElement 会拒绝 string
// 过宽：children: any 放弃检查
// 原则：能收窄就收窄，需要最宽就 ReactNode

// 坏：key={index} 在排序/增删时破坏状态
// 好：key 用唯一 id（配合泛型 keyOf）

// 坏：res.json() as UserDTO —— 运行时可能是别的
// 好：Zod 运行时验证

┌─ 共享类型层 ─────────────────────────────┐
│  @repo/types (UserDTO/ApiResponse/...)   │
│  ↓ 同一份类型                              │
├─ 后端 ──────────────────────────────┐    │
│  Fastify/Nest 路由 → DTO 校验 (zod) │    │
│  → 响应类型 = 共享类型               │    │
├─ 前端 ──────────────────────────────┘    │
│  API 封装 (泛型 api<T> + zod)            │
│  → LoadState 判别联合                    │
│  → useReducer 状态机                     │
│  → 组件 props/事件类型化                 │
└────────────────────────────────────────┘
 改动 UserDTO → 后端校验 + 前端组件同时编译报错

数据库/服务 → DTO(zod schema) → 共享类型 → API 响应
→ 前端 fetch(zod 验证) → LoadState<T> → 组件渲染
每一层都有类型/运行时验证，契约单一来源