bitrix-best-practice-sql

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bitrix Best Practice SQL

Bitrix SQL最佳实践

Скилл помогает понять, какие нужно использовать SQL/DB best practices. Используй его только для задач, где есть работа с базой данных: схема, SQL-запросы, ORM-модели, выборки, запись, миграции данных, индексы, транзакции или другие DB-boundary решения.

本Skill可帮助你了解应采用哪些SQL/DB最佳实践。仅在涉及数据库操作的任务中使用它：schema、SQL查询、ORM模型、数据查询、写入、数据迁移、索引、事务或其他数据库边界相关方案。

Как использовать

使用方法

Определи, действительно ли задача затрагивает SQL, ORM или хранение данных.
Выдели конкретную DB-область задачи: чтение, запись, схема, миграция, производительность, консистентность или безопасность запроса.
Открой только те rule-файлы, которые напрямую относятся к этой DB-области.
Сначала следуй более строгим правилам репозитория и ограничениям модуля.
Предпочитай framework-native и Bitrix-native паттерны работы с данными вместо самодельных SQL- и storage-абстракций.

确认任务是否确实涉及SQL、ORM或数据存储。
明确任务涉及的具体数据库领域：读取、写入、schema、迁移、性能、一致性或查询安全性。
仅打开与该数据库领域直接相关的规则文件。
优先遵循仓库的严格规则和模块限制。
优先使用框架原生和Bitrix原生的数据处理模式，而非自行构建的SQL和存储抽象。

Выбор rule-файла

规则文件选择

Когда читать

rules/query-execution.md

何时阅读

rules/query-execution.md

Читай

rules/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
```
, placeholders
```
?s
```
,
```
?i
```
,
```
?f
```
,
```
?#
```
,
```
?@
```
или ручную сборку SQL из частей;

SqlHelper::quote()

forSql()

prepareInsert()

prepareUpdate()

convertToDb*()

или

getTopSql()

;

замену legacy
```
$DB
```
/
```
CDatabase
```
на D7 DB API;
выбор между raw SQL через
```
Connection
```
и более высокоуровневым framework-native DB path.

如果任务涉及以下任一领域，请阅读

rules/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与使用更高级的框架原生数据库方案之间做选择。

Когда читать

rules/orm-datamanager-map.md

何时阅读

rules/orm-datamanager-map.md

Читай

rules/orm-datamanager-map.md

, если задача затрагивает хотя бы одну из этих областей:

класс

*Table extends Bitrix\Main\ORM\Data\DataManager

;

getTableName()

getConnectionName()

getMap()

getUfId()

postInitialize()

или

setDefaultScope()

;

описание полей через
```
Bitrix\Main\ORM\Fields\Field
```
и наследников вместо legacy array map;
```
Reference
```
,
```
OneToMany
```
,
```
ManyToMany
```
,
```
configureJoinType()
```
,
```
configureCascade*Policy()
```
именно на уровне декларации сущности;
primary key, autocomplete, validators, save/fetch modifiers, title и default values в entity map;
выбор между typed field objects и старым массивом в
```
getMap()
```
.

如果任务涉及以下任一领域，请阅读

rules/orm-datamanager-map.md

：

继承自
```
Bitrix\Main\ORM\Data\DataManager
```
的
```
*Table
```
类;

getTableName()

getConnectionName()

getMap()

getUfId()

postInitialize()

或

setDefaultScope()

;

通过
```
Bitrix\Main\ORM\Fields\Field
```
及其子类描述字段，而非旧版数组映射;

在实体声明层面使用

Reference

OneToMany

ManyToMany

configureJoinType()

configureCascade*Policy()

;

实体映射中的主键、自动补全、验证器、保存/获取修饰符、标题和默认值;
在类型化字段对象与
```
getMap()
```
中的旧版数组之间做选择。

Когда читать

rules/orm-objectify.md

何时阅读

rules/orm-objectify.md

Читай

rules/orm-objectify.md

, если задача затрагивает хотя бы одну из этих областей:

Bitrix\Main\ORM\Objectify\EntityObject

Collection

createObject()

createCollection()

wakeUpObject()

или

wakeUpCollection()

;

get()

require()

remindActual()

fill()

isFilled()

isChanged()

collectValues()

;

работу с relation graph через
```
addTo()
```
,
```
removeFrom()
```
,
```
removeAll()
```
или collection lifecycle;

Collection::walk()

filter()

find()

merge()

hasByPrimary()

или

getByPrimary()

;

выбор между Objectify-объектами и массивами результата;
object state (
```
RAW
```
,
```
ACTUAL
```
,
```
CHANGED
```
,
```
DELETED
```
) и in-memory поведение ORM.

如果任务涉及以下任一领域，请阅读

rules/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的内存内行为。

Когда читать

rules/orm-query-filter.md

何时阅读

rules/orm-query-filter.md

Читай

rules/orm-query-filter.md

, если задача затрагивает хотя бы одну из этих областей:

DataManager::query()

getList()

getRow()

getByPrimary()

или

getCount()

;

Bitrix\Main\ORM\Query\Query

Query::filter()

ConditionTree

where*

having*

logic()

или nested filters;

```
fetchObject()
```
,
```
fetchCollection()
```
,
```
fetch()
```
,
```
fetchAll()
```
и выбор между object fetch и массивами;

runtime fields,

registerRuntimeField()

Query::expr()

ExpressionField

в query-path;

```
buildFilterSql()
```
,
```
disableDataDoubling()
```
, private fields, aggregation/object-fetch restrictions;
выбор между modern query builder и legacy filter array.

如果任务涉及以下任一领域，请阅读

rules/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()
```
, 私有字段、聚合/对象获取限制;
在现代查询构建器与旧版过滤器数组之间做选择。

