bitrix-best-practice-core

Bitrix Core 最佳实践

该技能可帮助你了解应使用哪些 Bitrix/PHP 最佳实践。

使用方法

1. 确定任务涉及的架构层。
2. 仅打开与该层直接相关的规则文件。
3. 首先遵循更严格的仓库规则和模块限制。
4. 优先使用 Bitrix 原生框架模式，而不是自定义抽象。

规则文件选择

何时阅读 command.md

如果任务涉及以下任一方面，请阅读 command.md：

• Bitrix\Main\Command\CommandInterface、AbstractCommand 或应用命令的创建；
• 命令生命周期中的 run()、execute()、beforeRun() 和 afterRun()；
• CommandValidationException、CommandException 或命令结果处理；
• 命令输入数据验证或命令执行的事务边界。

何时阅读 controller.md

如果任务涉及以下任一方面，请阅读 controller.md：

• 继承 Bitrix\Main\Engine\Controller 或其子类的类；
• 任何 *Action() 方法；
• filters、attributes、prefilters 以及 Engine Controller 响应。

何时阅读 error.md

如果任务涉及以下任一方面，请阅读 error.md：

• Bitrix\Main\Error、Bitrix\Main\ErrorCollection 或基于它们构建的应用错误类；
• service、controller 或 response 流程中的 getErrors()、getError()、getErrorCollection() 或 getErrorByCode()；
• 为 UI、AJAX 或其他客户端选择 code、customData 和公开错误契约；
• 在 Result、controller 生命周期和 AjaxJson 之间传递已创建的错误。

何时阅读 result.md

如果任务涉及以下任一方面，请阅读 result.md：

• Bitrix\Main\Result、isSuccess()、setData()、getData()、addError() 或 addErrors()；
• 从 service、command、handler 或 integration layer 返回 Result，作为结果契约；
• 在 Bitrix\Main\Result、自定义 *Result 类和隐式数组之间选择，将其用作返回 DTO；
• Result::setData() 中 payload 的组成，以及 success-data 与错误流程之间的边界。

何时阅读 request.md

如果任务涉及以下任一方面，请阅读 request.md：

• Bitrix\Main\Request、HttpRequest、$this->getRequest() 或 Context::getCurrent()->getRequest()；
• 在 get()、getQuery()、getPost()、getHeader()、getCookie() 或 getJsonList() 之间选择；
• 将 $_REQUEST、$_GET、$_POST、$_COOKIE 和 php://input 替换为框架原生 request API；
• JSON body、JsonPayload、decodeJson() 或 decodeJsonStrict()。

何时阅读 response.md

如果任务涉及以下任一方面，请阅读 response.md：

• Bitrix\Main\Response、HttpResponse、addHeader()、setStatus()、addCookie() 或 redirectTo()；
• Bitrix\Main\Engine\Response\Json、AjaxJson、Redirect、File、HtmlContent 或 render-response 辅助函数；
• 将手动调用的 header()、Set-Cookie、setcookie() 或 json_encode() 替换为 Bitrix 内置的 response layer；
• 为 controller action 或其他 infrastructure endpoint 选择 HTTP 响应类型。

何时阅读 routing.md

如果任务涉及以下任一方面，请阅读 routing.md：

• <module>/install/routes/ 中的文件，或在 /bitrix/routes/ 和 /local/routes/ 中注册路由；
• RoutingConfigurator、prefix、group、路由 HTTP 方法、where、default、name；
• PublicPageController，或将 legacy URL 从 urlrewrite.php 迁移到现代路由；
• site-guard，以及多站点安装中针对特定站点的路由；
• 路由中的数组 [Controller::class, 'action']。

何时阅读 loader.md

如果任务涉及以下任一方面，请阅读 loader.md：

• Loader::includeModule() 或 Loader::requireModule()；
• CModule::IncludeModule() 或 CModule::IncludeModuleEx()；
• 模块缺失时带有回退处理的可选模块集成；
• fail-fast 依赖：模块缺失时应报错，而不是静默跳过。

