跳转到正文

数据库

数据库层让你可以在db.php文件中为区块定义数据模型。Blockstudio会生成REST CRUD 端点,根据架构验证输入,自动管理存储,并同时提供JavaScript客户端(bs.db())和PHPAPI(Db类)。

这是全栈区块的数据骨干。RPC数据库层处理结构化数据,无需编写任何样板代码。

工作原理

  1. 在区块目录中创建db.php
  2. 它会返回一个架构:字段、类型、验证规则和访问控制
  3. Blockstudio会创建存储(表、文件或文章元数据)
  4. 自动生成五个REST端点(列表、获取、创建、更新、删除)
  5. bs.db()和Db::get()提供客户端和服务器端访问

无需迁移、控制器或路由注册。

将字面值传递给REST和PHP API。meta和post_type后端会在内部处理WordPress元数据中的斜杠,保留标量值以及嵌套对象或数组中的反斜杠和带引号的字符串。不要预先对数据库记录值添加斜杠。

定义架构

单一架构

最简单的形式:每个区块对应一个数据模型。

PHP
return [
    'storage'    => 'table',
    'capability' => [
        'create' => true,
        'read'   => true,
        'update' => 'edit_posts',
        'delete' => 'manage_options',
    ],
    'fields' => [
        'email' => ['type' => 'string', 'format' => 'email', 'required' => true],
        'name'  => ['type' => 'string', 'maxLength' => 100],
        'plan'  => ['type' => 'string', 'enum' => ['free', 'pro'], 'default' => 'free'],
    ],
];

PHP原生构建器语法

db.php也可以使用一个小型构建器API,它基于命名参数和只读定义对象构建。数组仍是默认格式,但当架构变得较大时,这种方式提供了更易于发现的PHP原生选项。

PHP
<?php
use Blockstudio\Db\Field;
use Blockstudio\Db\Schema;
use Blockstudio\Db\Storage;

return Schema::make(
    storage: Storage::Table,
    capability: [
        'create' => true,
        'read'   => true,
        'update' => 'edit_posts',
        'delete' => 'manage_options',
    ],
    fields: [
        'email' => Field::string(required: true, format: 'email'),
        'name'  => Field::string(maxLength: 100),
        'plan'  => Field::string(enum: ['free', 'pro'], default: 'free'),
    ],
);

单一架构请使用Schema::make();多架构区块则返回由命名的Schema::make(...)调用组成的数组。

多个架构

单个区块可以包含多个数据模型。请返回一个命名数组:

PHP
return [
    'subscribers' => [
        'storage' => 'table',
        'fields'  => [
            'email' => ['type' => 'string', 'format' => 'email', 'required' => true],
            'plan'  => ['type' => 'string', 'enum' => ['free', 'pro']],
        ],
    ],
    'activity_log' => [
        'storage' => 'jsonc',
        'fields'  => [
            'action'  => ['type' => 'string', 'required' => true],
            'details' => ['type' => 'string'],
        ],
    ],
];

每个架构都有自己的端点、存储和访问控制。

存储模式

六种存储后端,分别适用于不同场景。

自定义表(storage: "table")

每条记录都是专用MySQL表中的一行。Blockstudio会使用WordPress的dbDelta()函数自动创建和管理该表。向架构添加新字段后,下次加载页面时会添加对应列。现有列不会被删除。

适用于:结构化数据、查询和生产应用。

SQLite (storage: "sqlite")

每个架构在db/子文件夹中都有自己的SQLite数据库文件。Blockstudio会自动创建文件和表,并在架构变更时添加缺失的列(类似MySQL中的dbDelta)。使用 WAL 日志模式以提升并发读取性能。

代码
blocks/my-block/
├── db.php
└── db/
    └── subscribers.sqlite   ← single-file database

适用于:需要真正SQL查询、同时又应保持可移植性的结构化数据。无需将所有记录加载到内存中,也能高效处理数千条记录。复制文件夹即可迁移数据。

JSONC文件(storage: "jsonc")

记录以每行一个JSON对象的形式存储在db/子文件夹中的.jsonc文件内。首次写入时会自动创建该文件。以//开头的行会被视为注释并保留。

