4. 参数校验规则：必填校验、正则表达式校验、取值范围校验、自定义校验函数

在发布工程自助门户中，服务模板参数配置的校验规则是保障用户输入正确性、系统安全性与流程稳定性的第一道防线。一个健壮的参数校验体系能够有效拦截无效输入、降低运行时错误率，并提升自助服务的用户体验。本章将系统阐述四种核心校验规则：必填校验、正则表达式校验、取值范围校验以及自定义校验函数。

4.1 校验规则体系概览

参数校验规则按照复杂度与适用场景可分为基础规则与高级规则。基础规则通常由平台内置支持，配置简单；高级规则则允许开发者编写自定义逻辑，满足复杂业务场景。下表对比了四种规则的核心特性：

4.2 必填校验

必填校验是最基础、最常用的校验规则。它确保用户在提交参数时，关键字段不会被遗漏。在自助门户的服务模板中，以下参数通常应标记为必填：

• 服务标识参数： 服务名称、命名空间、集群选择。
• 部署配置参数： 镜像地址、副本数、端口映射。
• 环境依赖参数： 数据库连接串、缓存地址、密钥引用。

配置示例（YAML 格式）：

parameters:
  - name: appName
    label: 应用名称
    required: true
    errorMessage: "应用名称不能为空"
  - name: replicas
    label: 副本数
    required: true
    errorMessage: "请指定副本数量"

4.3 正则表达式校验

正则表达式校验用于约束参数值的格式规范。在发布工程场景中，常见的正则校验包括：

• 版本号格式： ^\d+\.\d+\.\d+$（如 1.2.3）
• 域名格式： ^[a-zA-Z0-9][-a-zA-Z0-9]{0,62}(\.[a-zA-Z0-9][-a-zA-Z0-9]{0,62})+$
• 环境标签： ^(dev|staging|prod)$
• K8s 资源名称： ^[a-z0-9]([a-z0-9\-]{0,61}[a-z0-9])?$

配置示例：

parameters:
  - name: version
    label: 发布版本
    pattern: "^\d+\.\d+\.\d+$"
    errorMessage: "版本号格式必须为 x.y.z，例如 1.0.0"
  - name: envTag
    label: 环境标签
    pattern: "^(dev|staging|prod)$"
    errorMessage: "环境标签仅支持 dev、staging、prod"

4.4 取值范围校验

取值范围校验适用于数值型参数或有限枚举型参数。它通过定义最小/最大值或允许值列表来约束输入。在自助门户中，以下场景尤为常见：

配置示例：

parameters:
  - name: replicas
    label: 副本数
    type: integer
    min: 1
    max: 50
    errorMessage: "副本数必须在 1 到 50 之间"
  - name: instanceType
    label: 实例规格
    type: string
    enum: ["small", "medium", "large", "xlarge"]
    errorMessage: "请选择有效的实例规格"

4.5 自定义校验函数

当内置规则无法满足复杂业务逻辑时，自定义校验函数提供了最大的灵活性。它允许开发者编写一段可执行代码，对参数值进行深度校验，甚至发起异步调用。常见场景包括：

• 交叉字段校验： 校验两个参数之间的逻辑关系（如开始时间必须早于结束时间）。
• 外部系统查询： 校验镜像标签是否在镜像仓库中存在、校验域名是否已被占用。
• 动态规则校验： 根据当前用户权限或环境上下文动态调整校验逻辑。

以下是一个自定义校验函数的 JavaScript 示例（前端校验）：

// 自定义校验函数：校验镜像标签是否合法
function validateImageTag(value, params, context) {
  // 规则1：不能为空
  if (!value || value.trim() === '') {
    return { valid: false, message: '镜像标签不能为空' };
  }
  // 规则2：必须包含冒号分隔的仓库和标签
  if (!value.includes(':')) {
    return { valid: false, message: '镜像标签格式必须为 repository:tag' };
  }
  // 规则3：标签部分不能以 '-' 结尾
  const tag = value.split(':')[1];
  if (tag && tag.endsWith('-')) {
    return { valid: false, message: '镜像标签不能以连字符结尾' };
  }
  return { valid: true };
}

后端自定义校验函数示例（Python，支持异步查询）：

# 自定义校验函数：校验镜像是否在仓库中存在
async def validate_image_exists(value, params, context):
    import aiohttp
    registry_url = context.get('registry_url')
    if not registry_url:
        return {"valid": False, "message": "镜像仓库地址未配置"}
    async with aiohttp.ClientSession() as session:
        url = f"{registry_url}/v2/{value}/manifests/latest"
        async with session.head(url) as resp:
            if resp.status != 200:
                return {"valid": False, "message": f"镜像 {value} 在仓库中不存在"}
    return {"valid": True}

4.6 校验规则执行流程

下图展示了自助门户中参数校验规则的完整执行流程，从用户输入到最终提交的校验链路：

4.7 校验规则配置清单

在实际配置服务模板参数时，建议按照以下清单逐项确认校验规则是否完备：

1. 识别关键参数： 列出所有参数，标记哪些是业务关键字段。
2. 确定必填项： 对每个关键参数判断是否允许为空。
3. 定义格式规范： 对字符串类型参数，编写正则表达式约束格式。
4. 设定数值边界： 对数值类型参数，明确最小值和最大值。
5. 枚举可选值： 对有限选项参数，列出所有允许值。
6. 编写自定义逻辑： 对交叉依赖或外部查询场景，实现自定义校验函数。
7. 配置错误提示： 为每条校验规则编写清晰、友好的错误提示信息。
8. 测试校验覆盖： 编写测试用例，覆盖合法输入、边界输入和非法输入。