wuyuan/ClassworksKV

Fork 0

mirror of https://github.com/ZeroCatDev/ClassworksKV.git synced 2025-10-22 02:03:11 +00:00

SunWuyuan 521522c1d2

更新到一半

2025-10-02 12:07:50 +08:00

13 KiB

Raw Blame History

API 使用示例 - cURL

本文档提供所有API接口的完整cURL示例。

环境变量设置

# 设置基础URL和站点密钥
export BASE_URL="http://localhost:3030"
export SITE_KEY="your-site-key-here"

1. 应用管理 API

1.1 获取应用列表

# 基本查询
curl -X GET "http://localhost:3030/apps" \
  -H "x-site-key: ${SITE_KEY}"

# 带分页和搜索
curl -X GET "http://localhost:3030/apps?limit=10&skip=0&search=my-app" \
  -H "x-site-key: ${SITE_KEY}"

响应示例:

{
  "apps": [
    {
      "id": 1,
      "name": "我的应用",
      "description": "应用描述",
      "developerName": "开发者名称",
      "developerLink": "https://developer.com",
      "homepageLink": "https://app.com",
      "iconHash": "abc123",
      "metadata": {},
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "skip": 0
}

1.2 获取单个应用详情

curl -X GET "http://localhost:3030/apps/1" \
  -H "x-site-key: ${SITE_KEY}"

响应示例:

{
  "id": 1,
  "name": "我的应用",
  "description": "应用描述",
  "developerName": "开发者名称",
  "developerLink": "https://developer.com",
  "homepageLink": "https://app.com",
  "iconHash": "abc123",
  "metadata": {},
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z"
}

1.4 获取应用的所有安装记录

curl -X GET "http://localhost:3030/apps/1/installations?limit=10&skip=0" \
  -H "x-site-key: ${SITE_KEY}"

响应示例:

{
  "appId": 1,
  "installations": [
    {
      "id": "clx1234567890",
      "token": "a1b2c3d4e5f6...",
      "device": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "name": "我的设备"
      },
      "note": "完整访问",
      "installedAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "skip": 0
}

2. Token 管理 API

2.1 获取设备的所有Token

curl -X GET "http://localhost:3030/apps/devices/550e8400-e29b-41d4-a716-446655440000/tokens" \
  -H "x-site-key: ${SITE_KEY}"

响应示例:

{
  "deviceUuid": "550e8400-e29b-41d4-a716-446655440000",
  "deviceName": "我的设备",
  "tokens": [
    {
      "id": "clx1234567890",
      "token": "a1b2c3d4e5f6...",
      "app": {
        "id": 1,
        "name": "我的应用",
        "description": "应用描述",
        "developerName": "开发者",
        "iconHash": "abc123"
      },
      "note": "完整访问",
      "installedAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "total": 1
}

2.2 撤销Token

curl -X DELETE "http://localhost:3030/apps/tokens/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "x-site-key: ${SITE_KEY}"

成功响应: HTTP 204 No Content

错误响应:

{
  "statusCode": 404,
  "message": "Token不存在"
}

3. KV 操作 API（需要Token）

设置Token环境变量:

export TOKEN="a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"

3.1 获取所有键（含元数据）

# 基本查询
curl -X GET "http://localhost:3030/kv" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}"

# 带分页和排序
curl -X GET "http://localhost:3030/kv?sortBy=key&sortDir=asc&limit=50&skip=0" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}"

# 按更新时间排序
curl -X GET "http://localhost:3030/kv?sortBy=updatedAt&sortDir=desc&limit=20" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}"

响应示例:

{
  "items": [
    {
      "deviceId": 1,
      "key": "user.profile",
      "metadata": {
        "creatorIp": "192.168.1.1",
        "createdAt": "2025-01-01T00:00:00.000Z",
        "updatedAt": "2025-01-01T00:00:00.000Z"
      }
    }
  ],
  "total_rows": 1,
  "load_more": "/kv?sortBy=key&sortDir=asc&limit=50&skip=50"
}

3.2 获取键名列表（仅键名）

curl -X GET "http://localhost:3030/kv/_keys" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}"

# 带分页
curl -X GET "http://localhost:3030/kv/_keys?limit=100&skip=0" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}"

响应示例:

{
  "keys": [
    "user.profile",
    "user.settings",
    "app.config"
  ],
  "total_rows": 3,
  "current_page": {
    "limit": 100,
    "skip": 0,
    "count": 3
  }
}

3.3 获取键值

# 使用 Authorization header（推荐）
curl -X GET "http://localhost:3030/kv/user.profile" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}"

# 使用 query 参数
curl -X GET "http://localhost:3030/kv/user.profile?token=${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}"

响应示例:

