# 现代全栈集成模式 ## 数据流架构 ### 概述 ┌──────────────────────────────────────────────────────────────┐ │ 客户 │ │ ┌──────────────┐ ┐──────────────┐ ┌────────────┐ │ │ │ React/ │────▶│ 状态 │────▶│ 用户界面 │ │ │ │ Vue │ │ (Zustand/ │ │ 渲染 │ │ │ │ 组成部分 │ Pinia) │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────┐ │ │ │ 数据获取（React Query / SWR / Apollo） │ │ │ └────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────┘ │ ▼ HTTP / GraphQL ┌──────────────────────────────────────────────────────────────┐ │ 服务器 │ │ ┌──────────────┐ ┐──────────────┐ ┌────────────┐ │ │ │ API │────▶│ 业务 │────▶│ 数据 │ │ │ │ 路由 │ │ 逻辑 │ │ 层 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └──────────────────────────────────────────────────────────────┘ ## Next.js API 路由 ### 基本API路由 // 应用程序/api/产品/route.ts 从 'next/server' 导入 { NextRequest, NextResponse }; 从'@/lib/services/product-service'导入{productService}；导出异步函数 GET(请求: NextRequest) { const searchParams = request.nextUrl.searchParams; const page = parseInt(searchParams.get('page') ?? '1'); const limit = parseInt(searchParams.get('limit') ?? '10'); const 类别 = searchParams.get('类别'); 尝试{ const 产品 = 等待 ProductService.getProducts({ 页，限制，类别：类别??未定义， }); 返回 NextResponse.json(产品); } 捕获（错误）{ console.error('获取产品失败：', error); 返回 NextResponse.json( { error: '获取产品失败' }, { 状态：500 } ）； } } 导出异步函数 POST(request: NextRequest) { 尝试{ const body =等待request.json(); // 验证请求体 const validationResult = validateCreateProduct(body); if (!validationResult.success) { 返回 NextResponse.json( { 错误：validationResult.errors }, { 状态：400 } ）； } const 产品 = 等待 ProductService.createProduct(body); 返回 NextResponse.json(产品, { 状态: 201 }); } 捕获（错误）{ console.error('创建产品失败：', error); 返回 NextResponse.json( { error: '创建产品失败' }, { 状态：500 } ）； } } ### 动态 API 路由 // 应用程序/api/产品/[id]/route.ts 从 'next/server' 导入 { NextRequest, NextResponse }; 接口路由参数{ 参数: { id: 字符串 }; } 导出异步函数 GET(request: NextRequest, { params }: RouteParams) { const 产品 = 等待 ProductService.getById(params.id); 如果（！产品）{ 返回 NextResponse.json( { 错误：'找不到产品' }, {状态：404} ）； } 返回 NextResponse.json(产品); } 导出异步函数 PUT(request: NextRequest, { params }: RouteParams) { const body =等待request.json(); 尝试{ const 产品 = 等待 ProductService.update(params.id, body); 返回 NextResponse.json(产品); } 捕获（错误）{ if (NotFoundError 错误实例) { 返回 NextResponse.json( { 错误：'找不到产品' }, {状态：404} ）； } 抛出错误； } } 导出异步函数 DELETE(request: NextRequest, { params }: RouteParams) { 等待productService.delete(params.id); 返回新的 NextResponse(null, { 状态: 204 }); } ## GraphQL 集成 ### 查询定义 # 查询/products.graphql 查询 GetProducts($first: Int!, $after: String, $category: String) { 产品（第一：$第一，之后：$之后，类别：$类别）{ 边缘{ 节点{ 编号姓名蛞蝓价格图像{ 网址替代 } 类别{ 姓名 } } 光标 } 页面信息{ 有下一页结束光标 } 总数 } } 查询 GetProductBySlug($slug: String!) { 产品（slug：$slug）{ 编号姓名蛞蝓描述价格图片{ 网址替代 } 类别{ 姓名蛞蝓 } 变体{ 编号姓名存货单元价格 } } } 突变 AddToCart($productId: ID!, $quantity: Int!) { addToCart(输入：{ 产品Id：$productId，数量：$数量 }) { 购物车{ 编号项目{ 产品{ 姓名 } 数量 } 总计 } } } ### GraphQL 客户端设置 // lib/graphql/client.ts 从“graphql-request”导入{GraphQLClient}； const 端点 = process.env.GRAPHQL_ENDPOINT!; const apiKey = process.env.API_KEY!; 导出 const graphqlClient = new GraphQLClient(端点, { 标题：{ 'x-api-key': apiKey, }, }); // 使用错误处理包装器导出异步函数 fetchGraphQL( 查询：字符串，变量？：记录<字符串，未知> ): 承诺 { 尝试{ 返回等待 graphqlClient.request(查询, 变量); } 捕获（错误）{ console.error('GraphQL 错误：', error); throw new Error('获取数据失败'); } } ### GraphQL 的 React Hook // 钩子/useProducts.ts 从'@tanstack/react-query'导入{useQuery}；从'@/lib/graphql/client'导入{graphqlClient}；从“@/生成/graphql”导入{GetProductsDocument}；接口 UseProductsOptions { 类别？：字符串；限制？：数量； } 导出函数 useProducts({ 类别, limit = 10 }: UseProductsOptions = {}) { 返回 useQuery({ queryKey: ['产品', { 类别, 限制 }], queryFn: async () => { const data = 等待 graphqlClient.request(GetProductsDocument, { 第一：限制，类别， }); 返回数据.产品； }, staleTime: 5 * 60 * 1000, // 5 分钟 }); } ## 服务器组件 + 客户端数据 ### 带有数据的服务器组件 // 应用程序/产品/page.tsx 从 '@/lib/api/products' 导入 { getProducts } ；从 '@/components/ProductGrid' 导入 { ProductGrid }；从'@/components/ProductFilters'导入{ProductFilters}；接口 PageProps { searchParams: { 类别？: 字符串;页？：字符串 }; } 导出默认异步函数 ProductsPage({ searchParams }: PageProps) { const page = parseInt(searchParams.page ?? '1'); const 产品 = 等待 getProducts({ 类别：searchParams.category，页，限制：12， }); 返回（

