Next.js: App Router 文件系统路由

src/app/
├── page.tsx                    # → /
├── about/
│   └── page.tsx                # → /about
├── products/
│   ├── page.tsx                # → /products
│   └── [id]/
│       ├── page.tsx            # → /products/1, /products/2
│       └── reviews/
│           └── page.tsx        # → /products/1/reviews
└── api/
    └── products/
        └── route.ts            # → /api/products (GET/POST)

// ============================================
// 创建 /about 页面
// 文件：src/app/about/page.tsx
// 只需创建文件，路由自动注册
// ============================================

export default function AboutPage() {
  return (
    <div className="max-w-2xl mx-auto p-8">
      <h1 className="text-3xl font-bold">About TaskFlow</h1>
      <p className="mt-4 text-gray-600 leading-relaxed">
        TaskFlow is a collaborative project management platform that helps
        teams plan, track, and deliver projects efficiently. Built with
        Next.js 16 and React 19, it provides real-time updates, seamless
        collaboration, and enterprise-grade security.
      </p>
      <div className="mt-8 grid grid-cols-3 gap-4">
        <div className="p-4 bg-blue-50 rounded-lg text-center">
          <div className="text-2xl font-bold text-blue-600">10K+</div>
          <div className="text-sm text-gray-500">Active Users</div>
        </div>
        <div className="p-4 bg-green-50 rounded-lg text-center">
          <div className="text-2xl font-bold text-green-600">50K+</div>
          <div className="text-sm text-gray-500">Projects</div>
        </div>
        <div className="p-4 bg-purple-50 rounded-lg text-center">
          <div className="text-2xl font-bold text-purple-600">99.9%</div>
          <div className="text-sm text-gray-500">Uptime</div>
        </div>
      </div>
    </div>
  );
}

访问 http://localhost:3000/about 看到：
About TaskFlow
TaskFlow is a collaborative project management platform...
10K+  Active Users | 50K+  Projects | 99.9%  Uptime

// ============================================
// 商品详情页 — 动态路由 [id]
// 文件：src/app/products/[id]/page.tsx
// ============================================

// Next.js 16 中 params 是 Promise（异步）
export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const product = await fetch(`https://fakestoreapi.com/products/${id}`);

  return (
    <div className="container mx-auto p-8">
      <div className="flex gap-8">
        <img
          src={product.image}
          alt={product.title}
          className="w-80 h-80 object-contain"
        />
        <div>
          <h1 className="text-2xl font-bold">{product.title}</h1>
          <p className="text-xl text-green-600 font-bold mt-2">
            ${product.price}
          </p>
          <p className="text-sm text-gray-500 mt-1">
            Category: {product.category}
          </p>
          <p className="mt-4 text-gray-700">{product.description}</p>
        </div>
      </div>
    </div>
  );
}

访问 /products/1 看到：
Fjallraven - Foldsack No. 1 Backpack
$109.95
Category: men's clothing
Your perfect pack for day trips and hikes...

// ============================================
// Catch-all 路由 — 多级文档页面
// 文件：src/app/docs/[...slug]/page.tsx
// ============================================

export default async function DocsPage({
  params,
}: {
  params: Promise<{ slug: string[] }>;
}) {
  const { slug } = await params;

  return (
    <div className="container mx-auto p-8">
      <nav className="text-sm text-gray-500 mb-4">
        Home / Docs / {slug.join(" / ")}
      </nav>
      <h1 className="text-3xl font-bold">Docs: {slug.join(" > ")}</h1>
      <div className="mt-8 p-6 bg-yellow-50 border border-yellow-200 rounded-lg">
        <p className="font-medium">You are viewing documentation for:</p>
        <ul className="mt-2 list-disc list-inside">
          {slug.map((segment, index) => (
            <li key={index}>
              Level {index + 1}: <code className="bg-gray-100 px-2 py-0.5 rounded">{segment}</code>
            </li>
          ))}
        </ul>
      </div>
      <p className="mt-4 text-gray-600">
        Total depth: {slug.length} levels
      </p>
    </div>
  );
}

访问 /docs/getting-started/installation 看到：
Home / Docs / getting-started / installation
Docs: getting-started > installation

You are viewing documentation for:
  - Level 1: getting-started
  - Level 2: installation
Total depth: 2 levels

// ============================================
// 可选 Catch-all — 分类浏览页面
// 文件：src/app/categories/[[...categories]]/page.tsx
// /categories 和 /categories/electronics 都生效
// ============================================

