Next.js 16 + OpenAI 实战：从零构建带用量限制的AI SaaS

为什么这个项目值得关注

AI SaaS 的门槛正在快速降低。过去要搭一个带用户系统、数据库、AI 能力和 Freemium 计费的完整产品，动辄需要几周；现在借助 Next.js 16 的 Server Actions、Drizzle ORM 与 OpenAI SDK，一个人一下午就能跑通最小闭环。YouTube 创作者 Asama 发布的全栈实战视频，完整演示了 Brief.ai 的搭建过程：粘贴杂乱的会议记录，输出标题、摘要和清晰的行动项清单。本文拆解其中的架构决策与工程细节，并补充我对几个关键取舍的判断。

技术栈与请求链路

项目采用 Next.js 16 的 App Router 和 Server Actions，数据库层使用 Drizzle ORM——开发环境是本地 SQLite 文件，生产环境切到 Turso，只改连接字符串和 token，代码零改动。AI 层用 OpenAI SDK 配合 Zod schema，让模型返回结构化 JSON。样式用 Tailwind CSS v4。

一次生成请求的流转路径很清晰：proxy 文件先做快速校验，把未登录用户重定向；然后 Server Action 在服务端校验用户身份与输入；接着调用 OpenAI 生成 brief；最后落库并刷新页面。这条链路把认证和校验都放在服务端，客户端只负责提交表单和展示结果。

Server Actions 是 Next.js App Router 引入的服务端函数机制：在组件文件里用 'use server' 声明的函数会被编译成仅存在于服务端的端点，客户端调用它时实际发出的是一次 POST 请求，而非把函数体打进 bundle。这带来两个直接好处——数据库凭据、密钥这类敏感内容天然不会进入浏览器；表单提交不再需要手写 API 路由和 fetch 逻辑。代价是它建立在渐进增强之上，需要理解它与缓存、重验证（revalidatePath / refresh）之间的关系，否则容易出现页面数据不更新或误缓存的问题。文章里 proxy 做重定向、Server Action 做真正校验的分工，正是这套机制下的标准实践。

数据库设计与安全边界

两张表撑起整个应用。users 表存 name、唯一 email 和 password hash——视频里特别强调永远不要存明文密码。briefs 表存 title、summary 和 action items，并关联到用户；action items 以 JSON 形式存储。外键设置了 onDelete cascade，删除用户时其所有 briefs 一并清除，避免孤儿数据。

Drizzle 的连接模块用了 server-only 导入，确保这个文件永远不会被打包进浏览器 bundle。这是一个容易被忽视但很关键的约束：数据库凭据和查询逻辑一旦泄漏到客户端，等于把整个数据层暴露给攻击者。

会话与认证的落地细节

登录后生成一个包含用户 ID 的 JWT，用密钥签名，有效期 7 天，写进 cookie。HttpOnly 让浏览器 JavaScript 读不到它，防止会话被脚本窃取；生产环境下 cookie 仅通过 HTTPS 发送。读取会话时用同一密钥验证签名，签名被篡改或 token 过期时 JWT verify 抛错，返回 null。getSession 是整个应用读取 cookie 的唯一入口。

注册和登录都是 Server Action，用 use server 声明只在服务端运行。表单用 Zod 校验，密码用 bcrypt 哈希。登录时用 bcrypt compare 比对存储的哈希。一个值得借鉴的细节：邮箱不存在和密码错误返回同一条提示，攻击者无法通过表单探测哪些邮箱注册过账号。React 的 useActionState 提供了 action、服务端返回的 state 和 pending 标志，用来在请求期间禁用按钮并展示错误；由于 React 会在 action 结束后重置表单，代码把邮箱回传作为默认值，用户不必重新输入。

JWT（JSON Web Token） 是一段自包含的、经密钥签名的令牌，通常由 header、payload、signature 三段 base64url 字符串以点号连接。服务端不需要查库或维护会话表，只要用同一密钥验证签名，就能确认令牌未被篡改，payload 里的用户 ID 可信。这带来无状态、易横向扩展的优点，但也意味着签发后无法单方面撤销——令牌在过期前一直有效，所以有效期设置（文中为 7 天）和密钥管理尤为关键。这也是 HttpOnly、Secure、SameSite 这几个 cookie 属性必须同时配合的原因：令牌本身无法作废，就只能靠浏览器侧的限制来降低被窃取和跨站滥用的风险。

路由保护与数据访问层