代码
blocks/my-block/
├── db.php
└── db/
    └── subscribers.jsonc    ← one record per line

适用于:小型数据集、类似配置的数据、种子记录和可纳入版本控制的示例。JSONC特意设为区块文件夹中的单个文件。若希望数据随代码一起迁移,可以使用它;若预计会有大量并发写入,则不适合。

Storh文件(storage: "storh")

Storh会将每条记录分别存储为WordPress上传目录下的独立文件:

代码
wp-content/uploads/blockstudio/db/
└── my-theme-my-block/
    └── subscribers/
        ├── data/
        │   └── 00/
        │       ├── 00000000-0000-7000-8000-000000000001.jsonc
        │       └── 00000000-0000-7000-8000-000000000002.jsonc
        ├── .storh/
        │   └── indexes/
        └── .blockstudio/
            └── sequence.json

公开记录 ID 保持为bs.db()其余部分使用的整数 ID。Blockstudio会将这些 ID 映射到Storh内部的UUIDv7文件 ID,并在记录数据中存储整数id,因此JavaScript、REST和PHP调用方无需处理 UUID。

PHP
return [
    'storage' => 'storh',
    'fields'  => [
        'title'  => ['type' => 'string', 'required' => true],
        'status' => ['type' => 'string'],
        'count'  => ['type' => 'integer'],
    ],
];

Blockstudio会根据你的架构创建Storh索引。由于每个声明的字段都可以用作列表筛选条件,因此每个字段都会建立索引。整数、数字和日期类字段使用范围索引;标记为'unique' => true或'index' => 'unique'的字段使用唯一索引。

适用于:需要更安全并发写入、基于架构生成索引,以及可移植的 uploads 级存储,同时又不将实时记录提交到区块源代码树中的文件存储生产数据。

将JSONC迁移到Storh

如果你最初使用.jsonc文件,现在想将相同记录存入Storh,请运行:

命令行
wp bs db migrate my-theme/app subscribers --to=storh

对于单架构区块:

命令行
wp bs db migrate my-theme/app --to=storh

迁移会读取现有的db/{schema}.jsonc,将记录写入Storh,同时保留整数 ID,然后重新建立索引、验证目标存储,并保持JSONC文件不变。回滚只需将架构的storage改回"jsonc"。

文章元数据(storage: "meta")

记录以JSON数组的形式存储在WordPress文章元数据中,并通过postId关联到特定文章。

PHP
return [
    'storage' => 'meta',
    'postId'  => 42,
    'fields'  => [ /* ... */ ],
];

适用于:属于特定文章或页面的数据。

自定义文章类型(storage: "post_type")

每条记录都是自动注册的自定义文章类型中的一篇WordPress文章。架构中的每个字段都会成为单独的post_meta条目。这样一来,记录可通过WP_Query查询、兼容RESTAPI插件,也能在GraphQL等工具中查看。

适用于:需要原生集成到WordPress中的数据。每个字段都可以独立查询和建立索引。

JavaScript客户端

Blockstudio会在包含数据库区块的页面上注入bs.db()。它会返回一个包含五个方法的对象:

JavaScript
const db = bs.db('my-theme/block', 'subscribers');

// Create a record
const record = await db.create({ email: 'a@b.com', plan: 'pro' });

// List all records (with optional filters)
const all = await db.list();
const pros = await db.list({ plan: 'pro', limit: 10, offset: 0 });

// Get a single record
const one = await db.get(record.id);

// Update specific fields
const updated = await db.update(record.id, { plan: 'enterprise' });

// Delete a record
await db.delete(record.id);

第一个参数是区块名称(带/),第二个参数是架构名称。对于单架构区块,可以省略架构名称(默认为"default")。

缓存

bs.cache是在所有bs.query和bs.mutate调用之间共享的内存查询缓存。你也可以直接使用它:

JavaScript
// Read a cached value
const data = bs.cache.get('my-key');

// Write to the cache
bs.cache.set('my-key', { items: [...] });

// Invalidate a single key
bs.cache.invalidate('my-key');

