# Ansible 与 YAML 编码规范

## YAML 格式规范

### 基本格式
- 使用 `---` 作为 YAML 文件开头
- 缩进严格使用 **2 个空格**
- 禁止使用制表符 `\t`
- 保持每行末尾无多余空白

### 文件命名
- Playbook 文件使用 `snake_case`
- 文件扩展名为 `.yml`

## Ansible 编码规范

### 变量命名
- 变量名使用 `snake_case`
- 布尔变量使用肯定语气命名，如 `enable_feature`
- 使用有意义的、描述性的变量名

### Playbook 结构
- 每个 Playbook 应包含:
  1. `name`: 描述性标题
  2. `hosts`: 目标主机
  3. `vars`: 变量定义区
  4. `tasks`: 任务列表
  5. 可选 `handlers`: 触发的服务重启/重载任务

### 任务编写
- 每个任务使用 `name` 描述具体操作
- 优先使用 `ansible.builtin` 模块
- 添加 `when` 条件控制任务执行
- 使用 `register` 捕获任务输出
- 通过 `changed_when: false` 控制任务变更状态

### 注释规范
- 使用 `#` 添加注释
- 注释应解释"为什么"，而非"做什么"
- 在复杂配置处添加必要的注释说明

### 安全与最佳实践
- 使用 `become: yes` 控制权限提升
- 避免硬编码敏感信息
- 使用 `no_log: true` 隐藏敏感输出
- 合理使用 `backup: yes` 保护现有配置

## 示例代码风格
```yaml
---
- name: 配置服务
  hosts: servers
  become: yes

  vars:
    service_port: 8080
    enable_monitoring: true

  tasks:
    - name: 部署服务配置
      ansible.builtin.template:
        src: config.j2
        dest: /etc/service/config.yml
      when: enable_monitoring
```