企业官网建设流程全解析

Stacks路由系统完全指南：文件式路由与Laravel风格路由全解析

【免费下载链接】stacksModern, performant, optimized for DX & AX. Develop powerful apps, clouds & framework-agnostic libraries—faster.项目地址: https://gitcode.com/gh_mirrors/stack/stacks

Stacks 路由系统是现代 TypeScript 全栈框架 Stacks 的请求分发中枢，它同时支持文件式路由与 Laravel 风格路由两种范式。本文面向新手，带你 10 分钟读懂 Stacks 路由系统的核心机制：路由文件如何被自动发现、route.get('/path', 'Actions/XxxAction')这样的声明式写法如何工作、路由组与中间件如何组织权限，以及用户路由如何覆盖框架默认路由。

一、30秒认识 Stacks 路由：一套框架，两种路由哲学

Stacks 的路由构建在高性能的@stacksjs/router之上，底层基于 bun-router，并加入了 Action/Controller 解析、中间件与 Laravel 风格的请求助手方法。你可以把它理解成：

• 📁文件式路由：routes/目录下的每个.ts文件是一个路由文件，通过注册表声明挂载前缀，"结构即路由"。
• ✍️Laravel 风格路由：在路由文件内用一行route.get/post/...声明路径与处理者，写法与 Laravel 几乎同构，上手零成本。

两种风格并不是二选一，而是分层协作：文件式决定"这段路由挂在哪个前缀下"，Laravel 风格决定"具体路径指向哪个处理者"。下面这张图展示了 Stacks 运行时的整体结构，路由是其中的请求入口：

二、文件式路由：用「目录结构 + 注册表」声明路由

routes/ 目录：路由文件从哪来

Stacks 约定所有路由文件放在 routes/ 目录，官方脚手架内置了三个示例文件：

app/Routes.ts 注册表：文件与前缀的"合同"

路由文件不会自动生效，需要先在 app/Routes.ts 中登记。默认注册表位于 storage/framework/defaults/app/Routes.ts，核心规则只有一条：键名自动成为 URL 前缀。

// app/Routes.ts（节选） export default { 'api': 'api', // routes/api.ts → /api/* 'v1': { path: 'v1', prefix: 'v1' }, // 显式前缀 'admin': { path: 'admin', middleware: ['auth'] }, // 整组路由挂 auth 中间件 'internal': { path: 'internal', prefix: '' }, // 空前缀 = 挂载在根路径 }

几个新手容易踩的细节：

• 'api'键会自动补/api前缀，与开发代理的转发路径保持一致，写在routes/api.ts里的route.get('/cart/add', ...)实际注册为/api/cart/add；
• 只有'web'键默认挂在根路径（无前缀），其他空前缀场景请显式写prefix: ''；
• 注册表支持给整个文件统一挂中间件，适合给后台路由整体加认证。

三、Laravel 风格路由：一行 route.get 声明完整端点

进入路由文件后，写法就是熟悉的 Laravel 味道。Stacks 支持全部常见 HTTP 方法：get / post / put / patch / delete / options。

两种处理者写法：Action 与 Controller@method

// Action 风格：一个文件一个动作 route.get('/dashboard', 'Actions/DashboardAction') route.post('/login', 'Actions/Auth/LoginAction') // Controller 风格：一个类多个方法，@ 前是文件，@ 后是方法名 route.get('/users', 'Controllers/UserController@index') route.get('/users/:id', 'Controllers/UserController@show')

• Action（app/Actions/）：单一职责，适合"登录""刷新令牌"这类独立操作，还可自带validations做请求校验；
• Controller：把同一资源的 CRUD 收拢在一个类里，方法名与路由语义一一对应（index/show/store/update/destroy），是 Laravel 老用户最亲切的模式。

字符串路径会被路由系统自动解析定位到对应文件，无需手动 import。

路由组与中间件：批量管理权限和限流

// 前缀 + 中间件一次配好 route.group({ prefix: '/auth', middleware: 'auth' }, () => { route.post('/refresh', 'Actions/Auth/RefreshTokenAction') route.delete('/tokens/{id}', 'Actions/Auth/RevokeTokenAction') }) // 单条路由链式追加中间件（可带参数） route.get('/admin', 'Actions/AdminAction') .middleware('auth') .middleware('abilities:admin')