export default async function CategoriesPage({
  params,
}: {
  params: Promise<{ categories?: string[] }>;
}) {
  const { categories } = await params;

  const allProducts = await fetch("https://fakestoreapi.com/products");
  const categoriesList = [...new Set(allProducts.map(p => p.category))];

  const filteredProducts = categories
    ? allProducts.filter(p => p.category === categories[0])
    : allProducts;

  return (
    <div className="container mx-auto p-8">
      <h1 className="text-3xl font-bold mb-6">
        {categories ? `Category: ${categories[0]}` : "All Categories"}
      </h1>

      {!categories && (
        <div className="flex gap-2 mb-8 flex-wrap">
          {categoriesList.map(cat => (
            <a
              key={cat}
              href={`/categories/${encodeURIComponent(cat)}`}
              className="px-4 py-2 bg-gray-100 rounded-full hover:bg-blue-100"
            >
              {cat}
            </a>
          ))}
        </div>
      )}

      <div className="grid grid-cols-4 gap-6">
        {filteredProducts.slice(0, 8).map(p => (
          <div key={p.id} className="border rounded-lg p-4 hover:shadow-lg">
            <img src={p.image} alt={p.title} className="h-40 mx-auto" />
            <p className="mt-2 font-medium text-sm truncate">{p.title}</p>
            <p className="text-green-600 font-bold">${p.price}</p>
          </div>
        ))}
      </div>
    </div>
  );
}

访问 /categories 看到：
所有分类按钮（electronics, jewelery, men's clothing, women's clothing）

访问 /categories/electronics 看到：
Category: electronics
只显示电子产品（8个商品卡片）

// ============================================
// 加载骨架屏 — 页面数据获取时显示
// 文件：src/app/products/loading.tsx
// ============================================

export default function ProductsLoading() {
  return (
    <div className="container mx-auto p-8">
      <div className="h-8 w-48 bg-gray-200 rounded animate-pulse mb-6" />
      <div className="grid grid-cols-4 gap-6">
        {Array.from({ length: 8 }).map((_, i) => (
          <div key={i} className="border rounded-lg p-4">
            <div className="h-40 bg-gray-200 rounded animate-pulse" />
            <div className="h-4 bg-gray-200 rounded mt-2 animate-pulse" />
            <div className="h-4 w-16 bg-gray-200 rounded mt-2 animate-pulse" />
          </div>
        ))}
      </div>
    </div>
  );
}

访问 /products 时，数据加载完成前显示：
8 个灰色占位卡片（带脉冲动画）
数据加载完成后，骨架屏自动替换为实际内容
无闪烁、无白屏，过渡平滑

// ============================================
// 错误边界 — 捕获子组件错误
// 文件：src/app/products/error.tsx
// ============================================

'use client';

export default function ProductsError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div className="container mx-auto p-8 text-center">
      <div className="max-w-md mx-auto">
        <h2 className="text-2xl font-bold text-red-600 mb-4">
          Something went wrong!
        </h2>
        <p className="text-gray-600 mb-6">
          {error.message || "Failed to load products. Please try again."}
        </p>
        <button
          onClick={reset}
          className="px-6 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
        >
          Try Again
        </button>
      </div>
    </div>
  );
}

当产品页面数据获取失败时，显示：
Something went wrong!
Failed to load products. Please try again.
[Try Again] 按钮 → 点击自动重试

// ============================================
// 404 页面 — 路由不存在时显示
// 文件：src/app/not-found.tsx
// ============================================

import Link from "next/link";

export default function NotFound() {
  return (
    <div className="min-h-screen flex items-center justify-center">
      <div className="text-center">
        <h1 className="text-6xl font-bold text-gray-300">404</h1>
        <h2 className="text-2xl font-bold mt-4">Page Not Found</h2>
        <p className="text-gray-500 mt-2">
          The page you are looking for does not exist.
        </p>
        <Link
          href="/"
          className="inline-block mt-6 px-6 py-2 bg-blue-600 text-white rounded-lg"
        >
          Go Home
        </Link>
      </div>
    </div>
  );
}

访问不存在的 URL（如 /xyz），浏览器显示：
404
Page Not Found
The page you are looking for does not exist.
[Go Home] 链接

// ============================================
// Route Handler — 产品 CRUD API
// 文件：src/app/api/products/route.ts
// ============================================

// 模拟数据库
const products = [
  { id: 1, name: "Wireless Mouse", price: 29.99 },
  { id: 2, name: "Mechanical Keyboard", price: 89.99 },
];

// GET /api/products — 获取产品列表
export async function GET() {
  return Response.json(products);
}

// POST /api/products — 创建新产品
export async function POST(request: Request) {
  const body = await request.json();

  if (!body.name || !body.price) {
    return Response.json(
      { error: "Name and price are required" },
      { status: 400 }
    );
  }

  const newProduct = {
    id: products.length + 1,
    name: body.name,
    price: body.price,
  };
  products.push(newProduct);

  return Response.json(newProduct, { status: 201 });
}

// ============================================
// 单个产品的 API
// 文件：src/app/api/products/[id]/route.ts
// ============================================

export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const product = products.find(p => p.id === Number(id));

  if (!product) {
    return Response.json(
      { error: "Product not found" },
      { status: 404 }
    );
  }

  return Response.json(product);
}

export async function DELETE(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const index = products.findIndex(p => p.id === Number(id));

  if (index === -1) {
    return Response.json(
      { error: "Product not found" },
      { status: 404 }
    );
  }

  products.splice(index, 1);
  return Response.json({ message: "Product deleted" });
}

