约定、技巧和陷阱

在设计和开发模块时，请遵循以下基本约定和技巧，以获得简洁、可用的代码

模块的范围界定 

特别是如果您想将您的模块贡献给现有的 Ansible 集合，请确保每个模块都包含足够的逻辑和功能，但不要太多。如果这些指南看起来令人困惑，请考虑您是否真的需要编写模块。

每个模块都应该具有简洁且明确定义的功能。基本上，遵循 UNIX 哲学，把一件事做好。
不要向现有模块添加 get、list 或 info 状态选项 - 创建一个新的 _info 或 _facts 模块。
模块不应要求用户知道要使用的 API/工具的所有底层选项。例如，如果无法记录所需模块选项的合法值，则该模块不属于 Ansible Core。
模块应包含与资源交互的大部分逻辑。围绕复杂 API 的轻量级包装会迫使用户将太多逻辑卸载到他们的 playbook 中。如果您想将 Ansible 连接到复杂的 API，创建多个模块与 API 的较小部分进行交互。
避免创建执行其他模块工作的模块；这会导致代码重复和分歧，并使事情变得不统一、不可预测且更难维护。模块应该是构建块。如果您问“如何让一个模块执行其他模块”……您应该编写一个角色。

设计模块接口 

如果您的模块正在处理对象，则该对象的选项应尽可能称为 name，或者接受 name 作为别名。
接受布尔状态的模块应接受 yes、no、true、false 或用户可能抛给它们的任何其他内容。AnsibleModule 公共代码通过 type='bool' 支持这一点。
避免使用 action/command，它们是命令式的而不是声明式的，还有其他方法可以表达相同的事情。

通用指南和技巧 

每个模块都应包含在一个文件中，以便可以通过 ansible-core 自动传输。
模块名称必须使用下划线而不是连字符或空格作为单词分隔符。使用连字符和空格将阻止 ansible-core 导入您的模块。
开发模块时，始终使用 hacking/test-module.py 脚本 - 它会警告您常见的陷阱。
如果您有一个返回特定于您的安装信息的地方模块，则该模块的一个好名称是 site_info。
消除或最小化依赖项。如果您的模块有依赖项，请将其记录在模块文件的顶部，并在依赖项导入失败时引发 JSON 错误消息。
不要直接写入文件；使用临时文件，然后使用 ansible.module_utils.basic 中的 atomic_move 函数将更新的临时文件移动到位。这样可以防止数据损坏并确保保留文件的正确上下文。
避免创建缓存。Ansible 的设计没有中央服务器或授权，因此您无法保证它不会以不同的权限、选项或位置运行。如果您需要中央授权，请将其放在 Ansible 之上（例如，使用堡垒/cm/ci 服务器、AWX 或红帽 Ansible 自动化平台）；不要尝试将其构建到模块中。
如果您将模块打包在 RPM 中，请将模块安装在控制机器上的 /usr/share/ansible 中。将模块打包在 RPM 中是可选的。

函数和方法 

每个函数都应该简洁明了，并且应该描述有意义的工作量。
“不要重复自己”通常是一个好的哲学。
函数名称应使用下划线：my_function_name。
每个函数的名称都应该描述该函数的作用。
每个函数都应该有一个文档字符串。
如果您的代码嵌套太深，这通常表示循环主体可以从作为函数中受益。我们现有代码的某些部分有时并不是这方面的最佳示例。

Python 技巧 

包含一个包装正常执行的 main 函数。
从条件调用您的 main 函数，以便您可以将其导入单元测试 - 例如

if __name__ == '__main__':
    main()

导入和使用共享代码 

尽可能使用共享代码 - 不要重复造轮子。Ansible 提供了 AnsibleModule 通用 Python 代码，以及用于许多常见用例和模式的实用程序。您还可以为适用于多个模块的文档创建文档片段。
在导入其他库的同一位置导入 ansible.module_utils 代码。
不要使用通配符 (*) 来导入其他 python 模块；而是列出您要导入的函数（例如，from some.other_python_module.basic import otherFunction）。
在 try/except 中导入自定义包，捕获任何导入错误，并在 main() 中使用 fail_json() 处理它们。例如

import traceback

from ansible.module_utils.basic import missing_required_lib

LIB_IMP_ERR = None
try:
    import foo
    HAS_LIB = True
except:
    HAS_LIB = False
    LIB_IMP_ERR = traceback.format_exc()

然后在 main() 中，就在 argspec 之后，执行

if not HAS_LIB:
    module.fail_json(msg=missing_required_lib("foo"),
                     exception=LIB_IMP_ERR)

并在模块的 DOCUMENTATION block 的 requirements 部分中记录依赖项。

处理模块失败 

当你的模块失败时，请帮助用户了解哪里出了问题。如果你正在使用 AnsibleModule 通用 Python 代码，当你调用 fail_json 时，failed 元素将自动包含在内。为了实现友好的模块失败行为

请包含一个键名为 failed 以及一个字符串解释，放在 msg 中。如果你不这样做，Ansible 将使用标准返回代码：0=成功，非零=失败。
不要抛出回溯（堆栈跟踪）。Ansible 可以处理堆栈跟踪，并自动将任何无法解析的内容转换为失败结果，但在模块失败时抛出堆栈跟踪对用户不友好。
不要使用 sys.exit()。请使用模块对象中的 fail_json()。

优雅地处理异常（错误）

