nextjs-architecture

@architecture-rules.md @rules/project-structure.md @rules/services.md @rules/hooks.md @rules/db.md @rules/routes.md @rules/execution-model.md @rules/data-fetching.md @rules/server-actions.md @rules/route-handlers.md @rules/platform.md @rules/validation.md @references/official/nextjs-docs.md @references/official/current-docs-2026-06-02.md @references/official/drizzle-docs.md

Next.js 架构规范

<output_language>

默认使用韩语撰写所有面向用户的交付物、保存的产物、报告、计划、生成的文档、摘要、交接说明、提交信息草稿和验证说明，即使此规范文件以英语撰写。

保留源代码标识符、CLI 命令、文件路径、架构键、JSON/YAML 字段名称、API 名称、包名称、专有名词以及引用的源文摘录，并保持其所需或原有的语言。

只有在用户明确要求、现有目标产物必须为保持一致性而使用其他语言，或机器可读契约要求使用精确的英语词元时，才使用其他语言。如果存在本地化模板或参考资料（例如 *.ko.md 或 *.ko.json），优先使用它们来创建面向用户的产物。

</output_language>

• 确认仓库是否为 Next.js 项目，并在应用架构规范前识别其使用 App Router、Pages Router 还是混合模式。
• 强制遵循 Next.js 官方关于文件约定、Server/Client Component 边界、数据/缓存行为、Server Actions、Route Handlers、Proxy 以及环境变量/平台安全性的行为规范。
• 应用 Hypercore/仓库本地约定来组织嵌套共享文件夹，例如 src/modules/<domain>/、src/services/<domain>/、src/db/<area>/、src/server/<area>/、src/integrations/<provider>/ 和 src/config/<area>/，但不要将这些约定说成 Next.js 官方规则。
• 将 Drizzle、DAL/服务边界以及客户端 Hook 编排方面的内容引导至相应的专门规则文件，避免本入口文件过于臃肿。
• 将依赖版本的官方信息保存在 references/official/ 中，使核心规范保持精简，并能独立更新为当前文档。

<routing_rule>

在现有 Next.js 项目中执行架构规范、提供实现指导或进行审查时使用此规范，尤其适用于 App Router 工作、迁移到 App Router、Server/Client 边界、缓存/数据新鲜度、Server Actions、Route Handlers、Proxy、环境变量/平台安全性、服务/DAL 边界、客户端 Hook 编排、Drizzle/数据库放置位置以及嵌套共享文件夹组织。

不要将此规范用于通用 React 架构、Remix/TanStack Start 项目、仅涉及文档的摘要，或不涉及架构边界且只需快速安全检查的纯文案修改。在仅使用 Pages Router 的项目中，应用通用的 Next.js 安全性/平台检查，但除非用户要求迁移，否则不要强制采用仅适用于 App Router 的文件约定。

</routing_rule>

<instruction_contract>

字段	约定
意图	保障 Next.js 项目的架构安全，并使其符合官方文档及已标注的 Hypercore／仓库本地约定。
触发条件	涉及 App Router、Pages Router、Server／Client 边界、数据／缓存行为、Server Actions、Route Handlers、Proxy、平台／环境变量或共享目录布局的 Next.js 项目工作。
范围	审查并指导受影响的项目架构、主题规则文件、官方参考资料、验证说明，以及小范围、可逆的架构修复。
权限依据	用户／项目指令优先于此技能。当前官方 Next.js 文档优先于本地约定，作为框架行为的依据。安全策略禁止存在风险的运行时、身份验证、密钥和导入边界变更。
证据	使用本地包／配置／路由指示、受影响的源文件路径、主题规则、官方参考资料、验证脚本和项目检查输出。
工具	使用本地搜索／读取／编辑／验证命令；当 API 可能发生变化时，查阅当前官方文档；对破坏性迁移、凭据、生产环境副作用和大范围 codemod 进行把关。
循环	无。此技能每个请求仅执行一轮检查，只有用户要求再次检查时才会重新运行。
输出	以韩语给出架构决策或审查结果，说明规则分类、变更文件（如有）、验证证据、剩余风险，以及附日期的官方文档歧义说明。
验证	运行 rules/validation.md 中与受影响部分相关的检查；如果此技能目录发生变更，则运行 bash scripts/validate-nextjs-architecture-skill.sh。
停止条件	确认项目模式、通过适用的安全检查、应用或暂缓本地约定、记录验证证据，并为尚未解决的 API 变化注明日期和出处后停止。

