模板配置使用说明（SystemConf type=50）

入口

1. 后台导航：APP管理 - 统一管理 - 模板配置

若看不到菜单入口，请联系管理员授权。

功能概述

目前只作为链接模板使用，但也可以是链接外的其他内容

模板配置用于统一管理可复用的“链接模板”。前端或服务端在返回配置数据时，凡是出现形如 $模板名. 的占位符，系统会自动替换为该模板下已配置的一个 URL（随机选取）。

适用场景：

• 自有广告 selfAd.link 中的跳转链接
• 公告、官网、分享等包配置项

模板示例：

模板名：example
URL 列表：
- https://example.com
- https://example.cn

使用：$example.?v=123 → 可能替换为 https://example.com?v=123 或 https://example.cn?v=123。

页面功能

1. 模板列表

• 展示已配置的模板（模板名、URL 列表）。
• 支持“添加模板”“编辑模板”“删除模板”。
• 支持“复制模板名”快捷操作，便于在其他配置中引用。

引用规范：以 $ 开头、以 . 结尾，例如：$example.。

2. 添加/编辑模板

• 模板名称：英文与下划线组合，建议简短好记；引用时区分大小写。
• URL 列表：每行一个；系统替换时按行随机选取一个。
• 提交后立即生效（若下游有 CDN/缓存，可能有延迟）。

3. 启用说明

• 模板配置保存后，conf 服务会在生成配置 JSON 前对文本中 $模板名. 进行替换；
• 不存在的模板名将保留原样

使用流程

1. 新增模板

1. 打开“链接模板配置”页面
2. 点击“添加模板”
3. 输入模板名（如：example）与 URL 列表（每行一条）
4. 提交保存

2. 引用模板

1. 在相关配置（如自有广告跳转链接）中使用 $模板名. 作为占位：
   • 例：$example.?v=123、https://api.xxx.com?target=$example.
2. 保存业务配置
3. 客户端获取到配置时，系统会自动替换为随机 URL（并保留前后拼接参数）

3. 修改/删除模板

1. 编辑可直接修改 URL 列表，保存后新请求将生效
2. 删除模板后，所有使用 $模板名. 的位置将无法替换，原样返回

配置说明

替换规则

• 识别模式：$ + 模板名（字母/数字/下划线，首字符为字母或下划线） + .
• 模板名合法正则：[a-zA-Z_][a-zA-Z0-9_]*
• 替换策略：从模板的 URL 列表中随机选择一个值替换整段 $模板名.
• 追加参数：$模板名. 后面的内容不变，如：$example./path?a=1 → https://example.com/path?a=1

生效范围

• gobook v12 返回的数据（如广告配置 selfAd.link）
• Android/iOS 配置输出路径（conf.go 中已接入）

注意事项

1. 模板名以 $ 开头、以 . 结尾引用，缺一不可（如：$example.）。
2. URL 列表至少配置 1 条；为空时不会替换。
3. 模板名不存在时保持原样，便于排查。
4. 替换为随机 URL，若需固定，请只配置一条 URL。
5. 变更后可能由于CDN或redis缓存会导致更新延迟，一般最多6小时内缓存会全部刷新。

最佳实践

自有广告跳转链接自动切换

1 新增配置项，比如 ad1_url

2 复制模板名称粘贴到自有广告的跳转链接配置项并保存

3 此时该广告将会随机使用其中某个跳转链接，如果要更新跳转链接只需更新模板内容即可

公告、官网等自动轮换

1 新增配置项，比如 chengzhi_web

2 复制模板名称粘贴到包配置中任何需要模板替换的字段

3 保存后打开app确认生效即可

** 注意：跑马灯内容的模板内容不建议有多项，因为会随机使用一项导致每次获取到的公告内容都不一样，这会导致APP一直弹窗的，如果需要显示多个URL建议使用多个配置项。

常见问题（FAQ）

Q: $example. 不生效？
A: 检查是否遗漏结尾的点号；检查是否存在名为 example 的模板且列表非空。

Q: 为什么每次跳转不一样？
A: 替换策略为“随机选取”。如需固定，请只配置一条 URL。

Q: 跑马灯设置模板后为什么公告会一直弹出？
A: APP是通过公告内容判断是否弹出的，是每次都随机使用一个模板URL公告内容不一致导致的。建议公告内的模板只配置一项。

Q: 可以在同一字段中使用多个模板吗？
A: 可以，例如：$a.?id=1&from=$b.。系统会分别替换两处。

Q: 模板名可以包含中文或连字符吗？
A: 不建议。模板名规则为英文字母、数字与下划线（首字符不可为数字）。

Q: 是否支持非链接位置替换？
A: 只要是文本内容并匹配 $模板名.，都会被替换，不限于链接字段。

Q: 删除模板会影响已发布配置吗？
A: 删除后，新请求将无法替换该模板名，原样返回；历史已下发到客户端的配置不受影响。