odoo开发规范-开发必读-囊括模块视图后端前端规范-以odoo14/13为基准

• 模块结构
• XML文件
• Python
• Javascript和CSS
• Git 操作规范

模块结构

目录及对应作用

• data/:演示和数据文件
• models/:模型定义
• controllers/:控制器(包含HTTP路由)
• views/:视图和模版
• static/:web资源，包括css/, js/, img/, lib/, ...
• wizard/:向导及其视图
• report/:报表
• tests/:单元测试代码

文件命名

业务model放置在一个文件里，如果模块只包含一个model，它的名字就与模块名一致。如：

• models/<main_model>.py
• models/<inherited_main_model>.py
• views/<main_model>_templates.xml
• views/<main_model>_views.xml
• data/<main_model>_demo.xml
• data/<main_model>_data.xml

例如：销售模块包含sale_order和sale_order_line两个模型，并且sale_order是主模型，所以文件将被命名为models/sale_order.py和 views/sale_order_views.xml。
对于数据文件命名，按用途进行命名：demo或者data。例如:data/sale_order_demo.xml和data/sale_order_data.xml
每个模块的控制器都放在一个文件中，命名为main.py。如果是从另一个模块继承的，则将其命名为<module_name>.py。

与模型不同，每个控制器类应包含在一个分离的文件中。例如，采购模块在  controllers/portal.py  中实现其客户门户的一部分，并在 controllers/purchase.py上实现其自身的典型路由。

对于静态文件，由于资源可以在不同的上下文中使用（前端、后端、两者），因此它们将仅包含在一个捆绑包中。因此，CSS/Less、JavaScript 和 XML 文件应该捆绑一个其类型的后缀名称。

即：im_chat_common.css，用于"asset_common"捆绑的 im_chat_common.js，以及用于"asset_backend"捆绑的 im_chat_backend.js。如果模块只拥有一个文件，则约定将<module_name>.ext（如：project.js）。不要链接odoo外部资源数据（图像、库）：不要使用图像的 URL，而应将其复制到我们的代码库中。

关于数据，按用途拆分它们：数据或演示。文件名将是主模型名称，后缀为 _data.xml 或 _demo.xml。

关于向导和瞬态模型，命名约定是 ：

• <main_transient>.py
• <main_transient>_views.xml

其中<main_transient>是占主导地位的瞬态模型的名称，就像模型一样。<main_transient>.py 可以包含模型"transient_model.action"和"transient_model.action.line"。

统计报表命名：

• <report_name_A>_report.py
• <report_name_A>_report_views.py (一般提供 pivot 和 graph 视图)

可打印报表：

• <print_report_name>_reports.py (报表  actions, 格式定义, …)
• <print_report_name>_templates.xml (xml 报表模板)

完整的文件列表如下：

addons/<my_module_name>/
|-- __init__.py
|-- __manifest__.py
|-- controllers/
|   |-- __init__.py
|   |-- <inherited_module_name>.py
|   `-- <my_module_name>.py
|-- data/
|   |-- <main_model>_data.xml
|   `-- <inherited_main_model>_demo.xml
|-- models/
|   |-- __init__.py
|   |-- <main_model>.py
|   `-- <inherited_main_model>.py
|-- report/
|   |-- __init__.py
|   |-- <main_stat_report_model>.py
|   |-- <main_stat_report_model>_views.xml
|   |-- <main_print_report>_reports.xml
|   `-- <main_print_report>_templates.xml
|-- security/
|   |-- ir.model.access.csv
|   `-- <main_model>_security.xml
|-- static/
|   |-- img/
|   |   |-- my_little_kitten.png
|   |   `-- troll.jpg
|   |-- lib/
|   |   `-- external_lib/
|   `-- src/
|       |-- js/
|       |   |-- <my_module_name>.js
            `-- <my_widget_A>.js
|       |-- css/
|       |   `-- <my_module_name>.css
|       |-- scss/
|       |   `-- <my_module_name>.scss
|       `-- xml/
|           |-- <my_module_name>.xml
            `-- <my_widget_A>.xml
|-- views/
|   |-- <main_model>_templates.xml
|   |-- <main_model>_views.xml
|   |-- <inherited_main_model>_templates.xml
|   `-- <inherited_main_model>_views.xml
`-- wizard/
    |-- <main_transient_A>.py
    |-- <main_transient_A>_views.xml
    |-- <main_transient_B>.py
    `-- <main_transient_B>_views.xml