产品

{/* 用于交互的客户端组件 */} {/* 服务器渲染的产品网格 */} {/* 用于分页的客户端组件 */} <分页当前页={页} 总页数={产品.总页数} /> ）； } ### 带有突变的客户端组件 '使用客户端'；从'react'导入{useState}；从 '@tanstack/react-query' 导入 { useMutation, useQueryClient }; 接口 AddToCartButtonProps { 产品ID：字符串；产品名称：字符串； } 导出函数 AddToCartButton({ 产品Id, 产品名称 }: AddToCartButtonProps) { const [数量，设置数量] = useState(1); const queryClient = useQueryClient(); const 突变 = useMutation({ mutationFn：异步（数据：{productId：字符串；数量：数字}）=> { const 响应 = 等待 fetch('/api/cart', { 方法：'POST'， headers: { 'Content-Type': 'application/json' }, 正文：JSON.stringify（数据）， }); 如果（！response.ok）{ throw new Error('无法添加到购物车'); } 返回response.json(); }, 成功：() => { queryClient.invalidateQueries({ queryKey: ['cart'] }); }, }); 返回（

<输入类型=“数字” 分钟=“1” 最大=“10” 值={数量} onChange={(e) => setQuantity(parseInt(e.target.value))} className="w-20 px-3 py-2 边框圆角" /> <按钮 onClick={() =>mutation.mutate({productId, 数量})} 禁用={mutation.isPending} className =“px-6 py-2 bg-blue-600文本白色圆形悬停：bg-blue-700禁用：opacity-50” > {突变.isPending ? '添加...' : '添加到购物车'} {mutation.isError && ( 添加项目失败 )}

