开发文档

模板语法概览

TradeAdmin 的前台由 pongo2（Django 风格）模板引擎驱动。模板就是一份普通的 HTML，标签写在 HTML 里，渲染时被替换成数据。文件名后缀必须是 .html；变量与字段严格区分大小写，字段首字母大写——{{ archive.Title }} 对，{{ archive.title }} 取不到。

1. 模板里能用的四类东西

标签与过滤器是进程级全局注册，一次注册全站可用；4 个全局函数挂在模板引擎实例上，只有前台渲染链路才有。

2. 单值标签的两种写法

判据是标签名后面第一个词是不是 with：是就回退去解析参数（直接把值输出到页面），不是就把它当成变量名（只赋值、页面什么都不出现）。

{% system with name='SiteName' %}

{% system siteName with name='SiteName' %}
{{ siteName }}

块标签（列表类）必须给变量名；闭合标签写 {% endarchiveList %} 即可，也可以写 {% endarchiveList articles %}——写了名字就必须和开头一致。只有 jsonLd（匿名块）与 jump（位置参数）不需要变量名。

3. 参数的四条硬规则

• with 必须写、必须小写。写了参数却漏写 with，绝大多数标签会在解析期直接报 Malformed xxx-tag arguments.，不是静默忽略。
• 参数名大小写敏感。moduleid=1 等于没写，必须写 moduleId。
• 字符串值必须加引号。裸写 name=Title 会被当变量解析，取不到就是空值而不是报错——这是最常见的「参数传了没反应」。
• 布尔参数只认关键字 true / false。render="true" 是字符串，标签按布尔读会得到 false。
• 未知参数被静默忽略：没有中心化的参数白名单，名字打错不报错、只是没生效。

4. 渲染上下文里的变量

带登录身份的请求会绕过静态缓存——会员态字段（是否收藏、是否已购）让页面「随人而变」，匿名访客看到的是缓存版本，登录会员看到的是现渲染版本。

5. 转义

模板目录与页面级覆盖

前台模板放在 resource/template/<模板名>/，模板自带的 css / js / 图片放在 resource/public/static/<模板名>/（对应网址 /static/<模板名>/…）。静态资源引用一律走 {% system with name='TemplateUrl' %}，换模板后路径才不会断。

resource/template/<模板名>/
├── config.json          # 模板包信息（后台「模板设计」列表显示用）
├── base.html            # 全站骨架：head / 导航 / 页脚 + {% block %} 挖坑
├── index/index.html     # 首页
├── article/{index,list,detail}.html  # 模块首页 / 分类列表 / 详情
├── product/{index,list,detail}.html  # 同上（目录名 = 模块别名）
├── case/{list,detail}.html           # 分类绑定用的自定义模板
├── page/{about,service,detail}.html  # 单页
├── search/index.html    # 搜索结果
├── tag/{index,list}.html  # 标签首页 / 标签详情
├── errors/404.html      # 404
└── partial/             # include 用的零件：面包屑 / 分页 / 侧栏

引擎取模板的三级优先

页面地址与模板文件的对应关系

列表里的模板按顺序找，第一个存在的就用；一个都没找到就走 404。{模块别名} 就是模块的 URL 别名（后台「内容模型」里可改可加），它既是网址里的那一段，也是模板目录名。

固定结构之外的页面怎么做

标签总览 35 个

共 35 个模板标签（34 个业务标签 + 覆写的 set），分 4 组。点击标签名可跳转到详细说明。

过滤器与全局函数同样做成了卡片，见下方 过滤器速查表 与 函数速查表 之后的卡片区。模板能拿到的数据，前台公开 API 基本都能拿到 —— API 的完整清单在 前台公开 API 一节。

自定义过滤器速查 19 个

用法一律是 {{ 值|名字 }} 或 {{ 值|名字:参数 }}——没有 |名字(a,b) 这种写法，参数只有一个位置，要传多值就写成逗号分隔的字符串由过滤器自己切。内置的 split / wordwrap 已被换成自研实现。

下表是一览；每一项的完整卡片（参数表、示例、注意事项）见下方「自定义过滤器」一节，卡片内容来自后台模型「模板过滤器与函数」，改文档只需改后台。

全局函数速查 4 个

必须写成函数调用（带括号，不是过滤器）：{{ stampToDate(item.CreatedTime, "2006-01-02") }}。

下表是一览；每一项的完整卡片见下方「全局函数」一节。

前台公开 API 概览

