如何设计高可用的skill定义规范：从技术规范到工程实践

5次阅读

没有评论

共计 1741 个字符，预计需要花费 5 分钟才能阅读完成。

在微服务架构中，技能（skill）作为独立的功能单元，经常需要被不同的服务调用和组合。如果没有统一的定义规范，很容易陷入以下困境：

系统耦合度高：各服务对 skill 的理解不一致，导致接口混乱
版本兼容性问题：skill 升级后，调用方无法适配新版本
维护困难：缺乏明确的契约，修改 skill 就像拆盲盒

定义 skill 规范主要有两种主流方案：

JSON Schema
优点：人类可读、支持动态验证、与 REST API 天然契合
缺点：性能稍差、二进制体积较大
Protocol Buffers
优点：高性能、二进制紧凑、强类型
缺点：需要编译、修改 schema 较麻烦

对于 skill 定义这种需要频繁修改和动态验证的场景，JSON Schema 通常是更好的选择。

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "SkillDefinition",
  "type": "object",
  "properties": {
    "apiVersion": {
      "type": "string",
      "pattern": "^v\\d+$",
      "description": "版本号格式如 v1,v2"
    },
    "metadata": {
      "type": "object",
      "properties": {"name": {"type": "string"},
        "description": {"type": "string"}
      },
      "required": ["name"]
    },
    "spec": {
      "type": "object",
      "additionalProperties": true
    }
  },
  "required": ["apiVersion", "metadata"]
}

版本控制(versioning)
使用 apiVersion 字段明确版本
版本号格式建议为 v1,v2 等
可扩展性(extensibility)
spec字段使用 additionalProperties 允许扩展
metadata中包含必要的核心元数据

from jsonschema import validate, ValidationError
import json

# 加载 schema
with open('skill_schema.json') as f:
    schema = json.load(f)

def validate_skill(skill_json):
    try:
        validate(instance=skill_json, schema=schema)
        # 额外的业务逻辑校验
        if not skill_json['apiVersion'].startswith('v'):
            raise ValueError("Invalid version format")
        return True
    except ValidationError as e:
        print(f"Schema validation failed: {e.message}")
        return False
    except ValueError as e:
        print(f"Business validation failed: {str(e)}")
        return False

在 AWS c5.large 实例上测试：