提前验证——快速失败并返回有用且清晰的错误消息。
使用防御性编程——为你的模块使用简单的设计，优雅地处理错误，并避免直接的堆栈跟踪。
以可预测的方式失败——如果必须失败，请以最符合预期的方式进行。要么模仿底层工具，要么模仿系统的一般工作方式。
提供关于你正在做什么的有用消息，并将异常消息添加到其中。
避免捕获所有异常，除非底层 API 提供了非常好的、与尝试操作相关的错误消息，否则它们不是很有用。

创建正确且信息丰富的模块输出 

模块必须仅输出有效的 JSON。请遵循以下指南来创建正确、有用的模块输出

模块返回数据必须编码为严格的 UTF-8。无法返回 UTF-8 编码数据的模块应返回由诸如 base64 之类的东西编码的数据。可选地，模块可以确定它们是否可以编码为 UTF-8 并使用 errors='replace' 来替换非 UTF-8 字符，从而使返回值有损。
使你的顶级返回类型为哈希（字典）。
将复杂的返回值嵌套在顶级哈希中。
将任何列表或简单标量值合并到顶级返回哈希中。
不要将模块输出发送到标准错误，因为系统会将标准输出与标准错误合并，并阻止 JSON 解析。
捕获标准错误，并将其作为 JSON 中的一个变量返回到标准输出。这就是命令模块的实现方式。
永远不要在模块中使用 print("some status message")，因为它不会产生有效的 JSON 输出。
始终返回有用的数据，即使没有更改也是如此。
保持返回的一致性（某些模块太随机了），除非它对状态/操作有害。
使返回值可重用——大多数情况下，你不想读取它，但你确实想处理它并重新利用它。
如果在 diff 模式下，返回 diff。这不是所有模块都必需的，因为对于某些模块来说没有意义，但请在适用时包含它。
使你的返回值能够使用 Python 的标准 JSON 编码器和解码器库序列化为 JSON。基本 Python 类型（字符串、int、字典、列表等等）是可序列化的。
不要使用 exit_json() 返回对象。相反，将你需要从对象中获取的字段转换为字典的字段并返回该字典。
来自多个主机的结果将一次聚合，因此你的模块应仅返回相关的输出。返回整个日志文件的内容通常是不好的做法。

如果模块返回 stderr 或未能产生有效的 JSON，实际输出仍将在 Ansible 中显示，但该命令将不会成功。

遵循 Ansible 约定 

Ansible 约定在所有模块、playbook 和角色中提供可预测的用户界面。要在你的模块开发中遵循 Ansible 约定

在模块中使用一致的名称（是的，我们有很多遗留的偏差 - 不要让问题更糟！）。
在你的模块中使用一致的选项（参数）。
不要使用 'message' 或 'syslog_facility' 作为选项名称，因为这是 Ansible 内部使用的。
使用其他模块规范化选项 - 如果 Ansible 和你的模块连接的 API 对同一选项使用不同的名称，请为你的选项添加别名，以便用户可以选择在任务和 playbook 中使用哪个名称。
在结果字典的 ansible_facts 字段中返回来自 *_facts 模块的事实，以便其他模块可以访问它们。
在所有 *_info 和 *_facts 模块中实现 check_mode。如果在 check_mode 中返回事实，则基于事实信息进行条件化的 Playbook 仅在 check_mode 中才能正确地进行条件化。通常，在实例化 AnsibleModule 时，你可以添加 supports_check_mode=True。
使用特定于模块的环境变量。例如，如果你在 module_utils.api 中使用帮助程序，以便使用 module_utils.urls.fetch_url() 进行基本身份验证，并且你回退到环境变量以获取默认值，请使用特定于模块的环境变量，例如 API_<MODULENAME>_USERNAME 以避免模块之间的冲突。
保持模块选项简单且集中——如果你在现有选项上加载大量选择/状态，请考虑添加一个新的、简单的选项。
尽可能保持选项小。将大型数据结构传递给选项可能会为我们节省一些任务，但它增加了一个复杂的要求，我们在传递给模块之前无法轻松验证。
如果你想将复杂数据传递给选项，请编写一个允许这样做的专家模块，以及几个较小的模块，这些模块针对底层 API 和服务提供更“原子”的操作。复杂的操作需要复杂的数据。让用户选择是在任务和 play 中还是在 vars 文件中反映这种复杂性。
实现声明性操作（而不是 CRUD），以便用户可以忽略现有状态并专注于最终状态。例如，使用 started/stopped、present/absent。
努力实现一致的最终状态（又名幂等性）。如果连续两次在同一系统上运行你的模块会导致两种不同的状态，请查看是否可以重新设计或重写以实现一致的最终状态。如果不能，请记录该行为及其原因。
在标准 Ansible 返回结构中提供一致的返回值，即使对于在其他选项下通常返回的键使用 NA/None 也是如此。

模块安全 

避免从 shell 传递用户输入。
始终检查返回代码。
你必须始终使用 module.run_command，而不是 subprocess 或 Popen 或 os.system。
避免使用 shell，除非绝对必要。
如果必须使用 shell，则必须将 use_unsafe_shell=True 传递给 module.run_command。
如果你的模块中的任何变量可以通过 use_unsafe_shell=True 从用户输入中获取，则必须使用 pipes.quote(x) 将其包装起来。
在获取 URL 时，请使用 ansible.module_utils.urls 中的 fetch_url 或 open_url。请勿使用 urllib2，它本身不验证 TLS 证书，因此对于 https 是不安全的。
标记为 no_log=True 的敏感值将自动从模块返回值中删除该值。如果你的模块可以将这些敏感值作为字典键名称的一部分返回，你应该调用 ansible.module_utils.basic.sanitize_keys() 函数从键中删除这些值。有关示例，请参见 uri 模块。