React / 系统课时
设计项目架构
设计项目架构
项目需求确定后,下一步不是立即建表或堆页面,而是把路由、组件、接口、数据库访问和权限校验分成清晰边界。本节继续以团队任务看板为例,给出一套适合 Next.js App Router 的最小全栈结构,并用一个创建任务接口验证各层职责。
学习目标
- 划分路由、UI、业务逻辑、数据访问和权限模块的职责边界
- 判断页面数据读取、表单写入与 HTTP 接口分别应该放在哪里
- 用最小 Route Handler 验证身份检查、输入校验和响应契约
先固定五条架构边界
可以把项目拆成五个协作区域:app 负责路由与页面入口,组件层负责交互与展示,业务层负责“是否允许执行”这类规则,数据访问层负责数据库读写,认证与授权模块负责识别用户并提供权限事实。

这几个区域不是为了“分层而分层”。真正的目标是让变化被限制在局部:更换数据库时尽量不改页面,调整权限规则时不复制到多个按钮事件里,增加移动端客户端时还能复用同一套服务端规则。
组织路由与组件
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 响应。真实项目中,最后的创建动作应继续下沉到业务服务和数据访问层。
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 }
);
}项目开发服务器启动后,可以用下面的请求验证接口契约。
curl -i -X POST http://localhost:3000/api/tasks \
-H 'content-type: application/json' \
-H 'x-user-id: user-1' \
-d '{"title":"设计数据库表"}'预期输出
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 各自复制权限规则,或页面既处理表单状态又承担事务逻辑,就应该在继续开发前拆分。一个好的最小架构不是文件最多,而是每类变化都有明确落点,并且核心业务规则始终留在可信的服务端边界。