前台除了模板渲染，还能通过 /api 拿数据 —— 这是给无头前端、小程序、独立前端与外部采集用的。全站共 78 个端点：72 个契约端点（写在 server/api/api/ 下的接口定义）+ 6 个不走契约的原始处理器（微信 / 小程序回调、PayPal 返回页、插件反代）。另有 2 个页面级表单路由（/guestbook.html、/captcha）不在 /api 前缀下。

标签和 API 是同一套底层逻辑的两个出口：共用 internal/logic/cmsread 的查询与 internal/logic/cms/view 的视图，所以同一份数据的字段口径完全一致 —— 对照表见下方「API 与模板标签的关系」。

1. 地址怎么拼

站点地址 + /api + 端点路径

例：https://www.example.com/api/archive/list?moduleId=1&limit=10

• /api 前缀不是写死的：来自 server/manifest/config/config.yaml 的 router.api.prefix，由 utility/simple/simple.go:22 的 RouterPrefix 读出，路由注册在 server/internal/router/api.go:29。
• 契约（路径 / 方法 / 参数名 / 类型）按业务分目录放在 server/api/api/ 下：cms/ member/ order/ retailer/ pay/ google/ wechat/ weapp/ import/；控制器实现在 server/internal/controller/api/。

2. 请求要过四道闸，顺序是固定的

全部注册在 server/internal/router/api.go:28-75，顺序即下表从上到下。

这四道之外，还有一层全局中间件在更外层先跑（注册在 cmd/http.go:41-49，对全站生效）：Ctx → CORS → InstallGuard（未安装时把请求引到安装页）→ Blacklist（后台 IP 黑名单）→ DemoLimit（演示模式拦 POST）→ PreFilter（请求参数预处理）→ ResponseHandler（统一响应信封）。所以一个前台 API 请求的完整顺序是：

Blacklist → DemoLimit → PreFilter → ResponseHandler
    → CmsLimiter → CmsSite → ApiAuth → CmsApiOpen → 控制器

• CmsApiOpen 只管内容 API。会员登录注册、支付、微信 / 小程序、Google 登录、导入接口、分销、收银台、插件反代都不受它约束。所以「接口未启用」时，注册登录和下单照样能用，只有内容查询和评论留言会被挡。
• CmsApiOpen 读不到配置时按停用处理（保守失败），此时内容 API 一律拒绝。
• 被后台拉黑的 IP、演示模式下的 POST，都在最外层就被拦掉，返回的不是业务错误码。
• 只有 ResponseHandler 在最内层包住业务，负责把返回值包成下面第 4 条那个信封。

3. 谁要登录：白名单说了算

免登录路径写在 config.yaml 的 router.api.exceptLogin 里，判定函数是 internal/logic/middleware/init.go:165 的 IsExceptLogin。当前白名单共 30 条：

白名单是精确匹配，不是前缀匹配：写 /archive/list 就只放行这一个路径。要登录才能调的 cms 端点有 6 个（白名单 30 + 要登录 6 = 内容组 36 个，正好对上）：

4. 统一返回信封

所有 JSON 端点都走同一个信封（internal/library/response/response.go:41、模型定义在 internal/model/response.go:8）：

{
  "code": 0,
  "message": "操作成功",
  "data": { "...": "业务数据" },
  "timestamp": 1758600000,
  "traceID": "d0bb93048bc5c9164cdee845dcb7f820"
}

• code 为 0 才是成功。判断成败看 code，不要看 HTTP 状态码（多数业务错误 HTTP 仍是 200）。
• 出错时数据放在 error 字段，不是 data（code != 0 时 data 整个不出现）。调试模式下 error 里是错误堆栈。
• message 是给人看的中文提示，可能随版本改口径，不要用它做逻辑判断。

常见 code 取值（全部是 GoFrame 框架内置的 gcode 错误码，不是本项目自造的）：

5. 多站点、多语言怎么指定

解析逻辑全在 internal/logic/middleware/cms_site.go:29 的 CmsSite 里，按下面的顺序：

多语言的信号取法（cms_site.go:106）：cookie hl 优先，其次 query lang。顺序是先 cookie 后 query，所以用户切过一次语言之后，再带 ?lang= 访问不会生效 —— 这是刻意的，避免语言飘。

6. 限流：会返回非 JSON

判定在 internal/logic/sys/limiter.go:131 的 Check，总开关在后台「安全防护 → 请求限流」。几种拦截形态：