</instruction_contract>

概述

在代码变更前后执行官方 Next.js 架构规则。首先确认目标是否为 Next.js 项目，并识别其使用 App Router、Pages Router，还是两者兼用。然后针对路由、Server 和 Client Component 边界、数据／缓存行为、Server Actions、Route Handlers、Proxy 和平台配置，应用最小范围的相关规则。

官方优先规则： 当前 Next.js 文档是框架行为的事实依据。如果仓库本地约定比 Next.js 更严格，应将其标注为本地约定，而非框架规则。

App Router 默认规则： 对 app/ 和 src/app/ 中的工作进行全面检查。对于仅使用 Pages Router 的项目，应用通用的 Next.js 平台、环境变量和边界检查；除非用户正在迁移，否则不要强制要求仅适用于 App Router 的文件约定。

变更默认规则： 对于源自 App Router UI 的写入操作，优先使用 Server Actions。对于 webhook、信息流、CORS 端点、公开的机器可读端点和非 UI 响应等 HTTP 原生契约，使用 Route Handlers。

安全默认规则： 将每个 Server Action 都视为可访问的 POST 入口。在 action 内部或委托的仅限服务端的层中验证输入、进行身份验证、授权，并精简返回值。

快速选择适用界面

如果任务是……	默认界面	默认避免
在 App Router 中添加表单或内部 UI 修改	Server Action	route.ts RPC
添加 webhook、feed、CORS 端点、公共 API、XML、JSON 或流	Route Handler	Server Action
获取 UI 的初始页面数据	Server Component	以客户端为先的数据获取
添加交互、浏览器 API 或客户端钩子	精简的 Client Component	根级 'use client'
围绕 Server Action 添加客户端编排	调用该 action 的客户端钩子	导入 DB/DAL/仅服务端代码的钩子
添加领域逻辑、提供方调用或授权	仅服务端的服务/DAL 层	由路由文件或 Client Component 负责
添加 Drizzle schema、迁移、存储库或 DB 客户端	rules/db.md + 仅服务端的 src/db 约定	客户端钩子或 Route Handler 请求生命周期
在 Next.js 16+ 中缓存可重复使用的数据/UI	cacheComponents + use cache / cacheTag / cacheLife	过时的 fetch 默认行为假设
在修改后刷新 UI	updateTag、revalidateTag、revalidatePath、refresh 或重定向流程	未记录的时效性
在大量请求中于渲染前重定向/重写	优先使用 next.config.*，必要时再使用 Proxy	将 Proxy 用作通用中间件
仅使用 Pages Router 且不要求迁移	通用 Next.js 检查	仅适用于 App Router 的文件规则

<activation_examples>

正向示例：

• “审查此 Next.js App Router 功能的 Server/Client 边界和缓存正确性。”
• “重构此表单，使用 Server Actions 替代内部 Route Handler。”
• “为 webhook 添加 Route Handler，并确认其遵循当前 Next.js 文档。”
• “按 Next.js 16 的 cacheComponents 基准检查数据获取规则。”
• “在 Next.js App Router 中，像 src/lib/auth/session.ts 和 src/services/billing/mutations.ts 这样整理嵌套的共享文件夹。”
• “在此 Next.js 应用中添加 Drizzle schema 和迁移，同时避免 DB 访问泄漏到客户端钩子中。”
• “将此 Next.js 表单拆分为客户端钩子、Server Actions 和仅服务端的服务/DAL。”

负向示例：

• “创建一份通用 React 架构指南。”
• “审查一个 Remix 或 TanStack Start 应用。”
• “为 Next.js 落地页撰写营销文案，不涉及架构。”

边界示例：

• “对 Next.js 页面做一处微小的纯文案修改。” 如果不影响任何架构边界，直接编辑即可，但仍需快速检查所改文件的边界。
• “此代码库仅使用 Pages Router，我不会迁移到 App Router。” 应用通用的 Next.js 平台、环境和服务端/客户端安全检查；放宽仅适用于 App Router 的文件约定。

</activation_examples>

步骤 1：项目验证

进行架构工作前，先确认项目和路由模式：