{
  "name": "张三",
  "email": "zhangsan@example.com",
  "avatar": "https://example.com/avatar.jpg",
  "preferences": {
    "theme": "dark",
    "language": "zh-CN"
  }
}

错误响应（键不存在）:

{
  "statusCode": 404,
  "message": "未找到键名为 'user.profile' 的记录"
}

3.4 获取键的元数据

curl -X GET "http://localhost:3030/kv/user.profile/metadata" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}"

响应示例:

{
  "deviceId": 1,
  "key": "user.profile",
  "metadata": {
    "creatorIp": "192.168.1.1",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T12:30:00.000Z"
  }
}

3.5 创建/更新键值

# 创建新键
curl -X POST "http://localhost:3030/kv/user.profile" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "x-site-key: ${SITE_KEY}" \
  -d '{
    "name": "张三",
    "email": "zhangsan@example.com",
    "avatar": "https://example.com/avatar.jpg"
  }'

# 更新已存在的键
curl -X POST "http://localhost:3030/kv/user.profile" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "x-site-key: ${SITE_KEY}" \
  -d '{
    "name": "张三",
    "email": "newemail@example.com",
    "avatar": "https://example.com/new-avatar.jpg",
    "updatedBy": "admin"
  }'

# 存储数组
curl -X POST "http://localhost:3030/kv/user.tags" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "x-site-key: ${SITE_KEY}" \
  -d '["developer", "admin", "vip"]'

# 存储嵌套对象
curl -X POST "http://localhost:3030/kv/app.config" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "x-site-key: ${SITE_KEY}" \
  -d '{
    "database": {
      "host": "localhost",
      "port": 3306,
      "name": "mydb"
    },
    "cache": {
      "enabled": true,
      "ttl": 3600
    }
  }'

响应示例（创建）:

{
  "deviceId": 1,
  "key": "user.profile",
  "created": true,
  "updatedAt": "2025-01-01T00:00:00.000Z"
}

响应示例（更新）:

{
  "deviceId": 1,
  "key": "user.profile",
  "created": false,
  "updatedAt": "2025-01-01T12:30:00.000Z"
}

3.6 批量导入键值对

curl -X POST "http://localhost:3030/kv/_batchimport" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "x-site-key: ${SITE_KEY}" \
  -d '{
    "user.profile": {
      "name": "张三",
      "email": "zhangsan@example.com"
    },
    "user.settings": {
      "theme": "dark",
      "language": "zh-CN"
    },
    "app.config": {
      "version": "1.0.0",
      "debug": false
    }
  }'

响应示例:

{
  "deviceId": 1,
  "total": 3,
  "successful": 3,
  "failed": 0,
  "results": [
    {
      "key": "user.profile",
      "created": true
    },
    {
      "key": "user.settings",
      "created": true
    },
    {
      "key": "app.config",
      "created": false
    }
  ]
}

部分失败响应:

{
  "deviceId": 1,
  "total": 3,
  "successful": 2,
  "failed": 1,
  "results": [
    {
      "key": "user.profile",
      "created": true
    },
    {
      "key": "user.settings",
      "created": true
    }
  ],
  "errors": [
    {
      "key": "invalid.key",
      "error": "验证失败"
    }
  ]
}

3.7 删除键值对

curl -X DELETE "http://localhost:3030/kv/user.profile" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}"

成功响应: HTTP 204 No Content

错误响应（键不存在）:

{
  "statusCode": 404,
  "message": "未找到键名为 'user.profile' 的记录"
}

4. 完整工作流示例

场景：应用首次访问设备的KV存储

#!/bin/bash

# 1. 设置环境变量
export BASE_URL="http://localhost:3030"
export SITE_KEY="your-site-key"
export APP_ID="1"
export DEVICE_UUID="550e8400-e29b-41d4-a716-446655440000"
export DEVICE_PASSWORD="my-password"

# 2. 为应用授权获取token
echo "正在授权应用..."
RESPONSE=$(curl -s -X POST "http://localhost:3030/apps/${APP_ID}/authorize" \
  -H "Content-Type: application/json" \
  -H "x-site-key: ${SITE_KEY}" \
  -d "{
    \"deviceUuid\": \"${DEVICE_UUID}\",
    \"password\": \"${DEVICE_PASSWORD}\",
    \"readOnly\": false,
    \"note\": \"自动授权\"
  }")

# 3. 提取token
TOKEN=$(echo $RESPONSE | jq -r '.token')
echo "获取到Token: ${TOKEN:0:20}..."

# 4. 写入数据
echo "写入用户配置..."
curl -X POST "http://localhost:3030/kv/user.config" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "x-site-key: ${SITE_KEY}" \
  -d '{
    "theme": "dark",
    "notifications": true,
    "language": "zh-CN"
  }'

# 5. 读取数据
echo "读取用户配置..."
curl -X GET "http://localhost:3030/kv/user.config" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}"

