TypeScript 在 Next.js 16 中的全量实践

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [{ "name": "next" }],
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

// 这些都被 strict: true 涵盖
"strictNullChecks": true,       // null/undefined 必须显式处理
"strictFunctionTypes": true,    // 函数参数类型严格检查
"strictBindCallApply": true,    // bind/call/apply 类型检查
"strictPropertyInitialization": true, // 类属性必须初始化
"noImplicitAny": true,          // 禁止隐式 any
"noImplicitThis": true,         // 禁止隐式 this
"alwaysStrict": true,           // 每个文件加 "use strict"

{
  "compilerOptions": {
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "forceConsistentCasingInFileNames": true,
    "exactOptionalPropertyTypes": true
  }
}

// app/chat/[id]/page.tsx
type ChatPageProps = {
  params: Promise<{ id: string }>
  searchParams: Promise<{ tab?: string; page?: string }>
}
 
export default async function ChatPage({ params, searchParams }: ChatPageProps) {
  const { id } = await params
  const { tab = 'messages', page = '1' } = await searchParams
 
  const chat = await getChat(id)
  return <ChatDetail chat={chat} activeTab={tab} />
}

// app/(dashboard)/layout.tsx
type DashboardLayoutProps = {
  children: React.ReactNode
  modal: React.ReactNode  // 并行路由 slot
}
 
export default function DashboardLayout({ children, modal }: DashboardLayoutProps) {
  return (
    <div className="flex h-screen">
      <Sidebar />
      <main className="flex-1">{children}</main>
      {modal}
    </div>
  )
}

// app/api/chat/route.ts
import { NextRequest, NextResponse } from 'next/server'
 
export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams
  const page = Number(searchParams.get('page') ?? '1')
 
  const chats = await db.query.chats.findMany({
    limit: 20,
    offset: (page - 1) * 20,
  })
 
  return NextResponse.json(chats)
}
 
export async function POST(request: NextRequest) {
  const body = await request.json()
  // body 是 unknown，需要手动校验
  return NextResponse.json({ success: true })
}

// middleware.ts
import { NextRequest, NextResponse } from 'next/server'
 
