Nuxt Server Routes 完整指南：API 边界、验证、缓存与可维护性

Nuxt Server Routes 很容易让团队上手，因为在 server/api 下新建文件就能直接得到接口。但“容易上手”并不等于“容易长期维护”。项目一旦进入真实业务阶段，你很快会遇到三个问题：逻辑写在哪一层，请求校验怎么做，缓存和鉴权如何不互相打架。

Server Routes 的重点从来不是少写几行后端代码，而是为前后端一体项目建立一套轻量但清楚的服务边界。

1. 先把 Server Routes 看成“应用边界”，不是工具函数集合

很多仓库里的 server/api 最终失控，原因是开发者把它当成“任何和服务端有关的东西都能往里放”的目录。更稳的判断方式是：

路由文件负责接收请求、解析输入、返回协议
业务逻辑下沉到 service 层或 composable 层
外部依赖访问尽量集中封装

这样做的价值是：你以后要换调用方、拆后台任务、做权限复用时，不需要从路由文件里硬拆逻辑。

2. 文件结构要服务可读性，而不是只服务路由生成

推荐至少按资源或业务域组织：

server/api/articles/
server/api/auth/
server/api/search/

而不是把所有 .get.ts、.post.ts 平铺在一层。资源边界一旦清晰，接口查找、权限治理和测试都会容易很多。

3. 输入校验要尽早做，不要把脏数据交给后面每一层

Nuxt Server Routes 最常见的隐患之一，是开发者读完 body 直接执行业务逻辑：

export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  return createLead(body)
})

这样的问题不在“能不能运行”，而在错误边界非常模糊。更好的做法是把输入校验放在路由入口：

import { z } from 'zod'

const leadSchema = z.object({
  email: z.string().email(),
  source: z.string().min(1),
})

export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const parsed = leadSchema.safeParse(body)

  if (!parsed.success) {
    throw createError({ statusCode: 400, statusMessage: 'Invalid payload' })
  }

  return createLead(parsed.data)
})

入口越早拦住脏数据，后续层级越清爽。

4. 鉴权要和业务权限分开

很多 Nuxt 项目把“读到 token”误认为“权限完成”。其实仍然要分两步：

先确认当前请求来自谁
再判断这个人能否操作当前资源

比如：

有 token 只能说明已登录
能否修改某篇文章，还要看是不是该文章的作者或管理员

把这两层混在一起，接口越写越多后就会出现大量权限判断复制粘贴。

5. 错误返回要可预测，不要把原始异常直接透出

如果前端要稳定消费接口，错误结构就应该统一。至少建议明确：

哪些错误属于参数错误
哪些属于权限错误
哪些属于资源不存在
哪些属于系统异常

统一错误协议的价值，在于前端能稳定做提示、重试、埋点和监控，而不是每个接口返回风格都不同。

6. 缓存策略要与接口性质匹配

不是所有 Server Route 都需要缓存，也不是所有查询都该实时。可以按这组思路判断：

接口类型	建议
高频公开读取，如配置、列表、聚合内容	可考虑缓存或边缘分发
用户私有数据	谨慎缓存，避免跨用户污染
写操作	一般不缓存，但要关注幂等与重复提交

很多缓存事故都不是“没配缓存”，而是把不该缓存的个性化结果缓存了。

7. 失败案例：所有逻辑都写在路由文件里

典型失控写法通常长这样：

路由里读取 body
直接查数据库
直接调第三方服务
直接拼装返回值
顺手再做权限判断和日志

短期确实快，长期一定会变成难以复用、难以测试、难以定位问题的混合层。

Server Routes 的最佳角色是“HTTP 协议适配层”，不是业务与基础设施的总集线器。

8. Checklist：Nuxt Server Routes 稳定上线前必查

路由目录是否按业务域组织
输入校验是否在入口统一完成
鉴权和资源权限是否分层
错误返回是否统一
高频读取接口是否有明确缓存策略
路由文件是否避免堆叠大量业务实现

9. 结论：Server Routes 的价值是让边界清晰，而不是让服务端“隐形”

Nuxt Server Routes 适合很多中轻量业务，因为它能把前后端一体开发做得很顺。但要想一直顺，前提是你愿意在结构、校验、权限和错误协议上提前建立约束。否则接口目录会越来越方便新增，也越来越难维护。

进一步阅读：

Nuxt Server Routes 完整指南：API 边界、验证、缓存与可维护性