Next.js 企业级应用架构方案

src/
├── app/                   (App Router 核心目录)
│   ├── layout.tsx         # 根布局（持久化 UI 骨架）
│   ├── page.tsx           # 首页 (/)
│   ├── globals.css        # 全局样式
│   ├── (auth)/            # 路由分组（不影响 URL）
│   │   ├── login/page.tsx
│   │   └── register/page.tsx
│   ├── dashboard/
│   │   ├── layout.tsx     # 嵌套布局
│   │   ├── page.tsx       # /dashboard
│   │   └── [id]/page.tsx  # /dashboard/[id] 动态路由
│   └── api/               # Route Handlers (替代 Pages Router API)
│       └── posts/route.ts
├── components/            (公共组件库)
├── lib/                   (工具函数、数据库连接等)
├── hooks/                 (客户端自定义 Hooks)
├── types/                 (TypeScript 类型定义)
└── middleware.ts          (边缘中间件)

// Server Component（默认）— 可直接访问数据库
async function ProductList() {
  const products = await db.product.findMany(); // 服务端直接查询
  return <ul>{products.map(p => <li key={p.id}>{p.name}</li>)}</ul>;
}
 
// Client Component — 需要交互
'use client';
function AddToCartButton({ productId }: { productId: string }) {
  return <button onClick={() => addToCart(productId)}>加入购物车</button>;
}

// 静态缓存（SSG 行为）
const data = await fetch('https://api.example.com/posts', {
  cache: 'force-cache'
});
 
// 不缓存（SSR 行为，每次请求重新获取）
const data = await fetch('https://api.example.com/user', {
  cache: 'no-store'
});
 
// ISR：60 秒后重新验证
const data = await fetch('https://api.example.com/products', {
  next: { revalidate: 60 }
});

// app/api/posts/route.ts
import { NextRequest, NextResponse } from 'next/server';
 
export async function GET(request: NextRequest) {
  const posts = await db.post.findMany();
  return NextResponse.json(posts);
}
 
export async function POST(request: NextRequest) {
  const body = await request.json();
  const post = await db.post.create({ data: body });
  return NextResponse.json(post, { status: 201 });
}

// app/actions/post.ts
'use server';
 
export async function createPost(formData: FormData) {
  const title = formData.get('title') as string;
  await db.post.create({ data: { title } });
  revalidatePath('/posts');
}
 
// 在客户端表单中使用
<form action={createPost}>
  <input name="title" />
  <button type="submit">提交</button>
</form>

// middleware.ts — 保护 /dashboard 路径
import { auth } from '@/auth';
 
export default auth((req) => {
  if (!req.auth && req.nextUrl.pathname.startsWith('/dashboard')) {
    return Response.redirect(new URL('/login', req.url));
  }
});
 
export const config = { matcher: ['/dashboard/:path*'] };

// prisma/schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}
 
generator client {
  provider = "prisma-client-js"
}
 
model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  posts     Post[]
}
 
model Post {
  id        String   @id @default(cuid())
  title     String
  content   String?
  published Boolean  @default(false)
  authorId  String
  author    User     @relation(fields: [authorId], references: [id])
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

# 开发阶段：创建并应用迁移
npx prisma migrate dev --name add_post_table
 
# 生产部署：只执行已有迁移（不创建新迁移）
npx prisma migrate deploy
 
# 重置开发数据库（慎用）
npx prisma migrate reset
 
# 打开可视化管理界面
npx prisma studio

// lib/prisma.ts
import { PrismaClient } from '@prisma/client';
 
const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
 
export const db =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: process.env.NODE_ENV === 'development' ? ['query', 'error'] : ['error'],
  });
 
if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = db;

import { db } from '@/lib/prisma';
 
// 关联查询（include）
const user = await db.user.findUnique({
  where: { id: userId },
  include: { posts: { where: { published: true }, orderBy: { createdAt: 'desc' } } },
});
 
// 分页查询
const posts = await db.post.findMany({
  skip: (page - 1) * pageSize,
  take: pageSize,
  orderBy: { createdAt: 'desc' },
});
 
// 事务（保证原子性）
const [user, post] = await db.$transaction([
  db.user.update({ where: { id }, data: { name: 'New Name' } }),
  db.post.create({ data: { title: 'Hello', authorId: id } }),
]);
 
// 聚合查询
const stats = await db.post.aggregate({
  _count: { id: true },
  _max: { createdAt: true },
  where: { published: true },
});

// lib/validations/post.ts
import { z } from 'zod';
 
export const createPostSchema = z.object({
  title: z.string().min(1, '标题不能为空').max(100),
  content: z.string().optional(),
  published: z.boolean().default(false),
});
 
export type CreatePostInput = z.infer<typeof createPostSchema>;

// app/api/posts/route.ts
import { createPostSchema } from '@/lib/validations/post';
 
export async function POST(request: NextRequest) {
  const body = await request.json();
  const result = createPostSchema.safeParse(body);
 
  if (!result.success) {
    return NextResponse.json({ errors: result.error.flatten() }, { status: 400 });
  }
 
  const post = await db.post.create({ data: result.data });
  return NextResponse.json(post, { status: 201 });
}

// lib/errors.ts
export class AppError extends Error {
  constructor(
    public message: string,
    public statusCode: number = 500,
    public code?: string
  ) {
    super(message);
  }
}
 
// Route Handler 中统一捕获
export function withErrorHandler(
  handler: (req: NextRequest) => Promise<NextResponse>
) {
  return async (req: NextRequest) => {
    try {
      return await handler(req);
    } catch (error) {
      if (error instanceof AppError) {
        return NextResponse.json(
          { message: error.message, code: error.code },
          { status: error.statusCode }
        );
      }
      console.error(error);
      return NextResponse.json({ message: '服务器内部错误' }, { status: 500 });
    }
  };
}

// lib/services/post.service.ts
import { db } from '@/lib/prisma';
import { AppError } from '@/lib/errors';
import type { CreatePostInput } from '@/lib/validations/post';
 
export async function createPost(data: CreatePostInput, authorId: string) {
  return db.post.create({ data: { ...data, authorId } });
}
 
export async function getPostById(id: string) {
  const post = await db.post.findUnique({ where: { id } });
  if (!post) throw new AppError('文章不存在', 404, 'POST_NOT_FOUND');
  return post;
}
 
export async function getPublishedPosts(page = 1, pageSize = 10) {
  const [posts, total] = await db.$transaction([
    db.post.findMany({
      where: { published: true },
      skip: (page - 1) * pageSize,
      take: pageSize,
      orderBy: { createdAt: 'desc' },
    }),
    db.post.count({ where: { published: true } }),
  ]);
  return { posts, total, page, pageSize };
}

App Router 入口
├── RootLayout              (根布局：字体、全局样式)
│   ├── Providers           (客户端：Auth Session + Zustand + Query Client)
│   │   └── (auth)/         (路由分组：无 Layout 包裹)
│   │       └── login/page  (登录页)
│   └── (app)/              (路由分组：需鉴权)
│       └── dashboard/
│           ├── layout      (Dashboard 布局：Sidebar + Header)
│           └── page        (Server Component：直接查询数据库)
│               └── DataTable (Client Component：交互与分页)
└── api/                    (Route Handlers：第三方回调、Webhook)