mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-21 22:11:26 +08:00
feat(core): 引入统一错误码模型并新增 USERGUIDE
为 issue #1 的公共错误契约建立错误码模型： - core/src/error_code.rs：ErrorCode（BAT-ERR-<域3位><序号3位>，如 BAT-ERR-300012） + 44 个初始码表（覆盖输入/路径安全/网络下载/校验/发布存储/解析/任务RPC/内部 八域，网络域含代理故障 310001）、ErrorDomain、以及进入 RPC envelope / --json / bat-events.jsonl 的统一 ApiError { code, kind, domain, location, message, retryable }。 location 用稳定的组件·操作标签（不随行号漂移）。 - 新增 USERGUIDE.md：bat 命令、选项（发现/同步/守护/输出）、退出码（含 75=locked）、 运行时默认值，以及从码表同步的错误码参考（含承载结构与域一览）。 命名遵循国际惯例（英文 kind/domain slug）。码表以 error_code.rs 为准，USERGUIDE 错误码表与之逐条一致。后续各链路报错接入该码表在 issue #1 下推进。 对应 issue #1（错误码模型 + 用户指南）。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Claude Fable 5
+222
@@ -0,0 +1,222 @@
|
||||
# BlueArchiveToolkit 用户指南
|
||||
|
||||
本指南面向 `bat` 官方资源同步二进制的使用者，覆盖：命令、选项、退出码、运行时行为，以及统一错误码参考。
|
||||
|
||||
- 权威运行/部署说明另见 `docs/guides/official-resource-test-pull.md` 和 `docs/guides/deployment.md`。
|
||||
- 本文档中的命令、选项以 `bat --help` 为准；错误码以 `core/src/error_code.rs` 的码表为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 概览
|
||||
|
||||
`bat` 是 Linux 上官方日服（Yostar JP）资源同步的正式入口。它可以：
|
||||
|
||||
- `--auto-discover` 从官方 HTTP metadata 解析 `GameMainConfig`，自动获得 app-version、连接组和 server-info，不安装、不启动官方启动器。
|
||||
- 生成官方全量 pull plan、执行真实下载，维护 release 内的下载 manifest，并做 size + BLAKE3 复用校验、官方 seed `.hash`（标准 xxHash32(seed=0)）强校验、ZIP 结构校验。
|
||||
- 断点续传、失败分类重试、下载 quarantine、本地 manifest audit/repair。
|
||||
- 原子发布：先写 `.staging/<id>`，校验通过后发布 `versions/<id>` 并原子切换 `current` symlink。
|
||||
- 常驻运行（`--watch`）或后台化（`--daemon`），通过 `bat.sock` Unix socket JSON-RPC 控制。
|
||||
|
||||
### 运行形态
|
||||
|
||||
```bash
|
||||
# 一次性 dry-run（不写状态）
|
||||
bat --auto-discover --dry-run
|
||||
|
||||
# 前台常驻
|
||||
bat --auto-discover --watch --output /var/lib/bluearchive-toolkit/official
|
||||
|
||||
# 后台守护
|
||||
bat --auto-discover --daemon --output /var/lib/bluearchive-toolkit/official
|
||||
```
|
||||
|
||||
带凭据的代理**推荐用环境变量**（凭据不进命令行/argv/状态文件）：
|
||||
|
||||
```bash
|
||||
HTTPS_PROXY=http://user:pass@127.0.0.1:7890 bat --auto-discover --daemon
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 命令
|
||||
|
||||
无子命令时执行一次性同步（或配合 `--watch`/`--daemon`）。子命令如下：
|
||||
|
||||
| 命令 | 说明 |
|
||||
|---|---|
|
||||
| `refresh` | 执行一次更新检查；若有 live daemon，则通过 RPC 请求其刷新 |
|
||||
| `verify` | 校验远端计划、本地 manifest 和官方 seed hash（dry-run + 审计当前 release） |
|
||||
| `repair` | 重新下载本地校验失败的资源 |
|
||||
| `status` | 显示 daemon 状态 |
|
||||
| `stop` | 停止 daemon |
|
||||
| `restart` | 重启 daemon；未显式传参时复用保存的参数 |
|
||||
| `reload` | 请求 daemon 重新自动发现并强制刷新 |
|
||||
| `logs` | 显示 daemon 日志尾部（配合 `--tail`） |
|
||||
| `doctor` | 运行时诊断（输出目录、状态目录、curl/unzip、代理、PID、socket、锁） |
|
||||
| `clean-stable` | 清理 `.part`/`.tmp`/失效锁、PID、socket（daemon 运行中会拒绝执行） |
|
||||
|
||||
`status`/`stop`/`logs`/`reload` 和默认形态的 `refresh` 优先走 `bat.sock` JSON-RPC；socket 不可用时 `status`/`stop` 回退到 PID/状态文件兼容路径。
|
||||
|
||||
---
|
||||
|
||||
## 3. 选项
|
||||
|
||||
### 发现（Discovery）
|
||||
|
||||
| 选项 | 说明 |
|
||||
|---|---|
|
||||
| `--auto-discover` | 自动发现 app-version、server-info、连接组 |
|
||||
| `--server-info-url <URL>` | 使用官方 server-info URL |
|
||||
| `--server-info-file <NAME>` | 使用官方 server-info 文件名 |
|
||||
| `--server-info-path <PATH>` | 使用本地 server-info JSON 文件 |
|
||||
| `--app-version <VERSION>` | 覆盖 app 版本 |
|
||||
| `--connection-group <NAME>` | 覆盖连接组 |
|
||||
| `--launcher-version <VERSION>` | 启动器 metadata API 版本（默认 `1.7.2`） |
|
||||
|
||||
### 同步（Sync）
|
||||
|
||||
| 选项 | 说明 |
|
||||
|---|---|
|
||||
| `--platforms <LIST>` | 平台，如 `Windows,Android`（默认 `Windows,Android`） |
|
||||
| `--output <DIR>` | 资源发布根目录（默认 `./bat-resources`） |
|
||||
| `--snapshot <PATH>` | 覆盖 snapshot 路径（默认 `<output>/current/official-sync-snapshot.json`） |
|
||||
| `--curl <PATH>` | curl 可执行文件（默认 `curl`） |
|
||||
| `--proxy <URL\|auto\|none>` | curl 代理覆盖（默认 `auto`，从环境变量检测）。scheme 支持 http/https/socks4/socks4a/socks5/socks5h |
|
||||
| `--no-proxy` | 强制直连 |
|
||||
| `--unzip <PATH>` | unzip 可执行文件（默认 `unzip`） |
|
||||
| `--dry-run` | 不写同步状态 |
|
||||
| `--plan` | dry-run 时输出计划中的 URL |
|
||||
| `--force` | 强制下载/刷新 |
|
||||
| `--audit-local` / `--no-audit-local` | 启用/关闭本地 manifest 审计 |
|
||||
| `--repair` / `--no-repair` | 启用/关闭自动修复 |
|
||||
|
||||
### 守护（Daemon）
|
||||
|
||||
| 选项 | 说明 |
|
||||
|---|---|
|
||||
| `--watch` | 前台常驻循环 |
|
||||
| `--daemon` | 启动脱离终端的后台 watch 进程 |
|
||||
| `--state-dir <DIR>` | 后台状态目录（默认 `/tmp/bat-pid`） |
|
||||
| `--interval <DURATION>` | 正常检查周期（默认 `1h`） |
|
||||
| `--error-retry <DURATION>` | 失败后重试周期（默认 `60s`） |
|
||||
| `--quiet-up-to-date` / `--no-quiet-up-to-date` | 静默/总是打印 up-to-date 报告 |
|
||||
| `--tail <N>` | `logs` 命令返回的日志行数（默认 `200`） |
|
||||
|
||||
### 输出（Output）
|
||||
|
||||
| 选项 | 说明 |
|
||||
|---|---|
|
||||
| `--human` | 人类可读输出（默认） |
|
||||
| `--json` | 面向脚本的稳定 JSON 输出 |
|
||||
| `--progress` / `--no-progress` | 启用/关闭 stderr 进度日志 |
|
||||
| `--banner` / `--no-banner` | 启用/关闭启动横幅 |
|
||||
| `-h`, `--help` | 显示帮助 |
|
||||
|
||||
### 默认值与运行时行为
|
||||
|
||||
- 平台：`Windows,Android`。
|
||||
- 资源输出：`./bat-resources`（`current` → `versions/<id>`、`.staging/<id>`）。
|
||||
- 后台状态目录：`/tmp/bat-pid`（`bat.sock`、`bat.pid`、`bat-status.json`、`bat-daemon.log`、`bat-events.jsonl`、短生命周期 `bat-control.lock`；代理凭据在 `bat-proxy.secret`，`0600`）。
|
||||
- 强制刷新：每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 各一次。
|
||||
- 状态类文件默认 `0600` 权限，读写不跟随 symlink。
|
||||
|
||||
---
|
||||
|
||||
## 4. 退出码
|
||||
|
||||
| 退出码 | 含义 |
|
||||
|---|---|
|
||||
| `0` | 成功；`verify`/`doctor` 检查通过 |
|
||||
| `1` | 普通错误 |
|
||||
| `75` | 资源目录锁冲突（有 live daemon 正在管理同一目录，或 `.official-sync.lock` 被占用） |
|
||||
|
||||
`verify` 或 `doctor` 发现问题也返回非 0。`--json` 模式下错误以 JSON 写到 stderr。
|
||||
|
||||
---
|
||||
|
||||
## 5. 错误码参考
|
||||
|
||||
`bat` 使用一套稳定的数字错误码，作为 CLI、daemon RPC 和结构化日志的公共错误契约。
|
||||
|
||||
- **格式**：`BAT-ERR-<域 3 位><序号 3 位>`，共 6 位，例如 `BAT-ERR-300012`。
|
||||
- **域**：错误码首位按百位分大类。
|
||||
- **承载结构**（RPC envelope 的 `error` 字段、`--json` 输出、`bat-events.jsonl` 一致）：
|
||||
|
||||
```json
|
||||
"error": {
|
||||
"code": "BAT-ERR-310001",
|
||||
"kind": "proxy_failure",
|
||||
"domain": "network",
|
||||
"location": "official-sync.download.pull_one",
|
||||
"message": "代理返回 407 认证失败",
|
||||
"retryable": false
|
||||
}
|
||||
```
|
||||
|
||||
`location` 是稳定的「组件·操作」标签（跟随语义、不随行号漂移）。`retryable` 是该类错误的默认可重试性。
|
||||
|
||||
> 说明：错误码模型（`core/src/error_code.rs`）已建立并作为公共契约；将各链路的报错逐步接入到该码表的工作在 issue #1 下推进。下表随码表更新。
|
||||
|
||||
### 域一览
|
||||
|
||||
| 域 | 区间 | 含义 |
|
||||
|---|---|---|
|
||||
| input | `1xxxxx` | 输入/配置：CLI 参数、配置校验、代理配置 |
|
||||
| path_security | `2xxxxx` | 路径/安全边界：危险目录、路径逃逸、symlink、权限 |
|
||||
| network | `3xxxxx` | 网络/下载：HTTP/网络错误、代理故障、重试耗尽、quarantine |
|
||||
| integrity | `4xxxxx` | 校验/完整性：BLAKE3、官方 seed hash、size、ZIP 结构 |
|
||||
| publish_storage | `5xxxxx` | 发布/版本状态/存储：staging、原子发布、version-state、锁、CAS |
|
||||
| parse | `6xxxxx` | 解析/适配：manifest、UnityFS、GameMainConfig |
|
||||
| task_rpc | `7xxxxx` | 任务/RPC：未知方法、参数非法、未实现、任务不存在 |
|
||||
| internal | `9xxxxx` | 内部/未知：兜底 |
|
||||
|
||||
### 码表
|
||||
|
||||
| 码 | kind | 可重试 | 含义 |
|
||||
|---|---|:---:|---|
|
||||
| `BAT-ERR-100001` | missing_app_version | 否 | 缺少应用版本（未传 `--app-version` 且未启用 `--auto-discover`） |
|
||||
| `BAT-ERR-100002` | missing_connection_group | 否 | 缺少连接组 |
|
||||
| `BAT-ERR-100003` | missing_server_info_source | 否 | 缺少服务器信息来源 |
|
||||
| `BAT-ERR-100004` | invalid_proxy_scheme | 否 | 代理 URL scheme 不受支持 |
|
||||
| `BAT-ERR-100010` | invalid_argument | 否 | 命令行参数无效 |
|
||||
| `BAT-ERR-200001` | dangerous_output_root | 否 | 输出目录被判定为危险路径 |
|
||||
| `BAT-ERR-200002` | path_escape | 否 | 路径逃逸出允许根目录 |
|
||||
| `BAT-ERR-200003` | symlink_rejected | 否 | 目标不允许是 symlink 或路径组件含 symlink |
|
||||
| `BAT-ERR-200004` | file_permission | 否 | 文件权限或模式错误 |
|
||||
| `BAT-ERR-300001` | http_forbidden | 否 | HTTP 403 |
|
||||
| `BAT-ERR-300002` | http_not_found | 否 | HTTP 404 |
|
||||
| `BAT-ERR-300003` | http_client_error | 否 | HTTP 其它 4xx |
|
||||
| `BAT-ERR-300004` | http_too_many_requests | 是 | HTTP 429 / 请求过多 |
|
||||
| `BAT-ERR-300005` | http_server_error | 是 | HTTP 5xx |
|
||||
| `BAT-ERR-300010` | network_dns | 是 | DNS 解析失败 |
|
||||
| `BAT-ERR-300011` | network_connect | 是 | 连接失败 |
|
||||
| `BAT-ERR-300012` | network_timeout | 是 | 超时 |
|
||||
| `BAT-ERR-300013` | network_tls | 是 | TLS 失败 |
|
||||
| `BAT-ERR-300014` | network_interrupted | 是 | 传输中断 |
|
||||
| `BAT-ERR-300015` | network_other | 是 | 其它网络错误 |
|
||||
| `BAT-ERR-300020` | retry_exhausted | 否 | 下载重试次数耗尽 |
|
||||
| `BAT-ERR-300021` | quarantined | 否 | URL 因反复失败进入 quarantine |
|
||||
| `BAT-ERR-300030` | non_official_url | 否 | URL 不是官方 host（被拒绝） |
|
||||
| `BAT-ERR-310001` | proxy_failure | 否 | 代理自身故障（认证/解析/连接代理失败） |
|
||||
| `BAT-ERR-400001` | blake3_mismatch | 否 | 本地 BLAKE3 与 manifest 不符 |
|
||||
| `BAT-ERR-400002` | official_hash_mismatch | 否 | 官方 seed `.hash`（xxHash32）校验不符 |
|
||||
| `BAT-ERR-400003` | size_mismatch | 否 | 文件大小与 manifest 不符 |
|
||||
| `BAT-ERR-400004` | zip_structure_invalid | 否 | ZIP 结构无效 |
|
||||
| `BAT-ERR-500001` | resource_locked | 否 | 资源目录锁冲突（对应退出码 75） |
|
||||
| `BAT-ERR-500002` | staging_prepare_failed | 否 | staging 准备失败 |
|
||||
| `BAT-ERR-500003` | publish_failed | 否 | 原子发布失败 |
|
||||
| `BAT-ERR-500004` | version_state_write_failed | 是 | 版本状态写入失败 |
|
||||
| `BAT-ERR-500010` | cas_hash_mismatch | 否 | CAS 对象 Hash 不匹配 |
|
||||
| `BAT-ERR-500011` | cas_object_not_found | 否 | CAS 对象不存在 |
|
||||
| `BAT-ERR-500012` | cas_reference_underflow | 否 | CAS 引用计数下溢 |
|
||||
| `BAT-ERR-500013` | cas_database | 否 | CAS 元数据库错误 |
|
||||
| `BAT-ERR-600001` | manifest_parse_failed | 否 | Manifest / Addressables catalog 解析失败 |
|
||||
| `BAT-ERR-600002` | unityfs_parse_failed | 否 | UnityFS 解析失败 |
|
||||
| `BAT-ERR-600003` | game_main_config_failed | 否 | GameMainConfig 解密/解析失败 |
|
||||
| `BAT-ERR-700001` | rpc_unknown_method | 否 | 未知 RPC 方法 |
|
||||
| `BAT-ERR-700002` | rpc_invalid_params | 否 | RPC 参数无效 |
|
||||
| `BAT-ERR-700003` | rpc_not_implemented | 否 | 方法/命名空间尚未实现 |
|
||||
| `BAT-ERR-700004` | task_not_found | 否 | 任务不存在 |
|
||||
| `BAT-ERR-900001` | internal | 否 | 未归类的内部错误 |
|
||||
|
||||
新增错误码在 `core/src/error_code.rs` 的码表登记后，同步更新本表。
|
||||
@@ -0,0 +1,397 @@
|
||||
//! 统一错误码模型。
|
||||
//!
|
||||
//! 为 CLI、daemon RPC 和结构化日志提供一套稳定的数字错误码（`BAT-ERR-NNNNNN`）、
|
||||
//! 错误类别（kind）、问题位置（location）和可重试标记，作为项目公共错误契约。
|
||||
//!
|
||||
//! 码格式：`BAT-ERR-<域 3 位><序号 3 位>`，共 6 位，例如 `BAT-ERR-300012`。
|
||||
//! 域号按百位分大类，中间位保留给子域。
|
||||
|
||||
use serde::ser::{Serialize, SerializeStruct, Serializer};
|
||||
|
||||
/// 错误大类（域），对应错误码首位所在的百位区间。
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum ErrorDomain {
|
||||
/// 输入/配置（`1xxxxx`）：CLI 参数、配置校验、代理配置等。
|
||||
Input,
|
||||
/// 路径/安全边界（`2xxxxx`）：危险目录、路径逃逸、symlink、权限。
|
||||
PathSecurity,
|
||||
/// 网络/下载（`3xxxxx`）：curl HTTP/网络错误、代理故障、重试耗尽、quarantine。
|
||||
Network,
|
||||
/// 校验/完整性（`4xxxxx`）：BLAKE3、官方 seed hash、size、ZIP 结构。
|
||||
Integrity,
|
||||
/// 发布/版本状态/存储（`5xxxxx`）：staging、原子发布、version-state、锁、CAS。
|
||||
PublishStorage,
|
||||
/// 解析/适配（`6xxxxx`）：manifest、UnityFS、GameMainConfig。
|
||||
Parse,
|
||||
/// 任务/RPC（`7xxxxx`）：未知方法、参数非法、未实现、任务不存在。
|
||||
TaskRpc,
|
||||
/// 内部/未知（`9xxxxx`）：兜底。
|
||||
Internal,
|
||||
}
|
||||
|
||||
impl ErrorDomain {
|
||||
/// 从错误码数字推断所属域。
|
||||
pub fn from_number(number: u32) -> Self {
|
||||
match number / 100_000 {
|
||||
1 => Self::Input,
|
||||
2 => Self::PathSecurity,
|
||||
3 => Self::Network,
|
||||
4 => Self::Integrity,
|
||||
5 => Self::PublishStorage,
|
||||
6 => Self::Parse,
|
||||
7 => Self::TaskRpc,
|
||||
_ => Self::Internal,
|
||||
}
|
||||
}
|
||||
|
||||
/// 返回域的稳定英文标签。
|
||||
pub fn label(self) -> &'static str {
|
||||
match self {
|
||||
Self::Input => "input",
|
||||
Self::PathSecurity => "path_security",
|
||||
Self::Network => "network",
|
||||
Self::Integrity => "integrity",
|
||||
Self::PublishStorage => "publish_storage",
|
||||
Self::Parse => "parse",
|
||||
Self::TaskRpc => "task_rpc",
|
||||
Self::Internal => "internal",
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// 单个稳定错误码：数字、类别 slug 和默认可重试标记。
|
||||
///
|
||||
/// 通过命名常量引用（如 [`ErrorCode::HTTP_FORBIDDEN`]），保证码值稳定、可查表。
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct ErrorCode {
|
||||
number: u32,
|
||||
kind: &'static str,
|
||||
retryable: bool,
|
||||
}
|
||||
|
||||
impl ErrorCode {
|
||||
const fn new(number: u32, kind: &'static str, retryable: bool) -> Self {
|
||||
Self {
|
||||
number,
|
||||
kind,
|
||||
retryable,
|
||||
}
|
||||
}
|
||||
|
||||
/// 返回稳定的展示 ID，例如 `BAT-ERR-300012`。
|
||||
pub fn id(&self) -> String {
|
||||
format!("BAT-ERR-{:06}", self.number)
|
||||
}
|
||||
|
||||
/// 返回错误码数字。
|
||||
pub fn number(&self) -> u32 {
|
||||
self.number
|
||||
}
|
||||
|
||||
/// 返回错误类别 slug（英文、稳定）。
|
||||
pub fn kind(&self) -> &'static str {
|
||||
self.kind
|
||||
}
|
||||
|
||||
/// 返回该类错误默认是否可重试。
|
||||
pub fn retryable(&self) -> bool {
|
||||
self.retryable
|
||||
}
|
||||
|
||||
/// 返回所属错误域。
|
||||
pub fn domain(&self) -> ErrorDomain {
|
||||
ErrorDomain::from_number(self.number)
|
||||
}
|
||||
}
|
||||
|
||||
impl Serialize for ErrorCode {
|
||||
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
|
||||
serializer.serialize_str(&self.id())
|
||||
}
|
||||
}
|
||||
|
||||
/// 错误码码表。新增错误码只需在此登记，`docs`/`USERGUIDE.md` 从这里同步。
|
||||
impl ErrorCode {
|
||||
// ---- 100xxx 输入/配置 ----
|
||||
/// 缺少应用版本（未传 `--app-version` 且未启用 `--auto-discover`）。
|
||||
pub const MISSING_APP_VERSION: Self = Self::new(100_001, "missing_app_version", false);
|
||||
/// 缺少连接组。
|
||||
pub const MISSING_CONNECTION_GROUP: Self =
|
||||
Self::new(100_002, "missing_connection_group", false);
|
||||
/// 缺少服务器信息来源。
|
||||
pub const MISSING_SERVER_INFO_SOURCE: Self =
|
||||
Self::new(100_003, "missing_server_info_source", false);
|
||||
/// 代理 URL scheme 不受支持。
|
||||
pub const INVALID_PROXY_SCHEME: Self = Self::new(100_004, "invalid_proxy_scheme", false);
|
||||
/// 命令行参数无效。
|
||||
pub const INVALID_ARGUMENT: Self = Self::new(100_010, "invalid_argument", false);
|
||||
|
||||
// ---- 200xxx 路径/安全边界 ----
|
||||
/// 输出目录被判定为危险路径。
|
||||
pub const DANGEROUS_OUTPUT_ROOT: Self = Self::new(200_001, "dangerous_output_root", false);
|
||||
/// 路径逃逸出允许根目录。
|
||||
pub const PATH_ESCAPE: Self = Self::new(200_002, "path_escape", false);
|
||||
/// 目标不允许是 symlink 或路径组件含 symlink。
|
||||
pub const SYMLINK_REJECTED: Self = Self::new(200_003, "symlink_rejected", false);
|
||||
/// 文件权限或模式错误。
|
||||
pub const FILE_PERMISSION: Self = Self::new(200_004, "file_permission", false);
|
||||
|
||||
// ---- 300xxx 网络/下载 ----
|
||||
/// HTTP 403。
|
||||
pub const HTTP_FORBIDDEN: Self = Self::new(300_001, "http_forbidden", false);
|
||||
/// HTTP 404。
|
||||
pub const HTTP_NOT_FOUND: Self = Self::new(300_002, "http_not_found", false);
|
||||
/// HTTP 其它 4xx。
|
||||
pub const HTTP_CLIENT_ERROR: Self = Self::new(300_003, "http_client_error", false);
|
||||
/// HTTP 429 / 请求过多。
|
||||
pub const HTTP_TOO_MANY_REQUESTS: Self = Self::new(300_004, "http_too_many_requests", true);
|
||||
/// HTTP 5xx。
|
||||
pub const HTTP_SERVER_ERROR: Self = Self::new(300_005, "http_server_error", true);
|
||||
/// DNS 解析失败。
|
||||
pub const NETWORK_DNS: Self = Self::new(300_010, "network_dns", true);
|
||||
/// 连接失败。
|
||||
pub const NETWORK_CONNECT: Self = Self::new(300_011, "network_connect", true);
|
||||
/// 超时。
|
||||
pub const NETWORK_TIMEOUT: Self = Self::new(300_012, "network_timeout", true);
|
||||
/// TLS 失败。
|
||||
pub const NETWORK_TLS: Self = Self::new(300_013, "network_tls", true);
|
||||
/// 传输中断。
|
||||
pub const NETWORK_INTERRUPTED: Self = Self::new(300_014, "network_interrupted", true);
|
||||
/// 其它网络错误。
|
||||
pub const NETWORK_OTHER: Self = Self::new(300_015, "network_other", true);
|
||||
/// 下载重试次数耗尽。
|
||||
pub const RETRY_EXHAUSTED: Self = Self::new(300_020, "retry_exhausted", false);
|
||||
/// URL 因反复失败进入 quarantine。
|
||||
pub const QUARANTINED: Self = Self::new(300_021, "quarantined", false);
|
||||
/// URL 不是官方 host（被拒绝）。
|
||||
pub const NON_OFFICIAL_URL: Self = Self::new(300_030, "non_official_url", false);
|
||||
/// 代理自身故障（认证/解析/连接代理失败）。
|
||||
pub const PROXY_FAILURE: Self = Self::new(310_001, "proxy_failure", false);
|
||||
|
||||
// ---- 400xxx 校验/完整性 ----
|
||||
/// 本地 BLAKE3 与 manifest 不符。
|
||||
pub const BLAKE3_MISMATCH: Self = Self::new(400_001, "blake3_mismatch", false);
|
||||
/// 官方 seed `.hash`（xxHash32）校验不符。
|
||||
pub const OFFICIAL_HASH_MISMATCH: Self = Self::new(400_002, "official_hash_mismatch", false);
|
||||
/// 文件大小与 manifest 不符。
|
||||
pub const SIZE_MISMATCH: Self = Self::new(400_003, "size_mismatch", false);
|
||||
/// ZIP 结构无效。
|
||||
pub const ZIP_STRUCTURE_INVALID: Self = Self::new(400_004, "zip_structure_invalid", false);
|
||||
|
||||
// ---- 500xxx 发布/版本状态/存储 ----
|
||||
/// 资源目录锁冲突。
|
||||
pub const RESOURCE_LOCKED: Self = Self::new(500_001, "resource_locked", false);
|
||||
/// staging 准备失败。
|
||||
pub const STAGING_PREPARE_FAILED: Self = Self::new(500_002, "staging_prepare_failed", false);
|
||||
/// 原子发布失败。
|
||||
pub const PUBLISH_FAILED: Self = Self::new(500_003, "publish_failed", false);
|
||||
/// 版本状态写入失败。
|
||||
pub const VERSION_STATE_WRITE_FAILED: Self =
|
||||
Self::new(500_004, "version_state_write_failed", true);
|
||||
/// CAS 对象 Hash 不匹配。
|
||||
pub const CAS_HASH_MISMATCH: Self = Self::new(500_010, "cas_hash_mismatch", false);
|
||||
/// CAS 对象不存在。
|
||||
pub const CAS_OBJECT_NOT_FOUND: Self = Self::new(500_011, "cas_object_not_found", false);
|
||||
/// CAS 引用计数下溢。
|
||||
pub const CAS_REFERENCE_UNDERFLOW: Self = Self::new(500_012, "cas_reference_underflow", false);
|
||||
/// CAS 元数据库错误。
|
||||
pub const CAS_DATABASE: Self = Self::new(500_013, "cas_database", false);
|
||||
|
||||
// ---- 600xxx 解析/适配 ----
|
||||
/// Manifest / Addressables catalog 解析失败。
|
||||
pub const MANIFEST_PARSE_FAILED: Self = Self::new(600_001, "manifest_parse_failed", false);
|
||||
/// UnityFS 解析失败。
|
||||
pub const UNITYFS_PARSE_FAILED: Self = Self::new(600_002, "unityfs_parse_failed", false);
|
||||
/// GameMainConfig 解密/解析失败。
|
||||
pub const GAME_MAIN_CONFIG_FAILED: Self = Self::new(600_003, "game_main_config_failed", false);
|
||||
|
||||
// ---- 700xxx 任务/RPC ----
|
||||
/// 未知 RPC 方法。
|
||||
pub const RPC_UNKNOWN_METHOD: Self = Self::new(700_001, "rpc_unknown_method", false);
|
||||
/// RPC 参数无效。
|
||||
pub const RPC_INVALID_PARAMS: Self = Self::new(700_002, "rpc_invalid_params", false);
|
||||
/// 方法/命名空间尚未实现。
|
||||
pub const RPC_NOT_IMPLEMENTED: Self = Self::new(700_003, "rpc_not_implemented", false);
|
||||
/// 任务不存在。
|
||||
pub const TASK_NOT_FOUND: Self = Self::new(700_004, "task_not_found", false);
|
||||
|
||||
// ---- 900xxx 内部/未知 ----
|
||||
/// 未归类的内部错误。
|
||||
pub const INTERNAL: Self = Self::new(900_001, "internal", false);
|
||||
}
|
||||
|
||||
/// 结构化 API 错误：进入 RPC envelope、CLI `--json` 输出和结构化日志的统一形态。
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ApiError {
|
||||
code: ErrorCode,
|
||||
location: &'static str,
|
||||
message: String,
|
||||
}
|
||||
|
||||
impl ApiError {
|
||||
/// 构造错误：给定错误码、稳定的问题位置标签（如 `official-sync.download.pull_one`）
|
||||
/// 和人类可读消息。
|
||||
pub fn new(code: ErrorCode, location: &'static str, message: impl Into<String>) -> Self {
|
||||
Self {
|
||||
code,
|
||||
location,
|
||||
message: message.into(),
|
||||
}
|
||||
}
|
||||
|
||||
/// 错误码。
|
||||
pub fn code(&self) -> ErrorCode {
|
||||
self.code
|
||||
}
|
||||
|
||||
/// 问题位置标签。
|
||||
pub fn location(&self) -> &'static str {
|
||||
self.location
|
||||
}
|
||||
|
||||
/// 人类可读消息。
|
||||
pub fn message(&self) -> &str {
|
||||
&self.message
|
||||
}
|
||||
|
||||
/// 是否可重试（取自错误码默认值）。
|
||||
pub fn retryable(&self) -> bool {
|
||||
self.code.retryable()
|
||||
}
|
||||
}
|
||||
|
||||
impl std::fmt::Display for ApiError {
|
||||
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
write!(
|
||||
formatter,
|
||||
"[{} {}] {} (@{})",
|
||||
self.code.id(),
|
||||
self.code.kind(),
|
||||
self.message,
|
||||
self.location
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
impl std::error::Error for ApiError {}
|
||||
|
||||
impl Serialize for ApiError {
|
||||
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
|
||||
let mut state = serializer.serialize_struct("ApiError", 6)?;
|
||||
state.serialize_field("code", &self.code.id())?;
|
||||
state.serialize_field("kind", self.code.kind())?;
|
||||
state.serialize_field("domain", self.code.domain().label())?;
|
||||
state.serialize_field("location", self.location)?;
|
||||
state.serialize_field("message", &self.message)?;
|
||||
state.serialize_field("retryable", &self.code.retryable())?;
|
||||
state.end()
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn code_id_is_zero_padded_six_digits() {
|
||||
assert_eq!(ErrorCode::MISSING_APP_VERSION.id(), "BAT-ERR-100001");
|
||||
assert_eq!(ErrorCode::HTTP_FORBIDDEN.id(), "BAT-ERR-300001");
|
||||
assert_eq!(ErrorCode::PROXY_FAILURE.id(), "BAT-ERR-310001");
|
||||
assert_eq!(ErrorCode::INTERNAL.id(), "BAT-ERR-900001");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn code_maps_to_domain() {
|
||||
assert_eq!(ErrorCode::INVALID_ARGUMENT.domain(), ErrorDomain::Input);
|
||||
assert_eq!(ErrorCode::PATH_ESCAPE.domain(), ErrorDomain::PathSecurity);
|
||||
assert_eq!(ErrorCode::HTTP_SERVER_ERROR.domain(), ErrorDomain::Network);
|
||||
assert_eq!(ErrorCode::PROXY_FAILURE.domain(), ErrorDomain::Network);
|
||||
assert_eq!(ErrorCode::BLAKE3_MISMATCH.domain(), ErrorDomain::Integrity);
|
||||
assert_eq!(
|
||||
ErrorCode::PUBLISH_FAILED.domain(),
|
||||
ErrorDomain::PublishStorage
|
||||
);
|
||||
assert_eq!(ErrorCode::UNITYFS_PARSE_FAILED.domain(), ErrorDomain::Parse);
|
||||
assert_eq!(ErrorCode::TASK_NOT_FOUND.domain(), ErrorDomain::TaskRpc);
|
||||
assert_eq!(ErrorCode::INTERNAL.domain(), ErrorDomain::Internal);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn retryable_reflects_code_default() {
|
||||
assert!(ErrorCode::HTTP_SERVER_ERROR.retryable());
|
||||
assert!(!ErrorCode::HTTP_FORBIDDEN.retryable());
|
||||
assert!(!ErrorCode::PROXY_FAILURE.retryable());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn api_error_serializes_full_envelope_shape() {
|
||||
let error = ApiError::new(
|
||||
ErrorCode::PROXY_FAILURE,
|
||||
"official-sync.download.pull_one",
|
||||
"代理返回 407 认证失败",
|
||||
);
|
||||
let value = serde_json::to_value(&error).unwrap();
|
||||
assert_eq!(value["code"], "BAT-ERR-310001");
|
||||
assert_eq!(value["kind"], "proxy_failure");
|
||||
assert_eq!(value["domain"], "network");
|
||||
assert_eq!(value["location"], "official-sync.download.pull_one");
|
||||
assert_eq!(value["message"], "代理返回 407 认证失败");
|
||||
assert_eq!(value["retryable"], false);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn error_codes_are_unique() {
|
||||
// 防止新增码值撞号：列举全部命名常量，断言 number 唯一。
|
||||
let codes = [
|
||||
ErrorCode::MISSING_APP_VERSION,
|
||||
ErrorCode::MISSING_CONNECTION_GROUP,
|
||||
ErrorCode::MISSING_SERVER_INFO_SOURCE,
|
||||
ErrorCode::INVALID_PROXY_SCHEME,
|
||||
ErrorCode::INVALID_ARGUMENT,
|
||||
ErrorCode::DANGEROUS_OUTPUT_ROOT,
|
||||
ErrorCode::PATH_ESCAPE,
|
||||
ErrorCode::SYMLINK_REJECTED,
|
||||
ErrorCode::FILE_PERMISSION,
|
||||
ErrorCode::HTTP_FORBIDDEN,
|
||||
ErrorCode::HTTP_NOT_FOUND,
|
||||
ErrorCode::HTTP_CLIENT_ERROR,
|
||||
ErrorCode::HTTP_TOO_MANY_REQUESTS,
|
||||
ErrorCode::HTTP_SERVER_ERROR,
|
||||
ErrorCode::NETWORK_DNS,
|
||||
ErrorCode::NETWORK_CONNECT,
|
||||
ErrorCode::NETWORK_TIMEOUT,
|
||||
ErrorCode::NETWORK_TLS,
|
||||
ErrorCode::NETWORK_INTERRUPTED,
|
||||
ErrorCode::NETWORK_OTHER,
|
||||
ErrorCode::RETRY_EXHAUSTED,
|
||||
ErrorCode::QUARANTINED,
|
||||
ErrorCode::NON_OFFICIAL_URL,
|
||||
ErrorCode::PROXY_FAILURE,
|
||||
ErrorCode::BLAKE3_MISMATCH,
|
||||
ErrorCode::OFFICIAL_HASH_MISMATCH,
|
||||
ErrorCode::SIZE_MISMATCH,
|
||||
ErrorCode::ZIP_STRUCTURE_INVALID,
|
||||
ErrorCode::RESOURCE_LOCKED,
|
||||
ErrorCode::STAGING_PREPARE_FAILED,
|
||||
ErrorCode::PUBLISH_FAILED,
|
||||
ErrorCode::VERSION_STATE_WRITE_FAILED,
|
||||
ErrorCode::CAS_HASH_MISMATCH,
|
||||
ErrorCode::CAS_OBJECT_NOT_FOUND,
|
||||
ErrorCode::CAS_REFERENCE_UNDERFLOW,
|
||||
ErrorCode::CAS_DATABASE,
|
||||
ErrorCode::MANIFEST_PARSE_FAILED,
|
||||
ErrorCode::UNITYFS_PARSE_FAILED,
|
||||
ErrorCode::GAME_MAIN_CONFIG_FAILED,
|
||||
ErrorCode::RPC_UNKNOWN_METHOD,
|
||||
ErrorCode::RPC_INVALID_PARAMS,
|
||||
ErrorCode::RPC_NOT_IMPLEMENTED,
|
||||
ErrorCode::TASK_NOT_FOUND,
|
||||
ErrorCode::INTERNAL,
|
||||
];
|
||||
let mut numbers: Vec<u32> = codes.iter().map(ErrorCode::number).collect();
|
||||
let total = numbers.len();
|
||||
numbers.sort_unstable();
|
||||
numbers.dedup();
|
||||
assert_eq!(numbers.len(), total, "存在重复的错误码 number");
|
||||
}
|
||||
}
|
||||
@@ -17,10 +17,12 @@
|
||||
|
||||
pub mod domain;
|
||||
pub mod error;
|
||||
pub mod error_code;
|
||||
pub mod repositories;
|
||||
pub mod services;
|
||||
|
||||
pub use error::{Error, Result};
|
||||
pub use error_code::{ApiError, ErrorCode, ErrorDomain};
|
||||
|
||||
/// Core 版本号
|
||||
pub const VERSION: &str = env!("CARGO_PKG_VERSION");
|
||||
|
||||
Reference in New Issue
Block a user