数据库
数据库层让你可以在db.php文件中为区块定义数据模型。Blockstudio会生成REST CRUD 端点,根据架构验证输入,自动管理存储,并同时提供JavaScript客户端(bs.db())和PHPAPI(Db类)。
这是全栈区块的数据骨干。RPC数据库层处理结构化数据,无需编写任何样板代码。
工作原理
- 在区块目录中创建
db.php - 它会返回一个架构:字段、类型、验证规则和访问控制
- Blockstudio会创建存储(表、文件或文章元数据)
- 自动生成五个REST端点(列表、获取、创建、更新、删除)
bs.db()和Db::get()提供客户端和服务器端访问
无需迁移、控制器或路由注册。
将字面值传递给REST和PHP API。meta和post_type后端会在内部处理WordPress元数据中的斜杠,保留标量值以及嵌套对象或数组中的反斜杠和带引号的字符串。不要预先对数据库记录值添加斜杠。
定义架构
单一架构
最简单的形式:每个区块对应一个数据模型。
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
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(...)调用组成的数组。
多个架构
单个区块可以包含多个数据模型。请返回一个命名数组:
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。
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关联到特定文章。
return [
'storage' => 'meta',
'postId' => 42,
'fields' => [ /* ... */ ],
];
适用于:属于特定文章或页面的数据。
自定义文章类型(storage: "post_type")
每条记录都是自动注册的自定义文章类型中的一篇WordPress文章。架构中的每个字段都会成为单独的post_meta条目。这样一来,记录可通过WP_Query查询、兼容RESTAPI插件,也能在GraphQL等工具中查看。
适用于:需要原生集成到WordPress中的数据。每个字段都可以独立查询和建立索引。
JavaScript客户端
Blockstudio会在包含数据库区块的页面上注入bs.db()。它会返回一个包含五个方法的对象:
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调用之间共享的内存查询缓存。你也可以直接使用它:
// 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(不会重复获取)。
// 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:
// 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时抛出错误:
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回调,让你全面掌控操作:
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代码中使用它。
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);
对于单架构区块:
$db = Db::get('my-theme/block');
实时轮询
在架构中添加realtime即可启用自动轮询。服务器上的数据发生变化时,UI会通过 Interactivity API自动更新。无需修改JavaScript。
return [
'storage' => 'table',
'realtime' => true,
'fields' => [ /* ... */ ],
];
使用true时,Blockstudio每 3 秒轮询一次,并将架构名称用作 Interactivity API状态键(单架构区块使用default)。
自定义配置
return [
'storage' => 'table',
'realtime' => [
'key' => 'todos',
'interval' => 5000,
],
'fields' => [ /* ... */ ],
];
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
key |
string |
架构名称 | state中保存数据数组的属性名称 |
interval |
number |
3000 |
轮询间隔(毫秒) |
工作原理
- 页面加载时,客户端会获取当前数据的轻量级哈希值
- 每隔
interval毫秒,重新获取哈希值 - 如果哈希值发生变化,则获取完整数据集
- 新数据通过
store()推送到 Interactivity API存储中 - 绑定到该状态属性的所有指令都会自动重新渲染
只有存在匹配data-wp-interactive元素的页面才会运行轮询。浏览器标签页隐藏时会暂停,重新显示时会恢复。
哈希端点(?_hash=1)只返回 md5 校验和与记录数,以减小轮询请求的开销。
用户范围数据
将userScoped: true设为自动将所有记录限定到当前用户。Blockstudio会添加user_id列,在创建记录时设置该列,并将所有操作筛选为仅处理当前用户的记录:
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 |
需要身份验证(已登录用户) |
'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表示通过,也可以返回包含错误消息的字符串:
'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启发,可轻松将错误映射到表单字段:
{
"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."]
}
}
}
每个字段对应一个错误字符串数组。同一个字段可能违反多条规则。前端处理方式:
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(),即可使用字段对应的组件区块将所有字段渲染为表单。
'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']],
],
],
],
],
],
<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 而不输出内容时:
use Blockstudio\Db;
$db = Db::get('my-theme/app', 'subscribers');
$html = $db->form();
钩子
每次写入操作前后都会触发操作。所有钩子都会接收一个 $params 数组。完整列表请参阅 钩子参考PHP。
内联钩子
直接在 db.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']);
},
],
];
全局钩子
可在任何位置监听所有架构:
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 用于定义自定义服务器函数。两者都可以独立使用。
当你需要标准数据操作和自定义业务逻辑时,可以同时使用它们:
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/ 下,而不是区块文件夹中。这样可将实时可写数据排除在源代码树之外,同时仍为每个架构提供纯文件存储,方便独立备份、复制或迁移。
筛选器
在区块外以编程方式修改架构:
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;
});