odoo-ORM1

1. Date 和 Datetime 字段的重要性

日期和时间是任何业务应用中至关重要的字段。不正确的使用可能会导致隐蔽但棘手的问题。

赋值方式

Date 和 Datetime 字段可以通过以下方式赋值：

• Python 对象：date 或 datetime。
• 字符串格式：
  • 对于 Date 字段：YYYY-MM-DD。
  • 对于 Datetime 字段：YYYY-MM-DD HH:MM:SS。
• 特殊值：False 或 None（用于表示空值）。

辅助方法

Date 和 Datetime 字段的类提供了用于转换为兼容类型的辅助方法：

• to_date()：将值转换为 datetime.date。
• to_datetime()：将值转换为 datetime.datetime。

示例：

解析来自外部来源的日期或时间：

fields.Date.to_date(self._context.get('date_from'))

日期/时间比较的最佳实践

• Date 字段：只能与 date 对象比较。
• Datetime 字段：只能与 datetime 对象比较。

警告：

字符串形式的 Date 和 Datetime 是可以比较的，但不推荐，因为比较结果可能与预期不符。例如：

"2024-01-01 00:00:00" > "2024-01-01"  # 总是为 True

常见操作

Odoo 提供了便捷方法用于日期和时间的加减操作，以及获取特定周期的起始或结束时间。这些操作通过 odoo.tools.date_utils 提供的工具实现。

日期/时间操作方法：

1. start_of(value, granularity)
   • 用于获取指定日期/时间的起始时间。
   • 参数：
     • value: 初始日期或时间。
     • granularity: 周期类型，可选值包括 'year', 'quarter', 'month', 'week', 'day', 'hour'。
   • 返回值：返回起始日期/时间。
2. end_of(value, granularity)
   • 用于获取指定日期/时间的结束时间，参数和返回值与 start_of 类似。
3. add(value, *args, **kwargs)
   • 用于对日期/时间执行加操作。
   • 参数：
     • value: 初始日期/时间。
     • *args: 传递给 relativedelta 的参数。
     • **kwargs: 额外的关键字参数传递给 relativedelta。
   • 返回值：计算后的日期/时间。
4. subtract(value, *args, **kwargs)
   • 用于对日期/时间执行减操作，参数和返回值与 add 类似。

其他工具方法

1. today()
   • 返回当天的日期（格式适合 ORM 使用）。
   • 可用作计算字段的默认值。
2. context_today(record, timestamp=None)
   • 返回当前日期（客户端时区）。
   • 参数：
     • record: 从中获取时区的记录集。
     • timestamp: 可选，替代当前时间的时间值（必须为 datetime 类型）。
3. to_date(value)
   • 将值尝试转换为 date 对象，若为 datetime 则丢失时间信息（时、分、秒等）。
   • 参数：value（字符串、date 或 datetime）。
   • 返回值：date 或 None。
4. to_string(value)
   • 将 date 或 datetime 转换为字符串，格式适合服务器。
   • 返回值：如果是 datetime，则时间部分会被截断（00:00:00）。

时间字段与时区

1. 存储机制
   • Datetime 字段在数据库中以 UTC 时区存储。这使数据库不依赖托管服务器的时区。
   • 时区的转换完全由客户端负责。
2. 方法：context_timestamp(record, timestamp)
   • 将给定时间戳转换为客户端时区。
   • 注意：
     • 适用于特定时间展示，但不适合作为字段的默认值。
     • 默认值建议使用 now()。

应用场景总结

• 日期字段：适合纯日期（无时间）操作。
• 时间字段：适合需要处理时区的日期时间操作。
• 时间工具：如加减运算、周期计算，便于开发时处理复杂业务逻辑。

关系字段

1. 基础概念

在 Odoo 中，关系字段分为以下几种类型，用于定义模型间的关系：

• Many2one：表示当前模型到目标模型的单向多对一关系。
• One2many：表示当前模型到目标模型的单向一对多关系。
• Many2many：表示两个模型之间的多对多关系。
• Reference 和 Many2oneReference：伪关系字段，数据存储不使用外键。

每种字段有不同的参数和使用场景，以下是详细介绍。

2. Many2one 字段

含义

• Many2one 字段的值是一个大小为 0（无记录）或 1（单个记录）的记录集。

参数

• comodel_name（必填）：目标模型的名称。
• domain（可选）：用于客户端筛选候选值的可选域表达式，可以是固定的域或动态 Python 表达式。
• context（可选）：用于客户端操作该字段时的上下文。
• ondelete：指定目标记录被删除时的处理方式：
  • 'set null'：将字段值设置为 Null。
  • 'restrict'：禁止删除目标记录。
  • 'cascade'：删除目标记录时，当前模型的相关记录一并删除。
