3.3 参数与动态配置

3.3 参数与动态配置

本节摘要：参数是第四种通信原语，也是唯一自带"存储语义"的一种：每个参数挂在节点上、有类型、可被运行时修改、可从 YAML 覆盖。本节讲清参数的声明与读取、YAML 覆盖规则、动态回调的写法与边界，并用巡检机器人限速参数的完整方案示范"不改代码、不重启进程"的现场调参怎么做。这一节也是第 4 章 Launch 系统注入配置的前置知识。

配置的三个时刻

把"配置"这个词拆开看，它有三个时刻：写代码时确定的（编译期常量）、启动时确定的（命令行与文件注入）、运行时还会变的（现场调参）。ROS2 参数系统同时覆盖后两个时刻，而且用同一套机制——这是它与"读个配置文件"的本质区别。理解三个时刻的分工，参数就用对了九成。

一、声明、读取与类型系统

ROS2 的参数必须先声明后使用（除非节点显式允许未声明访问，不建议）。声明的意义在于给出名字、类型、默认值，以及可选的描述与约束：

import rclpy
from rclpy.node import Node

class PatrolNode(Node):
    def __init__(self):
        super().__init__('patrol_node')
        # 声明：名字、默认值；返回实际生效值（可能已被启动参数覆盖）
        self.declare_parameter('max_speed', 0.8)
        self.declare_parameter('patrol_points', ['A区', 'B区', 'C区'])
        self.max_speed = self.get_parameter('max_speed').value

        # 动态回调：外部修改参数时触发
        self.add_on_set_parameters_callback(self.on_param_change)

    def on_param_change(self, params):
        from rcl_interfaces.msg import SetParametersResult
        for p in params:
            if p.name == 'max_speed' and p.value < 0.0:
                self.get_logger().error('限速不能为负，拒绝修改')
                return SetParametersResult(successful=False)
            if p.name == 'max_speed':
                self.max_speed = p.value
                self.get_logger().info(f'限速已更新为 {p.value}')
        return SetParametersResult(successful=True)
​

三个工程细节。第一，declare_parameter 的返回值就是"实际生效值"——启动参数可能已覆盖默认值，用它初始化成员变量，别再读默认值。第二，参数类型跟随首次声明：声明成 double 后，外部传整数会被拒绝（除非声明时用动态类型），这是很多"运行时设置参数失败"的根因。第三，动态回调是集中审查点：合法性校验、范围检查都在这里做，拒绝就返回 unsuccessful，系统保持原值——参数系统的"事务性"就体现在这。

二、YAML 覆盖与命令行操作

启动时注入参数有两条路：命令行与 YAML 文件。命令行适合临时调试，YAML 适合正式配置。

# 命令行注入
ros2 run my_pkg patrol_node --ros-args -p max_speed:=0.5

# 查询与运行时修改
ros2 param get /patrol_node max_speed
ros2 param set /patrol_node max_speed 0.3    # 触发动态回调
# 巡检节点的日志：限速已更新为 0.3 —— 不重启，立即生效
​

# patrol_params.yaml：正式配置
/**:                        # 通配任意节点名，也可写具体节点名精确匹配
  ros__parameters:
    max_speed: 0.8
    patrol_points:
      - A区
      - B区
      - C区
    safety:
      min_obstacle_distance: 0.6
​

ros2 run my_pkg patrol_node --ros-args --params-file patrol_params.yaml
​

YAML 的匹配规则值得记牢：/** 通配所有节点，写具体节点名只命中该节点；同名节点在多个命名空间下时，用 /ns/node_name 精确寻址。参数文件里类型必须与声明兼容，YAML 里的 0.8 是 double、0 是整数——配置文件里写错类型，运行时参数会以"声明拒绝"收场，报错信息里通常能看到类型不匹配字样。

图 3-3：参数的三个时刻与生效路径

三、现场复盘：给巡检机器人做一套可调的限速

背景：巡检机器人白天在人流区作业，限速 0.8 米每秒；夜里同一个园区分流，可以放到 1.2 米每秒。运维同学不想碰代码，也不该碰。

操作分三步。第一步，把 max_speed 声明进节点（如上），动态回调里加"非负且不超过 1.5"的范围审查；第二步，准备两份 YAML：白班限 0.8、夜班限 1.2，由启动脚本按当前班次选文件注入；第三步，交付现场调整能力——运维用 param set 临时降速（比如人流量突增时段），调整记录落在节点日志里。

结果：上线一个月，运维做了十一次临时降速、两次班次配置切换，全程没有一次重启，也没有一次需要开发介入。解读：这套方案的关键设计不是"用了参数"，而是职责分层——代码守住安全底线（回调里的范围审查），配置表达场景差异（两份 YAML），现场只拥有临时微调权（param set）。三层权限边界清晰，配置系统才敢开放给非开发角色。

变式一：参数很多时，把 YAML 按职责拆成 safety、motion、network 几份文件，启动时按需叠加，比一份千行大文件好维护。变式二：需要"修改持久化"的场景（改完重启仍生效），参数系统本身不给答案，需要运维流程配合——要么改 YAML 源文件，要么用第 4 章 Launch 的参数目录约定。

⚠️ 常见坑：节点还没声明参数，外部就 param set，会收到"参数未声明"的拒绝——这不是故障，是声明制的正常表现。启动顺序敏感的场景（Launch 里先起参数服务器再起业务节点）会在第 4 章系统解决。

本节要点回顾

• 参数覆盖三个时刻：声明给基线，启动注入给场景，运行时修改给现场；
• 声明制是安全网：类型与合法性在声明与动态回调两道关卡审查，拒绝即回滚；
• YAML 通配与精确匹配并存，配置文件按职责拆分优于单一大文件；
• 职责分层是配置系统的灵魂：代码守底线、文件定场景、现场只调临时值；
• 参数修改不重启进程，但持久化需要文件层面的流程配合。

四种原语齐了。下一章解决一个更系统的问题：这么多节点、这么多参数，启动时怎么优雅地把它们组织起来。