// Clear all cached entries
bs.cache.clear();

缓存条目存储在内存中,并在页面导航时清除。它们主要由bs.query和bs.mutate在内部使用,但直接访问也可用于预先填充数据,或在自定义操作后手动使缓存失效。

查询

bs.query()可为任何异步函数提供缓存、去重和过期控制。请求进行期间,使用相同键的多次调用会返回同一个 promise(不会重复获取)。

JavaScript
// Basic cached fetch
const subscribers = await bs.query('subscribers', () =>
  bs.db('my-theme/app', 'subscribers').list()
);

// With staleTime: skip the fetch if cached data is younger than 30 seconds
const subscribers = await bs.query('subscribers', () =>
  bs.db('my-theme/app', 'subscribers').list(),
  { staleTime: 30000 }
);

第一个参数是缓存键(任意字符串)。第二个参数是返回 promise 的函数。第三个参数是可选的选项对象:

选项 类型 说明
staleTime number 缓存数据被视为过期前的毫秒数。0(默认值)始终会重新获取。

如果缓存中有该键的数据,且数据的存储时间短于staleTime,则会立即返回缓存值,而不会调用该函数。

修改

bs.mutate()通过乐观更新处理写入操作,并在失败时自动回滚。它有两种模式:适用于常见 CRUD 模式的自动模式,以及提供全面控制的手动模式。

自动模式适用于响应式状态对象(例如Alpine.js$data)。传入state、key、action,以及可选的optimistic:

JavaScript
// Optimistic create: item appears instantly, gets real ID on success
await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'create',
  optimistic: { text: 'New todo', done: false },
  fn: () =>
    bs.db('my-theme/app', 'todos').create({ text: 'New todo', done: false }),
});

// Optimistic update: field changes instantly, reverts on failure
await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'update',
  id: todoId,
  optimistic: { done: true },
  fn: () => bs.db('my-theme/app', 'todos').update(todoId, { done: true }),
});

// Delete: item removed from the array immediately
await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'delete',
  id: todoId,
  fn: () => bs.db('my-theme/app', 'todos').delete(todoId),
});

成功时,乐观数据会替换为服务器响应。失败时,状态会回滚到变更前的快照。每次成功变更后,缓存键都会自动失效。

当fn返回的 promise 被拒绝时,即表示失败。验证错误、记录缺失或权限检查失败时,bs.db()和bs.fn()会携带错误正文正常完成,因此如果这些情况也应触发回滚,请在结果包含code时抛出错误:

JavaScript
const ok = (request) =>
  request.then((result) => {
    if (result?.code) {
      throw result;
    }
    return result;
  });

await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'delete',
  id: todoId,
  fn: () => ok(bs.db('my-theme/app', 'todos').delete(todoId)),
});

对于创建操作,乐观条目会被分配一个临时id(例如__temp_1)。服务器响应后,临时条目会补入真实数据,包括服务器分配的id。

手动模式通过before、onSuccess和onError回调,让你全面掌控操作:

JavaScript
await bs.mutate({
  fn: () => bs.db('my-theme/app', 'todos').create({ text: 'New' }),
  invalidate: 'todos',
  before: () => {
    // Take a snapshot, return it for use in onError
    const snapshot = [...$data.todos];
    $data.todos.push({ id: '__temp', text: 'New' });
    return snapshot;
  },
  onSuccess: (result, snapshot) => {
    // Replace temp item with server response
  },
  onError: (error, snapshot) => {
    // Restore from snapshot
    $data.todos = snapshot;
  },
});
选项 类型 模式 说明
fn function 两者 执行变更的异步函数。必填。
state object 自动 响应式状态对象(e.g.、Alpine$data)。
key string 自动 保存数组的状态属性名称,也用作缓存键。
action string 自动 create、update或delete之一。
id any 自动 update和delete操作所用的记录 ID。
optimistic object 自动 服务器响应前要乐观应用的数据。
before function 手动 在fn前调用。其返回值会作为snapshot传给onSuccess/onError。
onSuccess function 手动 成功时携带(result, snapshot)调用。
onError function 手动 失败时携带(error, snapshot)调用。
invalidate string 手动 成功时要使其失效的缓存键。