• auto_join：是否在搜索时自动生成 SQL JOIN（默认为 False）。
• delegate：设为 True 时，当前模型可以直接访问目标模型的字段（相当于 _inherits）。
• check_company：启用公司约束，确保字段指向的记录与当前记录的公司一致。

3. One2many 字段

含义

• One2many 字段的值是一个记录集，包含所有满足以下条件的目标记录：
  • 目标模型中 Many2one 字段的值等于当前记录。

参数

• comodel_name（必填）：目标模型的名称。
• inverse_name（必填）：目标模型中与当前模型关联的 Many2one 字段的名称。
• 其他参数如 domain、context 和 auto_join 的意义与 Many2one 字段相同。

4. Many2many 字段

含义

• Many2many 字段的值是一个记录集，表示两个模型间的多对多关系。

参数

• comodel_name（必填）：目标模型的名称。
• relation（可选）：存储关系的中间表的名称，若未提供，Odoo 会根据模型名称自动生成。
• column1 和 column2（可选）：中间表中分别引用当前模型和目标模型记录的列名。
• 其他参数如 domain、context 和 check_company 的意义与 Many2one 字段相同。

注意事项

• 如果多个 Many2many 字段未显式定义 relation，且使用相同的目标模型，ORM 将报错。
• 解决方式：
  • 显式定义 relation。
  • 使模型的 _auto 属性为 False。

5. Command 方法

One2many 和 Many2many 字段支持使用 Command 类来操作其关系。每个命令是一个包含三部分的元组：

1. 命令标识符（整数）。
2. 记录 ID 或 0（取决于命令类型）。
3. 用于更新或创建记录的值，或新关联记录的列表，或 0。

命令类型

• CREATE (0)：创建新记录，并与当前记录关联。
• UPDATE (1)：更新已关联记录的字段值。
• DELETE (2)：删除记录，并移除关联。
• UNLINK (3)：仅移除关联，不删除目标记录。
• LINK (4)：将已有记录与当前记录关联。
• CLEAR (5)：移除所有关联。
• SET (6)：替换当前关联记录。

示例

# 添加一条新记录
Command.create({'name': 'New Item'})

# 更新已有记录
Command.update(3, {'name': 'Updated Name'})

# 删除记录并移除关联
Command.delete(3)

# 仅移除关联
Command.unlink(3)

# 替换关联
Command.set([1, 2, 3])

6. Reference 和 Many2oneReference 字段

Reference

• 存储值为字符串，格式为 "res_model,res_id"。
• 不建立数据库外键。

Many2oneReference

• 存储值为目标记录的整数 ID。
• 目标模型的名称需要存储在一个 Char 字段中，并通过 model_field 参数指定该字段的名称。

保留字段的名称

1. 计算字段 (Computed Fields)

定义

计算字段是动态计算值的字段，而不是直接从数据库中读取。通过参数 compute 指定计算方法。例如：

from odoo import api, fields, models

class MyModel(models.Model):
    _name = 'my.model'

    total = fields.Float(compute='_compute_total')

    @api.depends('value', 'tax')
    def _compute_total(self):
        for record in self:
            record.total = record.value + record.value * record.tax

依赖声明

• 如果计算字段依赖其他字段，需要通过 @api.depends 装饰器声明这些字段。
• 依赖字段可以是嵌套字段（如 line_ids.value）。

存储

• 默认情况下，计算字段不存储，每次访问时动态计算。
• 设置 store=True 可以将其存储到数据库中，同时允许搜索。

搜索

• 计算字段默认不可搜索。
• 使用 search 参数指定搜索方法，返回等效的搜索域：

upper_name = fields.Char(compute='_compute_upper', search='_search_upper')

def _search_upper(self, operator, value):
    if operator == 'like':
        operator = 'ilike'
    return [('name', operator, value)]

只读

• 默认情况下，计算字段是只读的。
• 可通过 inverse 参数设置逆运算方法，使字段值可写：

document = fields.Char(compute='_get_document', inverse='_set_document')

def _get_document(self):
    for record in self:
        with open(record.get_document_path()) as f:
            record.document = f.read()

def _set_document(self):
    for record in self:
        if record.document:
            with open(record.get_document_path(), 'w') as f:
                f.write(record.document)

多个字段的计算

• 同一个方法可以计算多个字段：

discount_value = fields.Float(compute='_apply_discount')
total = fields.Float(compute='_apply_discount')

@api.depends('value', 'discount')
def _apply_discount(self):
    for record in self:
        discount = record.value * record.discount
        record.discount_value = discount
        record.total = record.value - discount

注意事项

• 不建议为多个字段使用同一个逆运算方法，否则可能导致数据不一致。

2. 相关字段 (Related Fields)

