opinionated-nextjs-patterns

Opinionated Next.js 16 模式

为采用统一且有明确主张的架构的 Next.js 16（App Router） 代码库提供实现模式参考。包含 8 个类别中的 50 条规则，按执行生命周期中的级联影响排序：先处理授权和（可选的）租户建模，再处理请求边界、服务端数据获取、变更、客户端边界、架构和 UI 约定。

这些规则原则上与后端无关，但使用 Supabase 作为具体示例。每条规则都会讲解可迁移的理念（例如“在数据层进行授权”“通过类型化仓库读取”）；如果模式确实与后端有关，则会通过 *Transferable:* 说明如何用于其他存储方案（Drizzle、Prisma）。该结构采用 Turbo monorepo，包含由你维护的 @app/* 包，基于规范的库构建（next-safe-action、@supabase/ssr、@tanstack/react-query、react-hook-form + zod、shadcn/ui、next-intl、pino），而非引入一个供应商提供的入门套件。

适用场景

遇到以下情况时，请参考这些规则：

• 编写新代码——页面、布局、服务端操作、路由处理器、proxy.ts、功能包、客户端组件、Hooks、数据访问包、SQL/迁移文件、表单。
• 审查 PR——授权疏漏（使用特权客户端却没有防护、缺少 'server-only'）、请求瀑布（顺序执行 await、客户端获取服务端数据）、偏离规范（手动编辑生成的类型、深层包导入、硬编码的 i18n 字符串）。
• 重构——在 apps/web 和 packages/* 之间移动代码、拆分操作与服务、提升 'use client' 边界、将原始查询替换为类型化的数据访问工厂、通过数据访问包替换后端。
• 设计功能——选择合适的客户端（请求范围内、特权或浏览器端）、决定使用操作还是路由处理器、规划表单与服务端操作之间的契约、确定租户范围（如果是多租户）。
• 入职——通过具体且可迁移的示例，了解代码库为何采用当前的结构。

按优先级划分的规则类别

优先级	类别	影响	前缀
1	授权与数据层访问	CRITICAL	auth-
2	多租户 (可选，仅限 SaaS)	CRITICAL	tenant-
3	请求边界（代理）	HIGH	proxy-
4	服务端数据加载	HIGH	server-
5	变更：操作与路由处理器	HIGH	mutate-
6	客户端/服务端边界	MEDIUM-HIGH	client-
7	架构与服务	MEDIUM	arch-
8	表单与 UI 约定	MEDIUM	ui-

快速参考

1. 授权与数据层访问（CRITICAL）

• auth-use-standard-server-client — 使用与身份验证绑定、作用域限定于请求的客户端；不要默认使用特权客户端。
• auth-gate-admin-client — 在构造服务角色客户端之前进行授权。
• auth-trust-rls-no-duplicate-checks — 在数据层授权一次；不要在应用代码中重复检查。
• auth-use-sql-policy-helpers — 将范围限定谓词集中在可复用的 SQL 策略辅助函数中。
• auth-use-require-user — 使用一个 requireUser() 辅助函数集中处理身份验证关卡。
• auth-server-only-imports — 使用 import 'server-only' 标记特权模块。
• auth-mfa-in-middleware — 在 proxy.ts 边界强制执行 MFA，而非逐页处理。

2. 多租户（关键——可选，仅适用于 SaaS）

• tenant-accounts-as-tenant-root — 使用一张租户根表，供个人和团队工作区引用。
• tenant-account-id-on-product-tables — 在每张产品表上添加租户键、索引和范围限定策略。
• tenant-slug-in-team-urls — 在团队 URL 中使用易读的 slug，而非 UUID。
• tenant-storage-paths-include-account-id — 在对象存储路径中按租户 ID 进行命名空间划分。
• tenant-never-edit-generated-types — 将生成的数据库类型视为构建产物；应重新生成，切勿手动编辑。

3. 请求边界：代理（高优先级）

• proxy-single-pipeline — 在一个 proxy.ts 中组合完整的请求处理管道。
• proxy-redirect-auth-at-boundary — 在代理处执行身份验证重定向，而非在页面中执行。
• proxy-url-pattern-matching — 使用 URLPattern 匹配代理路由，而非字符串比较。
• proxy-set-correlation-id — 在请求边界设置关联 ID。
• proxy-secure-headers-flagged — 在环境标志启用时应用严格的 CSP 标头。

4. 服务端数据加载（高优先级）

• server-cache-workspace-loaders — 使用 React 的 cache() 包装每个请求的加载器。
• server-promise-all-parallel-loads — 使用 Promise.all 并行加载相互独立的数据。
• server-use-feature-api-factories — 通过有类型的数据访问工厂读取数据，而非直接调用 from('table')。
• server-redirect-on-missing-workspace — 工作区状态无效时，从加载器执行重定向。
• server-fetch-in-server-components — 在服务端组件中获取初始数据，而非在客户端获取。
• server-use-tables-generic-for-types — 使用生成的行类型，而非手写接口。
• server-services-receive-client — 将数据客户端作为构造函数参数传入服务。

5. 数据变更：操作与路由处理程序（高优先级）

• mutate-use-safe-action-clients — 通过基于 next-safe-action 构建的有类型操作客户端处理路由中的数据变更。
• mutate-zod-schema-separate-file — 将 Zod 架构放在单独的 *.schema.ts 文件中，供客户端和服务端共用。
• mutate-thin-action-service-holds-logic — 保持操作精简；将业务逻辑放入服务中。
• mutate-use-getlogger-not-console — 通过自有的结构化日志记录器记录日志，而非使用 console.log。
• mutate-revalidate-path-after-write — 写入成功后调用 revalidatePath()。
• mutate-enhance-route-handler — 使用负责身份验证和验证的有类型处理程序包装路由处理程序。
• mutate-webhook-verify-signature — Webhook 路由跳过用户身份验证，并验证提供方签名。

6. 客户端/服务端边界（中高）

• client-use-client-at-leaves — 在叶子组件而非页面根组件上标记 'use client'。
• client-pass-server-data-as-props — 将服务端数据作为属性传递给客户端组件，不要重新获取。
• client-use-supabase-with-react-query — 将记忆化的浏览器客户端与 TanStack Query 配合使用，以读取客户端数据。
• client-realtime-cleanup-subscription — 在 useEffect 的返回函数中清理所有订阅或事件源。
• client-use-action-hook — 使用 next-safe-action/hooks 中的 useAction 调用服务端操作。
• client-stable-query-keys — 使用稳定的分层查询键。

7. 架构与服务（中）

• arch-app-vs-packages-boundary — 可复用功能放在 packages/，特定于产品的代码放在 apps/web。
• arch-data-access-adapter — 将后端限定在一个具有稳定接口的数据访问包中。
• arch-feature-package-layout — 功能包采用 components / hooks / schema / server 布局。
• arch-import-via-package-exports — 通过包的 exports 映射导入，绝不使用深层内部路径。
• arch-provider-gateway-pattern — 通过网关接口封装供应商 SDK。
• arch-policy-engine-for-business-rules — 在由你掌控的策略层中建模业务规则，不要内联编写条件判断。
• arch-config-driven-navigation — 在 config/ 中定义路由和导航，不要在组件中硬编码。

8. 表单与 UI 规范（中）

• ui-rhf-zod-no-generics — 让 zodResolver 推断表单类型；不要为 useForm 添加泛型。
• ui-form-message-per-field — 为每个字段添加 FormMessage。
• ui-kit-ui-package-imports — 从 @app/ui 设计系统接口导入 UI，绝不使用内部路径。
• ui-semantic-tailwind-tokens — 使用语义化 Tailwind 令牌，不要硬编码颜色。
• ui-base-ui-render-not-aschild — 使用 Base UI 的 render 属性，而不是 Radix 的 asChild。
• ui-trans-for-display-text — 通过 <Trans> 或 useTranslations 渲染显示文本。

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 — 类别结构、影响级别和生命周期原理。
• 规则模板 — 添加新规则的模板。
• AGENTS.md — 自动生成的目录，便于快速导航。

参考文件

文件	描述
references/_sections.md	类别定义及按生命周期影响排序
assets/templates/_template.md	添加新规则的模板
metadata.json	版本、组织、参考资料

相关技能

• base-ui-migrator — 批量将 Radix asChild 模式迁移为 Base UI render 属性。
• tailwind-refactor — 将硬编码颜色重构为语义化令牌。
• react-optimise — 优化 React 组件的性能。
• nextjs-bundle-optimizer — 分析并缩减 Next.js 应用的包体积。