第21讲、Odoo 18 配置机制详解

Odoo 18 配置机制详解：res.config.settings 与 ir.config_parameter 原理与实战指南

在现代企业信息化系统中，灵活且可维护的系统参数配置是模块开发的核心能力之一。Odoo 作为一款高度模块化的企业管理软件，其参数配置机制主要依赖于两个关键模型：res.config.settings 和 ir.config_parameter。

本文将系统梳理这两个模型的设计原理、典型应用场景及开发实践，并通过完整案例演示如何从 Python 到 XML 快速实现系统设置项，助力开发者高效构建可配置的 Odoo 模块。

---

一、核心模型原理

1. ir.config_parameter —— 系统参数存储模型

• 作用：作为底层的键值对存储模型，负责持久化保存系统全局配置参数。

• 模型名称：ir.config_parameter

• 表结构（简化）：

  字段名	类型	描述
  key	char	设置项唯一键
  value	text	设置项值，统一为字符串类型

• 读写方式：

# 读取配置值（如布尔型需自行判断）
value = self.env['ir.config_parameter'].sudo().get_param('my_module.my_setting') == 'True'# 设置配置值
self.env['ir.config_parameter'].sudo().set_param('my_module.my_setting', 'True')

---

2. res.config.settings —— 系统设置表单模型

• 作用：为管理员提供 UI 表单接口，便于读取和设置 ir.config_parameter。
• 模型名称：res.config.settings（TransientModel，临时模型，数据不持久化）
• 关键特性：
  • 字段通过 config_parameter 属性与 ir.config_parameter.key 关联
  • 支持多种字段类型（Boolean、Char、Integer、Selection 等）
  • 设置项可直接在 Odoo 后台"设置"界面进行配置

---

二、典型应用场景

应用场景	说明
功能开关	启用/禁用模块功能（如"启用审批流程"）
默认参数	设定默认值（如"默认抄送邮箱"“默认负责人”）
第三方集成	存储 API Key、Webhook URL 等外部对接参数
系统行为设置	配置"数据保留天数""通知频率"等系统行为

---

三、开发流程实战

以"启用高级功能"为例，演示从字段定义到前端配置的完整开发流程。

1. 模块结构示例

my_module/
├── __init__.py
├── __manifest__.py
├── models/
│   ├── __init__.py
│   ├── res_config_settings.py
│   └── my_model.py
└── views/└── res_config_settings_views.xml

2. manifest 文件

my_module/__manifest__.py：

{'name': 'My Module','version': '1.0','category': 'Tools','summary': '演示 Odoo 配置机制','depends': ['base'],'data': ['views/res_config_settings_views.xml',],'installable': True,'application': False,
}

3. Python 字段定义

在 models/res_config_settings.py 中定义设置字段，并通过 config_parameter 绑定系统参数：

from odoo import models, fieldsclass ResConfigSettings(models.TransientModel):_inherit = 'res.config.settings'enable_advanced_feature = fields.Boolean(string="Enable Advanced Feature",help="启用后，将激活本模块的高级功能。",config_parameter='my_module.enable_advanced_feature')default_manager = fields.Many2one('res.users',string="Default Manager",help="新建任务时的默认负责人。",config_parameter='my_module.default_manager_id')

4. XML 视图定义

在 views/res_config_settings_views.xml 中扩展设置页面，使字段在前端可见：

<?xml version="1.0" encoding="UTF-8"?>
<odoo><record id="res_config_settings_view_form_my_module" model="ir.ui.view"><field name="name">res.config.settings.view.form.my.module</field><field name="model">res.config.settings</field><field name="inherit_id" ref="base.res_config_settings_view_form"/><field name="arch" type="xml"><xpath expr="//div[@id='settings']" position="inside"><div class="app_settings_block" data-string="My Module Settings" string="My Module Settings"><h2>My Module</h2><field name="enable_advanced_feature"/><field name="default_manager"/></div></xpath></field></record>
</odoo>

5. 业务代码中读取配置

my_module/models/my_model.py：

from odoo import modelsclass MyModel(models.Model):_name = 'my.model'def do_something(self):enable = self.env['ir.config_parameter'].sudo().get_param('my_module.enable_advanced_feature')if enable == 'True':self._do_advanced()else:self._do_basic()def _do_advanced(self):# 高级功能实现passdef _do_basic(self):# 基础功能实现pass

---

四、进阶技巧与实用建议

1. 多公司参数隔离

Odoo 默认的 ir.config_parameter 参数是全局共享的。如需为每个公司单独配置参数，可通过拼接公司 ID 实现隔离：

company_id = self.env.company.id
param_key = f"my_module.feature_enabled_company_{company_id}"
self.env['ir.config_parameter'].sudo().set_param(param_key, 'True')

2. 类型转换建议

所有参数值均以字符串存储，读取时需根据实际类型转换：

# 读取整数类型参数
retry_count = int(self.env['ir.config_parameter'].sudo().get_param('my_module.retry_count') or 0)

---

五、常见问题与排查建议

问题	解决方法
设置值后保存无效	检查字段是否正确添加 config_parameter 属性
设置页面不显示字段	检查 XML 是否正确继承并挂载到 res.config.settings
报错找不到字段	重启 Odoo 并升级模块，清理缓存
多公司参数混乱	使用公司 ID 拼接参数 key 或扩展公司字段

---

六、模型对比与总结

项目	res.config.settings	ir.config_parameter
模型类型	TransientModel	Regular Model
主要作用	提供设置表单 UI 接口	持久化存储配置值
是否持久化	否	是（持久存储）
字段控制	通过 config_parameter	代码直接 set/get
典型用途	用户界面参数配置	业务逻辑读取系统参数

---

七、常用模板片段（可直接复用）

Python 字段定义

my_option = fields.Boolean(string="My Option",config_parameter='my_module.my_option'
)

XML 视图片段

<xpath expr="//div[@id='settings']" position="inside"><div class="app_settings_block" string="My Module"><field name="my_option"/></div>
</xpath>

---

八、结语

通过合理利用 res.config.settings 与 ir.config_parameter，Odoo 开发者能够为模块快速添加灵活的系统配置项，实现功能开关、参数定制和第三方集成等多样化需求。这不仅提升了模块的通用性和可维护性，也为企业系统的持续演进提供了坚实基础。