fesiong/anqicms/api-dev

AnQiCMS 前端 API 开发技能

本技能描述面向前台访客/前端 JS 的公共 API（前缀 /api，由 Iris 的 app.Party("/api", ParseUserToken) 注册，见 route/base.go）。它与后台管理 API（前缀 /system/api，走 Admin 鉴权）是两套不同的接口，不要混用。

基础规范

• 路径前缀：/api
• 格式：JSON（文件上传为 multipart）
• 鉴权 Header：token: <jwt>（也兼容 Authorization: Bearer <jwt> 与 cookie token）。不是 Admin（那是后台）。
• token 采用滑动轮换：需要续期时，新 token 放在响应头 `update-token` 里，前端应读取并替换本地 token。
• 登录成功后 token 在 data.token。
• 公共内容 API 需站点开启：带 CheckApiOpen 的只读内容接口（archive/category/tag/page/setting 等）只有在后台开启"API 访问"后才可用，否则返回未开放。
• 响应体：{ code, msg, data, total? }，total 仅列表接口返回。始终以 `code` 判定成败，HTTP 200 不代表成功。

响应码（定义于 config/constant.go）

分页（两套词表，按接口区分）

• 内容列表（archive/list、tag/list、tag/data/list、comment/list）：用 page + limit。limit 可为 "n" 或 "offset,n"，上限受后台 Content.MaxLimit 约束。page/list 只读 limit。
• 用户/订单/分销列表（favorite/list、orders、retailer/*）：用 current + pageSize（默认 20）。

公共只读 API（无需登录，需开启 API 访问）

内容

站点信息

认证与用户（无需登录的部分）

需登录 API（token Header + UserAuth）

用户中心

订单

分销（零售商）

交互（需开启 API 访问）

其它入口

注意：本站没有购物车（cart）接口，下单直接走 POST /api/order/create。历史文档里的 /api/cart/*、/api/orders/checkout 均不存在。

关键工作流

全局数据（页面布局用）

GET /api/setting/system  → 站点名称、SEO
GET /api/nav/list        → 导航
GET /api/banner/list     → 幻灯片
GET /api/setting/contact → 联系方式
GET /api/languages       → 多语言

下单流程（无购物车）

POST /api/order/create   → 创建订单（直接下单）
POST /api/order/payment  → 发起支付
GET  /api/payment/check  → 轮询支付结果

错误处理

try {
  const res = await fetch("/api/xxx", { headers: { token: localToken } });
  // token 轮换：优先用响应头里的新 token
  const rotated = res.headers.get("update-token");
  if (rotated) localToken = rotated;
  const json = await res.json();
  if (json.code === 0) {
    // 成功，使用 json.data（列表另有 json.total）
  } else if (json.code === 1001) {
    // 未登录/过期，跳转 /login
  } else {
    // 显示 json.msg（-1 失败、1002 无权限）
  }
} catch (e) {
  // 网络错误处理
}

完整的端点级参数与后台管理接口，用 api 意图（action=list/schema，默认关闭需显式开启）在线查询，或加载 anqicms-dev 技能。