odoo-best-practices

Odoo 最佳实践

在构建、扩展或审查面向 18-20 版本的 Odoo 模块时，请遵循这些实践。除非用户指定较旧版本，否则本指南默认采用 Odoo 20.0 的约定。

设计理念

这些规则旨在维护 Odoo 的核心设计理念：

1. 一切皆为模块 — 即使 Enterprise 功能也只是叠加在 Community 之上的模块。
2. 数据就是程序 — 视图、操作、菜单和安全规则都是数据库记录；XML 数据文件负责安装它们。
3. 扩展，绝不修改 — 使用模型 _inherit、xpath 视图继承和 QWeb 继承；保持核心代码原样，才能顺利升级。
4. XML ID 是连接纽带 — module.xml_id 是全局命名空间；depends 的作用类似系统包管理器。
5. 约定优于配置 — 名称会自动映射到表、列和 UI；请遵循命名约定。
6. ORM 是 API，也是安全边界 — 公共方法会通过 RPC 暴露；原始 SQL 会绕过安全机制。
7. 设计上集成一体 — 使用一个数据库和共享的基础模型；OWL 是表现层的发展方向。

如有疑问，请选择能保障未来升级安全且遵循 ORM 的方案。

核心规则

• 绝不修改核心模块。始终在自定义模块中通过 _inherit 扩展。
• 每个新模型都必须定义 _description，并在 ir.model.access.csv 中配置访问规则。
• 使用 api.onchange 进行仅限 UI 的验证，使用 api.constrains 确保数据库级不变量。
• 自定义模块名称应以供应商或项目命名空间为前缀（例如 mycompany_feature），以避免冲突。
• 在 __manifest__.py 中设置与 Odoo 系列版本一致的 version（例如 20.0.1.0.0）。
• 使用 _() 标记面向用户的字符串，以支持翻译。
• 尽可能使用记录集方法（mapped、filtered、sorted）代替 Python 循环，以利用 ORM 预取。
• 尽量少用 sudo()；始终说明为何需要提升权限。
• 绝不拼接来自用户输入的域；使用 Domain 对象（domain &= Domain(...)）以防止注入。
• 在 Odoo 20+ 中使用 models.Constraint / models.Index，而不是旧式 _sql_constraints。

路由

当任务涉及某个领域时，请阅读相关参考文档。默认不要加载所有参考文档。

• **模块设置、清单、迁移：**阅读 references/module-architecture.md。
• **外部 JSON-2 API 集成、API 密钥、RPC 事务：**阅读 references/external-api.md。
• **模型定义、计算字段、约束、记录集：**阅读 references/orm-patterns.md。
• **XML 视图、视图继承、OWL 组件、前端资源：**阅读 references/views-owl.md。
• **Web 客户端架构、上下文、py_js、JS Domain 类：**阅读 references/frontend-architecture.md。
• **访问规则、记录规则、多公司、翻译：**阅读 references/security-i18n.md。
• **测试框架、性能实践、查询优化：**阅读 references/testing-performance.md。
• **开发环境设置、源码安装、odoo-bin、配置、脚手架、运行服务：**阅读 references/dev-environment.md。
• **官方文档索引（教程、参考文档、操作指南、安装、指南）：**阅读 references/official-docs.md。