bitrix-best-practice-sql

Bitrix 最佳实践 SQL

此技能可帮助你了解应该采用哪些 SQL/数据库最佳实践。 仅在任务涉及数据库工作时使用：架构、SQL 查询、ORM 模型、查询数据、写入、数据迁移、索引、事务或其他数据库边界决策。

如何使用

1. 判断任务是否确实涉及 SQL、ORM 或数据存储。
2. 确定任务涉及的具体数据库领域：读取、写入、架构、迁移、性能、一致性或查询安全性。
3. 只打开与该数据库领域直接相关的规则文件。
4. 优先遵循更严格的仓库规则和模块限制。
5. 优先采用框架原生和 Bitrix 原生的数据处理模式，而不是自制的 SQL 和存储抽象。

选择规则文件

何时阅读 query-execution.md

如果任务涉及以下任一领域，请阅读 query-execution.md：

• Bitrix\Main\Application::getConnection()、Bitrix\Main\DB\Connection 或 getSqlHelper()；
• query()、queryScalar()、queryExecute()、add()、addMulti() 或 Bitrix\Main\DB\Result；
• Bitrix\Main\DB\SqlExpression、占位符 ?s、?i、?f、?#、?@，或从多个部分手动拼接 SQL；
• SqlHelper::quote()、forSql()、prepareInsert()、prepareUpdate()、convertToDb*() 或 getTopSql()；
• 将旧版 $DB / CDatabase 替换为 D7 DB API；
• 在通过 Connection 执行原始 SQL 和使用更高层的框架原生数据库路径之间进行选择。

何时阅读 orm-datamanager-map.md

如果任务涉及以下任一领域，请阅读 orm-datamanager-map.md：

• *Table extends Bitrix\Main\ORM\Data\DataManager 类；
• getTableName()、getConnectionName()、getMap()、getUfId()、postInitialize() 或 setDefaultScope()；
• 使用 Bitrix\Main\ORM\Fields\Field 及其子类描述字段，而非使用旧版数组映射；
• 仅限实体声明层面的 Reference、OneToMany、ManyToMany、configureJoinType()、configureCascade*Policy()；
• 实体映射中的主键、自动补全、验证器、保存／获取修饰器、标题和默认值；
• 在类型化字段对象和 getMap() 中的旧版数组之间进行选择。

何时阅读 orm-objectify.md

如果任务涉及以下任一领域，请阅读 orm-objectify.md：

• Bitrix\Main\ORM\Objectify\EntityObject、Collection、createObject()、createCollection()、wakeUpObject() 或 wakeUpCollection()；
• get()、require()、remindActual()、fill()、isFilled()、isChanged()、collectValues()；
• 通过 addTo()、removeFrom()、removeAll() 或集合生命周期处理关联图；
• Collection::walk()、filter()、find()、merge()、hasByPrimary() 或 getByPrimary()；
• 在 Objectify 对象和数组结果之间进行选择；
• 对象状态（RAW、ACTUAL、CHANGED、DELETED）和 ORM 的内存行为。

何时阅读 orm-query-filter.md

如果任务涉及以下任一领域，请阅读 orm-query-filter.md：

• DataManager::query()、getList()、getRow()、getByPrimary() 或 getCount()；
• Bitrix\Main\ORM\Query\Query、Query::filter()、ConditionTree、where*、having*、logic() 或嵌套筛选条件；
• fetchObject()、fetchCollection()、fetch()、fetchAll()，以及在对象获取和数组之间进行选择；
• 运行时字段、registerRuntimeField()、Query::expr()、查询路径中的 ExpressionField；
• buildFilterSql()、disableDataDoubling()、私有字段、聚合／对象获取限制；
• 在现代查询构建器和旧版筛选数组之间进行选择。

何时阅读 orm-persistence-write.md

如果任务涉及以下任一领域，请阅读 orm-persistence-write.md：

• DataManager::add()、update()、delete()、addMulti()、updateMulti() 或 object/collection save()；
• DeleteByFilterTrait::deleteByFilter()、MergeTrait::merge() 或底层 ORM 写入辅助方法；
• Bitrix\Main\ORM\Data\AddStrategy、InsertIgnore、Merge、MergeByDefaultTrait、InsertIgnoreByDefaultTrait、AddMergeTrait 或 AddInsertIgnoreTrait；
• 在常规 ORM 写入、批量操作、merge/upsert 和 delete-by-filter 之间进行选择；
• 写入时的 ORM 事件、ignoreEvents、缓存清理以及批量持久化的注意事项；
• 通过 ORM 生命周期批量写入或更新多行。

何时阅读 transactions.md

如果任务涉及以下任一领域，请阅读 transactions.md：

• Connection::startTransaction()、commitTransaction() 或 rollbackTransaction()；
• 嵌套事务、savepoint、层级平衡或 TransactionException；
• 在同一连接中提交或回滚多个 SQL/ORM 操作；
• MySQL、PostgreSQL、MSSQL 和 Oracle 的事务 API 差异。