# 6. 获取所有键名
echo "获取所有键名..."
curl -X GET "http://localhost:3030/kv/_keys" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}"

# 7. 批量导入数据
echo "批量导入数据..."
curl -X POST "http://localhost:3030/kv/_batchimport" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "x-site-key: ${SITE_KEY}" \
  -d '{
    "user.profile": {"name": "张三", "age": 25},
    "user.preferences": {"color": "blue"},
    "app.version": {"current": "1.0.0"}
  }'

echo "完成！"

5. 错误处理示例

5.1 Token认证失败

# 使用无效token
curl -X GET "http://localhost:3030/kv/mykey" \
  -H "Authorization: Bearer invalid-token" \
  -H "x-site-key: ${SITE_KEY}"

响应:

{
  "statusCode": 401,
  "message": "无效的身份验证令牌"
}

5.2 缺少Token

curl -X GET "http://localhost:3030/kv/mykey" \
  -H "x-site-key: ${SITE_KEY}"

响应:

{
  "statusCode": 401,
  "message": "未提供身份验证令牌"
}

5.3 站点密钥错误

curl -X GET "http://localhost:3030/apps" \
  -H "x-site-key: wrong-key"

响应:

{
  "statusCode": 401,
  "message": "无效的站点密钥"
}

5.4 设备不存在

curl -X POST "http://localhost:3030/apps/1/authorize" \
  -H "Content-Type: application/json" \
  -H "x-site-key: ${SITE_KEY}" \
  -d '{
    "deviceUuid": "non-existent-uuid"
  }'

响应:

{
  "statusCode": 404,
  "message": "设备不存在"
}

6. 高级用例

6.1 使用jq处理响应

# 提取所有键名
curl -s -X GET "http://localhost:3030/kv/_keys" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}" \
  | jq -r '.keys[]'

# 获取token并保存
TOKEN=$(curl -s -X POST "http://localhost:3030/apps/1/authorize" \
  -H "Content-Type: application/json" \
  -H "x-site-key: ${SITE_KEY}" \
  -d '{"deviceUuid":"550e8400-e29b-41d4-a716-446655440000"}' \
  | jq -r '.token')

# 格式化输出
curl -s -X GET "http://localhost:3030/kv/user.profile" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}" \
  | jq '.'

6.2 循环批量操作

# 批量创建键值对
for i in {1..10}; do
  curl -X POST "http://localhost:3030/kv/item.${i}" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Content-Type: application/json" \
    -H "x-site-key: ${SITE_KEY}" \
    -d "{\"id\": ${i}, \"name\": \"Item ${i}\"}"
  echo "Created item.${i}"
done

# 批量读取
for key in user.profile user.settings app.config; do
  echo "Reading ${key}:"
  curl -s -X GET "http://localhost:3030/kv/${key}" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "x-site-key: ${SITE_KEY}" \
    | jq '.'
done

6.3 条件更新模式

# 读取当前值
CURRENT=$(curl -s -X GET "http://localhost:3030/kv/counter" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}")

# 修改值
NEW_VALUE=$(echo $CURRENT | jq '.count += 1')

# 写回
curl -X POST "http://localhost:3030/kv/counter" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "x-site-key: ${SITE_KEY}" \
  -d "${NEW_VALUE}"

7. 性能测试

7.1 并发请求测试

# 使用 xargs 进行并发测试
seq 1 10 | xargs -P 10 -I {} curl -s -X GET "http://localhost:3030/kv/test.key" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}" \
  -o /dev/null -w "Request {}: %{http_code} in %{time_total}s\n"

7.2 响应时间测试

# 测量单个请求时间
curl -X GET "http://localhost:3030/kv/user.profile" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-site-key: ${SITE_KEY}" \
  -w "\nTotal time: %{time_total}s\n" \
  -o /dev/null -s

13 KiB Raw Blame History Unescape Escape

API 使用示例 - cURL

环境变量设置

1. 应用管理 API

1.1 获取应用列表

1.2 获取单个应用详情

1.4 获取应用的所有安装记录

2. Token 管理 API

2.1 获取设备的所有Token

2.2 撤销Token

3. KV 操作 API（需要Token）

3.1 获取所有键（含元数据）

3.2 获取键名列表（仅键名）

3.3 获取键值

3.4 获取键的元数据

3.5 创建/更新键值

3.6 批量导入键值对

3.7 删除键值对

4. 完整工作流示例

场景：应用首次访问设备的KV存储

5. 错误处理示例

5.1 Token认证失败

5.2 缺少Token

5.3 站点密钥错误

5.4 设备不存在

6. 高级用例

6.1 使用jq处理响应

6.2 循环批量操作

6.3 条件更新模式

7. 性能测试

7.1 并发请求测试

7.2 响应时间测试

13 KiB

Raw Blame History