测试 API：

GET  http://localhost:3000/api/products
→ [{"id":1,"name":"Wireless Mouse","price":29.99},...]

POST http://localhost:3000/api/products
Body: {"name":"USB Hub","price":19.99}
→ {"id":3,"name":"USB Hub","price":19.99} (201)

GET  http://localhost:3000/api/products/1
→ {"id":1,"name":"Wireless Mouse","price":29.99}

DELETE http://localhost:3000/api/products/1
→ {"message":"Product deleted"} (200)

// ============================================
// 综合示例：电商商品浏览系统
// 涵盖页面、布局、加载、错误、API 路由
// ============================================

// src/app/layout.tsx — 根布局
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className="bg-gray-50">
        <nav className="bg-white shadow-sm p-4">
          <a href="/" className="text-xl font-bold text-blue-600">
            ShopHub
          </a>
        </nav>
        <main>{children}</main>
      </body>
    </html>
  );
}

// src/app/page.tsx — 首页
export default function HomePage() {
  return (
    <div className="container mx-auto p-8 text-center">
      <h1 className="text-4xl font-bold">Welcome to ShopHub</h1>
      <p className="mt-4 text-gray-600">
        Browse our collection of amazing products.
      </p>
      <a
        href="/products"
        className="inline-block mt-6 px-8 py-3 bg-blue-600 text-white rounded-lg"
      >
        Browse Products
      </a>
    </div>
  );
}

// src/app/products/page.tsx — 产品列表
export default async function ProductsPage() {
  const products = await fetch(
    "https://fakestoreapi.com/products"
  );

  return (
    <div className="container mx-auto p-8">
      <h1 className="text-3xl font-bold mb-6">All Products</h1>
      <div className="grid grid-cols-4 gap-6">
        {products.map(p => (
          <a
            key={p.id}
            href={`/products/${p.id}`}
            className="border rounded-lg p-4 bg-white hover:shadow-lg"
          >
            <img
              src={p.image}
              alt={p.title}
              className="h-40 mx-auto"
            />
            <p className="mt-2 font-medium text-sm">{p.title}</p>
            <p className="text-green-600 font-bold mt-1">${p.price}</p>
          </a>
        ))}
      </div>
    </div>
  );
}

// src/app/products/[id]/page.tsx — 产品详情
export default async function ProductDetailPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const product = await fetch(
    `https://fakestoreapi.com/products/${id}`
  );

  if (!product) {
    notFound();
  }

  return (
    <div className="container mx-auto p-8">
      <a
        href="/products"
        className="text-blue-600 hover:underline mb-4 inline-block"
      >
        &larr; Back to products
      </a>
      <div className="flex gap-8 bg-white p-8 rounded-lg shadow">
        <img
          src={product.image}
          alt={product.title}
          className="w-96 h-96 object-contain"
        />
        <div>
          <h1 className="text-3xl font-bold">{product.title}</h1>
          <p className="text-2xl text-green-600 font-bold mt-4">
            ${product.price}
          </p>
          <p className="mt-6 text-gray-700 leading-relaxed">
            {product.description}
          </p>
          <button className="mt-6 px-8 py-3 bg-blue-600 text-white rounded-lg">
            Add to Cart
          </button>
        </div>
      </div>
    </div>
  );
}

// src/app/products/loading.tsx — 加载骨架屏
export default function ProductsLoading() {
  return (
    <div className="container mx-auto p-8">
      <div className="h-8 w-48 bg-gray-200 rounded animate-pulse mb-6" />
      <div className="grid grid-cols-4 gap-6">
        {Array.from({ length: 8 }).map((_, i) => (
          <div key={i} className="border rounded-lg p-4 bg-white">
            <div className="h-40 bg-gray-200 rounded animate-pulse" />
            <div className="h-4 bg-gray-200 rounded mt-2 animate-pulse" />
            <div className="h-4 w-16 bg-gray-200 rounded mt-2 animate-pulse" />
          </div>
        ))}
      </div>
    </div>
  );
}

// src/app/products/error.tsx — 错误边界
'use client';
export default function ProductsError({
  error,
  reset,
}: {
  error: Error;
  reset: () => void;
}) {
  return (
    <div className="container mx-auto p-8 text-center">
      <h2 className="text-2xl font-bold text-red-600">
        Failed to load products
      </h2>
      <button
        onClick={reset}
        className="mt-4 px-6 py-2 bg-blue-600 text-white rounded-lg"
      >
        Try Again
      </button>
    </div>
  );
}

首页（/）：
  Welcome to ShopHub → [Browse Products]

产品列表（/products）：
  加载中 → 8 个灰色骨架屏
  加载完成 → 产品卡片网格（含图片、标题、价格）

产品详情（/products/1）：
  商品图片（左）+ 标题/价格/描述/Add to Cart（右）
  ← Back to products 链接返回列表

错误状态：
  Failed to load products
  [Try Again] 按钮

404 状态：
  自动由根 not-found.tsx 处理