XML文件

格式

当定义一个记录的xml时，需要<record>标记:

• id属性放在model属性前
• 字段(field)定义中，name属性放在第一个。然后，将值放在<field>标签内，或者放在eval属性中。最后将其他属性（widget、options...）按重要性排序。
• 尝试按模型对记录进行分组。如果操作/菜单/视图之间存在依赖关系，则此约定可能不适用。
• 使用在下一章节中定义的命名约定
• 标签<data>仅用于设置不可更新的数据noupdate=1,如果整个xml文件都是不可更新数据，则noupdate=1属性可以设置在<odoo>标签上，而不需要<data>标签。

Odoo支持一些自定义标签作为快捷方式：

• menuitem：作为ir.ui.menu的快捷方式
• template: 表示只需要arch视图部分的QWeb视图
• report: 用于定义报表report action
• act_window：当record用不了的时候用它

xml_id命名

权限(Security)、视图(View)和动作(Action)使用的命名规则：

• 菜单(menu): <model_name>_menu, 或 子菜单 <model_name>_menu_do_stuff .
• 视图(view): <model_name>_view_<view_type>,view_type可能的取值有：kanban, form, tree, search
• 动作(action): 主动作命名为<model_name>_action，其他的动作命名为<model_name>_action_<detail>，其中<detail>使用小写字母简单描述动作，适用于一个模型有多个动作
• 权限组(group): <model_name>_group_<group_name>，group_name为组名，可能的取值包括:‘user’, ‘manager’, …
• 记录规则(rule): <model_name>_rule_<concerned_group>，concerned_group 是相关权限组的缩写，如 (‘user’ for the ‘model_name_group_user’, ‘public’ for public user 公共用户, ‘company’ for multi-company rules 多公司规则, …).

<!-- views and menus -->
<record id="model_name_view_form" model="ir.ui.view">
    ...
</record>

<record id="model_name_view_kanban" model="ir.ui.view">
    ...
</record>

<menuitem
    id="model_name_menu_root"
    name="Main Menu"
    sequence="5"
/>
<menuitem
    id="model_name_menu_action"
    name="Sub Menu 1"
    parent="module_name.module_name_menu_root"
    action="model_name_action"
    sequence="10"
/>

<!-- actions -->
<record id="model_name_action" model="ir.actions.act_window">
    ...
</record>

<record id="model_name_action_child_list" model="ir.actions.act_window">
    ...
</record>

<!-- security -->
<record id="module_name_group_user" model="res.groups">
    ...
</record>

<record id="model_name_rule_public" model="ir.rule">
    ...
</record>

<record id="model_name_rule_company" model="ir.rule">
    ...
</record>

视图名称使用 . 连接关键语，my.model.view_type 或 my.model.view_type.inherit ，来标记ad of “This is the form view of My Model”.

继承XML的命名

继承视图的命名规则为

• #. Extension 扩展模式：使用与要扩展的原始视图相同的 xml id，并使用 _inherit 后缀 ：如 视图view project.project_view_form 被扩展 为 project_forecast.project_view_form_inherit.
• #. Primary 主模式：保持原有 xml id。

<record id="module2.model_view_form_inherit" model="ir.ui.view">
    <field name="inherit_id" ref="module1.model_view_form"/>
    ...
</record>

<record id="module2.model_view_form" model="ir.ui.view">
    <field name="inherit_id" ref="module1.model_view_form"/>
    <field name="mode">primary</field>
    ...
</record>

Python

PEP8 选项

Odoo源代码基本准守Python标准PEP8，但是忽略其中一些规则：

• E501：行太长了
• E301：预计有1个空行，找到0
• E302：预计有2个空行，找到1
• E126：延长线过度缩进以用于悬挂缩进
• E123：关闭支架与开口支架线的压痕不匹配
• E127：延伸线过度缩进以进行视觉缩进
• E128：用于视觉缩进的缩进的延续线
• E265：阻止评论应以'＃'开头

Import 导入

import 的顺序

1. 导入外部库
2. 导入odoo
3. 导入odoo的模块

在每组中的导入按字母顺序排序

# 1 : imports of python lib
import base64
import re
import time
from datetime import datetime
# 2 :  imports of odoo
import odoo
from odoo import api, fields, models # alphabetically ordered
from odoo.tools.safe_eval import safe_eval as eval
from odoo.tools.translate import _
# 3 :  imports from odoo addons
from odoo.addons.website.models.website import slug
from odoo.addons.web.controllers.main import login_redirect

