nyaKazuha/BlueArchiveToolkit

Fork 0

mirror of https://github.com/Yuyi-Oak/BlueArchiveToolkit.git synced 2026-09-18 06:34:54 +08:00

Files

T

nyaKazuha df361cff28

test(api): 固化 Rust-Go RPC 契约

2026-07-31 18:20:37 +08:00

8.5 KiB

Raw Blame History

Go 侧进度与边界（权威）

更新时间：2026-07-27
用途：统一 Go module bat-api 的产品边界、既有约定和组件进度；其他文档与此冲突时以本文为准。
关联：issue #19 / G-009（资源 bootstrap/分发）、G-008（已决策关闭）、docs/architecture/official-resource-backend.md §7

1. 三个入口分别是什么

名称	路径 / 产物	角色	是否产品入口
Rust `bat`	`infrastructure` bin → 正式同步二进制	官方资源自动发现 / 拉取 / 校验 / 发布 / watch·daemon / 运维子命令	是（同步与运维命令行）
Go `bat-api`	`cmd/bat-api` → `bin/bat-api`	资源 bootstrap + 分发 HTTP 服务（官方 CDN path 形态）+ release 观察 API	是（bootstrap/分发服务）
Go 试验 CLI	`cmd/bat` → `bin/bat-go`（不得再叫 `bin/bat`）	FFI 演示骨架	否

1.1 「同步命令行 = Rust `bat`」的含义

人类做资源同步与运维时，正式命令行是 Rust 编译的 bat（近乎全自动：--auto-discover、--watch / --daemon 后只需偶发 status / refresh / repair，不需要持久手操维护）。

这不是说整个项目只有 Rust，也不是取消 Go 入口：

Go 的正式产品入口是 bat-api 服务进程（给客户端/工具提供启动前资源 bootstrap、server-info 改写和已发布资源字节），不是再做一套同步 CLI。
Go cmd/bat 仅试验，禁止与 Rust bat 二进制重名。

1.2 `bat` 与 `bat-api` 的关系

bat 是资源生产者和状态拥有者；bat-api 是资源读侧和 HTTP 入口。

关系面	Rust `bat` / daemon	Go `bat-api`
资源发现	读取官方 launcher/resource metadata，解析 `GameMainConfig`、server-info 和 Addressables root	通过 `bat.sock` 读取已发布版本摘要，不重新探测官方 metadata
下载与发布	下载、校验、staging、原子发布 `current -> versions/<id>`，维护 manifest/snapshot/version-state	不下载、不写 staging、不改 version-state；生产资源根来自 RPC 返回的 `resource_root`
启动前资源入口	暴露 `catalog.status` / `resource.manifest` 等 RPC 数据	提供 `/v1/bootstrap`、`/v1/launcher/bootstrap`、launcher 资源 metadata 兼容端点、`/v1/server-info` 和 CDN path，组织给客户端/补丁器使用
长期状态	watch/daemon、任务队列、日志、错误码、repair/sync/verify	周期性经 RPC 刷新内存索引；认证 Web 控制面仅白名单转发 reload/refresh/restart/sync/verify/repair/catalog-refresh，不持有或写入同步状态

这条边界允许 bat-api 做资源 bootstrap 兼容，但不允许它复制 Rust 下载器或伪装完整游戏业务服务。

1.3 决策（已核验）

G-008 决策关闭（wontfix）：不另做产品级 Go 同步/运维 CLI。
G-009：资源 bootstrap/分发 MVP 部分完成；非完整游戏业务 API。
USERGUIDE 的 bat-api 基础章节已补；全量 release 联调后继续补充生产参数和排障样例。

2. 既有约定核对表（不可丢）

职责

ID	约定
A	自动发现 / 下载 / 校验 / 发布 / watch·daemon 只在 Rust `bat`
B	`bat-api` 只读分发已发布 release，不实现下载器，不写 staging/version-state
C	仿真范围 = 资源拉取相关（resource bootstrap + CDN path + 可选 server-info）；不是完整游戏业务 API
D	launcher 资源 metadata 可作为 bootstrap 输入/输出兼容；账号、登录、网关和鉴权全链非 G-009 关闭条件
E	USERGUIDE bat-api 基础章节已补；联调后补充实战样例

发现与数据

ID	约定
F	版本/清单经 `bat.sock` JSON-RPC（`--socket`）；不读 daemon 内部状态文件
G	RPC 顺序：先 `daemon.status`，再 `daemon.doctor`，再 catalog/manifest
H	生产文件字节从 RPC 返回的 `resource_root` 读盘；`bat-api` 与 daemon 同服务器/同容器/共享文件系统部署；`--resource-root` 仅 fixture 或应急只读诊断
I	真数据在已全量拉取且长期运行 Rust `bat` 的远程服务器；开发机不跑全量 `bat`，用 fixture、mock RPC 和 Go 门禁验证；远程联调等连接信息
J	索引以 manifest + 磁盘 Present/size 为准
J2	RPC 状态以 Rust 返回的 `status` / `status_code` 为准；`bat-api` 只读消费，不自行推导同步状态

