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

校验与规范化输入

校验与规范化输入

业务输入常同时包含空白、空值、大小写不一致、越界数字和非标准枚举值。本课将构建一个可运行的规范化函数:先清洗,再校验,最后返回结构化结果,使有效数据可以继续进入对象管道,无效数据则给出明确原因。

学习目标

  • 区分规范化、校验、拒绝和修复
  • 处理字符串、数字范围与枚举映射
  • 返回便于管道继续处理的结构化结果

先规范化,再做业务校验

规范化负责把不同写法转换成统一形式,例如去除首尾空白、把邮箱转为小写、把 enabled 和 on 映射为同一个状态。校验负责判断规范化后的值是否满足业务规则,例如姓名不能为空、年龄必须在指定范围内。

顺序不能颠倒。若直接校验原始值," Alice "、"ALICE" 和 "alice" 可能被误认为不同输入;若只规范化而不校验,空字符串和越界数字又可能悄悄进入后续系统。

输入规范化与校验流程

设计结构化处理结果

不要让函数只返回 $true 或 $false。调用方还需要知道输入是否有效、规范化后的数据是什么、失败原因有哪些。适合的返回对象至少包含 IsValid、Data 和 Errors。

  • IsValid:是否通过全部规则
  • Data:规范化后的对象;失败时可以为 $null
  • Errors:稳定、可记录的错误消息数组

这种结构既适合命令行脚本,也适合批量导入、接口适配和后台任务。

主示例:清洗并校验用户输入

下面的函数处理姓名、邮箱、年龄和状态。它拒绝无法安全推断的值,但对明确的别名进行自动修复,例如把 on 规范化为 Active。

powershell
function ConvertTo-NormalizedUser {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, ValueFromPipeline)]
        [pscustomobject]$InputObject
    )

    process {
        $errors = [System.Collections.Generic.List[string]]::new()

        # 空值先转换为可安全处理的空字符串,再统一清理格式
        $name = if ($null -eq $InputObject.Name) {
            ''
        }
        else {
            [string]$InputObject.Name
        }
        $name = $name.Trim()

        $email = if ($null -eq $InputObject.Email) {
            ''
        }
        else {
            ([string]$InputObject.Email).Trim().ToLowerInvariant()
        }

        # TryParse 让单条坏数据变成校验错误,而不是中断整批管道
        $age = 0
        $ageParsed = [int]::TryParse(
            ([string]$InputObject.Age).Trim(),
            [ref]$age
        )

        $statusKey = if ($null -eq $InputObject.Status) {
            ''
        }
        else {
            ([string]$InputObject.Status).Trim().ToLowerInvariant()
        }

        # 只维护业务批准的别名,未知值一律拒绝
        $statusMap = @{
            'active'   = 'Active'
            'enabled'  = 'Active'
            'on'       = 'Active'
            'inactive' = 'Inactive'
            'disabled' = 'Inactive'
            'off'      = 'Inactive'
        }

        if ([string]::IsNullOrWhiteSpace($name)) {
            $errors.Add('Name is required.')
        }

        if ($email -notmatch '^[^@\s]+@[^@\s]+\.[^@\s]+$') {
            $errors.Add('Email format is invalid.')
        }

        if (-not $ageParsed -or $age -lt 18 -or $age -gt 120) {
            $errors.Add('Age must be an integer from 18 to 120.')
        }

        if (-not $statusMap.ContainsKey($statusKey)) {
            $errors.Add('Status must be Active or Inactive.')
        }

        # 无论成功还是失败都输出同一结果结构,便于下游统一处理
        if ($errors.Count -gt 0) {
            [pscustomobject]@{
                IsValid = $false
                Data = $null
                Errors = $errors.ToArray()
            }
        }
        else {
            [pscustomobject]@{
                IsValid = $true
                Data = [pscustomobject]@{
                    Name = $name
                    Email = $email
                    Age = $age
                    Status = $statusMap[$statusKey]
                }
                Errors = @()
            }
        }
    }
}

$inputs = @(
    [pscustomobject]@{
        Name = '  Alice Zhang  '
        Email = ' Alice@example.COM '
        Age = '29'
        Status = 'on'
    }
    [pscustomobject]@{
        Name = ' '
        Email = 'invalid-address'
        Age = '160'
        Status = 'unknown'
    }
)

$results = $inputs | ConvertTo-NormalizedUser

$results[0].Data | Format-List
$results[1].Errors

预期输出:

text
Name   : Alice Zhang
Email  : alice@example.com
Age    : 29
Status : Active

Name is required.
Email format is invalid.
Age must be an integer from 18 to 120.
Status must be Active or Inactive.

正则表达式只做基础邮箱结构检查,不等同于确认邮箱真实存在。年龄使用 [int]::TryParse(),避免无效字符串触发异常并中断整批数据。枚举映射只接受明确列出的别名,未知值不会被猜测修复。

拒绝、修复与默认值的边界

可以无歧义地转换时才自动修复,例如去除首尾空白、统一大小写、把已批准别名映射为标准枚举。可能改变业务含义的操作应拒绝,例如把年龄 160 自动改为 120,或把未知状态自动设为 Inactive。

默认值也必须有明确触发条件。字段缺失不等于用户选择了默认值。只有业务规则明确允许时,才应在空值场景填入默认值,并最好在结果中记录 Warnings 或修复记录,便于审计。

对安全敏感字段,如权限级别、付款金额和资源标识,不应使用模糊匹配或“最接近值”自动修复。错误修复可能导致越权、错误扣款或写入错误对象,安全替代方案是拒绝输入并要求调用方提交明确值。

在管道中筛选有效数据

结构化结果可以继续参与对象管道。下面只提取有效对象,并把错误结果转换为便于记录的文本。

powershell
$validUsers = $results |
    Where-Object IsValid |
    ForEach-Object Data

$errorMessages = $results |
    Where-Object { -not $_.IsValid } |
    ForEach-Object { $_.Errors -join '; ' }

$validUsers.Count
$errorMessages

预期输出:

text
1
Name is required.; Email format is invalid.; Age must be an integer from 18 to 120.; Status must be Active or Inactive.

批量处理时,不要让单条无效输入终止整个管道。返回结构化结果可以让调用方决定跳过、记录、人工修复或整体回滚,同时保留每条记录的失败原因。

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

目录与阅读设置

阅读设置

17

记录一个想法

校验与规范化输入

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

登录哪都通