编程习惯

• 每个python文件都应该以 # -*- coding: utf-8 -*- 作为第一行。
• 简单易读的代码
• 不要使用.clone()

Odoo中编程

• 避免创建生成器和装饰器：仅使用Odoo API已有的
• 使用filtered, mapped, sorted, … 方法来提升代码可读性和性能。

让你的方法可以批量处理

当添加一个函数时，确保它可以处理多条数据，典型用法是通过 api.multi 装饰器，可以在self上进行循环处理

@api.multi
def my_method(self)
    for record in self:
        record.do_cool_stuff()

避免使用 api.one 装饰器，因为它可能不会像预想中一样工作。

注意，在odoo13中，连 api.multi 都取消了，因为不存在 api.one ，故默认全是 multi。

为了更好的性能，比如当定义一个状态按钮时，不在  api.multi 循环里用search 和 search_count 方法，要用 read_group 来实现一次请求中全部计算。

@api.multi
def _compute_equipment_count(self):
""" Count the number of equipement per category """
    equipment_data = self.env['hr.equipment'].read_group([('category_id', 'in', self.ids)], ['category_id'], ['category_id'])
    mapped_data = dict([(m['category_id'][0], m['category_id_count']) for m in equipment_data])
    for category in self:
        category.equipment_count = mapped_data.get(category.id, 0)

context上下文环境

context是一个 frozendict 不能修改。当需要使用不同的 context 来调用一个方法时，可以通过with_context 来实现。

records.with_context(new_context).do_stuff() # all the context is replaced
records.with_context(**additionnal_context).do_other_stuff() # additionnal_context values override native context ones

在 context 中传递参数可能会产生危险的副作用。由于值是自动传播的，因此可能会出现某些不可预期行为。在 context 调用具有 default_my_field 键的模型的  create() 方法将为相关模型设置 my_field 的默认值。但是，如果固化此创建，其他对象（如 sale.order.line，在sale.order 创建中）具有一个相同字段 my_field，其默认值也将设置。

如果需要创建影响某些对象行为的关键 context，请选择一个好名称，并最终按模块的名称为其前缀，以隔离其影响。一个很好的例子是 mail 模块的密钥：mail_create_nosubscribe, mail_notrack, mail_notify_user_signature, …

不要绕过ORM

当ORM可以实现的时候尽量使用ORM而不要直接写sql，因为它可能会绕过orm的一些规则如权限、事务等，还会让代码变得难读且不安全。

# very very wrong
self.env.cr.execute('SELECT id FROM auction_lots WHERE auction_id in (' + ','.join(map(str, ids))+') AND state=%s AND obj_price > 0', ('draft',))
auction_lots_ids = [x[0] for x in self.env.cr.fetchall()]

# no injection, but still wrong
self.env.cr.execute('SELECT id FROM auction_lots WHERE auction_id in %s '
           'AND state=%s AND obj_price > 0', (tuple(ids), 'draft',))
auction_lots_ids = [x[0] for x in self.env.cr.fetchall()]

# better
auction_lots_ids = self.search([('auction_id','in',ids), ('state','=','draft'), ('obj_price','>',0)])

防止SQL注入!

使用 SQL 代码查询时，必须注意不要引入 SQL 注入漏洞。当用户输入被错误地过滤或引用错误时，存在此漏洞，从而允许攻击者向 SQL 查询引入不需要的子句（例如绕过筛选器或执行 UPDATE 或 DELETE 命令）。

安全的最佳方法是永远不要使用 Python 字符串串联 （+） 或字符串参数插值 （%）将变量传递到 SQL 查询字符串。

几乎同样重要的第二个原因，应该由数据库抽象层 （psycopg2） 来决定如何格式化查询参数，而不是您的代码！例如，psycopg2 知道，当您传递一个值列表时，它需要将它们格式化为逗号分隔列表，包含在括号中！

# the following is very bad:
#   - it's a SQL injection vulnerability
#   - it's unreadable
#   - it's not your job to format the list of ids
self.env.cr.execute('SELECT distinct child_id FROM account_account_consol_rel ' +
           'WHERE parent_id IN ('+','.join(map(str, ids))+')')

# better
self.env.cr.execute('SELECT DISTINCT child_id '
           'FROM account_account_consol_rel '
           'WHERE parent_id IN %s',
           (tuple(ids),))

