5.7 公开接口

以下接口不需要登录态或 Bearer Token。公开写入类接口会通过短期签名 token 限制写入范围。

健康检查

GET /health
GET /health/simple

• /health：返回详细信息（数据库、缓存连通性、版本号）。
• /health/simple：只返回 200 OK，适合 LB 探活。

安装向导

安装未完成时访问任意 URL 都会被重定向到安装页，安装完成后以下接口失效。

首页

GET /

根据配置决定返回首页 HTML、重定向到管理后台，或跳转到默认短链接。

登录

POST /api/v1/auth/login

见「5.1 认证方式」。

短链接跳转

GET /{code}

• 命中：返回 302，Location 指向 original_url、高级路由目标 URL，或 A/B 测试变体目标 URL。
• 过期 / 禁用：渲染错误模板或返回 404。
• 记录点击事件（异步）。
• 命中运行中的 A/B 测试时，目标 URL 会追加 _dwz_abt 查询参数，用于后续转化反馈。
• code 只允许 [a-zA-Z0-9\-_.]+ 字符。

A/B 跳转示例：

https://example.com/page-a?_dwz_abt=<feedback_token>

A/B 测试转化反馈

POST /api/v1/public/ab_test_feedback
Content-Type: application/json

{
  "feedback_token": "<_dwz_abt 参数值>",
  "event_id": "order-202401150001",
  "value": 99.9,
  "currency": "CNY",
  "metadata": {
    "plan": "pro"
  },
  "occurred_at": "2024-01-15T10:30:00Z"
}

说明：

• feedback_token 必须来自短链 A/B 跳转目标 URL 的 _dwz_abt 参数。
• event_id 在同一 A/B 测试内幂等，重复提交不会重复计入转化。
• value 可用于累计转化价值，必须大于等于 0。
• currency 会被服务端转成大写。
• metadata 用于保存订单号、套餐、渠道等业务附加信息。
• token 无效、被篡改、过期，或绑定的实验/变体不存在时返回 401。

成功响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 10,
    "duplicate": false,
    "workspace_id": 1,
    "ab_test_id": 1,
    "variant_id": 2,
    "short_link_id": 5,
    "session_id": "ab_1_5_xxx",
    "event_id": "order-202401150001"
  }
}

落地页自动回传示例：

const token = new URLSearchParams(location.search).get('_dwz_abt');

if (token) {
  await fetch('https://your-domain.com/api/v1/public/ab_test_feedback', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      feedback_token: token,
      event_id: 'order-202401150001',
      value: 99.9,
      currency: 'CNY',
      metadata: {
        order_id: '202401150001',
        plan: 'pro'
      }
    })
  });
}

短链接预览

GET /preview/{code}

返回短链接对应的 HTML 预览页，展示目标 URL、标题、缩略图等，不触发点击统计。适合用户确认后再跳转的场景。