bitrix-framework

Bitrix Framework 规范

基准：main 23.0+ · 已验证：main 26.800.0

根据任务描述选择对应技能；本文件包含所有技能默认遵循的规则。

版本策略

• 先检查项目：bitrix/modules/main/classes/general/version.php → SM_VERSION。
• **Since main X.Y** — 功能需要此版本；每项技能都会提供回退方案。
• **Since main X.Y\*** — 确切版本未知；已确认该功能在 X.Y 中存在，在 main 25.100.500 中不存在。它可能稍早就已存在。模块版本也同理（**Since rest 26.200\***）：在 main 25.100.500 随附的模块版本中不存在。
• 内核源码：bitrix/modules/<module>/lib/。从 main 26.600 开始，许多 lib/ 目录使用 PascalCase（lib/Data），较早版本则使用小写形式——搜索时不区分大小写。

功能	自 main 版本起
路由（/local/routes）	21.400
/local/.settings.php	24.100
验证（Bitrix\Main\Validation）	24.300
控制器渲染辅助方法	25.700
新版 make:*（service、entity、event、message、agent …）	25.900
持久化存储	25.1100
控制器筛选属性、操作参数规则、LoggerFactory	26.250*
install/migrations 上的模块安装器（UpdateSystem\Migration）	26.600*
#[ActionAccess]	26.600*
功能标志 Config\Feature	26.700

强制规范

• 所有自定义代码都放在 /local/；绝不编辑 /bitrix/。/local/ 中的文件会覆盖 /bitrix/ 中相同路径的文件。
• 优先使用 D7；仅在没有 D7 API 时才使用旧版 API（CIBlock*、CUser、$DB）——并在注释中说明。
• 控制器、路由、组件和事件处理程序应保持精简；逻辑放在服务中；数据放在 ORM 表中。
• 使用任何模块类之前，先调用 Loader::includeModule() / requireModule()。
• 使用 declare(strict_types=1)、类型化签名；跨模块边界使用 Result/Error，而非异常或魔术数组。
• /local/.settings.php 会完全替换 /bitrix/.settings.php——复制所有区段，而不只是有改动的区段。
• 路由只能放在 /local/routes/*.php（模块路由通过 require 从此处引入）。绝不向 urlrewrite.php 添加新路由。
• 迁移：模块自身的表、事件和 Agent 放入其安装器（install/migrations、bitrix-modules）；项目数据和设置放入 sprint.migration。如果尚未安装该工具，应建议安装——绝不臆造迁移框架。

DI 边界

上下文	构造函数 DI	方式
应用服务	是	由 ServiceLocator::get(FQCN) 自动注入；仅当存在接口或标量参数时才在 services 中注册
控制器操作	是，参数	指定具体类的类型提示；操作参数中的接口不会被解析
控制器构造函数	否	引擎只传入 Request
控制台命令	否	在 execute() 中调用 ServiceLocator::getInstance()->get()
事件处理程序	否	在处理程序内部解析
Messenger 接收器	是	自动注入；仅当存在接口或标量参数时才注册

对于具体类，仅包含 className 的 services 条目会禁用自动注入（调用 new $class()，不传参数）。使用 constructor 闭包或 constructorParams，或者不要注册该条目。详情：bitrix-service-locator。

安全默认规则

• 绝不读取 $_GET/$_POST/$_SESSION/$_COOKIE；使用 Context 请求和 Application::getSession()。
• AJAX 操作保留默认前置过滤器（Authentication、HttpMethod、Csrf）；按操作添加权限检查。
• 转义输出（htmlspecialcharsbx、Json::encode），转换输入类型，并对白名单进行限制，确保所有进入 ORM select/order/runtime/ExpressionField 的内容均经过筛选。
• 密钥来自环境变量或 .settings.php，绝不写入代码、选项或迁移中。

完成前

• /local/ 中的代码已加载模块，并使用严格类型。
• 所有内核类、方法和命名参数均存在于项目的主版本中（检查 Since）。
• 控制器、组件和模板中没有数据库访问；错误通过 Result 返回。
• 对重复读取的数据使用带标签的缓存；通过 cleanCache() 清除 ORM 缓存。
• 安装时注册事件和 Agent，卸载时移除。
• 生产环境中的 exception_handling.debug 为 false。