企业官网建设流程全解析

全栈独立产品数据流架构：从请求到持久化的完整链路

大家好，我是蔓蔓。在搭建独立产品全栈架构时，我踩过的最大的坑不是某个技术选型错误，而是数据流设计的前后割裂。前端用 React Query 管缓存，后端用 ORM 管数据库，中间靠 REST API 传数据，三者各管各的。一个大版本重构时才发现，数据一致性、缓存失效和类型安全三者之间存在系统性的设计缺陷。今天和大家分享我重新设计的全栈数据流架构。

一、前后割裂的代价：当数据一致性成为系统性风险

在一个典型的全栈独立产品中，数据会流经以下路径：

浏览器状态 → HTTP 请求 → API 路由 → Service 层 → ORM → 数据库 ↑ | └─────────── 响应返回 ────────── 缓存策略 ──────────────┘

这条链路上常见的三个断层：

断层一：类型定义的"三份拷贝"

// 前端 types/user.ts interface User { id: number; name: string; email: string; createdAt: string; // 前端用 string } // 后端 types/user.ts interface User { id: number; name: string; email: string; created_at: Date; // 后端用 Date } // 数据库 schema // id INT, name VARCHAR, email VARCHAR, created_at TIMESTAMP

三个地方定义了同一份数据结构，任一修改都需要三处同步，实际运行中几乎不可能保持完全一致。

断层二：缓存与数据源的"双写"不一致

// 前端更新用户信息后，缓存和服务器状态不同步 function updateUser(userId: number, data: Partial<User>) { // 乐观更新缓存 queryClient.setQueryData(['user', userId], (old) => ({ ...old, ...data })); // 但服务器更新可能失败 fetch(`/api/users/${userId}`, { method: 'PATCH', body: JSON.stringify(data) }); }

断层三：请求状态管理的碎片化

Loading、Error、Empty 等状态在每个组件中重复处理，缺乏统一的抽象。

二、统一数据流架构设计

核心设计理念：以数据模型为中心，类型定义是唯一真相源（Single Source of Truth），前后端共享同一份 Schema。

flowchart TB subgraph 共享层 S[Prisma/Zod Schema<br/>唯一真相源] S --> T[共享类型定义<br/>自动生成] end subgraph 前端数据流 T --> RQ[React Query<br/>服务端状态管理] RQ --> C[组件层<br/>声明式数据获取] C --> UI[UI 渲染] end subgraph 后端数据流 T --> API[tRPC/API 路由<br/>类型安全接口] API --> SV[Service 层<br/>业务逻辑] SV --> ORM[ORM 查询层] ORM --> DB[(PostgreSQL)] end S --> API T -.-> RQ subgraph 缓存与同步 RQ <--> IS[缓存失效策略] API --> IS end

Schema 驱动的类型生成

// prisma/schema.prisma — 唯一数据模型定义 model User { id Int @id @default(autoincrement()) email String @unique name String avatar String? role Role @default(USER) posts Post[] createdAt DateTime @default(now()) @map("created_at") updatedAt DateTime @updatedAt @map("updated_at") @@map("users") } enum Role { USER ADMIN CREATOR } model Post { id Int @id @default(autoincrement()) title String content String @db.Text published Boolean @default(false) author User @relation(fields: [authorId], references: [id]) authorId Int @map("author_id") tags String[] createdAt DateTime @default(now()) @map("created_at") @@map("posts") }

前后端共享类型

// shared/types.ts — 从 Prisma 推导，前后端共享 import type { User, Post, Role } from '@prisma/client'; // 前端专用：API 响应包装 export type ApiResponse<T> = | { success: true; data: T } | { success: false; error: { code: string; message: string } }; // DTO 类型 export type CreatePostInput = Pick<Post, 'title' | 'content' | 'tags'>; export type UpdateUserInput = Partial<Pick<User, 'name' | 'avatar'>>; // 分页类型 export interface PaginatedResponse<T> { items: T[]; total: number; page: number; pageSize: number; hasMore: boolean; }

三、前端数据获取层：React Query 的统一抽象

查询 Key 的规范化管理

// frontend/hooks/query-keys.ts export const queryKeys = { users: { all: ['users'] as const, detail: (id: number) => ['users', id] as const, posts: (userId: number) => ['users', userId, 'posts'] as const, }, posts: { all: (filters?: PostFilters) => ['posts', filters] as const, detail: (id: number) => ['posts', id] as const, search: (query: string) => ['posts', 'search', query] as const, }, } as const;

