参数与返回值是一体两面
写任务时看两处：参数决定这次做什么，返回值决定后续怎么判断。参数里的必填项、默认值与可选值都在本地文档里；返回值则定义了注册之后能引用哪些字段。多数“任务成功了但后续判断一直不成立”的问题，都是引用了实际不存在的返回字段，或对字段类型理解有误。
基本信息
| 参数来源 | 本地模块文档，含类型、必填、默认值与可选值 |
|---|---|
| 传参方式 | 模块参数直接写在模块名下，也可用通用参数键传递 |
| 自由格式模块 | 命令类模块接收一个字符串，其余参数另有专用键 |
| 返回结构 | 返回一个字典，含变更状态、成败信息与模块专有字段 |
| 公共字段 | 变更状态、失败状态、消息、返回码、标准输出与错误输出等 |
| 版本差异 | 字段与参数随版本变动，以本机安装版本的文档为准 |
典型使用场景
- 首次使用某个模块：先看必填参数与默认值，避免凭记忆写
- 后续判断需要字段：确认返回值清单里有哪些可用字段
- 命令类任务取输出：区分整体文本与逐行文本，便于后续处理
- 循环任务的返回：结构从单条结果变成结果列表，取值方式随之改变
- 升级后报参数错误：核对参数是否改名或废弃
- 调试取值：用打印任务查看注册变量的实际结构
看参数与读返回
看参数与读返回
# 查参数与返回：ansible-doc <模块全名>
# 关注三段：OPTIONS（参数与默认值）、RETURN（返回字段）、EXAMPLES
- name: 执行并注册结果
ansible.builtin.command: /usr/local/bin/app --status
register: app_status
changed_when: false # 只读查询，不视为变更
- name: 直接打印整个返回结构（排障用）
ansible.builtin.debug:
var: app_status
- name: 引用具体字段
ansible.builtin.debug:
msg: >-
返回码 {{ app_status.rc }}，
首行 {{ app_status.stdout_lines[0] | default('无输出') }}
- name: 循环任务的返回是列表，逐项取值
ansible.builtin.command: 'true'
loop: [a, b]
register: loop_result
changed_when: false
- name: 取列表里的每一项
ansible.builtin.debug:
msg: '{{ item.rc }}'
loop: '{{ loop_result.results }}'公共返回字段读法
| 字段 | 含义 | 使用要点 |
|---|---|---|
| 变更状态 | 本次是否修改了目标 | 只读任务应显式声明无变更 |
| 失败状态 | 是否被判定为失败 | 与失败判定条件配合使用 |
| 消息 | 模块给出的人类可读说明 | 失败时是主要线索 |
| 返回码 | 命令类任务的退出码 | 退出码非零不代表一定失败，可按需判定 |
| 标准输出与错误输出 | 整体文本与逐行文本 | 逐行版本便于按行取用 |
| 结果列表 | 循环任务的各项结果 | 结构是列表，需逐项引用 |
排障时的有效做法是先打印整个返回结构，看清字段名与层级，再改成引用具体字段。凭记忆猜字段名是这类问题最常见的成因，一次打印能省掉多轮试错。
打印整个返回结构会把命令输出、参数取值原样写进日志，其中可能含口令与令牌。含敏感参数的任务应先确认是否真的需要打印，必要时用日志抑制，或只打印字段名不含值的摘要。
判断顺序
拿到一个任务的结果，判断顺序建议是：先看失败状态与返回码，再看业务字段（输出内容、状态字符串），最后才看变更状态。只依赖变更状态做判断容易误判，因为命令类任务默认总是报告变更。