CMS 驱动工具站:分组路由与旧后端降级

2026-11-19 前端开发 有希 45 次瀏覽

工具分组页的 URL 应该由 CMS 的 groupCode 决定,但旧后端没有这个字段。门户的做法是编号兜底、canonical 收敛、缺 code 时 noindex。

分组名不能当 URL

工具站最常见的做法是 /toolkit/group/图片工具,看起来直观,问题很多:

  • 分组名是给人看的,运营改一个字,URL 就变了;
  • 同名分组无法区分,切换语言后名称也会变;
  • 中文、空格、特殊字符要做 URL 编码,外链和日志都难看。

稳定的标识必须与展示名分离。数据库里用自增编号保证唯一,再补一个 ASCII 的 code 供 URL 使用:

字段用途是否稳定
id主键、关联外键稳定,但不可读
codeURL、埋点、接口参数稳定且可读,推荐
name页面标题、导航可随时改,不能进 URL

URL 里能出现的是 code,不是 name。

分组是同一张表里的节点

早期分组只是工具表里的一个 group_name 字符串,同组每个工具都重复存一份,排序也隐式跟随组内第一个工具。改造后分组没有另起一张表,而是变成 tool 里的树节点:

  • tool.node_type 区分节点:1 是分组,2 是工具;
  • tool.parent_id 指向父节点,工具挂在分组下,分组还可以再挂子分组;
  • tool.code 在租户内唯一,分组的 code 就是 URL 里的标识;
  • 名称、简介和 SEO 文案放在 tool_i18n,分组和工具共用,按 locale 取值。

工具记录的 parent_id 直接就是分组编号,所以接口里的 groupId 和 parentId 是同一个值,不再需要 group_id 外键列。

App 接口返回工具列表时,按 parent_id 批量查父节点,再把分组字段复制到每个工具上,前端不用再发第二次请求:

if group, ok := groupMap[entity.ParentID]; ok {
    vo.GroupID = group.ID
    vo.GroupCode = group.Code
    vo.GroupName = group.Name
    vo.GroupDescription = group.Description
    vo.GroupSeoTitle = group.SeoTitle
    vo.GroupSeoKeywords = group.SeoKeywords
    vo.GroupSeoDescription = group.SeoDescription
}

排序语义也变了:先按分组 sort,未分组排最后;同组内再按工具 sort、最后按 id。前端拿到的是排好序的列表,只负责归拢,不再自己排序。

前端按 groupId 归组

前端归组一律用 groupId,不能用名称:

export function groupToolsById(tools: CmsTool[], fallbackName: string): ToolGroup[] {
  const result: ToolGroup[] = []
  for (const tool of tools) {
    const id = tool.groupId || 0
    const name = tool.groupName || fallbackName
    let group = result.find((item) => item.id === id)
    if (!group) {
      group = {
        id,
        name,
        code: tool.groupCode || '',
        description: tool.groupDescription || '',
        seoTitle: tool.groupSeoTitle || '',
        seoDescription: tool.groupSeoDescription || '',
        seoKeywords: tool.groupSeoKeywords || '',
        tools: []
      }
      result.push(group)
    }
    group.tools.push(tool)
  }
  return result
}

用名称归组会把同名分组错误合并,切换语言后名称变化还会打乱分组。分组级字段由后端复制到组内每个工具,取第一个即可,前提是同一个 groupId 下的这些字段必须一致。

URL 的编号兜底

groupCode 是后端较新才加的字段。旧构建里没有这个字段,如果前端只认 code,整组会渲染成纯文本,导航看起来像“全部禁用”,用户会以为页面坏了。

兜底函数因此写成“优先 code,退化为编号”:

export function groupPathKey(group: ToolGroup): string {
  if (group.code) {
    return group.code
  }
  return group.id > 0 ? String(group.id) : ''
}

分组页查找也兼容两种标识,先按 code 精确匹配,再按编号匹配:

export function findGroupByKey(groups: ToolGroup[], key: string): ToolGroup | null {
  const byCode = groups.find((group) => group.code && group.code === key)
  if (byCode) {
    return byCode
  }
  const id = Number(key)
  if (!Number.isInteger(id) || id <= 0) {
    return null
  }
  return groups.find((group) => group.id === id) ?? null
}

编号地址只是兼容入口,不是正式地址。它的可读性和 SEO 都差,所以不能让它被收录。

canonical 收敛到 code 地址

同一个分组可能以两种地址访问:/toolkit/group/image-tools 和 /toolkit/group/26。如果两个地址都输出自己的 canonical,搜索引擎会当成两个页面。

页面把 canonical 统一收敛到 code:

const canonicalKey = computed(() => group.value?.code || key.value)

usePortalSeo({
  path: () => `/toolkit/group/${canonicalKey.value}`,
  noindex: () => isSearching.value || !group.value?.code
})

没有 code 时只能保留编号地址,这时输出 noindex,follow,避免临时地址进索引。搜索态同理:?q= 派生的是薄内容,不应该被收录。

