SUI URL路由配置
概述
SUI访问是基于文件系统的路径,通常一个URL对应一个sui页面,后缀名为.sui
。但在Yao SUI框架中,可以通过URL重定向(rewrite)机制,将多个URL映射到同一个页面,实现页面复用。这种方式特别适合以下场景:
- 多语言站点(如/en-US/about和/zh-CN/about指向同一个页面)
- 内容管理系统(如/blog/post-1和/news/post-1指向同一内容)
- API版本控制(如/api/v1/users和/api/v2/users)
- 维护旧URL兼容性
配置详解
在app.yao
配置文件中,通过public.rewrite
字段配置重定向规则。以下是一个完整配置示例,包含详细注释:
json
{
"public": {
// 基础配置
"disableGzip": false, // 是否禁用Gzip压缩
"sourceRoots": { "/public": "/data/templates/default" }, // 开发模式下的源文件映射
// 重定向规则(按优先级从高到低排序)
"rewrite": [
// 静态资源路由
{ "^\\/assets\\/(.*)$": "/assets/$1" }, // 匹配/assets/下的所有请求,保持原路径
// 内容页面路由(带命名参数)
{ "^\\/docs/(.*)$": "/docs/[name].sui" }, // 文档详情页,参数存入params.name
{ "^\\/blog/(.*)$": "/blog/[slug].sui" }, // 博客详情页,参数存入params.slug
{ "^\\/example/(.*)$": "/example/[id].sui" }, // 示例详情页,参数存入params.id
// 特殊文件路由
{ "^\\/install.sh$": "/install.sh.txt" }, // 安装脚本
{ "^\\/install.ps1$": "/install.ps1.txt" }, // PowerShell安装脚本
{ "^\\/sitemap.xml$": "/sitemap.xml" }, // 网站地图
// 多路由指向同一页面
{ "^\\/en-US(.*)$": "/index.sui" }, // 英文版路由
{ "^\\/components(.*)$": "/index.sui" }, // 组件库路由
{ "^\\/doc/(.*)$": "/index.sui" }, // 旧版文档路由兼容
// 默认路由规则(必须放在最后)
{ "^\\/(.*)$": "/$1.sui" } // 为所有路径添加.sui后缀
]
}
}
工作机制
规则匹配流程
初始化阶段:
- Yao启动时加载
app.yao
配置文件 - 将
rewrite
规则编译为正则表达式数组 - 规则按配置顺序排序(从上到下)
- Yao启动时加载
请求处理阶段:
- 收到请求后,按顺序尝试匹配每个规则
- 使用第一个匹配成功的规则
- 根据规则进行路径转换和参数提取
参数处理方式
位置参数 (
$1
,$2
等):json{ "^\\/category\\/(.*)\\/(.*)$": "/$2/$1.sui" }
- 访问
/category/books/123
→ 重定向到/123/books.sui
$1
匹配"books",$2
匹配"123"
- 访问
命名参数 (
[param]
):json{ "^\\/product\\/(.*)$": "/detail/[pid].sui" }
- 访问
/product/abc123
→ 重定向到/detail/[pid].sui
- 参数存入
params.pid = "abc123"
- 访问
混合使用:
json{ "^\\/(.*)\\/(.*)$": "/[$1]/[id].sui" }
- 访问
/user/123
→ 重定向到/[user]/[id].sui
- 参数存入:js
params = { user: 'user', // 来自$1 id: '123' // 来自$2 };
- 访问
最佳实践
调试
在url中使用debug参数或是**sui_disable_cache参数禁用页面缓存,?debug=true
或?**sui_disable_cache=true
。
规则设计建议
从特殊到通用:
- 将最具体的规则放在前面
- 通用规则(如默认路由)放在最后
参数命名:
- 使用有意义的参数名(如
[slug]
而非[name]
) - 保持命名一致性(全站使用相同的参数名表示相同含义)
- 使用有意义的参数名(如
性能优化:
- 减少正则表达式复杂度
- 将高频访问的路由放在前面
- 避免过多嵌套分组
错误排查:
- 404错误:检查目标文件是否存在
- 500错误:检查正则表达式语法
- 参数缺失:确认规则中的参数命名
常见问题
Q1: 规则不生效怎么办?
- 检查规则顺序(是否被前面的规则拦截)
- 验证正则表达式(可在正则测试工具中验证)
- 确认没有语法错误(如未转义的特殊字符)
Q2: 如何实现A/B测试路由?
json
{ "^\\/test\\/(.*)$": "/experiment/[variant].sui" }
- 访问
/test/v1
→ 重定向到/experiment/[variant].sui
- 在页面中通过
params.variant
获取版本号
Q3: 如何保留原始查询参数?
重定向会自动保留原始查询字符串:
- 访问
/old/path?key=value
→ 重定向到/new/path.sui?key=value
注意事项
文件存在性:
- 所有重定向目标必须对应实际存在的.sui文件
- 建议在部署前验证所有路由
性能影响:
- 过多重定向规则会影响性能
- 建议控制在20条规则以内
缓存问题:
- 浏览器可能会缓存重定向
- 开发时可禁用浏览器缓存
特殊字符:
- 正则表达式中需正确转义特殊字符
- 例如:
\\/
表示正斜杠
测试建议:
- 为所有重定向规则编写单元测试
- 覆盖各种边界情况
通过合理配置重定向规则,可以极大提高Yao SUI应用的灵活性和可维护性。建议结合具体业务需求,设计清晰的路由方案。