何时阅读 geo-ip.md

如果任务涉及以下任一方面，请阅读 geo-ip.md：

• Bitrix\Main\Service\GeoIp\Manager、getRealIp()、getDataResult() 或 getCountryCode() / getCityName() 等便捷 getter；
• 在 GeoIP 查询、范围缓存或地理数据的 IPv4 与 IPv6 差异相关场景中使用 Bitrix\Main\Web\IpAddress；
• 自定义 GeoIP handler、Bitrix\Main\Service\GeoIp\Base 的子类，或通过 onMainGeoIpHandlersBuildList 注册；
• 通过 onGeoIpGetResult 对 GeoIP 结果进行后处理；
• 在简单的字符串查询与完整的基于 Result 的 GeoIP 查询之间进行选择；
• 根据 IP 地址确定地理位置。

何时阅读 uri.md

如果任务涉及以下任一方面，请阅读 uri.md：

• Bitrix\Main\Web\Uri、new Uri($url)、getQuery()、addParams()、deleteParams()、toAbsolute() 或 resolveRelativeUri()；
• 在 Bitrix 代码中解析、修改或重新构建 URL / URI / 重定向 URL；
• 针对 query string、host、path、fragment 或 absolute URL，在 Uri、parse_url() 和 parse_str() 之间进行选择；
• 涉及点号或空格的 query 参数，且 preserveDots 会影响处理结果。

何时阅读 http-client.md

如果任务涉及以下任一方面，请阅读 http-client.md：

• Bitrix\Main\Web\HttpClient、new HttpClient()、get()、post()、query() 或 download()；
• 出站 HTTP(S) 请求、webhook 发送器、远程下载 / 上传或外部 API 集成；
• 替换用于远程 http / https URL 的 file_get_contents($url) / stream_context_create()；
• 将 curl_init、curl_setopt、curl_exec 和其他原始 curl_* 调用替换为框架原生传输方式。

何时阅读 json.md

如果任务涉及以下任一方面，请阅读 json.md：

• Bitrix\\Main\\Web\\Json、Json::encode()、Json::decode() 或 Json::validate()；
• 替换直接调用的 json_encode() / json_decode() 或本地 JSON 编解码辅助函数；
• Json::DEFAULT_OPTIONS、编码标志、编码 / 解码时的 ArgumentException，或对解码后结构的验证；
• HTML 属性中的 JSON 字符串，或在序列化字符串与现成的 JSON 响应之间进行选择。

何时阅读 jwt.md

如果任务涉及以下任一方面，请阅读 jwt.md：

• Bitrix\Main\Web\JWT、JWT::encode()、JWT::decode()、JWT::urlsafeB64Encode() 或 JWT::urlsafeB64Decode()；
• Bitrix\Main\Web\JWK、JWK::parseKeySet() 或 JWK::parseKey()；
• 签发、验证或解析 JWT / JWK / JWKS / JOSE 兼容数据；
• 在框架原生 JWT/JWK API 与手动构建令牌、解析密钥或使用 Base64 URL-safe 辅助函数之间进行选择。

何时阅读 date-time.md

如果任务涉及以下任一方面，请阅读 date-time.md：

• Bitrix\Main\Type\Date 或 Bitrix\Main\Type\DateTime；
• createFromUserTime()、tryParse()、toUserTime()、toString()、createFromTimestamp() 或 createFromPhp()；
• 在 Bitrix 代码中解析、格式化日期和时间，或进行时间戳转换；
• 在 Bitrix 日期类型与 \DateTime / \DateTimeImmutable 之间进行选择。

何时阅读 option.md

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

• Bitrix\Main\Config\Option、Option::get()、set()、getRealValue()、getForModule() 或 delete()；
• COption::GetOptionString()、SetOptionString()、GetOptionInt() 或 RemoveOption() 作为 legacy 触发器；
• default_option.php、模块的 options.php、站点专属设置，或数据库中的 feature flag / policy；
• 在 Option 中保存持久配置、在 .settings.php 中保存部署时配置，以及保存临时 runtime-state 之间的选择。

