nextjs-16-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Next.js 16 Architecture

Next.js 16 架构

Architecture patterns for Next.js 16 with Cache Components and feature-based organization.

适用于 Next.js 16、结合 Cache Components 与基于 feature 组织的架构模式。

Core Philosophy

核心理念

Dynamic by default, cache what you choose - Use
```
"use cache"
```
explicitly
Fetch in smallest possible component - Don't prop-drill data
Keep everything static, stream only dynamic - Use Suspense for dynamic parts
Suspense boundaries high - Place in pages/layouts, not feature components

默认动态，按需缓存 - 显式使用
```
"use cache"
```
在尽可能小的组件中获取数据 - 不要对数据进行 prop drilling
让所有内容保持静态，仅对动态部分使用 streaming - 使用 Suspense 处理动态部分
将 Suspense 边界放在较高层级 - 放在 pages/layouts 中，而不是 feature components 中

Quick Reference

快速参考

Feature Folder Structure

Feature 文件夹结构

features/{feature}/
├── components/
│   ├── server/       # Async data-fetching components
│   ├── client/       # 'use client' interactive components
│   └── skeletons/    # Loading states for Suspense
├── data/             # Database queries (SELECT, INSERT, UPDATE, DELETE)
├── actions/          # Server Actions ('use server' + cache invalidation)
├── types/            # TypeScript types (1 file = 1 type)
├── schemas/          # Zod schemas (1 file = 1 schema)
├── hooks/            # Client-side hooks
└── lib/              # Feature-specific utilities

features/{feature}/
├── components/
│   ├── server/       # Async data-fetching components
│   ├── client/       # 'use client' interactive components
│   └── skeletons/    # Loading states for Suspense
├── data/             # Database queries (SELECT, INSERT, UPDATE, DELETE)
├── actions/          # Server Actions ('use server' + cache invalidation)
├── types/            # TypeScript types (1 file = 1 type)
├── schemas/          # Zod schemas (1 file = 1 schema)
├── hooks/            # Client-side hooks
└── lib/              # Feature-specific utilities

File Naming

文件命名

Type	Pattern	Example
Server component	`kebab-case.tsx`	`agent-header.tsx`
Client component	`kebab-case.tsx`	`login-form.tsx`
Skeleton	`{name}-skeleton.tsx`	`agent-header-skeleton.tsx`
GET query	`get-{entity}.ts`	`get-agent.ts`
GET multiple	`get-{entities}.ts`	`get-agents.ts`
CREATE	`create-{entity}.ts`	`create-agent.ts`
DELETE	`delete-{entity}.ts`	`delete-agent.ts`
Server Action	`{verb}-{entity}-action.ts`	`delete-agent-action.ts`

类型	模式	示例
Server Component	`kebab-case.tsx`	`agent-header.tsx`
Client Component	`kebab-case.tsx`	`login-form.tsx`
Skeleton	`{name}-skeleton.tsx`	`agent-header-skeleton.tsx`
GET 查询	`get-{entity}.ts`	`get-agent.ts`
多个 GET 查询	`get-{entities}.ts`	`get-agents.ts`
CREATE	`create-{entity}.ts`	`create-agent.ts`
DELETE	`delete-{entity}.ts`	`delete-agent.ts`
Server Action	`{verb}-{entity}-action.ts`	`delete-agent-action.ts`

Cache Pattern

缓存模式

typescript

// Data file (SELECT with cache)
export async function getEntity(id: number) {
  "use cache";
  cacheTag(`entity-${id}`);
  cacheLife("hours");
  return await db.select()...
}

// Server Action (mutation + invalidation)
"use server";
export async function deleteEntityAction(id: number) {
  await deleteEntity(id);
  updateTag(`entity-${id}`);
}

typescript

// Data file (SELECT with cache)
export async function getEntity(id: number) {
  "use cache";
  cacheTag(`entity-${id}`);
  cacheLife("hours");
  return await db.select()...
}

// Server Action (mutation + invalidation)
"use server";
export async function deleteEntityAction(id: number) {
  await deleteEntity(id);
  updateTag(`entity-${id}`);
}

Import Rules

导入规则

Always absolute:
```
@/features/...
```
Never relative:
```
../../../
```
Direction:
```
app/
```
→
```
features/
```
→
```
shared/
```

始终使用绝对路径：
```
@/features/...
```
绝不使用相对路径：
```
../../../
```
依赖方向：
```
app/
```
→
```
features/
```
→
```
shared/
```

References

参考资料

Load these based on what you need:

Feature Structure - Complete feature organization, anatomy, rules
Components - Server, Client, Skeletons, Compound UI patterns
Data Layer - Cacheable queries, mutations, session handling
Server Actions - Actions, cache invalidation, auth patterns
Pages & Layouts - App router structure, route groups
Internationalization - next-intl setup, flat keys, translations
Shared Feature - Cross-cutting concerns, UI components
Checklists - Code review and new feature checklists

根据实际需要加载以下内容：

Feature 结构 - 完整的 feature 组织方式、结构说明和规则
组件 - Server Component、Client Component、Skeleton 和复合 UI 模式
数据层 - 可缓存查询、变更操作和 session 处理
Server Actions - Actions、缓存失效和 auth 模式
Pages 与 Layouts - App Router 结构和 route groups
国际化 - next-intl 配置、扁平化 keys 和翻译
共享 Feature - 跨领域关注点和 UI 组件
检查清单 - 代码审查与新功能开发检查清单