admin/verify
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bb802e765c651e78f585db55cda0ec487e6fa73f
verify/backend/docs/API.md
T
Admin afe67d704e Initial commit: 网络验证平台
2026-04-27 17:22:56 +08:00

11 KiB
Raw Blame History

应用对接 API 文档

概述

本文档描述了开发者应用程序对接网络验证平台的 API 接口。所有 API 请求的基础路径为：

http://your-domain:8080/api/v1/app/{appKey}

其中 {appKey} 为开发者在后台创建应用时获取的应用密钥。

通用说明

请求格式

  • 所有请求使用 JSON 格式
  • Content-Type: application/json

响应格式

{
  "code": 200,
  "message": "success",
  "data": {}
}

错误码

错误码 说明
200 成功
400 参数错误
404 资源不存在
500 服务器错误

应用信息接口

获取应用信息

获取应用的基本信息。

请求

GET /api/v1/app/{appKey}/info

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "应用名称",
    "description": "应用描述",
    "status": "active"
  }
}

检查更新

检查应用是否有新版本。

请求

GET /api/v1/app/{appKey}/check-update?version=1.0.0

参数

参数名 类型 必填 说明
version string 否 当前客户端版本号

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "has_update": true,
    "latest_version": "1.0.1",
    "download_url": "https://example.com/download/1.0.1",
    "update_notes": "修复若干bug",
    "update_strategy": "optional",
    "update_method": "manual"
  }
}

响应字段说明

字段名 类型 说明
has_update boolean 是否有更新
latest_version string 最新版本号
download_url string 下载地址
update_notes string 更新说明
update_strategy string 更新策略：optional(可选更新) 或 force(强制更新)
update_method string 更新方式：auto(自动更新) 或 manual(手动更新)

获取公告列表

获取应用的公告列表。

请求

GET /api/v1/app/{appKey}/announcements

响应

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "title": "公告标题",
      "content": "公告内容",
      "type": "info",
      "priority": "normal",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

用户认证接口

用户注册

注册新用户。

请求

POST /api/v1/app/{appKey}/register

请求体

{
  "username": "testuser",
  "password": "123456",
  "device_id": "DEVICE_001"
}
参数名 类型 必填 说明
username string 是 用户名
password string 是 密码
device_id string 否 设备ID

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "user_id": 1,
    "token": ""
  }
}

用户登录

用户登录验证。

请求

POST /api/v1/app/{appKey}/login

请求体

{
  "username": "testuser",
  "password": "123456",
  "device_id": "DEVICE_001"
}
参数名 类型 必填 说明
username string 是 用户名
password string 是 密码
device_id string 否 设备ID

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "user_id": 1,
    "token": ""
  }
}

账户管理接口

获取账户信息

获取用户账户详细信息。

请求

GET /api/v1/app/{appKey}/account

请求体

{
  "user_id": 1
}
参数名 类型 必填 说明
user_id uint 是 用户ID

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "user_id": 1,
    "username": "testuser",
    "expire_time": "2024-12-31T23:59:59Z",
    "status": "active"
  }
}

心跳检测

客户端心跳检测，保持在线状态。

请求

POST /api/v1/app/{appKey}/heartbeat

请求体

{
  "user_id": 1
}
参数名 类型 必填 说明
user_id uint 是 用户ID

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "message": "心跳成功"
  }
}

充值与试用接口

卡密充值

使用卡密为账户充值。

请求

POST /api/v1/app/{appKey}/recharge

请求体

{
  "user_id": 1,
  "card_key": "CARD_KEY_123456"
}
参数名 类型 必填 说明
user_id uint 是 用户ID
card_key string 是 卡密

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "message": "充值成功",
    "value": 30
  }
}

试用申请

申请试用功能。

请求

POST /api/v1/app/{appKey}/trial

请求体

{
  "user_id": 1
}
参数名 类型 必填 说明
user_id uint 是 用户ID

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "message": "试用成功",
    "duration": 7
  }
}

设备管理接口

获取设备列表

获取用户绑定的设备列表。

请求

GET /api/v1/app/{appKey}/devices

请求体

{
  "user_id": 1
}
参数名 类型 必填 说明
user_id uint 是 用户ID

响应

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "device_id": "DEVICE_001",
      "user_id": 1
    }
  ]
}

解绑设备

解绑指定设备。

请求

POST /api/v1/app/{appKey}/unbind-device

