OrpaonVision/OrpaonVision.Core/Results/Result.cs

namespace OrpaonVision.Core.Results;

/// <summary>
/// 非泛型统一返回结果。
/// 
/// 约束：
/// - 普通业务失败使用 Result 返回，不建议抛异常；
/// - 异常场景请由上层捕获后转换为统一错误码与消息。
/// </summary>
public class Result
{
    /// <summary>
    /// 是否成功。
    /// </summary>
    public bool Succeeded { get; init; }

    /// <summary>
    /// 业务编码（成功或失败编码）。
    /// </summary>
    public string Code { get; init; } = string.Empty;

    /// <summary>
    /// 业务消息。
    /// </summary>
    public string Message { get; init; } = string.Empty;

    /// <summary>
    /// 错误明细。
    /// </summary>
    public IReadOnlyCollection<string> Errors { get; init; } = Array.Empty<string>();

    /// <summary>
    /// 跟踪 ID，用于日志链路关联。
    /// </summary>
    public string? TraceId { get; init; }

    /// <summary>
    /// 创建成功结果。
    /// </summary>
    public static Result Success(string code = "OK", string message = "Success")
    {
        return new Result
        {
            Succeeded = true,
            Code = code,
            Message = message
        };
    }

    /// <summary>
    /// 创建成功结果（携带 TraceId）。
    /// </summary>
    public static Result SuccessWithTrace(string traceId, string code = "OK", string message = "Success")
    {
        return new Result
        {
            Succeeded = true,
            Code = code,
            Message = message,
            TraceId = traceId
        };
    }

    /// <summary>
    /// 创建失败结果。
    /// </summary>
    public static Result Fail(string code, string message, params string[] errors)
    {
        return new Result
        {
            Succeeded = false,
            Code = code,
            Message = message,
            Errors = errors
        };
    }

    /// <summary>
    /// 创建失败结果（携带 TraceId）。
    /// </summary>
    public static Result FailWithTrace(string code, string message, string traceId, params string[] errors)
    {
        return new Result
        {
            Succeeded = false,
            Code = code,
            Message = message,
            Errors = errors,
            TraceId = traceId
        };
    }

    /// <summary>
    /// 由异常创建失败结果。
    /// </summary>
    public static Result FromException(Exception exception, string code = "UNHANDLED_EXCEPTION", string message = "系统出现未处理异常。", string? traceId = null)
    {
        var errors = new List<string>();
        var current = exception;

        while (current is not null)
        {
            errors.Add(current.Message);
            current = current.InnerException;
        }

        return new Result
        {
            Succeeded = false,
            Code = code,
            Message = message,
            Errors = errors,
            TraceId = traceId
        };
    }
}

/// <summary>
/// 泛型统一返回结果。
/// </summary>
public sealed class Result<T> : Result
{
    /// <summary>
    /// 业务数据。
    /// </summary>
    public T? Data { get; init; }

    /// <summary>
    /// 创建成功结果。
    /// </summary>
    public static Result<T> Success(T data, string code = "OK", string message = "Success")
    {
        return new Result<T>
        {
            Succeeded = true,
            Code = code,
            Message = message,
            Data = data
        };
    }

    /// <summary>
    /// 创建成功结果（携带 TraceId）。
    /// </summary>
    public static Result<T> SuccessWithTrace(T data, string traceId, string code = "OK", string message = "Success")
    {
        return new Result<T>
        {
            Succeeded = true,
            Code = code,
            Message = message,
            Data = data,
            TraceId = traceId
        };
    }

    /// <summary>
    /// 创建失败结果。
    /// </summary>
    public static new Result<T> Fail(string code, string message, params string[] errors)
    {
        return new Result<T>
        {
            Succeeded = false,
            Code = code,
            Message = message,
            Errors = errors
        };
    }

    /// <summary>
    /// 创建失败结果（携带 TraceId）。
    /// </summary>
    public static new Result<T> FailWithTrace(string code, string message, string traceId, params string[] errors)
    {
        return new Result<T>
        {
            Succeeded = false,
            Code = code,
            Message = message,
            Errors = errors,
            TraceId = traceId
        };
    }
}