跳过限流的路径（同上文件 :134-149）：

• 含 /pay/notify 的路径 —— 支付回调绝不能被限流，否则平台重试遇 429 会造成订单状态不同步；
• 以 /api/mcp 结尾的路径 —— MCP 自带令牌桶；
• 以 /static、/uploads、/favicon.ico 开头的路径；
• 后台配置的「放行路径前缀」；蜘蛛（UA 命中蜘蛛库时）。

7. 通用参数约定

这几个参数在多个端点上反复出现，先集中说清楚，后面端点卡片里就不再重复解释。

8. 与模板标签的关系

模板标签和公开 API 不是两套实现 —— 它们共用同一批底层查询（internal/logic/cmsread）和同一批视图（internal/logic/cms/view）。完整对照表与「与参考实现的差异」见下方同名章节。

标签侧的完整参数表、坑与示例见本文前半部分的 标签总览；MCP 那套对外接口是独立体系（自带 token 鉴权，与 /api 不共用登录态），见 MCP 接入指南。

端点总览 78 个

共 78 个端点，分 6 组。点端点路径可跳到详细卡片（参数表、返回结构、curl 示例、注意事项都在那里）。

卡片内容来自后台模型「前台公开接口」，改文档只需改后台：分组顺序、组内顺序、参数表、返回结构、示例与注意事项全是后台字段。

参数表怎么读

前端怎么带登录态

1. 取令牌和传令牌

POST /api/member/login  {"username":"...","password":"..."}
→ data.token = "eyJhbGciOi..."

之后的请求带这个头：
Authorization: Bearer eyJhbGciOi...

这条链路上，令牌只认两种位置：Authorization 请求头，或 query 参数 authorization（internal/library/token/token.go:309）。

2. 跨域

站点与后台同域时不需要额外配置；前后端分离（比如小程序、独立前端）时在服务端配 CORS。带 Authorization 头属于「非简单请求」，浏览器会先发 OPTIONS 预检。

3. 调试建议

• 看 code 不看 HTTP 状态码（见「统一返回信封」）。
• 出错的细节在 error 字段里，message 只是给人看的提示。
• 每个响应都带 traceID，排查时拿它去后台「监控 → 接口日志」里对。
• Windows 控制台上中文会显示成乱码，把 curl 输出重定向到文件再用编辑器看。

curl 速查

把 BASE 换成你的站点地址即可（下面假定 http://127.0.0.1:8000）。

BASE=http://127.0.0.1:8000

# 1. 文档列表（第一页 10 条）
curl -s "$BASE/api/archive/list?limit=10&page=1"

# 2. 某分类下的文档（含子分类、按发布时间倒序）
curl -s "$BASE/api/archive/list?categoryId=3&order=created_time%20desc&limit=10"

# 3. 文档详情（带正文，正文渲染成 HTML）
curl -s "$BASE/api/archive/detail?id=101&render=true"

# 4. 按 URL 别名取文档
curl -s "$BASE/api/archive/detail?filename=hello-world"

# 5. 带密码的文档
curl -s "$BASE/api/archive/detail?id=101&password=123456"

# 6. 文档自定义字段
curl -s "$BASE/api/archive/params?id=101"

# 7. 筛选条件（价格 + 分类 + 「全部」）
curl -s "$BASE/api/archive/filters?moduleId=2&showPrice=true&showCategory=true&showAll=true"

# 8. 导航树
curl -s "$BASE/api/nav/list?typeId=1&showType=children"

# 9. 验证码
curl -s "$BASE/api/captcha?type=guestbook"

# 10. 提交留言（JSON）
curl -s -X POST "$BASE/api/guestbook.html" \
  -H 'Content-Type: application/json' \
  -d '{"user_name":"张三","contact":"13800000000","content":"你好"}'

# 11. 会员登录，取出 token
TOKEN=$(curl -s -X POST "$BASE/api/member/login" \
  -H 'Content-Type: application/json' \
  -d '{"username":"demo","password":"123456"}' | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')
echo "$TOKEN"

# 12. 带上 token 调需要登录的接口
curl -s "$BASE/api/favorite/list" -H "Authorization: Bearer $TOKEN"

# 13. 收藏 / 取消收藏（toggle）
curl -s -X POST "$BASE/api/favorite/add" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"archive_id":101}'

# 14. 指定站点（多站点场景）
curl -s "$BASE/api/archive/list?limit=5" -H 'Site-Id: 2'

