Vista.js 文件式 API Routes 实战：10分钟写出支持动态参数的 HTTP 后端

Vista.js 文件式 API Routes 实战：10分钟写出支持动态参数的 HTTP 后端

【免费下载链接】vista项目地址: https://gitcode.com/gh_mirrors/vista13/vista

Vista.js 是一款面向 React 的全栈框架，它的文件式 API Routes让你只需新建一个route.ts文件，就能立即拥有一个支持动态参数的 HTTP 后端接口，无需单独启动 Node 服务器。本文带你用 10 分钟时间，从零写出一个带增删改查接口的 REST 后端。

🧭 什么是 Vista API Routes？

一句话：app/目录下任何一个名叫route.ts的文件，就是一个 HTTP 端点。

Vista 的路由解析器会扫描整个app/目录，把目录结构映射为 URL，把文件里导出的函数映射为 HTTP 方法：

核心规则只有一条：每导出一个函数，就支持一个 HTTP 方法。导出了GET就能处理查询，导出了POST就能处理创建；没导出的方法自动返回405 Method Not Allowed。

这套扫描逻辑在框架中的实现，可以查看 route-handler-registry.ts，它保证了构建时扫描和运行时解析使用同一套规则，URL 和行为永远不会"打架"。

⚡ 10 分钟快速上手

第 1 步：创建项目

git clone https://gitcode.com/gh_mirrors/vista13/vista npx create-vista-app my-api cd my-api && pnpm install && pnpm dev

开发服务器会在3003端口启动，后续改代码即改即生效。

第 2 步：写出第一个route.ts

新建app/api/notes/route.ts，整个接口只需要两个函数：

export async function GET() { return Response.json({ notes: [] }); } export async function POST(request: Request) { const body = await request.json(); return Response.json({ note: body }, { status: 201 }); }

启动后访问http://localhost:3003/api/notes即可拿到 JSON 响应。没有路由表、没有装饰器、没有中间件注册——文件名就是路由。

第 3 步：加上动态参数

新建app/api/notes/[id]/route.ts，方括号目录[id]让 URL 多出一段动态值：

export async function GET( request: Request, { params }: { params: { id: string } } ) { return Response.json({ id: params.id }); }

请求/api/notes/42时，params.id的值就是"42"。动态参数的解析细节由 route-patterns.ts 负责，它把目录名转换成:id这样的 URL 模式再匹配请求。

想看一个完整的增删改查（GET / POST / PATCH / DELETE）示例，仓库里的 sample-app 已经写好了：

• 列表与创建：sample-app/app/api/notes/route.ts
• 按 ID 查询、修改、删除：sample-app/app/api/notes/[id]/route.ts
• 服务端内存数据源：sample-app/app/api/notes/notes-store.ts

📌 动态参数命名速查

和普通页面路由（app/docs/[...slug]/page.tsx）用的是同一套命名约定，学会一次，前后端通用。

🛠️ HTTP 方法与状态码实战要点

Vista 的 route handler 支持 7 种标准方法，按规范顺序为：

GET·HEAD·POST·PUT·PATCH·DELETE·OPTIONS

写接口时记住三个惯例：

1. 创建资源返回201：Response.json(data, { status: 201 })
2. 资源不存在返回404：Response.json({ error: 'Not found' }, { status: 404 })
3. 删除成功返回204（无响应体）：new Response(null, { status: 204 })

这三个状态码在 sample-app 的 sample-app/app/api/notes/[id]/route.ts 中都有标准用法，照着抄即可。

🔒 为什么安全？Handler 只在服务端运行

API Routes 的另一个隐藏福利：handler 是 server-only 的。

你在route.ts里导入的数据库客户端、密钥、内部工具，永远不会被打进浏览器端 bundle。像 sample-app 中这样的数据源文件：

"没有任何组件导入它，所以它永远不会进入客户端 bundle——真实项目里，这里就是接入数据库的地方。"

（引自 notes-store.ts 的源码注释）

也就是说，Vista 的 API Routes 在"极简"和"安全"之间没有取舍：少写代码的同时，天然隔离了敏感逻辑。

🚀 下一步：走向完整全栈应用

API Routes 解决了"快速暴露 HTTP 接口"的问题，如果你的需求升级了，Vista 还有两条进阶路径（同一仓库内混合使用）：

• Typed API（vista/stack）：用vista g api-init生成类型化路由，前后端共享类型，Server Component 甚至可以不经过 HTTP 直接调用后端
• Auth + 中间件：用vista g auth一键生成登录页、会话守卫和 fail-closed 中间件

两者与文件式 API Routes 可以共存，详细介绍见官方文档 fullstack-app.md，框架层面的全栈约定在 README.md 的 "Build a fullstack app" 章节。

✅ 小结

从route.ts到动态参数、再到状态码规范，Vista 的文件式 API Routes 用"约定"替代了"配置"。现在就去你的app/api/目录下建第一个端点吧 🎉

【免费下载链接】vista项目地址: https://gitcode.com/gh_mirrors/vista13/vista