声明式数据获取 Hook

// frontend/hooks/use-post.ts import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'; import type { Post, CreatePostInput, PaginatedResponse } from '@shared/types'; import { queryKeys } from './query-keys'; export function usePosts(filters?: PostFilters) { return useQuery({ queryKey: queryKeys.posts.all(filters), queryFn: async () => { const params = new URLSearchParams(); if (filters?.status) params.set('status', filters.status); if (filters?.page) params.set('page', String(filters.page)); const res = await fetch(`/api/posts?${params}`); if (!res.ok) { const error = await res.json(); throw new Error(error.message || '获取文章失败'); } const data: ApiResponse<PaginatedResponse<Post>> = await res.json(); if (!data.success) throw new Error(data.error.message); return data.data; }, staleTime: 60_000, // 1 分钟内视为新鲜 gcTime: 5 * 60_000, // 5 分钟后垃圾回收 retry: (failureCount, error) => { // 4xx 错误不重试，5xx 重试最多 2 次 if (error.message.includes('401') || error.message.includes('403')) { return false; } return failureCount < 2; }, }); } export function useCreatePost() { const queryClient = useQueryClient(); return useMutation({ mutationFn: async (input: CreatePostInput) => { const res = await fetch('/api/posts', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(input), }); if (!res.ok) { const error = await res.json(); throw new Error(error.message || '创建失败'); } return res.json(); }, onSuccess: () => { // 精确失效策略：只失效列表，不失效单个详情 queryClient.invalidateQueries({ queryKey: queryKeys.posts.all(), exact: false, }); }, onError: (error) => { // 统一错误提示 toast.error(error.message); }, }); }

四、后端 Service 层与事务管理

业务逻辑的 Service 抽象

// backend/services/post.service.ts import { prisma } from '../lib/prisma'; import type { Post, CreatePostInput } from '@shared/types'; export class PostService { async list(filters: { status?: 'published' | 'draft'; page?: number; pageSize?: number; }): Promise<{ items: Post[]; total: number; page: number; pageSize: number; hasMore: boolean }> { const page = filters.page || 1; const pageSize = filters.pageSize || 20; const where: Record<string, unknown> = {}; if (filters.status) where.published = filters.status === 'published'; const [items, total] = await Promise.all([ prisma.post.findMany({ where, skip: (page - 1) * pageSize, take: pageSize, orderBy: { createdAt: 'desc' }, include: { author: { select: { id: true, name: true, avatar: true } } }, }), prisma.post.count({ where }), ]); return { items, total, page, pageSize, hasMore: page * pageSize < total, }; } async create(userId: number, input: CreatePostInput): Promise<Post> { return prisma.$transaction(async (tx) => { const post = await tx.post.create({ data: { ...input, authorId: userId, }, include: { author: { select: { id: true, name: true } } }, }); // 关联操作：记录创建日志 await tx.activityLog.create({ data: { userId, action: 'POST_CREATED', targetId: post.id, }, }); return post; }); } async delete(userId: number, postId: number): Promise<void> { // 权限检查：只能删除自己的文章 const post = await prisma.post.findUnique({ where: { id: postId }, select: { authorId: true }, }); if (!post || post.authorId !== userId) { throw new Error('无权删除此文章'); } await prisma.post.delete({ where: { id: postId } }); } }

请求级缓存策略

// backend/lib/cache.ts interface CacheStrategy { ttl: number; // 缓存时间（秒） invalidateOn: string[]; // 失效触发器 } const strategies: Record<string, CacheStrategy> = { 'posts:list': { ttl: 60, invalidateOn: ['post:create', 'post:update', 'post:delete'], }, 'users:detail': { ttl: 300, invalidateOn: ['user:update'], }, }; // Express 中间件实现 function cacheMiddleware(strategyKey: string) { return async (req: Request, res: Response, next: NextFunction) => { const strategy = strategies[strategyKey]; if (!strategy) return next(); const cacheKey = `${strategyKey}:${req.originalUrl}`; const cached = await redis.get(cacheKey); if (cached) { res.setHeader('X-Cache', 'HIT'); return res.json(JSON.parse(cached)); } // 拦截 res.json 以缓存响应 const originalJson = res.json.bind(res); res.json = (body: unknown) => { redis.setex(cacheKey, strategy.ttl, JSON.stringify(body)); return originalJson(body); }; res.setHeader('X-Cache', 'MISS'); next(); }; }