中间件在 app/Middleware.ts 中集中注册，Stacks 内置了auth、guest、api、team、throttle（限流）、abilities/can（能力校验）、env（环境限定）等常用中间件，覆盖绝大多数鉴权与风控场景。

四、路由匹配优先级：用户路由如何覆盖框架默认路由

这是 Stacks 路由系统最有意思的设计之一。框架自带登录注册、仪表盘、电商、CMS 等默认路由包（位于 storage/framework/defaults/routes/），而 bun-router 采用先注册者生效（first-registration-wins）策略：

1. 用户路由先加载——你在routes/api.ts里定义的同路径路由永远优先；
2. 框架默认路由随后补齐，不会覆盖你的实现；
3. 因此不要直接编辑框架路由文件，要改行为就在自己的路由文件里重新声明同方法同路径的路由。

举个真实例子：框架的 storage/framework/defaults/routes/auth.ts 给登录、注册加了限流（如route.post('/login', 'Actions/Auth/LoginAction').rateLimit(5, 'minute')）；如果你的业务需要更宽松的限流，只需在 routes/api.ts 里重新注册POST /login即可接管。

五、进阶技巧：版本化 API、通配路由与优先级排序

版本化 API：让 /v1 与 /v2 并存

版本化是文件式路由的天然优势——新建一个routes/v2.ts文件，再在注册表登记'v2': 'v2'，即刻拥有独立的/v2/*命名空间，新旧接口互不干扰、可灰度可回滚。

通配路由与可选参数

// 通配符：匹配 /docs 下任意子路径 route.get('/docs/{path}', 'Actions/DocsAction').where('path', '.*') // 可选参数：当前推荐拆成两条路由 route.get('/posts', 'Actions/Post/IndexAction') route.get('/posts/{category}', 'Actions/Post/IndexAction')

路由优先级：具体路由排前面

路由按定义顺序匹配，记住一个排序口诀——先具体、后参数、最后兜底：

route.get('/users/me', 'Actions/User/CurrentUserAction') // 1. 具体路径 route.get('/users/{id}', 'Actions/User/ShowAction') // 2. 参数路由 route.get('/users/{path}', 'Actions/User/FallbackAction') // 3. 通配兜底

六、开箱即用的内置路由与开发利器

• 🩺健康检查：一行route.health()生成GET /health，返回服务状态 JSON，可直接对接监控告警；
• 📧邮件预览：开发环境下框架自动挂载/_stacks/mail/preview/*路由，浏览器里实时预览app/Mail/下的所有邮件模板（生产环境自动 404，杜绝预览面泄露）；
• 🛒默认路由包：登录/2FA、仪表盘、电商、表单、CMS 等路由由框架按需装配，应用无需手写——上图的仪表盘页面就是框架默认路由直接提供的能力；
• 📄智能 robots.txt：框架自动在非生产环境屏蔽爬虫收录，预览部署不会被搜索引擎索引。

七、新手速查表：Stacks 路由系统核心概念一览

💡新手落地建议：从 routes/api.ts 开始加第一条路由route.get('/hello', () => response.text('hello world'))，跑通后再按"资源拆 Controller、动作拆 Action"的思路逐步迁移，最后用路由组收敛权限前缀。

八、延伸阅读

• 路由原理与请求助手方法：storage/framework/core/router/src/（路由核心源码，含 stacks-router.ts、route-loader.ts）
• 路由相关文档：docs/basics/routing.md、docs/packages/router.md
• 路由测试示例：storage/framework/core/router/tests/route-loader.test.ts

掌握文件式路由与 Laravel 风格路由的分层协作后，你就拥有了在 Stacks 中组织任意复杂度 API 的能力——从第一行route.get到多版本、多租户的大型服务，路由结构始终清晰可控。

【免费下载链接】stacksModern, performant, optimized for DX & AX. Develop powerful apps, clouds & framework-agnostic libraries—faster.项目地址: https://gitcode.com/gh_mirrors/stack/stacks