请求体

{
  "user_id": 1,
  "device_id": "DEVICE_001"
}
参数名 类型 必填 说明
user_id uint 是 用户ID
device_id string 是 设备ID

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "message": "解绑成功"
  }
}

云端数据接口

注意：云端数据接口需要用户登录认证，需要在请求头中携带JWT token：

Authorization: Bearer {token}

获取云端常量

获取应用设置的云端常量。

请求

GET /api/v1/app/{appKey}/constants

响应

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "常量名称",
      "key": "CONSTANT_KEY",
      "value": "常量值",
      "var_type": "string",
      "description": "常量描述"
    }
  ]
}

获取指定云端常量

根据key获取指定的云端常量。

请求

GET /api/v1/app/{appKey}/constants/{key}

路径参数

参数名 类型 必填 说明
key string 是 常量key

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "常量名称",
    "key": "CONSTANT_KEY",
    "value": "常量值",
    "var_type": "string",
    "description": "常量描述"
  }
}

获取云端变量

获取用户的云端变量。

请求

GET /api/v1/app/{appKey}/variables

响应

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "变量名称",
      "key": "VARIABLE_KEY",
      "default_value": "默认值",
      "var_type": "string",
      "scope": "user",
      "description": "变量描述"
    }
  ]
}

获取指定云端变量

根据key获取指定的云端变量。

请求

GET /api/v1/app/{appKey}/variables/{key}

路径参数

参数名 类型 必填 说明
key string 是 变量key

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "变量名称",
    "key": "VARIABLE_KEY",
    "default_value": "默认值",
    "var_type": "string",
    "scope": "user",
    "description": "变量描述"
  }
}

更新云端变量

更新用户的云端变量。

请求

POST /api/v1/app/{appKey}/variables

请求体

{
  "variables": {
    "key1": "value1",
    "key2": "value2"
  }
}
参数名 类型 必填 说明
variables object 是 变量键值对

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "message": "更新成功"
  }
}

调用云端函数

调用云端自定义函数。

请求

POST /api/v1/app/{appKey}/call-function

请求体

{
  "name": "function_name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}
参数名 类型 必填 说明
name string 是 函数名称
params object 否 函数参数

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "result": null
  }
}

动态代码接口

注意：动态代码接口需要用户登录认证，需要在请求头中携带JWT token：

Authorization: Bearer {token}

获取动态代码

获取应用的动态代码。

请求

GET /api/v1/app/{appKey}/dynamic-code

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "code": "function hello() {\n  return 'Hello World';\n}"
  }
}

更新动态代码

更新应用的动态代码。

请求

POST /api/v1/app/{appKey}/dynamic-code

请求体

{
  "code": "function hello() {\n  return 'Hello World';\n}"
}
参数名 类型 必填 说明
code string 是 Goja代码（JavaScript语法）

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "message": "更新成功"
  }
}

说明

  • 动态代码使用Goja引擎执行（Go语言的JavaScript实现）
  • 支持完整的JavaScript语法
  • 代码执行环境受限，无法访问系统资源
  • 建议代码简洁高效，避免复杂逻辑

错误响应示例

应用不存在

{
  "code": 404,
  "message": "应用不存在",
  "data": null
}

参数错误

{
  "code": 400,
  "message": "参数错误",
  "data": null
}

用户不存在

{
  "code": 404,
  "message": "用户不存在",
  "data": null
}

卡密已使用

{
  "code": 400,
  "message": "卡密已使用",
  "data": null
}

接入流程

  1. 创建应用：在开发者后台创建应用，获取 appKey 和 secretKey
  2. 配置应用：设置应用的绑定类型、最大设备数、试用功能等
  3. 创建卡密类型：根据业务需求创建卡密类型（订阅/计时/点卡）
  4. 生成卡密：生成卡密供用户充值使用
  5. 客户端对接：按照本文档进行客户端开发

安全建议

  1. HTTPS：生产环境建议使用 HTTPS 加密传输
  2. 签名验证：敏感操作建议添加签名验证
  3. 频率限制：建议对 API 调用频率进行限制
  4. 数据加密：敏感数据建议加密存储和传输

版本历史

版本 日期 说明
1.1.0 2024-03-10 新增动态代码接口（使用Goja引擎）
1.0.0 2024-01-01 初始版本
Reference in New Issue View Git Blame Copy Permalink