跳转到正文

RPC

RPC(远程过程调用)让你可以在区块中定义 PHP 函数,并从前端调用这些函数。你只需在 rpc.php 中编写函数,然后使用 bs.fn() 调用即可,无需手动注册 REST API 路由、创建控制器或接入 fetch 调用。Blockstudio 会处理端点路由、身份验证、nonce 验证和 JSON 序列化。

此模式的灵感来自 tRPC:在服务器端定义过程,再通过类型化辅助工具从客户端调用。无需构造 URL,也无需手动编写 fetch 样板代码。

工作原理

  1. 在区块目录中创建 rpc.php
  2. 它会返回一个由命名函数组成的关联数组
  3. Blockstudio 会为每个函数注册一个 REST 端点
  4. bs.fn() 客户端按名称调用这些函数
  5. 传入参数,返回 JSON
代码
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

定义函数

返回数组中的每个键都是一个函数名。最简单的形式是直接使用回调函数:

PHP
return [
    'subscribe' => function (array $params): array {
        $email = sanitize_email($params['email']);
        // process subscription
        return ['success' => true];
    },
    'load_more' => function (array $params): array {
        $offset = (int) ($params['offset'] ?? 0);
        $posts = get_posts(['offset' => $offset, 'numberposts' => 5]);
        return ['posts' => $posts];
    },
];

每个函数都会接收一个 $params 数组,并应返回一个数组。返回值会作为 JSON 发送给客户端。

如需设置访问控制选项,请使用包含 callback 和其他键的扩展格式:

PHP
return [
    'admin_action' => [
        'callback'   => function (array $params): array {
            return ['ok' => true];
        },
        'capability' => 'manage_options',
    ],
];

PHP 原生定义

如果你更喜欢 PHP 原生元数据,而不是嵌套数组,rpc.php 也可以返回带有属性方法的对象。数组仍然可以照常使用。

PHP
<?php
use Blockstudio\Attributes\Rpc;
use Blockstudio\Rpc\Access;
use Blockstudio\Rpc\Method;

return new class {
    #[Rpc(access: Access::Session)]
    public function subscribe(array $params): array {
        $email = sanitize_email($params['email'] ?? '');
        return ['success' => !empty($email)];
    }

    #[Rpc(name: 'status', methods: [Method::Get, Method::Post])]
    public function getStatus(array $params): array {
        return ['status' => 'ok'];
    }

    #[Rpc(access: Access::Open)]
    public function webhook(array $params): array {
        return ['received' => true];
    }
};

注意:

  • 默认情况下,方法名称会规范化为小写蛇形命名,因此 getStatus() 会变成 get_status
  • 使用 name: 可明确指定端点名称
  • Access::Session 与旧版 'public' => true 行为一致
  • Access::Open 与旧版 'public' => 'open' 行为一致
  • 默认仅允许通过身份验证的用户访问;如需此默认行为,请省略 access:

从 JavaScript 调用

Blockstudio 会在包含 RPC 函数的区块页面上自动注入 bs.fn() 辅助工具。

签名: bs.fn(functionName, params?, blockName?) -> Promise

传递区块名称

省略第三个参数时,bs.fn() 会回退使用 document.currentScript 的 data-block 属性。Blockstudio 会将 script.js 和内联脚本(script-inline.js 或 script.inline.js)输出为 <script type="module"> 标签,而模块脚本没有 document.currentScript,因此在区块脚本中应将区块名称作为第三个参数传入:

JavaScript
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');

如果没有该参数,调用会抛出 bs.fn: block name required。

错误处理

无论 HTTP 状态如何,bs.fn() 都会以解析后的 JSON 正文完成。如果函数返回 WP_Error,Promise 会以包含其 code、message 和 data 的对象完成,因此请检查 code:

JavaScript
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');

if (result.code) {
  console.error('RPC failed:', result.message);
}

只有在请求本身失败或响应不是 JSON 时,Promise 才会被拒绝。

与 Interactivity API 配合使用

RPC 与 WordPress Interactivity API 配合使用十分自然。你的存储操作会调用服务器函数,并根据响应更新响应式状态。UI 会自动更新:

JavaScript
import { store, getContext } from '@wordpress/interactivity';

store('myTheme/newsletter', {
  actions: {
    subscribe: async () => {
      const ctx = getContext();
      ctx.loading = true;
      ctx.error = '';

      try {
        ctx.result = await bs.fn('subscribe', { email: ctx.email }, 'my-theme/newsletter');
        ctx.success = !ctx.result.code;
      } catch (e) {
        ctx.error = 'Something went wrong.';
      }

      ctx.loading = false;
    },
  },
});
PHP
<div
  data-wp-interactive="myTheme/newsletter"
  data-wp-context='{"email":"","loading":false,"success":false,"error":"","result":null}'
  useBlockProps