PHP API

Db类在服务器端提供相同的操作。可在rpc.php、cron.php、模板或任何PHP代码中使用它。

PHP
use Blockstudio\Db;

$db = Db::get('my-theme/block', 'subscribers');

// Create
$record = $db->create(['email' => 'a@b.com', 'plan' => 'pro']);

// List with filters
$all  = $db->list();
$pros = $db->list(['plan' => 'pro'], limit: 10, offset: 0);

// Count and paginate
$count = $db->count(['plan' => 'pro']);
$page  = $db->paginate(['plan' => 'pro'], limit: 10, offset: 20);

// Get by ID
$one = $db->get_record(1);

// Update
$db->update(1, ['plan' => 'enterprise']);

// Delete
$db->delete(1);

对于单架构区块:

PHP
$db = Db::get('my-theme/block');

实时轮询

在架构中添加realtime即可启用自动轮询。服务器上的数据发生变化时,UI会通过 Interactivity API自动更新。无需修改JavaScript。

PHP
return [
    'storage'  => 'table',
    'realtime' => true,
    'fields'   => [ /* ... */ ],
];

使用true时,Blockstudio每 3 秒轮询一次,并将架构名称用作 Interactivity API状态键(单架构区块使用default)。

自定义配置

PHP
return [
    'storage'  => 'table',
    'realtime' => [
        'key'      => 'todos',
        'interval' => 5000,
    ],
    'fields' => [ /* ... */ ],
];
选项 类型 默认值 说明
key string 架构名称 state中保存数据数组的属性名称
interval number 3000 轮询间隔(毫秒)

工作原理

  1. 页面加载时,客户端会获取当前数据的轻量级哈希值
  2. 每隔interval毫秒,重新获取哈希值
  3. 如果哈希值发生变化,则获取完整数据集
  4. 新数据通过store()推送到 Interactivity API存储中
  5. 绑定到该状态属性的所有指令都会自动重新渲染

只有存在匹配data-wp-interactive元素的页面才会运行轮询。浏览器标签页隐藏时会暂停,重新显示时会恢复。

哈希端点(?_hash=1)只返回 md5 校验和与记录数,以减小轮询请求的开销。

用户范围数据

将userScoped: true设为自动将所有记录限定到当前用户。Blockstudio会添加user_id列,在创建记录时设置该列,并将所有操作筛选为仅处理当前用户的记录:

PHP
return [
    'storage'    => 'sqlite',
    'userScoped' => true,
    'fields'     => [
        'text' => ['type' => 'string', 'required' => true],
        'done' => ['type' => 'boolean', 'default' => false],
    ],
];

无需手动添加user_id字段,无需before_create钩子,也无需在RPC中筛选。用户只能查看、编辑和删除自己的记录。user_id列完全由Blockstudio管理。

使用post_type存储时,userScoped会映射到post_author,而不是单独的user_id列。

访问控制

每种 CRUD 操作都有自己的权限级别:

值 行为
true 公开并提供 CSRF 保护(允许已登出用户,但需要X-BS-Token)
'open' 完全公开,无 CSRF、无需身份验证(用于 webhook 和外部 API)
'edit_posts' WordPress能力检查
['cap_a', 'cap_b'] 用户需要具备列出的任一能力
省略 / null 需要身份验证(已登录用户)
PHP
'capability' => [
    'create' => true,                               // public + CSRF protected
    'read'   => 'open',                             // truly open, no protection
    'update' => 'edit_posts',                       // editors and above
    'delete' => ['delete_posts', 'manage_options'], // either capability works
],

CSRF 保护

公共端点(true)受 X-BS-Token 标头保护。bs.db() 和 bs.fn() 会从未缓存的同源端点获取新凭据,而不是将会过期的令牌嵌入页面 HTML。由长期外部缓存提供的页面仍可正常工作。没有有效令牌的匿名调用会收到 403 响应。