）； } ## REST API 模式 ### API 客户端 // lib/api/client.ts const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL; 接口 RequestOptions 扩展 RequestInit { 参数？：记录<字符串，字符串>； } 类 ApiClient { 私有baseUrl：字符串；构造函数（baseUrl：字符串）{ this.baseUrl = baseUrl; } 私有异步请求( 端点：字符串，选项：请求选项 = {} ): 承诺 { const { params, ...init } = 选项; 让 url = `${this.baseUrl}${endpoint}`; 如果（参数）{ const searchParams = new URLSearchParams(params); url += `?${searchParams.toString()}`; } const 响应 = 等待获取（url，{ ...初始化，标题：{ '内容类型'：'应用程序/json'， ...init.headers， }, }); 如果（！response.ok）{ const error =等待response.json().catch(() => ({})); throw new ApiError(response.status, error.message ?? '请求失败'); } 返回response.json(); } async get(端点: string, params?: Record): Promise { return this.request(endpoint, { method: 'GET', params }); } 异步 post（端点：字符串，数据：未知）： Promise { 返回 this.request(端点, { 方法：'POST'，正文：JSON.stringify（数据）， }); } async put(端点：字符串，数据：未知): Promise { 返回 this.request(端点, { 方法：'放置'，正文：JSON.stringify（数据）， }); } 异步删除（端点：字符串）：Promise { 等待 this.request(endpoint, { method: 'DELETE' }); } } 导出 const api = new ApiClient(API_BASE_URL); ### 类型安全的 API 挂钩 // 钩子/api/useProducts.ts 从 '@tanstack/react-query' 导入 { useQuery, useMutation, useQueryClient }; 从 '@/lib/api/client' 导入 { api }；从 '@/types' 导入类型 { Product, CreateProductInput, UpdateProductInput }; 导出函数 useProducts(params?: { 类别?: 字符串; 页码?: 数字 }) { 返回 useQuery({ 查询键：['产品'，参数]， queryFn: () => api.get<{ items: Product[];总数：数量 }>('/产品', { 类别：参数？.类别，页：字符串（参数？.页??1）， }), }); } 导出函数 useProduct(id: string) { 返回 useQuery({ 查询键：['产品'，id]， queryFn: () => api.get<产品>(`/products/${id}`), 启用：！！id， }); } 导出函数 useCreateProduct() { const queryClient = useQueryClient(); 返回 useMutation({ 突变Fn：（数据：CreateProductInput）=> api.post<产品>('/产品', 数据), 成功：() => { queryClient.invalidateQueries({ queryKey: ['产品'] }); }, }); } 导出函数 useUpdateProduct() { const queryClient = useQueryClient(); 返回 useMutation({ mutationFn: ({ id, data }: { id: string; data: UpdateProductInput }) => api.put<产品>(`/products/${id}`, data), onSuccess: (产品) => { queryClient.invalidateQueries({ queryKey: ['产品'] }); queryClient.setQueryData(['产品', 产品.id], 产品); }, }); } 导出函数 useDeleteProduct() { const queryClient = useQueryClient(); 返回 useMutation({ mutationFn: (id: string) => api.delete(`/products/${id}`), 成功：() => { queryClient.invalidateQueries({ queryKey: ['产品'] }); }, }); } ## 环境变量 ### 配置 # .env.local # 仅限服务器（不暴露给浏览器） DATABASE_URL=postgresql://用户:pass@localhost:5432/db API_SECRET_KEY=sk_live_xxxxx GRAPHQL_ENDPOINT=https://api.example.com/graphql # Public（通过 NEXT_PUBLIC_ 前缀暴露给浏览器） NEXT_PUBLIC_API_URL=https://api.example.com NEXT_PUBLIC_SITE_URL=https://example.com NEXT_PUBLIC_ANALYTICS_ID=UA-XXXXX ### 类型安全环境 // lib/env.ts 从 'zod' 导入 { z }； const envSchema = z.object({ // 仅限服务器 DATABASE_URL: z.string().url(), API_SECRET_KEY: z.string().min(1), GRAPHQL_ENDPOINT: z.string().url(), // 公共 NEXT_PUBLIC_API_URL: z.string().url(), NEXT_PUBLIC_SITE_URL: z.string().url(), }); // 在构建时验证 const 解析 = envSchema.safeParse(process.env); if (!parsed.success) { console.error('无效的环境变量：', parsed.error.flatten()); throw new Error('无效的环境变量'); } 导出 const env = parsed.data; // 仅适用于客户端变量导出 const publicEnv = { apiUrl: process.env.NEXT_PUBLIC_API_URL!, siteUrl：process.env.NEXT_PUBLIC_SITE_URL！， }; ## 错误处理 ### 错误边界 '使用客户端'；从'react'导入{useEffect}；接口ErrorBoundaryProps { 错误：错误&{摘要？：字符串}；重置：() => 无效； } 导出默认函数 ErrorBoundary({ 错误, 重置 }: ErrorBoundaryProps) { 使用效果（（）=> { // 记录到错误跟踪服务 console.error('错误：', 错误); }, [错误]); 返回（

出了点问题

{错误消息|| '发生意外错误'}

<按钮 onClick={重置} className="px-6 py-2 bg-blue-600 文本白色圆形悬停：bg-blue-700" > 再试一次