定义

相关字段是特殊的计算字段，用于从当前记录的子字段中获取值。例如：

nickname = fields.Char(related='user_id.partner_id.name', store=True)

特性

• 默认不存储、不复制，只读，超管模式计算。
• 设置 store=True 可存储并允许搜索。

依赖声明

• 使用 depends 参数指定精确依赖，避免因子字段变化导致不必要的重新计算：

nickname = fields.Char(related='partner_id.name', store=True, depends=['partner_id'])

限制

• 不支持链式依赖 Many2many 或 One2many 的子字段。

3. 自动字段 (Automatic Fields)

Odoo 自动为模型生成以下字段，若 _log_access 属性启用，则会自动记录创建和更新信息：

访问日志字段

• create_date：记录创建时间。
• create_uid：记录创建者（res.users 的 Many2one）。
• write_date：记录最近更新时间。
• write_uid：记录最近更新者。

启用与禁用

• 默认 _log_access 和 _auto 均为 True。
• 禁用 _log_access 可以避免生成这些字段。

4. 保留字段 (Reserved Fields)

以下字段名称具有特定用途，定义时需遵守相关行为约定：

常见保留字段

1. name
   • 用作 _rec_name 的默认值，表示记录的主要名称。
2. active
   • 控制记录的全局可见性，默认为 True。设置为 False 时，记录在大多数搜索和列表中不可见。
   • 提供的方法：
     • toggle_active()：反转 active 值。
     • action_archive()：设置 active=False（归档）。
     • action_unarchive()：设置 active=True（取消归档）。
3. state
   • 用于表示对象的生命周期阶段，通常是 Selection 字段。
4. parent_id
   • 组织记录为树形结构时的父级记录字段。
   • 配合 _parent_store=True 和 parent_path 优化 child_of、parent_of 操作。
5. company_id
   • 用于多公司行为检查，定义记录的归属公司。

Recordsets（记录集）

定义

记录集是同一模型的记录的有序集合，用于在 Odoo 中与模型和记录进行交互。

警告

尽管名字中包含 “sets” 一词，但记录集中可能包含重复项。未来版本可能会对此进行更改。

特点

• 记录集的方法是在记录集范围内执行的，self 表示当前记录集。
• 记录集可以包含 0 到 N 条记录，甚至是整个数据库的所有记录。

单记录迭代

• 对记录集进行迭代时，会生成单条记录的记录集（“单例”）。

示例：

class AModel(models.Model):
    _name = 'a.model'

    def a_method(self):
        print(self)  # 输出记录集，比如 a.model(1, 2, 3)
        for record in self:
            print(record)  # 逐条输出单记录 a.model(1), a.model(2), ...

字段访问

直接访问字段

• 记录集提供了“活动记录”接口，可以直接读取或写入字段值：

  record.name  # 读取字段
  record.name = "New Name"  # 写入字段
  

动态字段访问

• 动态字段名称可以通过 getattr() 访问，更优雅且更安全：

  field_name = "name"
  print(record[field_name])  # 动态访问字段
  

非关系字段限制

• 如果记录集包含多条记录，读取非关系字段会抛出错误。
• 关系字段（Many2one、One2many、Many2many）总是返回记录集，即使字段为空。

批量字段访问

• 对多条记录批量获取字段值时，使用 mapped() 方法：

  total_qty = sum(self.mapped('qty'))  # 获取所有记录的 qty 总和
  

记录缓存与预取（Prefetching）

缓存机制

Odoo 使用缓存机制来避免每次访问字段时都查询数据库：

• 第一次访问字段时从数据库读取值。
• 后续访问直接从缓存中获取。

示例：

record.name  # 第一次访问，从数据库读取
record.name  # 第二次访问，从缓存读取

预取机制

• 为提高性能，Odoo 会根据某些启发式规则进行字段和记录的预取操作。
• 当访问某记录的某字段时，Odoo 实际上会从该记录集预取更多字段，并缓存这些值。

示例：

for partner in partners:
    print(partner.name)  # 第一次访问时预取所有 'name' 和 'lang' 字段
    print(partner.lang)  # 缓存中直接获取

• 如果访问了关联字段（如 Many2one），相关模型的记录也会被订阅以便未来预取。
• 例如：

  countries = set()
  for partner in partners:
      country = partner.country_id  # 首次预取所有关联国家
      countries.add(country.name)  # 再次访问时从缓存中获取
  

预取优势

• 例如在有 1000 条记录的循环中：
  • 如果没有预取，每次查询都会触发 2000 次数据库查询。
  • 有预取时，仅需 1 次查询。

辅助方法

• search_fetch() 和 fetch() 方法可以手动填充记录的缓存，适用于预取机制不足的场景。