何时阅读 logger.md

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

• Bitrix\Main\Diag\Logger、Bitrix\Main\Diag\LoggerFactory、LoggerRegistry、FileLogger 或 LogFormatter；
• Psr\Log\LoggerInterface、PSR-3 级别（info、warning、error、debug）以及结构化 context；
• 通过 .settings.php 中的 loggers 区段注册 logger id，或通过 constructorParams 使用 DI；
• 将 AddMessage2Log()、Logger::create() 或临时使用的 file_put_contents() / error_log() 替换为框架原生的日志记录方式；
• 在具名 logger id、default logger 回退机制和 legacy 日志边界之间进行选择。

何时阅读 uuid-generator.md

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

• Bitrix\Main\UuidGenerator 或 UuidGenerator::generateV4()；
• 为 session id、correlation id、upload token、public proxy id 或其他随机不透明标识符生成 UUID v4；
• 在 UuidGenerator、uniqid()、Random::getBytes()、手动组装 UUID 或本地辅助生成器之间进行选择；
• 需要在 {uuid} 之类的封装中提供 UUID 的 legacy 边界，同时保留统一的规范生成器。

何时阅读 validation.md

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

• *Action() 参数或输入对象属性上的 Bitrix\Main\Validation\Rule\...；
• ValidationParameter、ValidationService、ValidationResult、ValidationError 或 ValidationGroup；
• 在进入 action 前自动验证输入，或在 service layer 中手动验证 DTO / command；
• 在 validation attributes、ValidationParameter 和显式调用 ValidationService::validate() 之间进行选择；
• 基于 Bitrix\Main\Validation 实现自定义 validator 和自定义 validation attributes。

何时阅读 service-locator.md

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

• Bitrix\Main\DI\ServiceLocator、ServiceLocator::getInstance()、get()、has()、addInstance() 或 addInstanceLazy()；
• {module}/.settings.php、service 注册、service id、FQCN 绑定或用于 DI 的 interface 绑定；
• 在 action 自动装配、显式调用 ServiceLocator::get(...) 和通过 new MyService() 手动创建共享 service 之间进行选择；
• 将临时创建 service 类的方式替换为框架原生容器方式。

何时阅读 persistent-storage.md

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

• Bitrix\Main\Data\Storage\PersistentStorageInterface、StorageInterface、DeferredStorageDecorator 或 ServiceLocator::get(PersistentStorageInterface::class)；
• 在需要判断数据属于配置还是临时 runtime-state 的场景中使用 Bitrix\Main\Config\Option::get() / Option::set()；
• 请求之间的 TTL state、进度 / 检查点、一次性 token、上传 / 导入 session、速率限制计数器或其他临时 server-side state；
• 在使用 Option、persistent storage 和 cache（Bitrix\Main\Data\Cache / ManagedCache）存储数据之间进行选择。

Когда читать cache.md

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

• Bitrix\Main\Data\Cache, ManagedCache, TaggedCache, Cache::createInstance(), initCache(), startDataCache(), endDataCache() или abortDataCache();
• Application::getInstance()->getCache(), getManagedCache(), getTaggedCache() или container binding cache-сервисов в main/.settings.php;
• выбор между простым TTL-cache, managed invalidation по key/dir и tag-based invalidation;
• CPHPCache, CCacheManager, $CACHE_MANAGER или CStackCacheManager как legacy trigger;
• derived read-cache, который можно потерять и пересчитать, в отличие от runtime-state и постоянной конфигурации.

Когда читать event.md

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

• Bitrix\Main\Event, EventResult, EventManager, send() или getResults();
• генерацию классов событий и обработчиков через Bitrix CLI;
• создание собственного события, контракт параметров и ответов обработчиков или отмену операции по результатам события;
• addEventHandler(), registerEventHandler(), compatible-варианты, порядок вызова и снятие подписок;
• AddEventHandler() или RegisterModuleDependences() как legacy trigger и перенос позиционных обработчиков на D7.