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

news2025/6/8 8:42:59

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 设置项值，统一为字符串类型
读写方式：

字段名	类型	描述
`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, fields

class 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 models

class 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):
        # 高级功能实现
        pass

    def _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>