React / 系统课时

设计项目架构

设计项目架构

项目需求确定后,下一步不是立即建表或堆页面,而是把路由、组件、接口、数据库访问和权限校验分成清晰边界。本节继续以团队任务看板为例,给出一套适合 Next.js App Router 的最小全栈结构,并用一个创建任务接口验证各层职责。

学习目标

  • 划分路由、UI、业务逻辑、数据访问和权限模块的职责边界
  • 判断页面数据读取、表单写入与 HTTP 接口分别应该放在哪里
  • 用最小 Route Handler 验证身份检查、输入校验和响应契约

先固定五条架构边界

可以把项目拆成五个协作区域:app 负责路由与页面入口,组件层负责交互与展示,业务层负责“是否允许执行”这类规则,数据访问层负责数据库读写,认证与授权模块负责识别用户并提供权限事实。

Next.js 全栈项目模块边界

这几个区域不是为了“分层而分层”。真正的目标是让变化被限制在局部:更换数据库时尽量不改页面,调整权限规则时不复制到多个按钮事件里,增加移动端客户端时还能复用同一套服务端规则。

组织路由与组件

App Router 中,页面和布局默认是 Server Components,可直接承载只在服务端需要的数据读取;只有需要浏览器状态、事件处理、DOM API 或客户端 Hook 的局部组件才加入 "use client"。这样可以把数据库凭据、私有环境变量和服务端权限逻辑留在服务端边界。

路由 入口职责 适合的组件边界
/projects 读取当前用户可访问项目 页面主体保持服务端渲染
/projects/[id] 读取项目与任务 任务列表可服务端渲染,交互表单局部客户端化
/projects/[id]/members 管理成员并校验管理员权限 服务端先鉴权,再渲染管理界面
/api/tasks 对外提供任务写入 HTTP 契约 只做请求解析、调用业务逻辑、返回响应

表单只服务于本应用时,可以考虑 Server Action;需要给外部客户端、Webhook 或独立前端提供稳定 HTTP 契约时,更适合 Route Handler。两者都不应该绕过服务端权限校验直接写数据库。

让接口只承担传输职责

下面是一个最小 app/api/tasks/route.ts 示例。它故意不连接真实数据库,只演示 Route Handler 应负责的三件事:识别请求身份、校验输入、形成稳定的 HTTP 响应。真实项目中,最后的创建动作应继续下沉到业务服务和数据访问层。

ts
import { NextResponse } from "next/server";

type CreateTaskBody = {
  title?: string;
};

export async function POST(request: Request) {
  const userId = request.headers.get("x-user-id");
  if (!userId) {
    return NextResponse.json({ error: "UNAUTHORIZED" }, { status: 401 });
  }

  const body = (await request.json()) as CreateTaskBody;
  const title = body.title?.trim();
  if (!title) {
    return NextResponse.json({ error: "TITLE_REQUIRED" }, { status: 400 });
  }

  return NextResponse.json(
    { id: crypto.randomUUID(), title, ownerId: userId },
    { status: 201 }
  );
}

项目开发服务器启动后,可以用下面的请求验证接口契约。

bash
curl -i -X POST http://localhost:3000/api/tasks \
  -H 'content-type: application/json' \
  -H 'x-user-id: user-1' \
  -d '{"title":"设计数据库表"}'

预期输出

text
HTTP/1.1 201 Created
content-type: application/json

{"id":"<ID>","title":"设计数据库表","ownerId":"user-1"}

<ID> 是运行时生成的 UUID,实际值会不同。删除 x-user-id 请求头时应得到 401,把标题改为空字符串时应得到 400;这两种结果比页面是否隐藏按钮更能证明服务端边界已经生效。

把数据库和权限放到服务端

数据库层只暴露业务需要的读写方法,例如“按用户查询可访问项目”“在指定项目创建任务”,而不是把 ORM 客户端对象传给页面。业务层则在调用数据访问前完成规则判断,例如用户是否属于项目、是否有管理员角色、任务状态转换是否合法。

权限设计也应遵循同一原则:客户端可以根据权限事实决定显示哪些操作,但真正的拒绝必须发生在 Server Action、Route Handler 或它们调用的服务端业务层。数据库查询还应带上租户或项目范围条件,避免只校验“已登录”却读取到其他项目的数据。

用依赖方向检查设计

架构评审时只需要检查一条依赖方向:页面和接口可以依赖业务层,业务层可以依赖抽象的数据访问能力,数据访问层连接数据库;权限事实从服务端认证模块进入业务判断。反过来的依赖通常意味着边界正在泄漏。

如果一个 Client Component 直接导入数据库客户端、多个 Route Handler 各自复制权限规则,或页面既处理表单状态又承担事务逻辑,就应该在继续开发前拆分。一个好的最小架构不是文件最多,而是每类变化都有明确落点,并且核心业务规则始终留在可信的服务端边界。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计项目架构

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通