开放 API 文档

BaseForme 为每个应用提供独立的 KV 存储空间，对外只暴露 HTTP + JSON 接口：单键读写与删除、按 glob 模式列举与计数，写入时可设置 TTL 自动过期。一个 API Key 只能操作其所属应用的数据。

基础地址

http://localhost:3000由 .env 的 BASE_URL 配置，构建时固化

鉴权

Authorization: Bearer <API_KEY>所有 /openapi 接口都必须携带，缺少或无效时返回 401

快速开始

1. 在控制台的「API Keys」标签页为应用创建 Key，明文只在创建成功时显示一次。
2. 携带 Authorization: Bearer <API_KEY> 调用 insert 写入，再用 get 读回：
   写入后读回复制

   curl -X POST "http://localhost:3000/openapi/kv/insert" \
     -H "Authorization: Bearer $BASEFORME_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"key":"greeting","value":"hello","ttl":3600}'
   
   curl "http://localhost:3000/openapi/kv/get?key=greeting" \
     -H "Authorization: Bearer $BASEFORME_API_KEY"

   读取响应

   {
     "data": {
       "key": "greeting",
       "value": "hello",
       "expiresAt": 1763200060000
     }
   }

3. 响应统一为 { "data": ... } 或 { "error": "..." }，完整约定见「通用约定」。

接口一览

在控制台的「API Keys」标签页为应用创建 Key。Key 明文只在创建成功时显示一次，请及时复制保存；之后列表只展示脱敏值。

• 每个应用最多创建 10 个 API Key，默认永久有效。
• 每个 Key 只授权访问创建它时所属的应用，不能跨应用读写。
• Key 全局唯一；删除 Key 后，使用该 Key 的调用会立即返回 401。

Authorization: Bearer bfk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

也支持直接填入 Key（省略 Bearer 前缀）。缺少 Header 或 Key 无效时返回 401。

{ "data": { "count": 2 } }

{ "error": "键不存在" }

所有请求都需要携带 Authorization Header；POST 请求还需要设置 Content-Type: application/json，并使用合法的 JSON 对象作为请求体。

list 与 count 用 pattern 筛选键名。模式采用 glob 风格，匹配的是完整键名而不是子串：要按子串查找请写成 *keyword*。

通配符

示例

注意事项

• 模式匹配的是完整键名，不是子串搜索；要按子串查找，请在关键词前后各加一个星号。
• 匹配区分大小写，与数据库的 utf8mb4_bin 排序规则一致。
• 只作用于当前 API Key 所属应用，且查询前已清理过期键。
• 查询参数需要 URL 编码：? 写成 %3F、\ 写成 %5C、% 写成 %25、# 写成 %23；* 可以直接书写。
• pattern 首尾空白会被去除；空 pattern 返回 400，匹配全部请使用 *。
• 模式以 * 开头时无法命中键名索引，数据量大时建议先用 count 预估结果数量。

查询单个键

返回指定 key 的 value 与过期时间。键不存在、已过期，或在请求开始清理过期数据时被删除，都会返回 404。键名区分大小写，查询参数需要经过 URL 编码。

请求参数

响应字段

{
  "data": {
    "key": "greeting",
    "value": "hello",
    "expiresAt": 1763200060000
  }
}

状态码

• 200查询成功
• 400缺少 key，或 key 为空、超长
• 401缺少或无效的 API Key
• 404键不存在或已过期

特性与注意事项

• 只能访问该 API Key 所属应用的数据。
• 每次读写前都会先清理过期的键，因此不会返回已过期的数据。
• 键名区分大小写，greeting 与 Greeting 是两个不同的键。

curl "http://localhost:3000/openapi/kv/get?key=greeting" \
  -H "Authorization: Bearer $BASEFORME_API_KEY"

按模式列出键值

pattern 为必填参数，支持 glob 风格的通配符，语法见「模式匹配」小节。返回结果包含完整的 value，按 key 升序排列，暂不分页；结果集较大时请使用更精确的 pattern，或先用 count 预估数量。

请求参数

响应字段

{
  "data": [
    {
      "key": "user:1",
      "value": "alice",
      "expiresAt": null
    },
    {
      "key": "user:2",
      "value": "bob",
      "expiresAt": 1763200060000
    }
  ]
}

状态码

• 200查询成功，未匹配时返回空数组
• 400缺少 pattern 或 pattern 为空
• 401缺少或无效的 API Key

特性与注意事项

• 只能访问该 API Key 所属应用的数据。
• 只返回未过期的键；过期数据会在查询前被清理。
• 结果按 key 升序排列（二进制排序，区分大小写），暂不支持分页。

curl "http://localhost:3000/openapi/kv/list?pattern=user:*" \
  -H "Authorization: Bearer $BASEFORME_API_KEY"

统计匹配数量

匹配规则与 list 完全一致，但只返回数量。适合在批量读取前预估结果规模，或用于分页、限额等场景的前置判断。

请求参数

响应字段

{
  "data": {
    "count": 2
  }
}

状态码

• 200统计成功，无匹配时 count 为 0
• 400缺少 pattern 或 pattern 为空
• 401缺少或无效的 API Key

特性与注意事项

• 只能访问该 API Key 所属应用的数据。
• 只统计未过期的键；过期数据会在统计前被清理。
• pattern 的语法与转义规则见「模式匹配」小节。

curl "http://localhost:3000/openapi/kv/count?pattern=user:*" \
  -H "Authorization: Bearer $BASEFORME_API_KEY"

插入单个键值

force=true（默认）时执行新增或覆盖：键不存在返回 201，已存在则覆盖并返回 200。force=false 时只做新增：键已存在返回 409，原值保持不变。存在性判断在事务内加行锁完成，并发写入同一个键时行为稳定。

请求参数

{
  "key": "greeting",
  "value": "hello",
  "ttl": 60
}

响应字段

{
  "data": {
    "key": "greeting",
    "value": "hello",
    "expiresAt": 1763200060000,
    "created": true
  }
}

状态码

• 201新建成功
• 200覆盖已有键成功
• 400force、key、value 或 ttl 不合法
• 401缺少或无效的 API Key
• 409force=false 且键已存在，原值未被修改

特性与注意事项

• 只能访问该 API Key 所属应用的数据。
• 请求头需要包含 Content-Type: application/json。
• 已过期的键视为不存在：即使 force=false，也可以重新插入一个刚过期的键。
• force=false 的并发写入最多只有一个请求成功，其余请求返回 409。
• 非法 JSON 请求体同样返回 400，不会写入任何数据。

curl -X POST "http://localhost:3000/openapi/kv/insert?force=false" \
  -H "Authorization: Bearer $BASEFORME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"greeting","value":"hello","ttl":60}'

删除单个键

删除指定 key 及其值，操作不可恢复。键不存在或已过期时返回 404。公开 API 不提供批量删除，需要通过多次单点调用完成。

请求参数

{
  "key": "greeting"
}

响应字段

{
  "data": {
    "key": "greeting",
    "deleted": true
  }
}

状态码

• 200删除成功
• 400请求体不是合法 JSON 对象，或 key 为空、超长
• 401缺少或无效的 API Key
• 404键不存在或已过期

特性与注意事项

• 只能访问该 API Key 所属应用的数据。
• 请求头需要包含 Content-Type: application/json。
• 删除前会先清理过期数据，因此已过期的键同样返回 404。
• 删除不可恢复，请谨慎操作。

curl -X POST "http://localhost:3000/openapi/kv/delete" \
  -H "Authorization: Bearer $BASEFORME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"greeting"}'