React / 系统课时
设计接口鉴权
设计接口鉴权
接口鉴权的目标不是“读到一个 token 就放行”,而是把凭据提取、身份验证、权限判断和失败响应连成稳定链路。完成本节后,你可以在 Route Handler 中同时处理 Bearer 令牌与服务端会话,并正确区分 401 和 403。
学习目标
- 区分“未认证”和“已认证但无权限”,为它们返回正确状态码
- 从请求头或 Cookie 中读取凭据,并把验证结果转换成服务端可信身份
- 设计可替换为真实认证库或会话存储的 Route Handler 鉴权边界
先定义接口的信任边界
Route Handler 收到的请求头、Cookie、查询参数和 JSON 都来自客户端,不能直接把 userId、role 或“已登录”标记当成可信事实。接口应该先验证凭据,再生成服务端身份对象,最后依据这个身份判断能否执行目标操作。
常用约定是:缺少、失效或无法验证的凭据返回 401 Unauthorized;身份已经确认,但权限不足返回 403 Forbidden。业务代码只接收已经验证过的身份,不再重复解析 token 或 Cookie。
让请求先经过鉴权链路
一条清晰的接口链路应按“提取凭据 → 验证身份 → 构造 principal → 检查权限 → 执行业务”推进。这样无论以后接入 JWT、OAuth 会话还是内部服务令牌,业务处理器都不需要知道凭据的具体格式。

下面把演示路由放在 app/api/private/route.ts。管理员权限通过查询参数 admin=1 触发,便于一次验证 401、403 和成功响应。
import type { NextRequest } from 'next/server';
type Principal = {
userId: string;
role: 'admin' | 'user';
source: 'bearer' | 'session';
};
function readPrincipal(request: NextRequest): Principal | null {
const authorization = request.headers.get('authorization');
const bearer = authorization?.startsWith('Bearer ')
? authorization.slice(7).trim()
: null;
// 仅用于本地教学:生产环境应验证签名、有效期或查询认证服务。
if (bearer && bearer === process.env.DEMO_API_TOKEN) {
return { userId: 'service-client', role: 'admin', source: 'bearer' };
}
const session = request.cookies.get('session')?.value;
if (session && session === process.env.DEMO_SESSION_TOKEN) {
return { userId: 'demo-user', role: 'user', source: 'session' };
}
return null;
}
export async function GET(request: NextRequest) {
const principal = readPrincipal(request);
if (!principal) {
return Response.json(
{ error: { code: 'UNAUTHORIZED', message: 'Authentication required' } },
{ status: 401, headers: { 'WWW-Authenticate': 'Bearer' } },
);
}
const requiresAdmin = request.nextUrl.searchParams.get('admin') === '1';
if (requiresAdmin && principal.role !== 'admin') {
return Response.json(
{ error: { code: 'FORBIDDEN', message: 'Admin permission required' } },
{ status: 403 },
);
}
return Response.json({ data: principal });
}在 .env.local 中准备仅供本地演示的值,修改后重新启动开发服务器让环境变量生效。
DEMO_API_TOKEN=dev-api-token
DEMO_SESSION_TOKEN=dev-session-token验证时依次发送无凭据、普通会话和管理员 Bearer 令牌三个请求。
curl -i -s http://localhost:3000/api/private
printf '\n'
curl -i -s -H "Cookie: session=dev-session-token" "http://localhost:3000/api/private?admin=1"
printf '\n'
curl -i -s -H "Authorization: Bearer dev-api-token" "http://localhost:3000/api/private?admin=1"预期输出的关键状态与响应体如下;实际 HTTP 协议版本和附加响应头可能不同。
HTTP/1.1 401 Unauthorized
{"error":{"code":"UNAUTHORIZED","message":"Authentication required"}}
HTTP/1.1 403 Forbidden
{"error":{"code":"FORBIDDEN","message":"Admin permission required"}}
HTTP/1.1 200 OK
{"data":{"userId":"service-client","role":"admin","source":"bearer"}}把真实验证交给认证层
Bearer 令牌至少要验证完整性、有效期以及面向当前服务的签发范围;仅解码 JWT payload 不等于验证。服务端会话则应根据 Cookie 中的随机会话标识查询可信存储,并检查会话是否过期、撤销或更换过权限。
基于 Cookie 的登录通常还要使用 HttpOnly、Secure 和合适的 SameSite 策略;对会改变状态的请求,还要结合应用部署方式评估 CSRF 防护。无论使用哪种方案,都不要让客户端提交角色后由接口“照单全收”。
用失败场景验收鉴权
验收时至少覆盖四种情况:没有凭据、凭据失效、身份有效但权限不足、身份与权限都满足。前三种响应不能泄露签名密钥、数据库错误、用户是否真实存在等内部细节;成功路径则应把可信身份传给后续业务逻辑。
当鉴权逻辑被集中在可复用函数或认证库中,Route Handler 的职责会变得很清楚:先证明“你是谁”,再判断“你能做什么”,最后才执行接口真正的业务。