采用next.js+postgresql+prisma的全栈架构需遵循五大原则：一、按功能垂直切分目录，app/下路由模块化，数据访问集中于lib/prisma.ts，服务逻辑封装在lib/services/，类型定义统一收口types/；二、prisma schema作为数据层唯一事实来源，严格建模、显式索引与关系，迁移区分dev与prod；三、依执行上下文选择数据获取方式：服务器组件直调prisma并配置缓存，客户端组件通过api路由交互，敏感数据校验会话；四、环境变量隔离配置，.env.local不提交，vercel中配置生产变量，prisma启用driveradapters提升稳定性；五、zod运行时校验请求、select显式投影必填字段、所有写入包裹事务、prisma异常分类处理。
如果您正在规划一个现代化全栈 Web 应用，采用 Next.js 作为框架、PostgreSQL 作为数据库、Prisma 作为 ORM 层，则需构建一套兼顾类型安全、开发效率与生产稳定性的架构体系。以下是该技术组合下项目架构设计的关键环节：
一、目录结构与模块划分
清晰的目录结构是可维护性的基础。Next.js（App Router）推荐以功能/领域为单位组织代码，避免传统 MVC 的僵化分层，转而采用垂直切片（vertical slicing）方式组织逻辑边界。核心原则是将数据获取、服务逻辑、UI 组件尽可能靠近其使用上下文。
1、在 app/ 目录下按路由功能划分子目录，如 app/users/、app/posts/，每个子目录内包含 page.tsx、layout.tsx 及专属 API 路由（route.ts）。
2、将数据访问逻辑集中于 lib/prisma.ts，该文件导出已初始化的 PrismaClient 实例，并配置连接池与错误监听；禁止在组件或路由处理函数中直接 new PrismaClient()。
3、业务服务层置于 lib/services/，例如 lib/services/user-service.ts，封装对 Prisma Client 的调用，添加输入校验、事务控制及领域逻辑，隔离数据库细节。
4、类型定义统一收口至 types/ 目录，包括数据库模型扩展类型（如 UserWithProfile）、API 响应契约（ApiResponse
二、数据库建模与 Prisma 配置
Prisma Schema 是整个数据层的单一事实来源（Single Source of Truth），其设计直接影响后续迁移可靠性、查询性能与类型推导精度。必须严格遵循关系规范化原则，并显式声明约束与索引。
1、在 prisma/schema.prisma 中定义 datasource，确保 provider = "postgresql"，且 url 从环境变量读取：env("DATABASE_URL")。
2、为每个模型启用 @id 和 @unique 约束，对高频查询字段（如 email、slug）显式添加 @map 与 @@index 指令。
3、使用 @relation 明确外键字段与引用模型，避免隐式关联；对多对多关系，必须通过显式中间模型建模（如 UserRole），而非 Prisma 的隐式联结表。
4、运行 npx prisma db push 同步本地模型至开发数据库，生成客户端类型；生产环境则必须使用 npx prisma migrate dev 创建版本化迁移脚本，禁止直接 push 到生产库。
三、数据获取策略与缓存边界
Next.js App Router 提供了服务器组件（Server Component）、客户端组件（Client Component）与 Server Action 三种执行上下文，每种上下文的数据获取方式与缓存语义截然不同，需按场景精准选用。
1、在服务器组件中，直接调用 prisma.user.findMany() 等方法获取数据，利用 React 的 streaming 渲染能力实现渐进式加载；该调用默认不缓存，但可通过 fetchCache: 'force-cache' 或 next: { revalidate: 60 } 显式声明缓存策略。
2、在客户端组件中，禁止直接调用 Prisma Client；必须通过 fetch 请求应用自身的 API 路由（app/api/users/route.ts），并在路由中完成数据库操作与响应封装。
3、对敏感或用户专属数据（如个人资料），在 API 路由中验证 auth session，并使用 cookies().get('next-auth.session-token') 或 Next-Auth 提供的 getServerSession 进行身份确认。
4、对静态内容（如博客文章列表），在服务器组件中设置 revalidate: 300（5 分钟），平衡新鲜度与数据库负载；对实时性要求高的操作（如点赞计数），使用 Server Action 触发后端写入，并通过 redirect 或 revalidateTag 主动刷新缓存。
四、环境隔离与部署配置
开发、预发布与生产环境必须使用完全独立的 PostgreSQL 实例，数据库连接字符串、密钥、认证提供者配置等敏感信息严禁硬编码，全部通过环境变量注入，并在构建时进行校验。
1、在 .env.local 中定义开发环境变量，如 DATABASE_URL、NEXTAUTH_SECRET；该文件不提交至 Git，由团队共享一份 .env.example 模板。
2、在 Vercel 部署时，在 Project Settings → Environment Variables 中配置生产环境变量；Vercel Postgres 自动注入 POSTGRES_URL，需在 prisma/schema.prisma 中将其映射为 DATABASE_URL，保持配置一致性。
3、在 prisma/schema.prisma 的 generator client 块中启用 previewFeatures = ["driverAdapters"]，配合 @prisma/adapter-pg 实现与 pg 驱动的深度集成，提升连接稳定性与类型推导精度。
4、为防止环境误用，在 lib/prisma.ts 初始化客户端前加入断言：if (!process.env.DATABASE_URL) throw new Error("DATABASE_URL is missing")，确保启动失败早于运行时数据库错误。
五、类型安全与错误处理纵深防御
类型安全不能仅依赖 TypeScript 编译时检查，必须贯穿请求解析、数据库交互、响应序列化全流程。错误处理需区分客户端可恢复错误（如表单校验失败）与服务端不可恢复错误（如数据库连接中断），并提供对应反馈路径。
1、在 API 路由中，使用 Zod 对 Request.json() 解析结果进行运行时校验，失败时返回 400 Bad Request 及具体字段错误信息，而非让 Prisma 抛出模糊的 P2002 错误。
2、Prisma 查询结果默认为 Partial 类型，对必填字段（如 user.name）使用 select 显式投影，或在服务层用 z.infer 断言返回结构，避免空值穿透至 UI 层引发渲染异常。
3、所有数据库写入操作（create、update、delete）均包裹在 prisma.$transaction 中，即使单语句操作也启用事务，确保原子性与一致性。
4、在服务器组件中捕获 Prisma 异常，对 Prisma.PrismaClientKnownRequestError 分类处理：P2002（唯一约束冲突）转为用户友好的提示；P2025（记录未找到）返回 notFound()；其他未知错误记录日志并抛出通用错误页面。
