BaaS Engine Reference

系统架构与全局规范

Obsidian V25 是构建于 Cloudflare Workers 与 D1 SQLite 之上的百万级高并发 Serverless 引擎。所有 API 请求均强制采用 POST 方法与 application/json 载荷,以防范跨站请求伪造 (CSRF) 并最大化边缘路由性能。

全局特性约束:

  • 软删除保护:若表中存在 deleted_at 字段,查询和更新时引擎会自动注入 deleted_at IS NULL,除非手动设置 excludeDeleted: false
  • 全局速率限制:每个 IP 被底层防火墙限制为 300次/分钟。
  • 自动时间戳:写入数据时,引擎会自动维护 created_atupdated_at
  • 防崩溃全表扫描:禁止 /update/delete 在不传递 where 参数时运行。

身份认证 (Auth)

引擎支持两种身份级别的调用。所有请求必须携带 Authorization 头。

身份类型 请求头示例 权限范围
管理员 (Root) Bearer <ADMIN_KEY> 拥有绝对控制权。可调用 /issueApp/raw/telemetry。操作无视表名前缀沙盒。
应用/开发者 (App) Bearer <JWT_TOKEN> 通过 /issueApp 签发的 JWT 令牌。只能操作沙盒前缀(如 appID_users)内的表。
* 管理员可通过传递 X-DB-Binding: db_2 请求头来动态穿透路由,强制指定操作的物理集群节点。

查询语法树 (AST Compiler) 指南

引擎内置了安全且强大的 JSON 转 SQL 编译器。它用于 selectupdatedeletecountaggregate 接口中的 where 字段。

1. 基础等值匹配与多字段 AND

"where": {
  "status": "active",
  "role": "admin" // 默认为 AND 关系
}

2. 关系操作符

支持:$gt(>), $gte(>=), $lt(<), $lte(<=), $ne(!=), $like, $match

"where": {
  "age": { "$gte": 18, "$lt": 35 },
  "username": { "$like": "%admin%" }
}

3. 集合与范围操作符

支持:$in (数组), $nin (不在数组中), $between (两个元素的数组)

"where": {
  "category_id": { "$in": [1, 2, 5, 9] },
  "created_at": { "$between":["2026-01-01", "2026-12-31"] }
}

4. 逻辑操作符 ($or / $and)

必须传入对象数组,最大嵌套深度 5 层。

"where": {
  "deleted_at": { "$isNull": true },
  "$or":[
    { "status": "pending" },
    { "balance": { "$lt": 0 } }
  ]
}

5. JSON 动态路径解析 (提取 JSON 内部字段)

当数据库列存储的是 JSON 字符串时,可用 点(.) 语法深度查询。

"where": {
  "profile.address.city": "Shanghai"  // 编译为: "profile"->>'$.address.city' = 'Shanghai'
}

POST /select

获取数据列表。支持游标分页、边缘缓存加速和子查询连表(Relations)。

参数 Payload

参数名 类型 描述
table String 必需。目标数据表名称。
columns Array 可选。要查询的字段列表。例如 ["id", "name", "profile.avatar"]。默认 ["*"]
where Object 可选。AST 格式查询条件。详见上文 AST 指南。
limit Number 可选。单页数量,默认 100,最大 1000。
offset / page Number 可选。传统偏移量分页。推荐使用 cursor 替代。
cursor String 可选。游标字符串(基于 orderBy 字段自动生成,在响应中返回),用于千万级数据高效翻页。
orderBy String 可选。排序字段,支持 JSON 路径 "profile.age"
orderDesc Boolean 可选。是否降序排列。默认 false (ASC)。
relations Array 可选。连表映射数组(自动利用 JSON_GROUP_ARRAY 组装子查询)。最多支持 5 组关联。
strategy String 可选。传 "fast" 可开启 Isolate 级别的 L1 短暂内存缓存(约 3 秒),抵御瞬间读并发洪峰。
excludeDeleted Boolean 可选。如果传 false,将返回包含被软删除的数据。默认 true。

请求示例 (包含 Relations 连表)

{
  "table": "users",
  "limit": 10,
  "orderBy": "created_at",
  "orderDesc": true,
  "relations":[
    {
      "table": "orders",
      "fKey": "user_id",    // 子表的外键
      "lKey": "id",         // 主表的主键
      "as": "user_orders",  // 映射后的别名
      "columns": ["id", "amount", "status"]
    }
  ]
}

响应示例