凭据会在首次 API 调用时请求,而不是每次查看页面时都请求。两个客户端(包括数据库实时轮询)会共用一个正在进行的凭据刷新请求。凭据使用五分钟后会刷新。WordPress nonce 或 Blockstudio CSRF 令牌被拒绝时,会触发一次刷新和重试;普通权限错误不会重试。已登录请求仍使用访问者的会话,并遵循架构的功能权限和记录所有权检查。

请勿将 POST /wp-json/blockstudio/v1/client/credentials 放在任何代理或 CDN 缓存之后。它会发送 Cache-Control: private, no-store,并要求请求来自同源且包含非简单标头。内置客户端会自动处理这些要求。

如果需要在无 CSRF 保护的情况下完全免身份验证访问,例如接收外部服务发来的 webhook,请使用'open'。

字段类型

类型 MySQL列 PHP类型 说明
string varchar(maxLength) string 文本,默认 maxLength 255
integer bigint(20) int 整数
number decimal(20,6) float 小数
boolean tinyint(1) bool 真/假
text longtext string 长篇文本内容

验证

所有写入操作(创建和更新)在接触存储前都会根据架构进行验证。无论请求来自bs.db()、RESTAPI还是Db::get(),验证都在服务器端进行。

内置规则

规则 示例 说明
required 'required' => true 创建时必须提供该字段
type 'type' => 'integer' 值必须符合声明的类型
enum 'enum' => ['a', 'b'] 值必须是所列选项之一
maxLength 'maxLength' => 100 字符串长度不能超过此值
minLength 'minLength' => 3 字符串长度至少为此值
format: "email" 'format' => 'email' 必须是有效的电子邮件地址
format: "url" 'format' => 'url' 必须是有效的URL

自定义验证

为任意字段添加validate回调,即可执行超出内置规则范围的服务器端检查。返回true表示通过,也可以返回包含错误消息的字符串:

PHP
'email' => [
    'type'     => 'string',
    'format'   => 'email',
    'required' => true,
    'validate' => function ($value, $data) {
        if (str_ends_with($value, '@disposable.com')) {
            return 'Disposable email addresses are not allowed.';
        }
        return true;
    },
],

回调会接收字段值和完整数据数组,因此你可以进行跨字段验证。

错误响应格式

验证错误会返回400状态码,并为每个字段提供错误数组。此格式受到Zod的fieldErrors启发,可轻松将错误映射到表单字段:

JSON
{
  "code": "blockstudio_db_validation",
  "message": "Validation failed.",
  "data": {
    "status": 400,
    "errors": {
      "email": [
        "Must be a valid email address.",
        "Disposable email addresses are not allowed."
      ],
      "plan": ["Must be one of: free, pro."]
    }
  }
}

每个字段对应一个错误字符串数组。同一个字段可能违反多条规则。前端处理方式:

JavaScript
const result = await db.create({ email: 'bad', plan: 'invalid' });

if (result.data?.errors) {
  // { email: ["Must be a valid email address."], plan: ["Must be one of: free, pro."] }
  Object.entries(result.data.errors).forEach(([field, messages]) => {
    showFieldError(field, messages[0]);
  });
}

REST端点

所有端点都位于blockstudio/v1/db/命名空间下:

代码
/db/{block-name}/{schema-name}

区块名称中的/会替换为-。对于单架构区块,架构名称为default。

方法 端点 说明
GET /db/{block}/{schema} 列出记录
POST /db/{block}/{schema} 创建记录
GET /db/{block}/{schema}/{id} 获取单条记录
PUT /db/{block}/{schema}/{id} 更新记录
DELETE /db/{block}/{schema}/{id} 删除记录

查询参数(列表)

参数 说明
limit 最多返回的记录数(默认 50,最多 100)
offset 要跳过的记录数
任意字段名 按完全匹配的值筛选

示例:GET /db/my-theme-app/subscribers?plan=pro&limit=10

表单渲染

字段可以定义一个component键,用于引用Blockstudio区块。在模板中调用bs_db_form(),即可使用字段对应的组件区块将所有字段渲染为表单。