# 15. 指定语言（多语言 single 形态）
curl -s "$BASE/api/archive/list?limit=5&lang=en"

# 16. 页面元数据（给 SPA 用）
curl -s "$BASE/api/metadata?path=/article/hello.html"

# 17. 导入接口（token 走 query）
curl -s "$BASE/api/import/categories?token=你的token&module_id=1"

API 与模板标签的关系

模板标签和公开 API 不是两套实现 —— 它们共用同一批底层查询（internal/logic/cmsread）和同一批视图（internal/logic/cms/view），所以同一份数据的字段口径完全一致。

与参考实现的差异

参考实现（安企 CMS）对应的是 controller/apiTag.go（31 个端点）。本站的差异：

API 常见问题

MCP 接入指南

MCP 对外接口把站点能力开放成 113 个工具、10 个分组。一条 URL + 一个 Token 就能让 Claude Desktop、Cursor、Cherry Studio、WorkBuddy 这类客户端直接读写站内数据。后台「智能与接入设置 → MCP 对外接口」按客户端提供「一键复制配置」。

1. 创建访问 Token

• 进入 /system/ → 智能与接入设置 → MCP 对外接口。
• 新建 Token，按需勾选工具分组（内容、分类与模型、SEO、会员与交易……）。
• 设置调用频率限制：单 Token 的 QPS 与日额度分别可配。
• 复制生成的 Token，只显示一次。

2. 填进客户端配置

{
  "mcpServers": {
    "tradeadmin": {
      "url": "https://your-site.com/mcp",
      "headers": {
"Authorization": "Bearer ta_你的Token"
      }
    }
  }
}

3. 验证连通

在客户端里问一句「列出 tradeadmin 有哪些工具」，能返回 113 个工具即接入成功。之后可以直接让 AI 干活：

# 你可以这样说：
帮我把「2026 秋季新品」这个分类下所有文章的标题重写得更口语一些，
改完先别发布，放进待发布。

运行时插件开发

插件放进 resource/addons/<name>/ 即被自动发现并安装，独立进程运行、崩溃不牵连宿主，语言不限（Go / Node / Python / PHP 均可）。宿主通过 HTTP 反向代理转发请求，并用 HMAC 签名身份头传递调用者身份。

1. 最小可用插件

{
  "name": "pay-gateway",
  "title": "示例支付网关",
  "version": "1.0.0",
  "author": "your-name",
  "command": ["./pay-gateway"],
  "prefix": "/addon/pay-gateway",
  "port": 18081,
  "hooks": ["pay.notify", "pay.refund"],
  "config": {
    "app_id": { "type": "text", "label": "应用 ID" },
    "app_secret": { "type": "password", "label": "应用密钥" }
  }
}

2. 身份头与鉴权

宿主转发请求时会附带以下请求头，插件应校验签名后再处理业务：

3. 生命周期

• 发现 —— 扫描 resource/addons/，读取 addon.json 并登记。
• 安装 / 启动 —— 以后台配置的 command 拉起独立进程，等待健康检查通过。
• 运行 —— 宿主按 prefix 反向代理到插件端口；插件回调宿主走内部接口。
• 停止 / 卸载 —— 发送终止信号，超时强杀；卸载可选是否保留配置。

常见坑速查

一个完整的列表页模板

把上面这些拼起来，一个带面包屑、列表与分页的列表页长这样。要点是 type="page" 必须写——它既决定按第几页取数，也负责生成分页对象。

{% extends "base.html" %}
{% block title %}<title>{% tdk with name="Title" siteName=true %}</title>{% endblock %}

{% block container %}
  {%- breadcrumb crumbs with title="False" %}
    {%- for item in crumbs %}<a href="{{ item.Link }}">{{ item.Name }}</a>{% endfor %}
  {%- endbreadcrumb %}

  {% archiveList archives with type="page" limit="10" %}
    {% for item in archives %}
      <a href="{{ item.Link }}">{{ item.Title }}</a>
      <time>{{ stampToDate(item.CreatedTime, "2006-01-02") }}</time>
      <p>{{ item.Description|truncatechars:40 }}</p>
    {% empty %}
      <li>该分类下暂无内容</li>
    {% endfor %}
  {% endarchiveList %}

  {% include "partial/pagination.html" %}
{% endblock %}

分页条本身在 partial/pagination.html 里，写法见 pagination。注意 {% empty %} 是空列表分支，比在外面套一层 {% if %} 干净。

常见问题