游戏客户端架构 / 系统课时

如何阻止不合规资源进入主干

如何阻止不合规资源进入主干

资源命名错误、放错目录、扩展名不允许或元数据缺失,如果等到打包阶段才暴露,修复成本会很高。本节把这些规则做成可重复执行的静态校验器,并设计本地检查、CI 阻断、失败反馈和修复入口,让不合规资源在进入主干前就被拦下。

学习目标

  • 把命名、路径、扩展名和元数据要求转成确定性校验规则
  • 用非零退出码让 CI 能真正阻断不合规提交
  • 让失败信息直接指出文件、规则和修复方向

先把规则写成机器能判断的条件

有效规则必须满足两个条件:结果确定,并且能够自动修复或明确告诉人怎么修。例如“命名要规范”不可执行,而“文件名只允许小写字母、数字和下划线”就可以静态判断。

本节使用以下最小规则:

  • 资源必须位于 assets/characters 或 assets/environment 下。
  • 文件名只能使用小写字母、数字和下划线。
  • 只允许 .fbx、.png、.wav 三类资源。
  • 每个资源都必须存在同名 .assetmeta.json。
  • 元数据至少包含 schemaVersion、platforms 和 runtimeUsage。

这些规则适合放在独立校验器中,而不是散落在构建脚本的多个分支里。

实现一个可阻断提交的校验器

下面脚本只依赖 Python 标准库。它递归扫描 assets 目录,逐个检查路径、文件名、扩展名和伴随元数据;只要发现一个错误,就以退出码 1 结束。

python
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())

假设项目目录中的资源都符合规则,执行:

bash
python validate_assets.py

预期输出:

text
OK: all assets passed validation

如果存在 assets/characters/Hero Body.fbx,且没有对应元数据文件,则会得到类似下面的失败结果:

text
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 直接执行同一个脚本:

yaml
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 提供不可绕过的最终保证,而错误信息直接给出修复入口。这样主干保存的是已经满足流水线契约的资源,而不是把问题推迟到导入、打包或运行阶段。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

如何阻止不合规资源进入主干

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通