CMS 驱动工具站:分组路由与旧后端降级
工具分组页的 URL 应该由 CMS 的 groupCode 决定,但旧后端没有这个字段。门户的做法是编号兜底、canonical 收敛、缺 code 时 noindex。
分组名不能当 URL
工具站最常见的做法是 /toolkit/group/图片工具,看起来直观,问题很多:
- 分组名是给人看的,运营改一个字,URL 就变了;
- 同名分组无法区分,切换语言后名称也会变;
- 中文、空格、特殊字符要做 URL 编码,外链和日志都难看。
稳定的标识必须与展示名分离。数据库里用自增编号保证唯一,再补一个 ASCII 的 code 供 URL 使用:
| 字段 | 用途 | 是否稳定 |
|---|---|---|
id | 主键、关联外键 | 稳定,但不可读 |
code | URL、埋点、接口参数 | 稳定且可读,推荐 |
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;三件事要同时做,缺一件都会留下长期问题。
评论
还没有评论,来说两句吧