import { Tabs, Tab } from '@rspress/core/theme';
SFMC 依托伴生架构，在 Minecraft Script API（SAPI）与宿主 Node.js 数据中枢之间建立了高性能的本地通信桥梁。
本篇文档面向需要进行跨模块调用的业务开发者，以及开发 Node.js 扩展工具或调试底层的架构师。
flowchart LR
A["接口导读"] --> B["鉴权机制与错误码"]
A --> C["SDK 导读 (SAPI 首选)"]
C --> D["模块服务目录 (RPC)"]
A --> E["平台 HTTP API (底层/调试)"]
- 服务基础地址（Base URL）：
http://127.0.0.1:3001 - 监听模式：仅限本机本地回环接口（Loopback Only）。
- 端口配置：定义在
configs/db_config.json的db_port字段（可通过环境变量DB_PORT动态覆盖）。
# 本地服务连通性与健康度快速探测
curl http://127.0.0.1:3001/api/health| 业务场景 | 官方标准做法 | 禁忌与原则 |
|---|---|---|
| 编写 SAPI 游戏业务模块 | 统一使用 @sfmc-bds/sdk 提供的抽象封装。- 数据库： @sfmc-bds/sdk/sapi/db- 私有配置： @sfmc-bds/sdk/sapi/config- 跨模块调用： @sfmc-bds/sdk/sapi/service |
SDK 会自动处理身份注入与网络异常重试，不建议在业务模块中手写 fetch 直连 127.0.0.1:3001。 |
| Node.js 侧扩展与外部脚本 | 可直接发起 HTTP REST 请求（参考本节各平台 HTTP 子路由）。 | 需在 Request Header 中显式携带 Bearer Token。 |
| 查阅强类型签名 | 参阅自动生成的 SDK 类型参考手册。 | — |
- 鉴权规范与错误码处理 — 了解身份鉴权、Bearer Token 注入与平台错误响应契约。
- SDK 核心导读 — 学习
db、config、runtime、service四大抽屉的用法。 - 官方模块服务目录 — 查阅经济（economy）、领地（land）、区域（area）等现成可调用的 RPC 接口。
- 鉴权与通信约定 — 统一请求头格式、状态码映射。
- 核心 REST 端点详解：
- 模块管控 API — 查询已安装 catalog、启停状态切换。
- 配置管理 API — 获取全局启动快照（
configs/all）与命名空间持久化。 - 数据库操作 API — 动态表定义、参数化 CRUD 与跨模块原子事务（
tx）。 - 服务发现与 RPC — 跨模块能力注册与分发。
- 多端消息路由 API — 游戏聊天队列与 QQ 桥接出入站。
| 章节文档 | 核心内容介绍 |
|---|---|
| 鉴权与通信约定 | 请求鉴权、标准 JSON 响应结构、全局错误码与路由映射 |
| SDK 核心能力导读 | runtime / db / config / service 四大能力集 |
| 模块服务目录 (RPC) | 官方各模块（economy, land, area 等）对外导出的远程接口 |
| 模块管控 API | 获取安装清单、动态启停模块、热重载触发 |
| 配置服务 API | configs/all 启动快照接口与单模块配置更新 |
| 数据库操作 API | 参数化 SQL、表定义注册与事务调用链路 |
| 远程服务 RPC API | 服务提供方注册与消费者消费 |
| 消息中继 API | 游戏与 QQ 桥接消息双向推送机制 |