Next.js 16 把 middleware 重命名为 proxy，它在页面渲染前运行：未登录用户打开 dashboard 会被送到 login，已登录用户打开 login 或 signup 会直接跳回 dashboard。但视频作者明确说这只是乐观的快速检查，真正的鉴权在服务端完成——数据访问层里有一个把 cookie 转成 user 的函数，每个页面和每个 Server Action 都会调用它。这个函数只 select 安全列，password hash 永远不会离开它。原则只有一条：永不信任客户端。

结构化输出与 Demo 模式

AI 层没有让模型返回自由文本再自己解析，而是用 Zod schema 描述期望结果：一个 title、一个 summary、一个 action items 列表。调用 OpenAI 的 responses API 并启用结构化输出后，模型必须返回完全符合该形状的 JSON，output parsed 直接给出带类型的结果。API key 只存在于服务端，不会到达浏览器。

一个很实用的设计是 demo 模式：没有配置 API key 时，应用用简单规则替代 AI——包含 will、need to、should 等词的句子被识别为行动项，dashboard 顶部有明确标识。对开源项目来说这降低了试用门槛，任何人 clone 仓库都能跑起来，无需付费购买 API key。

Zod 是一个 TypeScript 优先的运行时校验库：你用链式 API 描述数据形状，它同时产出静态类型和可在运行时执行的校验函数。在调用大模型时这个双重身份特别有用——同一份 schema 既被转换成模型可理解的 JSON Schema 约束（结构化输出），又能在结果返回后再校验一遍，任何字段缺失或类型不符都会立刻暴露而不是静默流到下游。相比手写正则或 JSON.parse 加类型断言，Zod 让「模型返回的东西」第一次拥有了可信的边界，类型系统也从编译期延伸到了运行时。

用量限制与 Server Action 编排

生成 brief 的 Server Action 串起了完整流程：获取当前用户；用 Zod 校验输入，设置最小和最大长度，既拦截空请求也防止超长粘贴文档带来意外成本；统计当天 brief 数量以执行免费计划限制；调用 AI；保存结果；调用 refresh 让 dashboard 显示新内容。

用量统计就是一条 Drizzle 查询：数出该用户从当天零点起创建的 brief 数量。限制值来自环境变量，不碰代码就能调整；后续可以给付费用户更高额度。dashboard 页面上，用量卡片显示今天已经用掉多少条免费 brief。视频演示中额度用满后生成按钮被禁用。

Next.js 16 的 cache components 默认开启，意味着任何读取 cookie 的地方必须放在 Suspense 边界内。页面外壳立即渲染，dashboard 以流式方式补入。内部先取用户，然后用 Promise.all 并行加载其 briefs 和当日用量。生成表单复用同一套 useActionState 模式，AI 工作期间按钮显示 thinking，达到每日上限后禁用；失败时把用户粘贴的内容回传，不丢失输入。

Suspense 边界与流式渲染：React 的 Suspense 允许把读取异步数据的组件「挂起」，先渲染外层可立即呈现的部分（页面外壳、导航、骨架），等数据就绪后再把内容补入同一位置，浏览器通过流式响应逐段接收 HTML。Next.js 16 默认开启 cache components 后，凡是读取 cookie、headers 等请求期数据的组件都无法在构建时预渲染，必须包在 Suspense 里，否则会报错。这也解释了文中 dashboard 的结构：外壳秒开，用量与列表在边界内并行加载（Promise.all），用户的感知从「白屏等待」变成「逐步填满」，而表单的禁用状态和 pending 标志正好和这段异步窗口对齐。

部署与扩展方向

部署路径是：在 Turso 建免费数据库并复制 URL 和 token，对其跑 DrizzleKit push 建表，在 Vercel 导入仓库并配置环境变量——会话密钥、数据库 URL 与 token、OpenAI key。最后一步很容易被跳过但必须做：在 OpenAI 账户设置月度消费上限，防止一个 bug 烧掉大量费用。

作者给出的扩展方向包括：接入 Stripe 订阅做更高额度的 Pro 计划；流式输出让文本边生成边显示；增加团队功能共享 briefs，或导出到 Notion、邮件。这些既是练手项目，也是求职作品集里能拿得出手的完整案例。

我的判断

这个项目的价值不在于代码量，而在于它把 AI 产品最容易踩坑的几处——会话安全、成本控制、结构化输出、降级体验——都处理得干净。结构化输出替代文本解析，是从「玩具 demo」走向「可维护产品」的分水岭；demo 模式则体现了对开源分发场景的理解。真正的门槛已经不在能不能调用模型，而在这些工程约束是否被认真对待。