rg -n '"next"' package.json
find . -maxdepth 3 \( -path './app' -o -path './src/app' -o -path './pages' -o -path './src/pages' \)
test -f next.config.ts -o -f next.config.mjs -o -f next.config.js

说明：

• 没有 next 依赖：停止；此技能不适用。
• 存在 app/ 或 src/app/：App Router 模式。
• 存在 pages/ 或 src/pages/，且没有 App Router：通用 Next.js 模式。
• 同时存在 app/ 和 pages/：对所修改的 app/ 代码执行 App Router 规则；除非用户提出要求，否则避免迁移旧代码。

步骤 2：阅读最小相关规则集

必须首先阅读： architecture-rules.md。

然后仅加载与所改动部分相关的规则文件：

• rules/routes.md — 文件约定、路由段规则、路由组、私有文件夹、并行路由／拦截路由注意事项
• rules/project-structure.md — 项目顶层结构、src/、共享代码的放置位置、嵌套的 src/modules、src/services、src/db、src/server、src/integrations、src/config、仓库本地组织约定
• rules/services.md — DAL／服务／提供方边界、DTO、授权委托、仅服务端辅助函数拆分
• rules/hooks.md — 客户端 Hook 编排边界，以及 Hook 不得跨越的服务端／数据层
• rules/db.md — Drizzle schema／配置／迁移、连接生命周期、关系／RQB、验证集成、仅服务端 DB 的放置位置
• rules/execution-model.md — 服务端／客户端组件、'use client'、提供方、可序列化属性、server-only／client-only
• rules/data-fetching.md — 服务端优先读取、流式传输、Cache Components、use cache／use cache: remote／use cache: private、缓存标签、重新验证、动态渲染
• rules/server-actions.md — use server、表单、验证、身份验证／授权、DAL 委托、updateTag／重新验证／重定向顺序
• rules/route-handlers.md — route.ts、HTTP 方法、缓存意图、参数、非 UI 响应、CORS／Webhook
• rules/platform.md — 环境、next.config.*、typedRoutes、Proxy、路由段配置、部署敏感设置

对于容易发生变更的 Next.js 行为，还应首先阅读 references/official/current-docs-2026-06-02.md，然后阅读 references/official/nextjs-docs.md；需要浏览器可读的 Markdown 时，通过 https://r.jina.ai/https://nextjs.org/docs/... 获取官方页面。对于 Drizzle 特有的行为，请阅读 references/official/drizzle-docs.md。

步骤 3：变更前检查关卡

棕地项目采用

• 默认情况下，不要因未修改的旧代码偏差而判定失败。
• 所修改文件中的安全、机密、身份验证和边界问题会立即阻止变更。
• 除非这需要大范围迁移，否则应使所修改文件符合规范。

关卡 1：路由、文件约定和项目结构

检查项	规则
将 page.tsx、layout.tsx、loading.tsx、error.tsx、not-found.tsx 或 route.ts 放置在无效的路由段结构之外	阻止
在同一路由段中创建 route.ts 和 page.tsx	阻止
将路由组当作会改变 URL 的结构使用	阻止
将私有实现文件暴露为可路由段，而非使用 _folder	阻止
在嵌套的领域／提供方分组能让所改代码更清晰时，仍强制将共享的 src/modules／src/services／src/db／src/server／src/integrations／src/config 组织为扁平结构或直接叶节点	警告。优先采用嵌套分组
将仓库本地的文件夹偏好说成 Next.js 官方规范	阻止
添加并行路由／拦截路由，却未配置匹配的布局插槽或硬导航行为	视风险警告／阻止

关卡 2：服务端和客户端边界

检查项	规则
交互式组件缺少 'use client'	阻止
在没有必要的情况下，将 'use client' 添加到组件树较高的位置	阻止
客户端组件导入 DB 代码、私有环境变量、cookies()、headers() 或仅服务端辅助函数	阻止
跨越服务端→客户端边界的属性范围过大、包含机密信息或不可序列化	阻止
提供方包裹的组件树范围超出所需范围	警告
客户端 Hook 导入 DB、Drizzle schema、DAL、私有环境变量、cookies()、headers() 或仅服务端提供方客户端	阻止

Gate 3：数据获取、缓存与新鲜度

