游戏客户端架构 / 系统课时
如何阻止不合规资源进入主干
如何阻止不合规资源进入主干
资源命名错误、放错目录、扩展名不允许或元数据缺失,如果等到打包阶段才暴露,修复成本会很高。本节把这些规则做成可重复执行的静态校验器,并设计本地检查、CI 阻断、失败反馈和修复入口,让不合规资源在进入主干前就被拦下。
学习目标
- 把命名、路径、扩展名和元数据要求转成确定性校验规则
- 用非零退出码让 CI 能真正阻断不合规提交
- 让失败信息直接指出文件、规则和修复方向
先把规则写成机器能判断的条件
有效规则必须满足两个条件:结果确定,并且能够自动修复或明确告诉人怎么修。例如“命名要规范”不可执行,而“文件名只允许小写字母、数字和下划线”就可以静态判断。
本节使用以下最小规则:
- 资源必须位于
assets/characters或assets/environment下。 - 文件名只能使用小写字母、数字和下划线。
- 只允许
.fbx、.png、.wav三类资源。 - 每个资源都必须存在同名
.assetmeta.json。 - 元数据至少包含
schemaVersion、platforms和runtimeUsage。
这些规则适合放在独立校验器中,而不是散落在构建脚本的多个分支里。
实现一个可阻断提交的校验器
下面脚本只依赖 Python 标准库。它递归扫描 assets 目录,逐个检查路径、文件名、扩展名和伴随元数据;只要发现一个错误,就以退出码 1 结束。
import json
import re
import sys
from pathlib import Path
ASSET_ROOT = Path("assets")
ALLOWED_DIRS = {
Path("assets/characters"),
Path("assets/environment"),
}
ALLOWED_EXTENSIONS = {".fbx", ".png", ".wav"}
NAME_PATTERN = re.compile(r"^[a-z0-9_]+$")
def validate_asset(path: Path) -> list[str]:
errors = []
relative_parent = path.parent
if not any(relative_parent == root or root in relative_parent.parents for root in ALLOWED_DIRS):
errors.append("path must be under assets/characters or assets/environment")
if path.suffix.lower() not in ALLOWED_EXTENSIONS:
errors.append(f"extension {path.suffix} is not allowed")
if not NAME_PATTERN.fullmatch(path.stem):
errors.append("file name may contain only lowercase letters, digits, and underscores")
meta_path = path.with_name(path.stem + ".assetmeta.json")
if not meta_path.exists():
errors.append(f"missing metadata file: {meta_path.as_posix()}")
return errors
try:
metadata = json.loads(meta_path.read_text(encoding="utf-8"))
except json.JSONDecodeError as exc:
errors.append(f"invalid metadata JSON: {exc.msg}")
return errors
for field in ("schemaVersion", "platforms", "runtimeUsage"):
if field not in metadata:
errors.append(f"metadata missing required field: {field}")
return errors
def main() -> int:
if not ASSET_ROOT.exists():
print("ERROR: assets directory does not exist")
return 1
failures = 0
for path in sorted(ASSET_ROOT.rglob("*")):
if not path.is_file() or path.name.endswith(".assetmeta.json"):
continue
errors = validate_asset(path)
for error in errors:
failures += 1
print(f"{path.as_posix()}: {error}")
if failures:
print(f"FAILED: {failures} validation error(s)")
return 1
print("OK: all assets passed validation")
return 0
if __name__ == "__main__":
raise SystemExit(main())假设项目目录中的资源都符合规则,执行:
python validate_assets.py预期输出:
OK: all assets passed validation如果存在 assets/characters/Hero Body.fbx,且没有对应元数据文件,则会得到类似下面的失败结果:
assets/characters/Hero Body.fbx: file name may contain only lowercase letters, digits, and underscores
assets/characters/Hero Body.fbx: missing metadata file: assets/characters/Hero Body.assetmeta.json
FAILED: 2 validation error(s)失败数量会随实际资源变化,但退出码仍为 1,CI 可以据此拒绝合并。
把校验放在主干之前
只在开发者本机运行校验还不够,因为本地钩子可能被跳过。更稳妥的做法是同时保留两个入口:本地命令用于快速反馈,CI 作为最终强制门禁。

以 GitHub Actions 为例,可以让 CI 直接执行同一个脚本:
name: asset-validation
on:
pull_request:
paths:
- "assets/**"
- "validate_assets.py"
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: python validate_assets.py这段配置的验证方法是:在拉取请求中提交一个故意违规的资源,检查工作流是否失败;修正资源后再次提交,工作流应恢复成功。具体运行编号和时间属于动态值,不应写进规则本身。
失败反馈要能直接指导修复
校验器最忌讳只输出“validation failed”。有效反馈至少要包含三个信息:哪个文件失败、触发了哪条规则、下一步应该改什么。这样开发者无需打开 CI 配置或查脚本源码就能修复。
对于可以机械修复的问题,还可以在校验器之外增加独立修复命令,例如统一改名或补齐元数据模板;但校验命令本身应保持只读。门禁阶段偷偷修改资源会让提交内容和开发者看到的内容不一致,也会掩盖真正的问题。
防止规则本身变成新的阻塞点
静态校验应优先检查可客观判断的约束,不要把审美偏好或模糊质量标准塞进硬门禁。规则升级时,也应先批量修复存量资源,再开启新的强制检查,否则一次规则调整可能让整个仓库同时变红。
最终目标不是让 CI 更严格,而是让资源问题尽量在离作者最近的位置暴露:本地检查给出秒级反馈,CI 提供不可绕过的最终保证,而错误信息直接给出修复入口。这样主干保存的是已经满足流水线契约的资源,而不是把问题推迟到导入、打包或运行阶段。