YaoDocs

外观

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后缀
    ]
  }
}

工作机制 ​

规则匹配流程 ​

  1. 初始化阶段：

    • Yao启动时加载app.yao配置文件
    • 将rewrite规则编译为正则表达式数组
    • 规则按配置顺序排序（从上到下）

  2. 请求处理阶段：

    • 收到请求后，按顺序尝试匹配每个规则
    • 使用第一个匹配成功的规则
    • 根据规则进行路径转换和参数提取

参数处理方式 ​

  1. 位置参数 ($1, $2等)：

    json
    { "^\\/category\\/(.*)\\/(.*)$": "/$2/$1.sui" }
    • 访问/category/books/123 → 重定向到/123/books.sui
    • $1匹配"books"，$2匹配"123"

  2. 命名参数 ([param])：

    json
    { "^\\/product\\/(.*)$": "/detail/[pid].sui" }
    • 访问/product/abc123 → 重定向到/detail/[pid].sui
    • 参数存入params.pid = "abc123"

  3. 混合使用：

    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。

规则设计建议 ​

  1. 从特殊到通用：

    • 将最具体的规则放在前面
    • 通用规则（如默认路由）放在最后

  2. 参数命名：

    • 使用有意义的参数名（如[slug]而非[name]）
    • 保持命名一致性（全站使用相同的参数名表示相同含义）

  3. 性能优化：

    • 减少正则表达式复杂度
    • 将高频访问的路由放在前面
    • 避免过多嵌套分组

  4. 错误排查：

    • 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

注意事项 ​

  1. 文件存在性：

    • 所有重定向目标必须对应实际存在的.sui文件
    • 建议在部署前验证所有路由

  2. 性能影响：

    • 过多重定向规则会影响性能
    • 建议控制在20条规则以内

  3. 缓存问题：

    • 浏览器可能会缓存重定向
    • 开发时可禁用浏览器缓存

  4. 特殊字符：

    • 正则表达式中需正确转义特殊字符
    • 例如：\\/表示正斜杠

  5. 测试建议：

    • 为所有重定向规则编写单元测试
    • 覆盖各种边界情况

通过合理配置重定向规则，可以极大提高Yao SUI应用的灵活性和可维护性。建议结合具体业务需求，设计清晰的路由方案。