Когда читать

rules/orm-persistence-write.md

何时阅读

rules/orm-persistence-write.md

Читай

rules/orm-persistence-write.md

, если задача затрагивает хотя бы одну из этих областей:

DataManager::add()

update()

delete()

addMulti()

updateMulti()

или object/collection

save()

;

DeleteByFilterTrait::deleteByFilter()

MergeTrait::merge()

или low-level ORM write helpers;

Bitrix\Main\ORM\Data\AddStrategy

InsertIgnore

Merge

MergeByDefaultTrait

InsertIgnoreByDefaultTrait

AddMergeTrait

или

AddInsertIgnoreTrait

;

выбор между обычной ORM-записью, batch-операцией, merge/upsert и delete-by-filter;
события ORM при записи,
```
ignoreEvents
```
, cache cleanup и caveats batch persistence;
массовая запись или обновление нескольких строк через ORM lifecycle.

如果任务涉及以下任一领域，请阅读

rules/orm-persistence-write.md

：

DataManager::add()

update()

delete()

addMulti()

updateMulti()

或对象/集合的

save()

;

DeleteByFilterTrait::deleteByFilter()

MergeTrait::merge()

或底层ORM写入助手;

Bitrix\Main\ORM\Data\AddStrategy

InsertIgnore

Merge

MergeByDefaultTrait

InsertIgnoreByDefaultTrait

AddMergeTrait

或

AddInsertIgnoreTrait

;

在常规ORM写入、批量操作、merge/upsert和按过滤器删除之间做选择;
写入时的ORM事件、
```
ignoreEvents
```
、缓存清理和批量持久化注意事项;
通过ORM生命周期批量写入或更新多行数据。

bitrix-best-practice-sql

Original

Translation

Bitrix Best Practice SQL

Bitrix SQL最佳实践

Как использовать

使用方法

Выбор rule-файла

规则文件选择

Когда читать
`rules/query-execution.md`

何时阅读
`rules/query-execution.md`

Когда читать
`rules/orm-datamanager-map.md`

何时阅读
`rules/orm-datamanager-map.md`

Когда читать
`rules/orm-objectify.md`

何时阅读
`rules/orm-objectify.md`

Когда читать
`rules/orm-query-filter.md`

何时阅读
`rules/orm-query-filter.md`

Когда читать
`rules/orm-persistence-write.md`

何时阅读
`rules/orm-persistence-write.md`