mcpField
B
bitrix-result-and-errors

bitrix-result-and-errors

github.com/bxmaximum开发47279 次安装2 周前更新
代码仓库

关于 bitrix-result-and-errors

面向 Bitrix 开发者的结果与错误处理技能，说明何时返回 Result、何时抛出异常，并涵盖错误码、ORM 结果和控制器边界。

主要功能

  1. 01Result 与异常的使用规则
  2. 02稳定且可机器读取的错误码
  3. 03类型化结果模式
  4. 04ORM 结果处理指引
  5. 05控制器错误响应模式
  6. 06模块边界的异常处理

适用场景

  1. 01设计服务方法契约
  2. 02返回验证与业务错误
  3. 03处理失败的 ORM 操作
  4. 04将异常映射为控制器错误

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/bxmaximum/bitrix-framework-skills --skill bitrix-result-and-errors

安装后在 Claude Code 中输入/bitrix-result-and-errors确认已加载。

详细介绍

结果与错误

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

契约

  • 预期失败（验证失败、业务规则不符、未找到、无权限）→ 返回带有 Error 的 Result。
  • 状态或契约异常（模块缺失、数据库不可用、配置错误、程序错误）→ 抛出异常。
  • 一个方法，一种契约：始终返回 Result，或者返回值，并在特殊情况下抛出异常。绝不使用 bool/null/-1/['error' => …]。

Bitrix\Main\Result

use Bitrix\Main\Error;
use Bitrix\Main\Result;

$result = new Result();
if ($title === '')
{
    return $result->addError(new Error('Title required', 'BLOG_POST_TITLE_EMPTY', ['field' => 'title']));
}

return $result->setData(['id' => $id]);
  • isSuccess()、addError(Error)、addErrors(Error[])、getErrors()、getError()（第一个错误或 null）、getErrorMessages()、getErrorCollection()、setData(array)、getData()。设置方法返回 $this。
  • setData() 会静默丢弃 SqlExpression 值。

Error 和代码

new Error($message, $code = 0, $customData = null)。JSON 格式：{"message", "code", "customData"}。

  • 错误代码应稳定且可供机器读取：由模块、实体和原因组成（BLOG_POST_NOT_FOUND），并定义为常量。客户端应根据代码而非文本进行分支处理。
  • 消息通过 Loc::getMessage('BLOG_ERROR_POST_TITLE_EMPTY') 获取。
  • ErrorCollection：new ErrorCollection([$error])、setError()、add([...])、getErrorByCode('CODE')、可迭代、isEmpty()、toArray()。

类型化结果

为调用方提供 getter，而不是让他们使用 getData()['post']：

final class CreatePostResult extends \Bitrix\Main\Result
{
    private ?Post $post = null;

    public function setPost(Post $post): self
    {
        $this->post = $post;
        return $this;
    }

    public function getPost(): ?Post
    {
        return $this->post;
    }
}

ORM 结果（Bitrix\Main\ORM\Data\*）

  • AddResult：getId()、getPrimary()、getObject()。
  • UpdateResult：getId()、getPrimary()、getAffectedRowsCount()。
  • DeleteResult：没有自有方法（没有受影响行数）。
  • Bitrix\Main\Entity\*Result 是兼容性别名。请使用 ORM\Data\*。
  • 如果失败的 ORM 结果中的错误无人读取（isSuccess() / getErrors()），销毁时会触发 E_USER_WARNING。务必检查并返回该结果，或将其中的错误复制到上层。
$add = PostTable::add(['TITLE' => $title]);
if (!$add->isSuccess())
{
    return (new Result())->addErrors($add->getErrors());
}
$id = $add->getId();

其他结果类型

  • EventResult（SUCCESS、ERROR、UNDEFINED）是处理器的响应，不是服务结果：bitrix-events。
  • ValidationResult（bitrix-validation）继承自 Result：将其中的错误添加到服务结果中。

控制器

$this->addErrors($result->getErrors()); return null; 会生成 {"status":"error","data":null,"errors":[…]}。响应封装详情：bitrix-controllers。

在边界处处理异常

在模块/控制器边界处捕获异常，记录日志，并返回通用错误：

try
{
    return $this->service->run($dto);
}
catch (\Bitrix\Main\SystemException $e)
{
    $this->logger->error('Run failed', ['exception' => $e]);
    return (new Result())->addError(new Error('Internal error', 'VENDOR_INTERNAL_ERROR'));
}
  • 绝不能在不记录日志的情况下吞掉 \Throwable。
  • 开发者错误（InvalidArgumentException、LogicException、TypeError）和“不可能发生”的领域状态（例如货币类型中出现除以零）应继续作为异常处理。

评论

支持 Markdown