4、角色参数化设计：使用 vars 与 defaults 实现灵活配置、变量优先级详解

角色参数化是 Ansible 角色复用的核心能力。通过将硬编码值抽取为变量，并利用 vars/ 与 defaults/ 目录的优先级差异，你可以构建出既安全又灵活的角色，适配开发、测试、生产等不同环境。

4.1 变量目录职责与优先级基础

Ansible 角色中两个关键的变量目录承担不同职责：

4.2 变量优先级全景图

理解完整的变量优先级顺序，是避免“变量不生效”或“意外覆盖”的关键。以下按优先级从低到高排列：

1. 角色 defaults —— 最低优先级
2. Inventory 变量（group_vars / host_vars）
3. Play 级别 vars
4. 角色 vars（vars/main.yml）
5. Play 中 include_vars / vars_files
6. Play 中 set_fact
7. 命令行 -e 传入的额外变量 —— 最高优先级

4.3 实战：角色参数化设计模式

以下是一个 Nginx 角色的参数化设计示例，展示如何利用 defaults/ 和 vars/ 实现灵活配置：

4.3.1 defaults/main.yml —— 可被外部覆盖的参数

---
# Nginx 角色默认参数
nginx_port: 80
nginx_server_name: localhost
nginx_root: /usr/share/nginx/html
nginx_worker_processes: auto
nginx_keepalive_timeout: 65
nginx_ssl_enabled: false
nginx_ssl_cert_path: /etc/nginx/ssl/server.crt
nginx_ssl_key_path: /etc/nginx/ssl/server.key
nginx_access_log: /var/log/nginx/access.log
nginx_error_log: /var/log/nginx/error.log

4.3.2 vars/main.yml —— 角色内部常量

---
# Nginx 角色内部常量（不建议外部覆盖）
nginx_package_name: nginx
nginx_service_name: nginx
nginx_config_dir: /etc/nginx
nginx_conf_file: "{{ nginx_config_dir }}/nginx.conf"
nginx_sites_available: "{{ nginx_config_dir }}/sites-available"
nginx_sites_enabled: "{{ nginx_config_dir }}/sites-enabled"
nginx_user: www-data
nginx_group: www-data

4.4 变量覆盖场景对比表

4.5 变量合并与哈希行为

当变量是哈希（字典）类型时，Ansible 默认行为是完全替换而非合并。若需要合并哈希，需在 ansible.cfg 中设置：

[defaults]
hash_behaviour = merge

或在 play 中使用 combine 过滤器手动合并：

---
- name: 合并哈希变量
  set_fact:
    merged_config: "{{ default_config | combine(override_config) }}"

4.6 变量作用域与角色间传递

角色内部的变量默认是私有的，不会自动暴露给其他角色。若需要在角色间共享变量，有以下几种方式：

• 通过 play 变量传递：在 play 中定义变量，多个角色均可访问。
• 使用角色依赖（meta/main.yml）：在依赖关系中传递参数。
• 通过 set_fact 提升为全局变量：在角色内使用 set_fact 并设置 cacheable: yes。

4.7 常见陷阱与避坑指南

• 陷阱1：在 defaults/ 中使用了 {{ }} 引用其他变量，但该变量尚未定义。解决方案：使用 default() 过滤器提供回退值。
• 陷阱2：误以为 vars/ 中的变量安全。实际上 -e 仍可覆盖。若需真正保护，可在角色内用 assert 模块校验。
• 陷阱3：哈希变量被意外替换而非合并。解决方案：显式使用 combine 过滤器，或统一团队 hash_behaviour 配置。
• 陷阱4：角色依赖中传递变量时，变量作用域仅限于被依赖的角色，不会自动传递到主角色。需在依赖定义中显式传递。