>
  <input
    type="email"
    data-wp-bind--value="context.email"
    data-wp-on--input="actions.updateEmail"
  />
  <button
    data-wp-on--click="actions.subscribe"
    data-wp-bind--disabled="context.loading"
  >Subscribe</button>
  <p data-wp-if="context.error" data-wp-text="context.error"></p>
  <p data-wp-if="context.success">Thanks for subscribing!</p>
</div>

访问控制

默认情况下,函数要求用户已通过身份验证(已登录)。这符合 WordPress 的惯例,即 REST 端点默认受到保护。

公共函数

允许未经身份验证的访问,同时启用 CSRF 保护:

PHP
return [
    'get_count' => [
        'callback' => function (array $params): array {
            return ['count' => wp_count_posts()->publish];
        },
        'public' => true,    // public + CSRF protected via X-BS-Token
    ],
];

已缓存的页面

bs.fn() 会从未缓存的同源 POST /wp-json/blockstudio/v1/client/credentials 端点获取新凭据。过期的 WordPress nonce 和 Blockstudio CSRF 令牌不会存储在页面 HTML 中,因此即使外部页面缓存提供的是超过 24 小时的 HTML,公共调用仍可正常工作。

刷新按需进行:加载页面但不调用 API 时,不会请求凭据。RPC 和数据库客户端会共用刷新请求;凭据使用五分钟后会续期;nonce 或 CSRF 令牌过期时会重试一次。功能权限失败和应用错误不会重试。身份验证仍遵循当前访问者的 WordPress 登录 Cookie;刷新凭据不会授予访问私有函数的权限。请将凭据端点排除在任何 CDN 或代理缓存之外;其响应会明确标记为 private, no-store。

开放函数

对于需要完全开放访问且无需任何令牌的 Webhook 或外部 API 回调:

PHP
return [
    'webhook' => [
        'callback' => function (array $params): array {
            // Called by an external service
            return ['received' => true];
        },
        'public' => 'open',  // no CSRF, no auth
    ],
];

功能权限

限制为特定的 WordPress 功能权限。单个功能权限可使用字符串;如果用户只需具备其中一个权限,则可使用数组:

PHP
return [
    'save_draft' => [
        'callback'   => function (array $params): array { /* ... */ },
        'capability' => 'edit_posts',
    ],
    'moderate' => [
        'callback'   => function (array $params): array { /* ... */ },
        'capability' => ['edit_others_posts', 'manage_options'],
    ],
];

HTTP 方法

默认情况下,函数只接受 POST 请求。这是修改状态的操作最安全的默认设置。需要时可允许其他方法:

PHP
return [
    'get_status' => [
        'callback' => function (array $params): array {
            return ['status' => 'ok'];
        },
        'methods' => ['GET', 'POST'],
    ],
];

跨区块调用

从 JavaScript 调用

任何区块都可以通过传递区块名称作为第三个参数,调用其他任意区块的函数。这使区块之间能够组合调用:

JavaScript
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');

从 PHP 调用

使用 Rpc::call() 进行服务器端跨区块调用。当一个 RPC 函数需要协调调用其他区块时,这种方式很有用:

PHP
use Blockstudio\Rpc;

return [
    'refresh_dashboard' => function (array $params): array {
        $feed  = Rpc::call('my-theme/blog-feed', 'load_more', ['offset' => 0]);
        $stats = Rpc::call('my-theme/analytics', 'get_summary', []);

        return ['feed' => $feed, 'stats' => $stats];
    },
];

REST 端点

在底层,每个函数都会映射到一个 REST 路由:

代码
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}

请求正文: { "params": { ... } }

响应: PHP 函数的返回值,格式为 JSON。

你可以从任何 HTTP 客户端直接调用这些端点,但推荐使用 bs.fn(),因为它会自动处理 nonce 身份验证。

钩子

每次 RPC 调用前后都会触发操作,无论调用来自 REST 还是 PHP。所有钩子都会接收一个 $params 数组:

钩子 参数
blockstudio/rpc/before_call block、function、params
blockstudio/rpc/after_call block、function、params、result
PHP
add_action('blockstudio/rpc/after_call', function ($params) {
    // Log every RPC call
    error_log($params['block'] . '::' . $params['function'] . ' called');
});

add_action('blockstudio/rpc/before_call', function ($params) {
    // Rate limiting, audit logging, etc.
});

筛选器

在区块外以编程方式修改或添加函数:

PHP
add_filter('blockstudio/rpc', function (array $functions): array {
    $functions['my-theme/hero']['custom_action'] = [
        'callback' => function (array $params): array {
            return ['ok' => true];
        },
        'public' => false,
    ];
    return $functions;
});

何时使用 RPC,何时使用数据库

db.php 会根据架构自动生成 CRUD 端点。需要带验证的标准创建、读取、更新和删除操作时,可使用它。

rpc.php 用于自定义逻辑:发送电子邮件、调用外部 API、汇总多个架构中的数据、运行复杂查询,或处理任何不符合 CRUD 模式的需求。

这两个系统相互独立且互为补充。许多区块会同时使用两者:db.php 用于数据模型,rpc.php 用于在其基础上实现业务逻辑。