命令行与文本处理 / 系统课时
读取并校验巡检配置
读取并校验巡检配置
本课实现巡检工具的输入边界:同时读取 JSON 和 CSV,将不同格式统一成主机对象,并在建立远程连接前拒绝缺失字段、非法端口、重复名称和重复地址。
学习目标
- 根据扩展名读取 JSON 或 CSV 配置
- 将文本字段规范化为统一的数据类型
- 汇总配置错误,并阻止无效目标进入巡检流程
约定输入格式
两种配置都使用 Name、Address、Port 和 Enabled 字段。Name 用于报告展示且必须唯一;Address 可以是主机名或 IP 地址;Port 必须是 1~65535 的整数;Enabled 决定目标是否参与本次巡检。
JSON 适合保存嵌套结构,CSV 适合批量维护简单主机清单。本课只实现 Hosts 主机数组;超时、阈值和报告格式等全局设置可在项目配置中扩展为独立的 Settings 段。下面是本课使用的 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,只返回启用目标,并用不区分大小写的集合检测重复名称和地址。
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预期输出
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 后再次运行,脚本应在任何远程连接发生前终止。预期结果
配置校验失败:
Name 重复:web-01实际错误前可能带有 PowerShell 的异常位置和调用栈。验收重点是错误原因被明确指出,并且没有返回可供巡检执行的目标数组。
当前实现会收集多项错误后统一抛出,便于一次修正配置。对于生产工具,还可以把错误对象扩展为包含行号、字段名和错误代码的结构,但不要在校验失败时“尽量继续”,否则报告可能遗漏或重复主机。
处理关键边界
空 JSON 数组在语法上合法,但通常应视为没有可执行目标。可在返回前增加 $targets.Count -eq 0 检查,并根据业务选择报错或输出“无启用主机”。
CSV 中所有字段最初都是字符串,因此必须显式转换端口和布尔值。不要直接使用 [bool]'false',因为非空字符串会被转换为 $true;本课使用受控映射来避免这个陷阱。
重复判断应在规范化之后进行,因此 WEB-01 与 web-01、前后带空格的地址都被视为同一目标。若多个名称允许指向同一负载均衡地址,应调整地址唯一性规则,而不是删除全部重复检查。