Odoo 方法装饰器（Method decorators）

Odoo 提供了一些方法装饰器，用于简化和增强模型方法的功能。

1. @api.model

• 作用：用于装饰记录风格的方法。在这种方法中，self 是一个记录集，但记录集的内容不重要，只关心模型本身。

示例：

@api.model
def method(self, args):
    ...

• 解读：此装饰器用于那些与模型本身相关，但不依赖于特定记录的操作。

2. @api.constrains(*args)

• 作用：用于定义约束检查方法，检查一个或多个字段的条件。每个参数必须是一个字段名。

示例：

@api.constrains('name', 'description')
def _check_description(self):
    for record in self:
        if record.name == record.description:
            raise ValidationError("Fields name and description must be different")

• 解读：此装饰器用于约束方法，当指定字段发生更改时触发。若验证失败，应抛出 ValidationError。
• 注意：@constrains 只支持简单字段名，关系字段（如 partner_id.customer）将被忽略。

3. @api.depends(*args)

• 作用：指定计算字段的方法依赖的字段。每个参数必须是字段名（可以是以点分隔的关系字段）。

示例：

@api.depends('partner_id.name', 'partner_id.is_company')
def _compute_pname(self):
    for record in self:
        if record.partner_id.is_company:
            record.pname = (record.partner_id.name or "").upper()
        else:
            record.pname = record.partner_id.name

• 解读：该装饰器用于指定计算字段的依赖关系，确保当依赖字段的值发生变化时，计算字段会自动更新。

4. @api.onchange(*args)

• 作用：用于装饰当字段值发生变化时被调用的方法。每个参数必须是一个字段名。

示例：

@api.onchange('partner_id')
def _onchange_partner(self):
    self.message = "Dear %s" % (self.partner_id.name or "")
    return {
        'warning': {'title': "Warning", 'message': "What is this?", 'type': 'notification'},
    }

• 解读：该装饰器会在指定字段变化时触发。方法返回的内容会自动发送回客户端，显示通知或警告。
• 警告：@onchange 只支持简单字段名，不支持关系字段（如 partner_id.tz）。

5. @api.returns(model, downgrade=None, upgrade=None)

• 作用：装饰器用于指定方法的返回值模型。downgrade 和 upgrade 参数用于将记录风格和传统风格的输出进行转换。

示例：

@api.returns('res.partner')
def find_partner(self, arg):
    ...

• 解读：该装饰器用于方法返回记录风格的实例，downgrade 和 upgrade 可以用于转换返回值的格式。

6. @api.autovacuum(method)

• 作用：装饰一个方法，使其在每天的自动清理任务中被调用，通常用于垃圾回收类的任务。

7. @api.depends_context(*args)

• 作用：用于指定非存储“计算”字段的方法的上下文依赖关系。每个参数是上下文字典中的键。

示例：

@api.depends_context('pricelist')
def _compute_product_price(self):
    for product in self:
        pricelist = self.env['product.pricelist'].browse(self.env.context['pricelist'])
        product.price = pricelist._get_products_price(product).get(product.id, 0.0)

• 解读：此装饰器指定计算字段依赖于上下文中的值。

8. @api.model_create_multi(method)

• 作用：装饰一个方法，使其可以接受一个字典列表并创建多个记录。方法可以通过单个字典或字典列表调用。

示例：

python复制代码record = model.create(vals)
records = model.create([vals, ...])

• 解读：该装饰器用于批量创建记录，允许同时处理多个字典数据。

9. @api.ondelete(*args, at_uninstall)

• 作用：装饰一个方法，在删除记录时触发，通常用于防止删除某些特定记录（如已验证的销售订单）时抛出错误。at_uninstall 参数控制是否在卸载模块时触发该方法。

示例：

@api.ondelete(at_uninstall=False)
def _unlink_if_user_inactive(self):
    if any(user.active for user in self):
        raise UserError("Can't delete an active user!")

• 解读：该装饰器用于防止删除某些记录。例如，阻止删除处于活动状态的用户。at_uninstall 默认是 False，意味着只有在通过 unlink 删除时才会触发。如果设置为 True，则在模块卸载时也会触发。

总结

这些装饰器为 Odoo 提供了强大的方法修饰功能。通过这些装饰器，可以轻松地实现如下功能：

1. 模型方法定义 (@api.model),
2. 约束验证 (@api.constrains),
3. 字段计算 (@api.depends, @api.depends_context),
4. 字段变化监听 (@api.onchange),
5. 方法返回值处理 (@api.returns),
6. 自动清理 (@api.autovacuum),
7. 批量创建记录 (@api.model_create_multi),
8. 删除记录时的验证 (@api.ondelete).

未完待续->  odoo-ORM2 | 同欣数字化落地