进程配置

ID	约定
K	`.env` / 环境变量 / CLI：端口、public base、RPC socket、RPC 刷新周期；预留 database/redis
L	管理面 / bootstrap：`/healthz`、`/readyz`、`/v1/bootstrap`、`/v1/release`、`/v1/resources`、`/openapi.yaml`、`/admin/` 控制入口
M	CDN：`GET/HEAD /prod-clientpatch.bluearchiveyostar.com/...`，支持 Range、ETag、Last-Modified、长期缓存头
N	server-info 可选；只改 AddressablesCatalogUrlRoot
N2	launcher 兼容仅限资源引导：`/v1/launcher/bootstrap` 与 `/api/launcher/...` 形状端点输出已发布 release、launcher metadata 和 GameMainConfig 摘要；不下载 launcher 包、不生成完整 PC package update manifest、不仿造登录/网关
N3	玩家-facing HTTP 控制面：可配置 token 鉴权、进程内限流、访问日志、反代 IP 适配、动态 JSON `no-store`、`/v1/resources` 分页上限
N4	`/admin/control/{action}` 白名单控制面；`restart` 通过 Rust live RPC 启动 lifecycle controller，Go 不直接执行 `bat` binary

工程

ID	约定
O	权威文档与 `go list` 一致，禁止「API 完全没有」等过时句
P	试验 CLI 产物 `bin/bat-go`，禁止 `bin/bat`
Q	空目录标明 reserved empty
R	默认门禁：`make test-go-api` + `make build-go-api`（无 FFI）

3. 组件进度

组件	路径	状态	说明
Module	`go.mod` → `bat-api`	已用	服务层模块名
RPC client	`internal/backendrpc`	完成	typed JSON-RPC；覆盖 daemon restart、resource/catalog/task、parse/localized 和文件级 UnityFS patch 调用；fake transport 单测，配合 `internal/api/testdata/contract/` 固化 Rust 输出 mirror
资源 bootstrap/分发	`cmd/bat-api` + `internal/api`	MVP+生产控制面	RPC 发现 + 周期刷新/诊断 + `/v1/bootstrap` + `/v1/launcher/bootstrap` + launcher 资源 metadata 兼容 + `/readyz` + CDN Range/缓存头 + 鉴权/限流/访问日志/反代适配 + OpenAPI + 管理控制白名单 + `.env`
试验 CLI	`cmd/bat`	试验	doctor 固定 ok；manifest/sync 走 FFI
FFI	`internal/ffi`	可选	需 `build-ffi`
空骨架	`api/`、`pkg/`、部分 `internal/`	空	见各目录 README
Web	`web/`	空	G-010

go list ./... 当前包：

bat-api/cmd/bat-api
bat-api/cmd/bat
bat-api/internal/api
bat-api/internal/backendrpc
bat-api/internal/ffi

4. 验证门禁

# 默认（提交前 / CI 建议）
make test-go-api
make build-go-api
go vet ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/...

# 可选：改 FFI 或试验 CLI 时
make build-ffi
make test-go-ffi
make build-go-cli   # 产出 bin/bat-go

5. 与缺口 / issue 对应

项	状态
G-008 Go 同步 CLI	已决策关闭（正式同步 CLI = Rust `bat`）
G-009 bat-api 资源 bootstrap/分发	部分完成（MVP+生产控制面）；已含资源 bootstrap 关系面、launcher 资源 metadata 兼容、HTTP 鉴权/限流/日志/反代适配、RPC 周期刷新/诊断、readiness、OpenAPI、管理控制白名单和部署模板，后续远程服务器联调/可选持久化
issue #19	资源面 MVP 与 USERGUIDE 基础章节已编码；真机联调后继续补充实战样例；未自动关 issue
G-010 Web	未开始

6. 资源布局与逆向

Release / URL / 分发契约（权威）：docs/architecture/resource-release-layout.md
真机全量实勘、seed inventory diff、issue #2/#3 样本采集按该文档 §9–§10 执行

7. 后续（不在进度统一范围内）

服务器 SSH 只读实勘（连接信息到位后）
bat-api 与远程长期运行的 bat / 全量 release 联调（含 /v1/bootstrap、server-info 和 CDN path）
预留 database/redis 的接入时机另议
USERGUIDE bat-api 联调排障样例（全量 release 验证后）
launcher 完整安装包更新链 / 登录网关链（若需要，新 issue）

8.5 KiB Raw Blame History Unescape Escape