踩坑：乐观更新的回滚陷阱与缓存失效遗漏

全栈数据流中最常见的两类 Bug：

第一，乐观更新失败后的回滚不完整。React Query 的useMutation支持onMutate（乐观更新缓存）和onError（回滚），但回滚时如果只恢复了列表缓存而忘了恢复详情缓存，会导致页面数据不一致——列表中显示旧标题，点击进入详情页仍显示乐观更新后的新标题。正确的回滚必须覆盖所有相关的 queryKey：

export function useUpdatePost() { const queryClient = useQueryClient(); return useMutation({ mutationFn: async (input: UpdatePostInput & { id: number }) => { const res = await fetch(`/api/posts/${input.id}`, { method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(input), }); if (!res.ok) throw new Error('更新失败'); return res.json(); }, onMutate: async (input) => { // 乐观更新：同时更新列表和详情 await queryClient.cancelQueries({ queryKey: queryKeys.posts.all() }); await queryClient.cancelQueries({ queryKey: queryKeys.posts.detail(input.id) }); const previousList = queryClient.getQueryData(queryKeys.posts.all()); const previousDetail = queryClient.getQueryData(queryKeys.posts.detail(input.id)); queryClient.setQueryData(queryKeys.posts.detail(input.id), (old: Post) => ({ ...old, ...input, })); return { previousList, previousDetail }; }, onError: (_err, input, context) => { // 回滚：恢复所有相关缓存 if (context?.previousList) { queryClient.setQueryData(queryKeys.posts.all(), context.previousList); } if (context?.previousDetail) { queryClient.setQueryData(queryKeys.posts.detail(input.id), context.previousDetail); } }, onSettled: (_data, _err, input) => { // 最终：精确失效，让服务器数据覆盖 queryClient.invalidateQueries({ queryKey: queryKeys.posts.all() }); queryClient.invalidateQueries({ queryKey: queryKeys.posts.detail(input.id) }); }, }); }

第二，Redis 缓存失效的触发遗漏。PostService 的create方法写入数据库后，如果忘记触发post:create事件，Redis 中posts:list的 60 秒缓存仍会返回旧数据。在 Service 层的每个写操作中必须显式调用缓存失效：

// 正确做法：每个写操作后触发缓存失效 async create(userId: number, input: CreatePostInput): Promise<Post> { const post = await prisma.$transaction(async (tx) => { const post = await tx.post.create({ data: { ...input, authorId: userId } }); await tx.activityLog.create({ data: { userId, action: 'POST_CREATED', targetId: post.id } }); return post; }); // 触发缓存失效 await redis.del('posts:list:*'); await eventBus.emit('post:create', { postId: post.id }); return post; }

4.1 数据库事务的最佳实践

在使用Prisma进行事务操作时，需要注意事务的范围和性能影响。长时间运行的事务会持有数据库连接，可能导致连接池耗尽。建议将事务控制在最小范围内，只包含所有必要的数据库操作。对于需要执行外部API调用或发送邮件等操作，应该放在事务外部，使用事件驱动的方式异步处理。同时，应该为事务设置合理的超时时间，避免事务长时间阻塞其他操作。

五、总结

全栈数据流架构的核心挑战在于保持"从数据库到 UI"的完整性和一致性。三个设计原则：

第一，Schema 是唯一的真相源。使用 Prisma 或 Drizzle 等 Schema-first 的 ORM，让数据库定义自动生成前后端的类型声明，彻底消除"三份拷贝"的问题。这是 ROI 最高的架构决策之一。

第二，缓存要有明确的失效策略。无论是前端的 React Query 缓存，还是后端的 Redis 缓存，都必须定义清晰的 TTL 和失效触发器。没有失效策略的缓存不是优化，而是隐患。

第三，请求状态需要统一抽象。将 Loading、Error、Empty、Success 的状态管理从组件中抽离到数据获取层，通过 React Query 或 SWR 的声明式 API 统一处理，可以将组件代码量减少 40% 以上。

推荐实施路径：从 Schema 驱动类型生成开始，这是最基础的架构改进；然后引入 React Query 统一前端数据获取；最后完善后端的 Service 层和缓存策略。

你在全栈项目中是如何管理数据流的？欢迎在评论区交流～