PHP
'fields' => [
    'email' => [
        'type'     => 'string',
        'format'   => 'email',
        'required' => true,
        'component' => [
            'name' => 'my-theme/field',
            'attributes' => ['label' => 'Email', 'type' => 'email'],
            'innerBlocks' => [
                [
                    'name' => 'my-theme/input',
                    'attributes' => ['placeholder' => 'Enter your email'],
                ],
            ],
        ],
    ],
    'plan' => [
        'type' => 'string',
        'enum' => ['free', 'pro'],
        'component' => [
            'name' => 'my-theme/field',
            'attributes' => ['label' => 'Plan'],
            'innerBlocks' => [
                [
                    'name' => 'my-theme/select',
                    'attributes' => ['options' => ['free', 'pro']],
                ],
            ],
        ],
    ],
],
PHP
<form>
  <?php bs_db_form('my-theme/app', 'subscribers'); ?>
  <button type="submit">Subscribe</button>
</form>

每个组件都会在其属性中接收完整的字段定义 field,因此组件可以根据架构调整渲染方式。例如,$a['field']['name'] 提供字段名称,$a['field']['type'] 提供类型,$a['field']['required'] 表示字段是否必填,等等。

组件结构遵循与 WordPress 区块相同的 name、attributes、innerBlocks 格式。内部区块先渲染,再作为 $content 传递给父级。

在使用 PHP 而不输出内容时:

PHP
use Blockstudio\Db;

$db   = Db::get('my-theme/app', 'subscribers');
$html = $db->form();

钩子

每次写入操作前后都会触发操作。所有钩子都会接收一个 $params 数组。完整列表请参阅 钩子参考PHP。

内联钩子

直接在 db.php 中定义钩子。钩子会自动限定在该架构的范围内,因此无需检查区块或架构名称:

PHP
return [
    'storage' => 'table',
    'fields'  => [ /* ... */ ],
    'hooks' => [
        'after_create' => function ($params) {
            // $params['record'] is the created record
            wp_mail($params['record']['email'], 'Welcome!', 'Thanks for subscribing.');
        },
        'before_delete' => function ($params) {
            // $params['id'] is the record being deleted
            error_log('Deleting subscriber ' . $params['id']);
        },
    ],
];

全局钩子

可在任何位置监听所有架构:

PHP
add_action('blockstudio/db/after_create', function ($params) {
    // $params['block'] and $params['schema'] identify the source
    if ('my-theme/app' === $params['block'] && 'subscribers' === $params['schema']) {
        // sync to external CRM
    }
});

与 RPC 结合使用

db.php 和 rpc.php 是相互独立的系统。db.php 根据架构定义生成 CRUD 端点。rpc.php 用于定义自定义服务器函数。两者都可以独立使用。

当你需要标准数据操作和自定义业务逻辑时,可以同时使用它们:

PHP
use Blockstudio\Db;

return [
    'export' => [
        'callback'   => function (array $params): array {
            $db   = Db::get('my-theme/app', 'subscribers');
            $rows = $db->list(['plan' => 'pro']);
            // custom CSV generation, email sending, etc.
            return ['exported' => count($rows)];
        },
        'capability' => 'manage_options',
    ],
];

可移植性

使用 JSONC 存储时,数据与代码存放在一起。将区块文件夹复制到其他站点,所有内容都会一并迁移:UI、逻辑、访问控制以及数据本身。

代码
my-app/
├── block.json
├── index.twig
├── style.css
├── rpc.php        ← custom endpoints
├── db.php         ← data schema
├── cron.php       ← scheduled tasks
└── db/
    └── entries.jsonc  ← the actual data

无需数据库迁移,也不必执行导出或导入。只需复制文件夹即可。

Storh 存储同样具有可移植性,但数据位于 uploads/blockstudio/db/ 下,而不是区块文件夹中。这样可将实时可写数据排除在源代码树之外,同时仍为每个架构提供纯文件存储,方便独立备份、复制或迁移。

筛选器

在区块外以编程方式修改架构:

PHP
add_filter('blockstudio/database', function (array $schemas): array {
    // Add a field to an existing schema
    $schemas['my-theme/app:subscribers']['fields']['source'] = [
        'type'    => 'string',
        'default' => 'website',
    ];
    return $schemas;
});