404 和接口错误要分开

分组页加载工具列表后,如果列表已就绪却找不到当前分组,应该抛 404;如果接口本身报错,不能当成 404:

const { data, error } = await useCmsTools('web')
const group = computed(() => findGroupByKey(groups.value, key.value))

if (!error.value && !group.value) {
  throw createError({
    statusCode: 404,
    statusMessage: t('pages.toolkit.groupNotFound'),
    fatal: true
  })
}

否则后端短暂不可用会把所有分组页变成 404,搜索引擎可能据此删掉已有页面。接口错误应该保留错误态,交给布局的重试入口。

SEO 文案走数据库优先

分组页的标题、简介和 SEO 字段优先取后台配置,没配才回退前端模板:

usePortalSeo({
  title: () => group.value?.seoTitle || t('pages.toolkit.groupSeoTitle', { name: group.value?.name ?? '' }),
  description: () => group.value?.seoDescription || fallbackDescription(),
  keywords: () => group.value?.seoKeywords || fallbackKeywords(),
  path: () => `/toolkit/group/${canonicalKey.value}`,
  noindex: () => isSearching.value || !group.value?.code
})

后台文案按 zh-CN、zh-TW、en-US 三种语言维护。繁体由 opencc 生成后必须人工校正,常见错词包括“位圖”应为“點陣圖”、“許可權”应为“權限”。分组简介还要和组内实际工具一致,不能拿旧分组文案套新工具。

sitemap 只收 code 地址

sitemap 生成分组路径时只取 groupCode:

const groupPaths = [...new Set(tools.map((item) => item.groupCode).filter(Boolean))].map(
  (code) => `/toolkit/group/${code}`
)

编号兜底地址不会出现在 sitemap 里,与页面上的 noindex 保持一致。工具详情页同理,按三种语言各输出一条;分组页有独立翻译,也按三语输出。

验证:两种地址都要看

curl -s http://[::1]:3001/toolkit/group/image-tools | grep -E 'rel="canonical"|robots'
curl -s http://[::1]:3001/toolkit/group/26 | grep -E 'rel="canonical"|robots'
curl -s http://[::1]:3001/sitemap.xml | grep -c 'toolkit/group/'
验证项期望结果
code 地址 canonical指向 /toolkit/group/image-tools
编号地址 canonical仍指向 code 地址(有 code 时)
编号地址 robots有 code 时正常;无 code 时 noindex,follow
sitemap 分组条数只包含 code 地址,不含纯编号地址
接口故障时保留错误态,不返回 404

后端字段变更时,可以先用 App 接口确认返回:

curl -s 'https://api.example.com/tools?platform=web&locale=zh-CN' \
  | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{const j=JSON.parse(d);const t=j.data.find(x=>x.groupId>0);console.log(t.groupId,t.groupCode,t.groupName)})"

如果 groupCode 是空串,说明后端仍是旧版本,前端会走编号兜底;这不是前端 bug,但升级后要重新确认 canonical 和 sitemap。

边界与常见错误

  • 编号兜底只解决“导航不可用”,不解决 SEO。上线后应尽快升级后端,让所有分组都有 code。
  • code 一旦发布不要改。它同时出现在 canonical、sitemap、埋点和外链里。
  • 分组页的搜索态不要收录,noindex 必须跟着 query 变化。
  • 接口错误和 404 必须分开,否则一次后端抖动会放大成收录损失。
  • 分组文案要按语言维护,不能把中文简介直接回退给英文页。

相关工具

用 nginx location 匹配测试 检查分组页的反向代理规则;用 Meta 标签生成器 对照 canonical 与 robots 输出。多语言 canonical 的完整规则见 Nuxt 多语言 SEO:canonical、hreflang 怎么配,更多前端文章在 前端开发分类。

FAQ

为什么分组页不直接用分组名做 URL?

分组名会改、会重名、切换语言还会变,不适合当稳定标识。URL 用 ASCII 的 code,展示名单独存。

旧后端没有 groupCode 怎么办?

前端用分组编号兜底,保证导航可用;同时对编号地址输出 noindex,等后端升级后 canonical 和 sitemap 会自动收敛到 code 地址。

编号地址需要 301 到 code 地址吗?

当前实现用 canonical 收敛,不强制跳转。这样旧链接仍能访问,又不会让搜索引擎收录两份。如果要彻底统一,可以在确认没有旧外链后加 301。

接口报错时为什么不能返回 404?

404 表示“页面不存在”,接口报错表示“暂时查不到”。把后者当 404,搜索引擎可能删除已收录页面。保留错误态并允许重试更安全。

结语:分组路由的稳定性靠 code,可用性靠编号兜底,收录正确性靠 canonical 和 noindex;三件事要同时做,缺一件都会留下长期问题。

評論

登入後即可參與評論

還沒有評論,來說兩句吧

相關文章