不要手动提交事务

Odoo 框架负责为所有 RPC 调用提供事务上下文。原则是，在每个 RPC 调用开始时，打开一个新的数据库游标，并在调用return返回时commit，即在commit前先将结果返回至 RPC 客户端，大致如下所示：

def execute(self, db_name, uid, obj, method, *args, **kw):
    db, pool = pooler.get_db_and_pool(db_name)
    # create transaction cursor
    cr = db.cursor()
    try:
        res = pool.execute_cr(cr, uid, obj, method, *args, **kw)
        cr.commit() # all good, we commit
    except Exception:
        cr.rollback() # error, rollback everything atomically
        raise
    finally:
        cr.close() # always close cursor opened manually
    return res

如果在执行 RPC 调用期间发生任何错误，事务将以原方式回滚，从而保留系统的状态。

同样，系统在执行测试代码期间还提供专用事务，因此可以回滚或不依赖于服务器启动选项。

因此，如果您在任何地方代码调用 cr.commit()  ，您很有可能会以各种方式破坏系统，因为您将导致部分提交，从而导致部分和不干净的回滚，从而导致问题：

1. 业务数据不一致，通常是数据丢失
2. 工作流取消同步，文档永久卡住
3. 无法干净地回滚的测试，并且将开始污染数据库并触发错误（即使事务期间未发生错误也是如此）

所以请遵照以下非常简单的规则：

您绝对不要自己调用 cr.commit()，除非 您已显式创建自己的数据库游标！或者你有特殊的原因必须这样做。

如果您确实创建了自己的游标，则需要处理错误情况和适当的回滚，并在完成该游标后正确关闭游标。

与普遍的看法相反，在以下情况下，您甚至不需要调用cr.commit() ：

• 在模型的 _auto_init() 方法中。模型对象：这是由加载项初始化方法，或由 ORM 事务在创建自定义模型时处理
•  在报表中： commit()  也由框架处理，因此您甚至可以在报表内更新数据库
•  在模型中。瞬态方法：这些方法与常规模型完全一样。模型，在事务中，并在末尾使用相应的 cr.commit()/rollback()
• 其它情况（如果您有疑问，请参阅上面的一般规则！

正确的使用翻译方法

Odoo 使用类似于 GetText 的方法名  _( ) 来指示代码中使用的静态字符串需要在运行时使用上下文的语言进行翻译。通过在代码中通过导入访问此伪方法：

from odoo.tools.translate import _

在使用它时，必须遵循一些非常重要的规则，以便它正常工作，避免在翻译中填充无用的垃圾。

基本上，此方法只应用于在代码中手动编写的静态字符串，它无法转换字段值，如产品名称等。必须使用相应字段上的翻译标志来完成此操作。

规则非常简单：对下划线方法的调用应始终以 _（"文本字符串"）的形式进行，而没有其他内容：

# good: plain strings
error = _('This record is locked!')

# good: strings with formatting patterns included
error = _('Record %s cannot be modified!') % record

# ok too: multi-line literal strings
error = _("""This is a bad multiline example
             about record %s!""") % record
error = _('Record %s cannot be modified' 
          'after being validated!') % record

# bad: tries to translate after string formatting
#      (pay attention to brackets!)
# This does NOT work and messes up the translations!
error = _('Record %s cannot be modified!' % record)

# bad: dynamic string, string concatenation, etc are forbidden!
# This does NOT work and messes up the translations!
error = _("'" + que_rec['question'] + "' n")

# bad: field values are automatically translated by the framework
# This is useless and will not work the way you think:
error = _("Product %s is out of stock!") % _(product.name)
# and the following will of course not work as already explained:
error = _("Product %s is out of stock!" % product.name)

# bad: field values are automatically translated by the framework
# This is useless and will not work the way you think:
error = _("Product %s is not available!") % _(product.name)
# and the following will of course not work as already explained:
error = _("Product %s is not available!" % product.name)

# Instead you can do the following and everything will be translated,
# including the product name if its field definition has the
# translate flag properly set:
error = _("Product %s is not available!") % product.name

此外，请记住，翻译者必须使用传递给 _() 函数的字面值，因此请尽量使其易于理解，并将伪字符和格式保持在最低限度。翻译者必须注意，需要保留格式模式（如 %s 或 %d、newline 换行等），以明智和明显的方式使用这些格式模式非常重要：

