4. Netmiko输出解析入门

Netmiko 的 send_command() 返回的是设备回显的原始字符串。对单台设备、单条命令做人工查看时，字符串足够；但一旦要把几十台交换机的接口状态、邻居信息、路由表汇总成表格，字符串就会成为障碍——不同厂商、不同型号、不同 IOS 版本的列宽、表头、分隔线、空行都不一致，用正则逐条匹配既脆弱又难维护。本节要解决的核心问题就是：如何把 show 命令的文本输出稳定地转成 Python 可编程处理的结构化数据。

一、TextFSM 与 ntc-templates 的分工

TextFSM 是 Google 开源的一个基于状态机的文本解析引擎。它的工作方式不是“写正则去抓字段”，而是先定义一张模板：模板里声明有哪些字段（Value），再声明文本在什么状态下应该匹配哪一行（Rule），匹配到某行后执行什么动作（Action，如 Record 记录一条、Next 切换状态、Error 报错）。解析器逐行读取设备输出，按状态迁移，最终产出一组字典。

ntc-templates 则是社区维护的模板库，它把大量厂商、命令的 TextFSM 模板预先写好，并按“厂商/命令”的目录结构组织。Netmiko 内置了对 ntc-templates 的调用入口：只要安装该库，并在连接时或调用时启用 use_textfsm=True，Netmiko 就会根据当前设备类型和命令，自动去模板库里找匹配的模板并完成解析。也就是说，TextFSM 是“引擎”，ntc-templates 是“现成模板仓库”，Netmiko 是“把两者接起来的胶水”。

二、启用解析的两种方式

第一种是在建立连接时全局开启。这样该连接对象后续所有 send_command() 都会尝试走 TextFSM 解析：

from netmiko import ConnectHandler

dev = {
    "device_type": "cisco_ios",
    "host": "192.0.2.11",
    "username": "admin",
    "password": "Cisco123",
}

with ConnectHandler(**dev) as conn:
    data = conn.send_command("show ip interface brief", use_textfsm=True)
    print(type(data))   # <class 'list'>
    print(data[0])      # {'interface': 'GigabitEthernet0/1', 'ip_address': '10.0.0.1', ...}

第二种是逐条命令控制，只在需要结构化的命令上传入 use_textfsm=True，其余命令仍返回字符串。实际工程中更推荐第二种：并非所有命令都有现成模板，盲目全局开启会让没有模板的命令返回原始文本，反而容易在后续代码里误判类型。

三、模板匹配的判定逻辑

Netmiko 找模板时依赖两个关键信息：device_type 映射出的平台名（如 cisco_ios 对应 cisco_ios 目录），以及命令字符串本身。ntc-templates 的 index 文件里记录了“平台 + 命令”到模板文件的映射。如果命令写法与索引不一致，就会匹配失败。例如索引里登记的是 show ip interface brief，而你传的是 show ip int brief，就可能找不到模板。因此建议在代码中统一使用完整命令写法，或先查询索引确认。

四、一个可复用的解析与校验流程

下面这段示例把“采集—解析—校验—输出”串成一个闭环。示例中的 IP、接口名均为教学假设值，实际运行时以设备真实回显为准。

from netmiko import ConnectHandler

dev = {"device_type": "cisco_ios", "host": "192.0.2.11",
       "username": "admin", "password": "Cisco123"}

with ConnectHandler(**dev) as conn:
    rows = conn.send_command("show ip interface brief", use_textfsm=True)

    if not isinstance(rows, list):
        raise RuntimeError("TextFSM 未匹配到模板，返回原始文本")

    up_ports = [r for r in rows if r.get("status") == "up"]
    print(f"接口总数={len(rows)}  已启用={len(up_ports)}")

    for r in up_ports:
        print(f"{r['interface']:<24}{r['ip_address']:<16}{r['status']}")

运行后应看到类似 接口总数=24 已启用=18 的统计，以及逐行对齐的接口清单。如果 rows 是字符串，说明模板未命中，此时应检查命令拼写、device_type 是否正确，以及 ntc-templates 是否已安装。

五、常见问题与排查方向

• 返回字符串而非列表：优先检查命令是否与 ntc-templates 索引中的写法完全一致，其次确认 device_type 对应的平台目录存在。
• 字段名与预期不符：不同模板的键名不同，例如有的用 interface，有的用 intf。应先打印一条记录查看真实键名，再写后续逻辑。
• 部分行丢失：通常是设备回显中出现了模板未覆盖的异常行（如 administratively down 的变体），需要查看原始文本并考虑自定义模板。
• 版本差异：同一命令在不同 IOS 版本下表头可能变化，模板库更新滞后时会出现解析偏差，此时应锁定模板版本或自行维护模板。

掌握本节内容后，你已经能把单条 show 命令的输出变成可筛选、可统计、可写入表格的字典列表。这是后续做多设备批量采集、配置合规检查、状态巡检报告的基础能力。真正决定解析稳定性的，不是代码写得多复杂，而是命令写法、平台标识与模板索引三者是否严格对齐。