检查项	规则
在无需仅限客户端处理的情况下，通过客户端组件获取初始 UI 数据	阻止
缓存行为是偶然产生的、未记录的，或基于过时的默认设置	阻止
已启用 cacheComponents，但未缓存的运行时数据缺少 use cache、connection()、loading.tsx 或 <Suspense> 意图	阻止
use cache 在缓存作用域内读取 cookies() / headers()，而不是接收可序列化参数	阻止，除非明确使用有充分理由的实验性 use cache: private
新的 App Router 工作使用 unstable_noStore 而非 connection()	阻止，除非是在维护旧代码
Mutation 缺少 updateTag、revalidateTag、revalidatePath、refresh、重定向新鲜度，或有文档记录的替代方案	阻止

Gate 4：Server Actions

检查项	规则
内部 UI Mutation 使用 route.ts 实现，尽管 Server Action 已足够	阻止，除非需要 HTTP 语义
Action 未验证或重新验证就信任 FormData、params、headers 或 search params	阻止
Action 仅依赖页面级身份验证检查	阻止
Action 返回原始 DB 行或宽泛的内部对象	阻止
Action 绕过必要的仅限服务端的 service/DAL 边界，用于授权、DTO 处理或 provider 编排	根据风险警告/阻止
redirect() 在必要的重新验证或标签更新之前运行	阻止

Gate 5：Route Handlers 和 Proxy

检查项	规则
将 Route Handler 用作仅限 UI 流程的默认内部 RPC	阻止
在 Route Handler 内使用 NextResponse.next()	阻止
在正确性至关重要时，依赖隐式而非显式的 Route Handler 缓存行为	阻止
在 Route Handler 主体中直接放置 use cache，而非放在辅助函数中	阻止
新增 middleware.ts，而非 proxy.ts	阻止
已足以使用 next.config.*、headers、redirects、rewrites 或渲染时逻辑，却仍添加 Proxy	阻止
Proxy matcher 缺失、范围过广，或在需要时未能排除元数据/静态内容路径	阻止

Gate 6：平台与环境

检查项	规则
假设 .env* 文件会从 src/ 加载	阻止
客户端代码读取非 NEXT_PUBLIC_ 环境变量	阻止
将运行时客户端环境变量视为构建时公开环境变量	阻止
启用 cacheComponents 时使用已在 v16 移除的路由片段配置选项（dynamic、revalidate、fetchCache）	阻止
未进行平台兼容性检查就更改 runtime: 'edge' 或 Proxy 运行时假设	阻止
未记录对部署敏感的 Server Action 来源/配置更改	根据风险警告/阻止

第 4 步：实施策略

自动修复局部、可逆的问题：缩小客户端边界，将仅限服务端的代码移至 DAL/辅助函数后方，添加 server-only，补充缺失的新鲜度，将仅限 UI 的 route.ts Mutation 替换为简洁的 Server Actions，收紧 Proxy matcher，并明确缓存意图。

不要自动应用大范围迁移：Pages→App Router 重写、大范围更改缓存模型、大批量将 Route Handler 转换为 Server Action，或对部署敏感的来源/加密更改。

<validation_checklist>

第 5 步：变更后验证

运行能证明结论的最小项目专属检查，然后报告证据：

1. 项目模式仍与编辑的部分相匹配
2. 特殊文件位于有效的片段中，且不存在 page/route 冲突
3. 共享文件夹和片段本地文件夹遵循项目结构规则；除非明确记录了例外，否则新增或修改的共享代码必须按嵌套的 src/lib / src/services 进行分组
4. 'use client' 边界范围小且安全
5. 客户端代码无法导入仅限服务端的模块或私有环境变量
6. 数据/缓存策略明确，且与当前文档兼容
7. 数据变更后的新鲜度处理使用 updateTag、revalidateTag、revalidatePath、refresh、重定向流程或有文档记录的替代方案
8. Route Handler 和 Proxy 的使用仍有充分理由
9. next.config.*、环境变量加载、路由片段配置和部署设置彼此协调

对于此技能文件夹本身，请运行：

bash skills/nextjs-architecture/scripts/validate-nextjs-architecture-skill.sh

停止条件

当 Next.js 模式已明确、所有变更部分都通过相关检查、验证结果为最新，且任何剩余的仓库本地约定或风险都已明确报告时，即可完成。