📚 课程目录第2章参数配置基础

2. 参数配置基础

服务模板的参数配置是自助门户的核心能力。一个设计良好的参数体系，能让用户在创建服务实例时仅需填写少量关键信息，而无需关心底层基础设施的复杂细节。本章将系统讲解参数的定义规范、支持的数据类型以及默认值的最佳实践。

2.1 参数定义结构

每个参数在模板中由一组元数据字段描述，这些字段共同定义了参数的名称、类型、约束和展示方式。以下是一个标准参数定义的结构示例：

parameters:
  - name: instance_type
    display_name: "实例规格"
    type: string
    default: "t3.medium"
    enum:
      - "t3.small"
      - "t3.medium"
      - "t3.large"
    description: "选择计算实例的规格类型"
    required: true
    group: "基础配置"
    order: 1

字段	说明	是否必填
name	参数唯一标识符，在模板内部引用时使用	是
display_name	门户界面中向用户展示的标签名称	是
type	参数的数据类型，决定输入控件的渲染方式	是
default	用户未填写时使用的默认值	否
enum	枚举类型参数的候选值列表	条件必填
description	参数的帮助提示文本，显示在输入框下方	推荐
required	标识用户是否必须提供该参数的值	否
group	参数在门户表单中的分组标签	否
order	参数在分组内的显示顺序	否

最佳实践：始终为每个参数提供 description 字段。清晰的帮助文本能减少用户咨询量，提升自助服务成功率。建议描述中包含取值范围、单位以及与其他参数的关联关系。

2.2 参数类型体系

自助门户支持四种核心参数类型，每种类型对应不同的输入控件和验证规则。选择正确的参数类型是保证用户输入质量的第一步。

2.3 各类型详解与使用场景

2.3.1 字符串 (string)

字符串是最通用的参数类型，适用于名称、标签、描述、连接地址等文本信息。支持通过 pattern 字段定义正则表达式进行格式验证。

parameters:
  - name: vpc_name
    type: string
    display_name: "VPC 名称"
    default: "production-vpc"
    pattern: "^[a-z0-9-]{3,32}$"
    description: "3-32位小写字母、数字或连字符"

2.3.2 数字 (number)

数字类型用于端口号、副本数量、资源配额等数值场景。可通过 min 和 max 字段约束取值范围。

parameters:
  - name: replica_count
    type: number
    display_name: "副本数量"
    default: 3
    min: 1
    max: 10
    description: "服务实例的副本数，建议生产环境至少3个"

2.3.3 布尔 (boolean)

布尔类型用于开关选项，例如是否启用日志收集、是否开启自动扩缩容等。在门户中渲染为开关控件或复选框。

parameters:
  - name: enable_monitoring
    type: boolean
    display_name: "启用监控"
    default: true
    description: "是否自动接入平台监控系统"

2.3.4 枚举 (enum)

枚举类型提供一组预定义的候选值，用户只能从中选择。适用于环境类型、地域、规格型号等有限选项的场景。

parameters:
  - name: environment
    type: enum
    display_name: "部署环境"
    default: "staging"
    enum:
      - "development"
      - "staging"
      - "production"
    description: "选择目标部署环境，生产环境将触发审批流程"

注意：枚举类型的 default 值必须严格匹配 enum 列表中的某个值，否则模板验证将失败。建议将最常用的选项设为默认值，减少用户操作步骤。

2.4 默认值设计原则

默认值是参数配置中提升用户体验的关键杠杆。合理的默认值能降低用户决策负担，同时保证服务实例的基线安全。

  默认值设计检查清单：
  安全基线：默认值必须符合最小权限原则，例如端口号避免使用 22、3306 等敏感端口作为默认值。
统计驱动：通过分析历史创建数据，选择出现频率最高的值作为默认值。
显式声明：在门户界面中明确标注哪些参数使用了默认值，避免用户产生困惑。
版本演进：当模板版本升级时，默认值的变更应遵循向后兼容策略，避免破坏已有实例。

2.5 参数验证与约束

除了类型和默认值，参数定义还支持丰富的验证规则，确保用户输入在进入编排引擎之前就符合预期。

验证规则	适用类型	示例
required	所有类型	用户必须提供值，不能留空
pattern	string	`pattern: "^[a-zA-Z0-9_-]+$"`
min / max	number	`min: 1, max: 65535`
enum	enum	值必须在预定义列表中
min_length / max_length	string	`min_length: 3, max_length: 64`

提示：验证规则在门户前端和后端引擎侧会分别执行。前端验证提供即时反馈，后端验证作为安全兜底。建议两端验证逻辑保持一致，避免出现前端通过而后端拒绝的情况。

2.6 参数分组与排序

当模板包含较多参数时，合理的分组和排序能显著提升表单的可填写性。通过 group 和 order 字段，可以将参数组织为逻辑清晰的表单区域。

parameters:
  # 基础配置组
  - name: app_name
    group: "基础配置"
    order: 1
  - name: environment
    group: "基础配置"
    order: 2

  # 资源规格组
  - name: instance_type
    group: "资源规格"
    order: 1
  - name: disk_size
    group: "资源规格"
    order: 2

  # 网络配置组
  - name: vpc_id
    group: "网络配置"
    order: 1
  - name: subnet_id
    group: "网络配置"
    order: 2

分组设计应遵循 从高频到低频、从基础到高级 的原则。最常用的参数放在第一个分组，高级或可选参数放在后续分组，必要时可使用折叠面板减少页面信息密度。