）； } ### API 错误处理 // lib/errors.ts 导出类 ApiError 扩展错误 { 构造函数（公共状态：数量，消息：字符串，公共代码？：字符串）{ 超级（消息）； this.name = 'ApiError'; } 静态 isApiError（错误：未知）：错误是 ApiError { 返回错误 ApiError 实例； } } // 在组件中的使用函数产品页面（）{ const { 数据，错误，正在加载 } = useProduct(id); if (isLoading) 返回 ; 如果（错误）{ if (ApiError.isApiError(error) && error.status === 404) { return ; } 返回 ; } 返回 ; } ## 乐观更新 // 钩子/useToggleFavorite.ts 从 '@tanstack/react-query' 导入 { useMutation, useQueryClient }; 导出函数 useToggleFavorite() { const queryClient = useQueryClient(); 返回 useMutation({ mutationFn: async (productId: string) => { const 响应 = 等待 fetch(`/api/favorites/${productId}`, { 方法：'POST'， }); 返回response.json(); }, // 乐观更新 onMutate: 异步 (productId) => { // 取消传出重新获取等待 queryClient.cancelQueries({ queryKey: ['products'] }); // 快照之前的值 const previousProducts = queryClient.getQueryData(['产品']); // 乐观更新 queryClient.setQueryData(['产品'], (旧: 产品[]) => 旧地图（（产品）=> 产品.id === 产品Id ？ { ...产品，isFavorite：！product.isFavorite } ：产品））；返回 { 以前的产品 }; }, // 出错时回滚 onError: (err, ProductId, context) => { queryClient.setQueryData(['products'], context?.previousProducts); }, // 成功或错误后重新获取已解决：() => { queryClient.invalidateQueries({ queryKey: ['产品'] }); }, }); } ## 实时更新 ### WebSocket 集成 // lib/websocket.ts 从 'react' 导入 { useEffect, useRef }; 从'@tanstack/react-query'导入{useQueryClient}；导出函数 useWebSocket(url: string) { const ws = useRef(空); const queryClient = useQueryClient(); 使用效果（（）=> { ws.current = new WebSocket(url); ws.current.onmessage = (事件) => { const 消息 = JSON.parse(event.data); 开关（消息.类型）{ 案例“产品：更新”： queryClient.invalidateQueries({ queryKey: ['产品', message.productId] }); 打破；案例“购物车：已更新”： queryClient.invalidateQueries({ queryKey: ['cart'] }); 打破；案例“通知”： // 处理通知打破； } }; ws.current.onclose = () => { // 重新连接逻辑设置超时（（）=> { ws.current = new WebSocket(url); }, 3000); }; 返回（）=> { ws.current?.close(); }; }, [url, queryClient]); 返回{ 发送：（数据：未知）=> { ws.current?.send(JSON.stringify(data)); }, }; } ## SSR vs SSG vs ISR ### 静态生成（SSG） // 对于很少改变的内容 // 应用程序/博客/[slug]/page.tsx 导出异步函数generateStaticParams() { const posts = 等待 getPosts(); 返回 posts.map((post) => ({ slug: post.slug })); } 导出默认异步函数 BlogPost({ params }: { params: { slug: string } }) { const post =等待 getPost(params.slug); return <文章post={post} />; } ### 增量静态再生 (ISR) // 对于定期更新的内容 // 应用程序/产品/page.tsx 导出常量重新验证= 60； // 每 60 秒重新验证一次导出默认异步函数 ProductsPage() { const 产品 = 等待 getProducts(); 返回 ; } ### 服务器端渲染 (SSR) // 对于个性化或实时数据 // 应用程序/仪表板/page.tsx 导出 const 动态 = '力动态'; 导出默认异步函数 DashboardPage() { const user = 等待 getCurrentUser(); const data = 等待 getDashboardData(user.id); return ; } ## 预览模式/草稿内容 // 应用程序/api/preview/route.ts 从'next/headers'导入{draftMode}；从“下一步/导航”导入{重定向}；导出异步函数 GET(请求: NextRequest) { const searchParams = request.nextUrl.searchParams; const Secret = searchParams.get('秘密'); const slug = searchParams.get('slug'); if (秘密!== process.env.PREVIEW_SECRET) { return NextResponse.json({ error: '无效令牌' }, { status: 401 }); } // 启用草稿模式 DraftMode().enable(); // 重定向到页面重定向（slug ?? '/'）； } // 应用程序/api/exit-preview/route.ts 导出异步函数 GET() { DraftMode().disable(); 重定向（'/'）； } // lib/api/content.ts 从'next/headers'导入{draftMode}；导出异步函数 getContent(slug: string) { const { isEnabled: isDraft } = DraftMode(); // 根据模式获取草稿或已发布的内容 const content = 等待 cms.getContent(slug, { 预览： isDraft， }); 返回内容； }

全栈现代

包含技能