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

读取并校验巡检配置

读取并校验巡检配置

本课实现巡检工具的输入边界:同时读取 JSON 和 CSV,将不同格式统一成主机对象,并在建立远程连接前拒绝缺失字段、非法端口、重复名称和重复地址。

学习目标

  • 根据扩展名读取 JSON 或 CSV 配置
  • 将文本字段规范化为统一的数据类型
  • 汇总配置错误,并阻止无效目标进入巡检流程

约定输入格式

两种配置都使用 Name、Address、Port 和 Enabled 字段。Name 用于报告展示且必须唯一;Address 可以是主机名或 IP 地址;Port 必须是 1~65535 的整数;Enabled 决定目标是否参与本次巡检。

JSON 适合保存嵌套结构,CSV 适合批量维护简单主机清单。本课只实现 Hosts 主机数组;超时、阈值和报告格式等全局设置可在项目配置中扩展为独立的 Settings 段。下面是本课使用的 JSON 配置:

json
[
  {
    "Name": "web-01",
    "Address": "10.0.0.11",
    "Port": 5985,
    "Enabled": true
  },
  {
    "Name": "db-01",
    "Address": "db-01.example.local",
    "Port": 5986,
    "Enabled": true
  }
]

配置生效行为:脚本读取两个目标,将端口转换为整数,将启用字段转换为布尔值,并返回统一的 PSCustomObject 数组。CSV 使用相同列名即可得到相同结果。

建立校验顺序

校验应按“文件级、记录级、集合级”执行。先确认文件存在且扩展名受支持,再检查每条记录的必填字段与数据范围,最后检查跨记录重复。这样错误信息更接近根因,也能一次报告多个问题。

巡检配置读取与校验流程

文件解析成功并不代表配置可信。必须在任何网络连接之前完成全部校验,否则重复目标可能被执行两次,非法端口会把输入错误伪装成连接故障。

实现读取、规范化与拒绝逻辑

将上面的配置与脚本保存在同一目录,再运行下面的完整脚本。它支持 .json 与 .csv,只返回启用目标,并用不区分大小写的集合检测重复名称和地址。

powershell
function ConvertTo-Boolean {
    # CSV 会把布尔值读成字符串,因此只接受明确的白名单值
    param(
        [Parameter(Mandatory)]
        [object]$Value
    )

    if ($Value -is [bool]) {
        return $Value
    }

    switch ($Value.ToString().Trim().ToLowerInvariant()) {
        'true'  { return $true }
        '1'     { return $true }
        'yes'   { return $true }
        'false' { return $false }
        '0'     { return $false }
        'no'    { return $false }
        default { throw "Enabled 值无效:$Value" }
    }
}

function Read-InspectionConfig {
    param(
        [Parameter(Mandatory)]
        [string]$ConfigPath
    )

    if (-not (Test-Path -LiteralPath $ConfigPath -PathType Leaf)) {
        throw "配置文件不存在:$ConfigPath"
    }

    # 文件级校验通过后,再按扩展名选择解析器
    $extension = [IO.Path]::GetExtension($ConfigPath).ToLowerInvariant()
    $records = switch ($extension) {
        '.json' {
            @(Get-Content -LiteralPath $ConfigPath -Raw |
                ConvertFrom-Json)
        }
        '.csv' {
            @(Import-Csv -LiteralPath $ConfigPath)
        }
        default {
            throw "不支持的配置格式:$extension"
        }
    }

    # 错误集中返回,避免用户每次只能修正一处
    $errors = [Collections.Generic.List[string]]::new()
    $targets = [Collections.Generic.List[object]]::new()
    $names = [Collections.Generic.HashSet[string]]::new(
        [StringComparer]::OrdinalIgnoreCase
    )
    $addresses = [Collections.Generic.HashSet[string]]::new(
        [StringComparer]::OrdinalIgnoreCase
    )

    # 先规范化单条记录,再执行字段级与集合级校验
    for ($index = 0; $index -lt $records.Count; $index++) {
        $rowNumber = $index + 1
        $record = $records[$index]
        $name = [string]$record.Name
        $address = [string]$record.Address
        $port = 0
        $addressValid = $false

        $name = $name.Trim()
        $address = $address.Trim()

        if ([string]::IsNullOrWhiteSpace($name)) {
            $errors.Add("第 $rowNumber 条记录缺少 Name")
        }

        if ([string]::IsNullOrWhiteSpace($address)) {
            $errors.Add("第 $rowNumber 条记录缺少 Address")
        }
        elseif ([Uri]::CheckHostName($address) -eq 'Unknown') {
            $errors.Add("第 $rowNumber 条记录的 Address 无效")
        }
        else {
            $addressValid = $true
        }

        if (-not [int]::TryParse([string]$record.Port, [ref]$port) -or
            $port -lt 1 -or $port -gt 65535) {
            $errors.Add("第 $rowNumber 条记录的 Port 无效")
        }

        try {
            $enabled = ConvertTo-Boolean -Value $record.Enabled
        }
        catch {
            $errors.Add("第 $rowNumber 条记录:$($_.Exception.Message)")
            $enabled = $false
        }

        if ($name -and -not $names.Add($name)) {
            $errors.Add("Name 重复:$name")
        }

        if ($address -and -not $addresses.Add($address)) {
            $errors.Add("Address 重复:$address")
        }

        if ($name -and $addressValid -and $port -ge 1 -and
            $port -le 65535 -and $enabled) {
            $targets.Add([pscustomobject]@{
                Name = $name
                Address = $address
                Port = $port
                Enabled = $true
            })
        }
    }

    # 任何错误都会阻止目标数组流入远程巡检阶段
    if ($errors.Count -gt 0) {
        throw "配置校验失败:`n$($errors -join "`n")"
    }

    return $targets.ToArray()
}

$Path = Join-Path $PSScriptRoot 'hosts.json'
Read-InspectionConfig -ConfigPath $Path |
    Format-Table Name, Address, Port, Enabled

预期输出

text
Name   Address               Port Enabled
----   -------               ---- -------
web-01 10.0.0.11             5985    True
db-01  db-01.example.local    5986    True

列宽和空格可能因终端宽度不同而变化,但应得到两条启用记录,且 Port 为整数、Enabled 为布尔值。

验证拒绝无效配置

将第二条记录的 Name 改成 web-01 后再次运行,脚本应在任何远程连接发生前终止。预期结果

text
配置校验失败:
Name 重复:web-01

实际错误前可能带有 PowerShell 的异常位置和调用栈。验收重点是错误原因被明确指出,并且没有返回可供巡检执行的目标数组。

当前实现会收集多项错误后统一抛出,便于一次修正配置。对于生产工具,还可以把错误对象扩展为包含行号、字段名和错误代码的结构,但不要在校验失败时“尽量继续”,否则报告可能遗漏或重复主机。

处理关键边界

空 JSON 数组在语法上合法,但通常应视为没有可执行目标。可在返回前增加 $targets.Count -eq 0 检查,并根据业务选择报错或输出“无启用主机”。

CSV 中所有字段最初都是字符串,因此必须显式转换端口和布尔值。不要直接使用 [bool]'false',因为非空字符串会被转换为 $true;本课使用受控映射来避免这个陷阱。

重复判断应在规范化之后进行,因此 WEB-01 与 web-01、前后带空格的地址都被视为同一目标。若多个名称允许指向同一负载均衡地址,应调整地址唯一性规则,而不是删除全部重复检查。

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

目录与阅读设置

阅读设置

17

记录一个想法

读取并校验巡检配置

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

登录哪都通