# Bad: makes the translations hard to work with
error = "'" + question + _("' nPlease enter an integer value ")

# Better (pay attention to position of the brackets too!)
error = _("Answer to question %s is not valid.n" 
          "Please enter an integer value.") % question

通常，在 Odoo 中，在操作字符串时，更多用 % 而不是用 .format()（当字符串中只有一个变量替换），更多用 %(varname) 而不是指定位置（当多个变量必须替换时）。这使得社区翻译人员更容易翻译。

符号和习惯

• 模型名-使用.分隔，模块名做前缀
  • 定义odoo模型时，使用单数形式的名字如res.partner,sale.order 而不是 res.partnerS,saleS.orderS
  • 定义odoo Transient / wizard时，命名格式为<related_base_model>.<action>，此瞬态模型是 related_base_model是基础模型（在目录 models/ 中定义)进行的关联，action是功能简称，避免使用 wizard 关键字. 例如： account.invoice.make, project.task.delegate.batch, …
  • 定义报表模型（或者SQL View）时，使用<related_base_model>.report.<action>，和瞬态模型一样
• python类-使用驼峰命名

class AccountInvoice(models.Model):
    ...

• 变量命名
  • 模型变量使用驼峰命名方式
  • 普通变量用小写字母 + 下划线关联来命名
  • 如果变量包含记录 id 或 id 列表则将变量名称后缀为 _id 或 _ids。不要使用 partner_id 来包含一条 res.partner 的记录（_id 只记录id这个数字，而非对象）

Partner = self.env['res.partner']
partners = Partner.browse(ids)
partner_id = partners[0].id

• One2Many， Many2Many字段一般以ids作为后缀如：sale_order_line_ids
• Many2One 字段一般以_id为后缀如：partner_id, user_id
• 方法命名
  • 计算字段： 计算方法一般是_compute_<field_name>
  • 搜索方法： _search_<field_name>
  • 默认方法： _default_<field_name>
  • 列表值方法： _selection_<field_name>
  • onchange方法： _onchange_<field_name>
  • Constraint 约束方法： _check_<constraint_name>
  • Action动作方法： 一个对象的动作方法一般以action_开头，它的装饰器是 @api.multi,如果它只使用单条计算，可在方法头添加self.ensure_one()
• 模型中属性顺序
  1. 私有属性：(_name, _description, _inherit, …)
  2. 默认方法和 _default_get
  3. Field 字段声明
  4. Compute, inverse and search 等计算和搜索方法和字段声明顺序一致
  5. Selection 方法(返回 selection 字段的列表值)
  6. Constrains 约束方法(@api.constrains) and onchange 字段值变更方法 (@api.onchange)
  7. CRUD方法(ORM 覆盖与继承)
  8. Action方法
  9. 最后是其他业务方法

class Event(models.Model):
    # Private attributes
    _name = 'event.event'
    _description = 'Event'

    # Default methods
    def _default_name(self):
        ...

    # Fields declaration
    name = fields.Char(string='Name', default=_default_name)
    seats_reserved = fields.Integer(oldname='register_current', string='Reserved Seats',
        store=True, readonly=True, compute='_compute_seats')
    seats_available = fields.Integer(oldname='register_avail', string='Available Seats',
        store=True, readonly=True, compute='_compute_seats')
    price = fields.Integer(string='Price')
    event_type = fields.Selection(string="Type", selection='_selection_type')

    # compute and search fields, in the same order of fields declaration
    @api.multi
    @api.depends('seats_max', 'registration_ids.state', 'registration_ids.nb_register')
    def _compute_seats(self):
        ...

    @api.model
    def _selection_type(self):
        return []

    # Constraints and onchanges
    @api.constrains('seats_max', 'seats_available')
    def _check_seats_limit(self):
        ...

    @api.onchange('date_begin')
    def _onchange_date_begin(self):
        ...

    # CRUD methods (and name_get, name_search, ...) overrides
    def create(self, values):
        ...

    # Action methods
    @api.multi
    def action_validate(self):
        self.ensure_one()
        ...

    # Business methods
    def mail_user_confirm(self):
        ...

Javascript和CSS

• 除非你的javascript代码需要全局（即在所有页面）运行，否则必须在website模块中声明一个 if_dom_contains 。对 dom 元素的操作要使用 JQuery 代码

odoo.website.if_dom_contains('.jquery_class_selector', function () {
    /*your code here*/
});