export function middleware(request: NextRequest) {
  const token = request.cookies.get('session')?.value
 
  if (!token && request.nextUrl.pathname.startsWith('/chat')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
 
  return NextResponse.next()
}
 
export const config = {
  matcher: ['/chat/:path*', '/settings/:path*', '/admin/:path*'],
}

import type { Metadata, ResolvingMetadata } from 'next'
 
// 静态 metadata
export const metadata: Metadata = {
  title: 'AI 对话',
  openGraph: {
    title: 'AI 对话',
    images: ['/og/chat.png'],
  },
}
 
// 动态 metadata
export async function generateMetadata(
  { params }: { params: Promise<{ id: string }> },
  parent: ResolvingMetadata,
): Promise<Metadata> {
  const { id } = await params
  const chat = await getChat(id)
  const previousImages = (await parent).openGraph?.images || []
 
  return {
    title: chat.title,
    openGraph: {
      images: [`/api/og?title=${chat.title}`, ...previousImages],
    },
  }
}

// app/chat/actions.ts
'use server'
 
import { z } from 'zod'
import { revalidatePath } from 'next/cache'
 
const CreateChatSchema = z.object({
  title: z.string().min(1, '标题不能为空').max(100),
  model: z.enum(['gpt-4o', 'claude-3.5-sonnet', 'gemini-pro']),
})
 
export async function createChat(formData: FormData) {
  const parsed = CreateChatSchema.safeParse({
    title: formData.get('title'),
    model: formData.get('model'),
  })
 
  if (!parsed.success) {
    return { error: parsed.error.flatten().fieldErrors }
  }
 
  const chat = await db.insert(chats).values({
    title: parsed.data.title,
    model: parsed.data.model,
    userId: await getCurrentUserId(),
  }).returning()
 
  revalidatePath('/chat')
  return { data: chat[0] }
}

pnpm add next-safe-action zod

// lib/safe-action.ts
import { createSafeActionClient } from 'next-safe-action'
import { auth } from '@/lib/auth/config'
 
export const actionClient = createSafeActionClient()
 
export const authActionClient = createSafeActionClient({
  async middleware() {
    const session = await auth()
    if (!session?.user) {
      throw new Error('Unauthorized')
    }
    return { userId: session.user.id }
  },
})

// app/chat/actions.ts
'use server'
 
import { authActionClient } from '@/lib/safe-action'
import { z } from 'zod'
 
export const createChat = authActionClient
  .schema(z.object({
    title: z.string().min(1).max(100),
    model: z.enum(['gpt-4o', 'claude-3.5-sonnet']),
  }))
  .action(async ({ parsedInput, ctx }) => {
    // parsedInput 有完整类型推导
    // ctx.userId 来自 middleware
    const chat = await db.insert(chats).values({
      title: parsedInput.title,
      model: parsedInput.model,
      userId: ctx.userId,
    }).returning()
 
    revalidatePath('/chat')
    return chat[0]
  })

// 客户端调用 — 返回值有完整类型
'use client'
 
import { useAction } from 'next-safe-action/hooks'
import { createChat } from './actions'
 
export function NewChatButton() {
  const { execute, result, isExecuting } = useAction(createChat)
 
  return (
    <button
      onClick={() => execute({ title: '新对话', model: 'gpt-4o' })}
      disabled={isExecuting}
    >
      {isExecuting ? '创建中...' : '新建对话'}
    </button>
    // result.data 类型自动推导为 Chat
    // result.serverError 类型为 string | undefined
  )
}

// ❌ 危险：类型断言不做任何运行时检查
const body = await request.json() as { title: string }
// 如果请求体没有 title 字段，运行时才会崩溃
 
// ✅ 安全：Zod 在运行时校验
import { z } from 'zod'
 
const schema = z.object({ title: z.string().min(1) })
const result = schema.safeParse(await request.json())
if (!result.success) {
  return NextResponse.json({ error: result.error }, { status: 400 })
}
// result.data.title 类型安全且运行时确认

// types/schemas.ts
import { z } from 'zod'
 
// 分页参数
export const PaginationSchema = z.object({
  page: z.coerce.number().int().min(1).default(1),
  pageSize: z.coerce.number().int().min(1).max(100).default(20),
})
 
// 用户注册
export const RegisterSchema = z.object({
  email: z.string().email('邮箱格式不正确'),
  password: z.string().min(8, '密码至少 8 位').max(100),
  name: z.string().min(2, '姓名至少 2 个字符').max(50),
})
 
// AI 对话消息
export const ChatMessageSchema = z.object({
  role: z.enum(['user', 'assistant', 'system']),
  content: z.string().min(1).max(10000),
})
 
// 从 Schema 推导 TypeScript 类型
export type Pagination = z.infer<typeof PaginationSchema>
export type Register = z.infer<typeof RegisterSchema>
export type ChatMessage = z.infer<typeof ChatMessageSchema>

// server/trpc/router.ts
import { z } from 'zod'
import { router, protectedProcedure } from './trpc'
 
export const chatRouter = router({
  list: protectedProcedure
    .input(z.object({ page: z.number().default(1) }))
    .query(async ({ ctx, input }) => {
      return db.query.chats.findMany({
        where: eq(chats.userId, ctx.userId),
        limit: 20,
        offset: (input.page - 1) * 20,
      })
    }),
 
  create: protectedProcedure
    .input(z.object({ title: z.string(), model: z.string() }))
    .mutation(async ({ ctx, input }) => {
      return db.insert(chats).values({
        ...input,
        userId: ctx.userId,
      }).returning()
    }),
})

// 客户端调用 — 零手动类型定义
'use client'
 
import { trpc } from '@/lib/trpc/client'
 
export function ChatList() {
  const { data: chats } = trpc.chat.list.useQuery({ page: 1 })
  // chats 的类型自动推导为数据库查询结果类型
 
  const createChat = trpc.chat.create.useMutation()
  // createChat.mutate({ title: '...', model: '...' }) — 参数类型自动校验
}

// 1. 从 API 响应推导类型
type ApiResponse = Awaited<ReturnType<typeof getChats>>
 
// 2. 组件 Props 提取
type ButtonProps = React.ComponentProps<typeof Button>
 
// 3. 去除 null/undefined
type NonNullChat = NonNullable<typeof chat>
 
// 4. 部分字段可选
type PartialChat = Partial<Pick<Chat, 'title' | 'model'>>
 
// 5. 从数组元素推导类型
type Chat = (typeof chats)[number]

// ❌ 错误：Type 'string | null' is not assignable to type 'string'
const title = searchParams.get('title') // string | null
db.insert({ title }) // 期望 string
 
// ✅ 方案1：空值合并
db.insert({ title: title ?? 'Untitled' })
 
// ✅ 方案2：提前校验
if (!title) throw new Error('Title is required')
db.insert({ title }) // 此时 title 被收窄为 string
 
// ✅ 方案3：Zod 校验
const { title } = z.object({ title: z.string() }).parse({ title: searchParams.get('title') })

// 🚫 绝对禁止
const data = response as any
const user = body as User  // 类型断言不做运行时检查
 
// 🚫 避免使用
// @ts-ignore
// @ts-expect-error（除非你真的知道在做什么并写了注释）
 
// ✅ 替代方案
const data = schema.parse(response)         // Zod 运行时校验
const user = UserSchema.parse(body)         // 类型+运行时双重安全