{
  "data":[
    {
      "id": "u_001",
      "name": "Alice",
      "user_orders":[
        {"id": "ord_1", "amount": 250},
        {"id": "ord_2", "amount": 10}
      ]
    }
  ],
  "nextCursor": "eyIkZ3QiOiIyMDI2LTA0LTAzIn0="
}
POST /insert

新增实体数据,支持单条或多条(数组)批量写入,支持 Edge Buffer 高并发排队缓冲。

参数 Payload

参数名 类型 描述
table String 必需。目标数据表名称。
values Obj/Arr 必需。要插入的实体对象或对象数组。若未传 id 将自动生成 UUID。
buffered Boolean 可选。设为 true 将请求存入 Worker 内存队列后立即返回 200,由后台协程组装批量刷盘。极大幅度提升写入吞吐。
webhookUrl String 可选。插入成功后,引擎后台会向该 URL 异步发送 POST 请求(CDC 数据变更捕获)。
{
  "table": "logs",
  "buffered": true,
  "values": {
    "action": "login",
    "ip": "192.168.1.1",
    "metadata": { "browser": "Chrome" }
  }
}
POST /upsert

原子级的存在则更新、不存在则插入。利用了 SQLite 的 ON CONFLICT(id) DO UPDATE 原生语法,无竞态问题。

规范要求

  • 实体对象必须包含 id 字段。
  • 目标表必须显式设置了 id 为主键或唯一索引。
{
  "table": "user_stats",
  "values": {
    "id": "stat_user_001",
    "login_days": 15,
    "last_login": "2026-04-03"
  }
}
POST /update

参数 Payload

参数名 类型 描述
table String 必需。目标数据表名称。
where Object 必需。AST 匹配条件。严禁为空(防呆全表覆写)。
values Object 必需。要更新的键值对。自动忽略 idcreated_at
webhookUrl String 可选。更新后的 CDC 推送。
POST /delete

参数 Payload

参数名 类型 描述
table String 必需。目标数据表名称。
where Object 必需。AST 匹配条件。严禁为空。
softDelete Boolean 可选。若设为 true 且表有 deleted_at 字段,则执行软删除(UPDATE deleted_at),否则执行硬删除 (DELETE)。

POST /aggregate

在数据库底层执行数学统计操作,支持同时聚合多个字段,并支持边缘内存加速。

{
  "table": "orders",
  "where": { "status": "completed" },
  "sum": ["amount", "fee"],
  "avg": ["processing_time"],
  "max": ["amount"],
  "strategy": "fast" // 对于实时大屏建议开启
}
响应示例: {"data":[{"sum_amount": 10500, "sum_fee": 300, "avg_processing_time": 1.5, "max_amount": 4999}]}
POST /batch

将最多 50 个互不相关的操作(查、插、删、改)打包为单次 HTTP 请求。引擎在底层开启事务,确保执行顺序与原子性。

{
  "ops":[
    {
      "action": "insert",
      "payload": { "table": "users", "values": { "id": "u1", "name": "Tom" } }
    },
    {
      "action": "update",
      "payload": { "table": "stats", "where": {"type": "users"}, "values": {"total": 10} }
    },
    {
      "action": "select",
      "payload": { "table": "users", "limit": 1 }
    }
  ]
}
响应将是一个数组,按严格索引顺序返回 ops 中每一个 action 的执行结果。

Admin Root Only

管理员集群接口

POST
/issueApp

创建子应用空间。引擎会自动扫描所有节点,并将新 App 路由至负载最低的物理集群上,最后签发永久 JWT。

{ "appName": "E-Commerce Frontend" }
POST
/migrate

集群级架构定义 (DDL)。支持创建表和建立常规/联合索引。底层会自动对表名进行 AppID 沙盒化拼接。

{
  "tables":[
    {
      "name": "products",
      "columns":[
        { "name": "id", "type": "TEXT PRIMARY KEY" },
        { "name": "title", "type": "TEXT" },
        { "name": "price", "type": "INTEGER" },
        { "name": "created_at", "type": "DATETIME DEFAULT CURRENT_TIMESTAMP" }
      ],
      "indexes":[
        "title",              // 单列索引
        ["category", "price"] // 复合索引
      ]
    }
  ]
}
POST
/raw

执行无沙盒防御、无安全限制的底层原生 SQL 穿透。极其危险,仅作调试和特殊数据干预使用。

{
  "db": "db_2", // 强制穿透至 db_2 节点,不传则使用默认主节点
  "sql": "DELETE FROM sqlite_sequence WHERE name = ?",
  "params":["public_users"]
}

© 2026 Obsidian Engine Architecture. Powered by Nine-Tailed Fox Routing.