Stacks路由系统完全指南文件式路由与Laravel风格路由全解析【免费下载链接】stacksModern, performant, optimized for DX AX. Develop powerful apps, clouds framework-agnostic libraries—faster.项目地址: https://gitcode.com/gh_mirrors/stack/stacksStacks 路由系统是现代 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/ 目录官方脚手架内置了三个示例文件路由文件挂载前缀说明routes/api.ts/api应用 API 入口示例路由GET /api/helloroutes/v1.ts/v1版本化路由内置GET /v1/statusroutes/users.ts需在注册表声明自定义路由文件示例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 与 Controllermethod// Action 风格一个文件一个动作 route.get(/dashboard, Actions/DashboardAction) route.post(/login, Actions/Auth/LoginAction) // Controller 风格一个类多个方法 前是文件 后是方法名 route.get(/users, Controllers/UserControllerindex) route.get(/users/:id, Controllers/UserControllershow)Actionapp/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策略用户路由先加载——你在routes/api.ts里定义的同路径路由永远优先框架默认路由随后补齐不会覆盖你的实现因此不要直接编辑框架路由文件要改行为就在自己的路由文件里重新声明同方法同路径的路由。举个真实例子框架的 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/*.ts一个文件一批相关路由routes/路由注册表声明文件挂载前缀与全局中间件app/Routes.tsAction单文件单动作自带校验app/Actions/Controllermethod类方法式资源 CRUD 收拢一处app/Controllers/路由组route.group()批量加前缀/中间件—匹配优先级先注册者生效用户路由覆盖框架默认—中间件认证、限流、能力校验链式挂载app/Middleware.ts新手落地建议从 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考