命令行与文本处理 / 系统课时

校验函数参数

校验函数参数

参数校验把错误拦截在函数入口,而不是让非法值进入业务逻辑后才失败。本课将组合类型约束与五类验证属性,并通过成功和失败调用验证它们的实际行为。

学习目标

  • 根据参数特征选择合适的验证属性
  • 组合类型约束、集合、范围、格式和脚本校验
  • 设计可预测、可捕获的参数绑定错误

参数校验发生在函数体之前

PowerShell 会先完成参数绑定、类型转换和验证,再进入 Begin、Process 或 End。任一参数不满足约束时,函数体不会开始执行,因此校验适合保护文件写入、远程调用和配置变更等有副作用的操作。

类型约束负责把输入转换为目标类型,例如 [int]、[datetime]、[uri];验证属性则检查转换后的值是否符合业务规则。两者组合使用,能够把“数据类型正确”和“业务取值合理”分开表达。

选择合适的验证器

约束 适用问题 典型示例
ValidateSet 值必须来自固定集合 环境只能是 dev、test、prod
ValidateRange 数值必须位于闭区间 副本数为 1 到 20
ValidatePattern 字符串必须符合正则格式 版本号必须是 v1.2.3
ValidateScript 需要自定义条件或跨属性检查 URI 必须使用 HTTPS
类型约束 输入必须能转换为指定类型 端口为整数、地址为 URI

优先使用语义明确的内置验证器。只有现成属性无法表达规则时才使用 ValidateScript,并让脚本返回 $true 或抛出清晰异常。

主示例:组合五类约束

下面的函数创建部署规格对象。它同时使用固定集合、数值范围、正则格式、自定义脚本和类型约束;第二次调用故意传入非法版本号,用于确认函数体不会执行。

powershell
function New-DeploymentSpec {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [ValidateSet('dev', 'test', 'prod')]
        [string]$Environment,

        [Parameter(Mandatory)]
        [ValidateRange(1, 20)]
        [int]$Replicas,

        [Parameter(Mandatory)]
        [ValidatePattern('^v\d+\.\d+\.\d+$')]
        [string]$Version,

        [Parameter(Mandatory)]
        [ValidateScript({
            if ($_.Scheme -ne 'https') {
                throw 'Endpoint must use HTTPS.'
            }
            $true
        })]
        [uri]$Endpoint,

        [Parameter(Mandatory)]
        [ValidateRange(1024, 65535)]
        [int]$Port
    )

    # 只有全部参数通过绑定与校验后,函数体才会创建对象。
    [pscustomobject]@{
        Environment = $Environment
        Replicas    = $Replicas
        Version     = $Version
        Endpoint    = $Endpoint.AbsoluteUri
        Port        = $Port
    }
}

$spec = New-DeploymentSpec `
    -Environment 'prod' `
    -Replicas 3 `
    -Version 'v1.4.0' `
    -Endpoint 'https://api.example.com' `
    -Port 8443

'{0}|{1}|{2}|{3}|{4}' -f `
    $spec.Environment,
    $spec.Replicas,
    $spec.Version,
    $spec.Endpoint,
    $spec.Port

try {
    New-DeploymentSpec `
        -Environment 'prod' `
        -Replicas 3 `
        -Version '1.4' `
        -Endpoint 'https://api.example.com' `
        -Port 8443 |
        Out-Null
}
catch {
    'Validation failed'
}

预期输出

text
prod|3|v1.4.0|https://api.example.com/|8443
Validation failed

实际错误对象会包含参数名、失败值和验证规则;错误文本可能随 PowerShell 版本及显示语言变化,因此自动化测试更适合断言异常类型或失败状态,而不是逐字匹配整段消息。

设计 ValidateScript

ValidateScript 中的 $_ 表示当前待校验值。脚本应保持快速、确定且无副作用,避免在参数绑定阶段执行写文件、修改系统或耗时网络请求。需要自定义提示时直接 throw,比单纯返回 $false 更容易定位原因。

验证脚本只检查单个参数时最清晰。若规则依赖多个参数,例如“生产环境至少三个副本”,应在函数体开头进行组合校验,并在任何副作用发生前抛出异常。

校验边界与错误处理

多个验证属性会共同生效,只要一个失败,参数绑定就终止。ValidateSet 适合稳定的小集合;值来自外部系统且经常变化时,不应把远程查询写进验证属性,而应在函数体内显式检查。

调用方可以使用 try 和 catch 捕获参数绑定异常。对外提供的函数应让错误指出哪个参数、接受什么格式以及如何修正,避免只返回“输入错误”这类无法行动的信息。

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

目录与阅读设置

阅读设置

17

记录一个想法

校验函数参数

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

登录哪都通