bitrix-result-and-errors

結果とエラー

ベースライン：main 23.0+ · 検証済み：main 26.800.0

契約

• 想定される失敗（検証、ビジネスルール、見つからない、権限がない）→ Error を含む Result。
• 状態や契約の破綻（モジュールが見つからない、DB が停止している、設定ミス、バグ）→ 例外。
• 1 つのメソッドには 1 つの契約を設けます。常に 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()。

型付き結果

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）や「起こり得ない」ドメイン状態（金額型におけるゼロ除算）は、例外のままにします。