hw-web/Admin.NET-v2/Admin.NET/Plugins/Admin.NET.Plugin.HwPortal/Common/HwPortalAjaxResult.cs

// ============================================================================
// 【文件说明】HwPortalAjaxResult.cs - Ajax 统一响应结果类
// ============================================================================
// 这个类用于统一所有 API 接口的返回格式。
// 在 Java 若依（RuoYi）框架中，有一个 AjaxResult 类做同样的事情。
// 
// 统一返回格式的好处：
// 1. 前端可以用同一套逻辑处理所有接口响应
// 2. 便于统一添加日志、监控、错误处理
// 3. 接口文档更清晰，返回结构可预测
// 
// 返回的 JSON 结构示例：
// 成功：{ "code": 200, "msg": "操作成功", "data": { ... } }
// 失败：{ "code": 500, "msg": "操作失败", "data": null }
// 警告：{ "code": 301, "msg": "警告信息", "data": null }
// ============================================================================

namespace Admin.NET.Plugin.HwPortal;

/// <summary>
/// Ajax 统一响应结果类。
/// <para>
/// 【设计模式 - 静态工厂方法模式】
/// 这个类大量使用了"静态工厂方法"设计模式：
/// - Success() 返回成功结果
/// - Error() 返回失败结果
/// - Warn() 返回警告结果
/// 
/// 对比 Java：
/// Java 中你可能会写：
///   AjaxResult result = new AjaxResult();
///   result.put("code", 200);
///   result.put("msg", "操作成功");
/// 
/// C# 这里用静态工厂方法更优雅：
///   return HwPortalAjaxResult.Success("操作成功", data);
/// 
/// 好处：
/// 1. 代码更简洁，一行搞定
/// 2. 避免忘记设置 code/msg
/// 3. 可以在工厂方法里统一加日志、校验等逻辑
/// </para>
/// </summary>
public class HwPortalAjaxResult
{
    /// <summary>
    /// 返回码字段名。
    /// <para>
    /// 【C# 语法知识点 - const 常量】
    /// const 是"编译期常量"，值在编译时就确定了，不能修改。
    /// 
    /// 对比 Java：
    /// Java 写法：public static final String CODE_TAG = "code";
    /// C#  写法：public const string CodeTag = "code";
    /// 
    /// const 和 readonly 的区别：
    /// - const：编译期确定，值直接嵌入调用处（类似宏替换）
    /// - readonly：运行时确定，可以在构造函数中赋值
    /// 
    /// 这里用 const 是因为字段名永远不会变，编译期确定更高效。
    /// </para>
    /// 与原 Java AjaxResult 的 CODE_TAG 对齐。
    /// </summary>
    public const string CodeTag = "code";

    /// <summary>
    /// 返回消息字段名。
    /// 与原 Java AjaxResult 的 MSG_TAG 对齐。
    /// </summary>
    public const string MsgTag = "msg";

    /// <summary>
    /// 返回数据字段名。
    /// 与原 Java AjaxResult 的 DATA_TAG 对齐。
    /// </summary>
    public const string DataTag = "data";

    /// <summary>
    /// 成功状态码。
    /// HTTP 200 OK 的含义是"请求成功"，这里借用这个惯例。
    /// </summary>
    public const int SuccessCode = 200;

    /// <summary>
    /// 警告状态码。
    /// RuoYi 默认使用 301 作为 warn（HTTP 301 是重定向，但这里只是借用数字）。
    /// 警告通常表示"操作部分成功"或"需要用户注意但不阻断"的情况。
    /// </summary>
    public const int WarnCode = 301;

    /// <summary>
    /// 错误状态码。
    /// HTTP 500 Internal Server Error 的含义是"服务器内部错误"。
    /// 这里用于表示"操作失败"的业务错误。
    /// </summary>
    public const int ErrorCode = 500;

    /// <summary>
    /// 状态码。
    /// <para>
    /// 【C# 语法知识点 - 自动属性】
    /// public int Code { get; set; }
    /// 这是 C# 的"自动属性"语法，编译器自动生成后备字段和 get/set 方法。
    /// 
    /// 对比 Java：
    /// Java 需要手写 getter/setter：
    ///   private int code;
    ///   public int getCode() { return code; }
    ///   public void setCode(int code) { this.code = code; }
    /// </para>
    /// </summary>
    public int Code { get; set; }

    /// <summary>
    /// 返回消息。
    /// </summary>
    public string Msg { get; set; }

    /// <summary>
    /// 返回数据。
    /// <para>
    /// 【C# 语法知识点 - object 类型】
    /// object 是 C# 的"根类型"，所有类型都继承自 object。
    /// 类似 Java 的 Object，但 C# 的 object 可以是值类型（int, bool 等）。
    /// 
    /// 为什么用 object？
    /// 因为 Data 可以是任何类型：
    /// - 单个对象：{ "id": 1, "name": "张三" }
    /// - 列表：[{ "id": 1 }, { "id": 2 }]
    /// - 字符串："操作成功"
    /// - null：没有数据
    /// 
    /// 使用 object 可以容纳所有可能的数据类型。
    /// </para>
    /// </summary>
    public object Data { get; set; }

    /// <summary>
    /// 无参构造函数。
    /// <para>
    /// 【C# 语法知识点 - 构造函数】
    /// 构造函数名称必须与类名相同，没有返回类型。
    /// 
    /// 对比 Java：
    /// Java 和 C# 的构造函数语法几乎一致。
    /// 
    /// 为什么需要无参构造函数？
    /// 某些序列化框架（如 JSON 反序列化）需要无参构造函数来创建对象，
    /// 然后再通过属性赋值。
    /// </para>
    /// </summary>
    public HwPortalAjaxResult()
    {
    }

    /// <summary>
    /// 带参数的构造函数。
    /// <para>
    /// 【C# 语法知识点 - 可选参数 data = null】
    /// object data = null 中的 = null 是"默认参数值"。
    /// 调用时可以不传这个参数，自动使用默认值 null。
    /// 
    /// 对比 Java：
    /// Java 不支持可选参数，需要写多个重载构造函数：
    ///   public HwPortalAjaxResult(int code, String msg) { this(code, msg, null); }
    ///   public HwPortalAjaxResult(int code, String msg, Object data) { ... }
    /// 
    /// C# 一个构造函数就搞定了，更简洁。
    /// </para>
    /// </summary>
    /// <param name="code">状态码</param>
    /// <param name="msg">返回消息</param>
    /// <param name="data">返回数据，默认为 null</param>
    public HwPortalAjaxResult(int code, string msg, object data = null)
    {
        Code = code;
        Msg = msg;
        Data = data;
    }

    /// <summary>
    /// 返回成功结果（默认消息）。
    /// <para>
    /// 【C# 语法知识点 - 静态工厂方法】
    /// public static HwPortalAjaxResult Success()
    /// 这是一个静态方法，返回类本身的实例。
    /// 
    /// 为什么用静态工厂方法而不是直接 new？
    /// 1. 命名更清晰：Success() 比 new AjaxResult(200, "操作成功") 更易读
    /// 2. 可以缓存常用实例（这里没做，但可以扩展）
    /// 3. 可以返回子类（这里没用到，但这是工厂模式的优势）
    /// 
    /// 对比 Java：
    /// Java 的静态工厂方法写法一样：
    ///   public static AjaxResult success() { return new AjaxResult(200, "操作成功"); }
    /// </para>
    /// </summary>
    /// <returns>成功结果实例</returns>
    public static HwPortalAjaxResult Success()
    {
        // 方法重载链：调用带消息参数的版本
        return Success("操作成功");
    }

    /// <summary>
    /// 返回成功结果（带数据）。
    /// </summary>
    /// <param name="data">返回数据</param>
    /// <returns>成功结果实例</returns>
    public static HwPortalAjaxResult Success(object data)
    {
        return Success("操作成功", data);
    }

    /// <summary>
    /// 返回成功结果（带自定义消息）。
    /// </summary>
    /// <param name="msg">返回消息</param>
    /// <returns>成功结果实例</returns>
    public static HwPortalAjaxResult Success(string msg)
    {
        return Success(msg, null);
    }

    /// <summary>
    /// 返回成功结果（完整参数）。
    /// <para>
    /// 【C# 语法知识点 - 对象初始化器】
    /// new HwPortalAjaxResult { Code = ..., Msg = ..., Data = ... }
    /// 这是"对象初始化器"语法，可以在创建对象时直接给属性赋值。
    /// 
    /// 对比 Java：
    /// Java 需要这样写：
    ///   HwPortalAjaxResult result = new HwPortalAjaxResult();
    ///   result.setCode(SuccessCode);
    ///   result.setMsg(msg);
    ///   result.setData(data);
    ///   return result;
    /// 
    /// C# 一行搞定，更简洁。
    /// </para>
    /// </summary>
    /// <param name="msg">返回消息</param>
    /// <param name="data">返回数据</param>
    /// <returns>成功结果实例</returns>
    public static HwPortalAjaxResult Success(string msg, object data)
    {
        return new HwPortalAjaxResult
        {
            Code = SuccessCode,
            Msg = msg,
            Data = data
        };
    }

    /// <summary>
    /// 返回警告结果（仅消息）。
    /// </summary>
    /// <param name="msg">警告消息</param>
    /// <returns>警告结果实例</returns>
    public static HwPortalAjaxResult Warn(string msg)
    {
        return Warn(msg, null);
    }

    /// <summary>
    /// 返回警告结果（带数据）。
    /// </summary>
    /// <param name="msg">警告消息</param>
    /// <param name="data">返回数据</param>
    /// <returns>警告结果实例</returns>
    public static HwPortalAjaxResult Warn(string msg, object data)
    {
        return new HwPortalAjaxResult
        {
            Code = WarnCode,
            Msg = msg,
            Data = data
        };
    }

    /// <summary>
    /// 返回错误结果（默认消息）。
    /// </summary>
    /// <returns>错误结果实例</returns>
    public static HwPortalAjaxResult Error()
    {
        return Error("操作失败");
    }

    /// <summary>
    /// 返回错误结果（自定义消息）。
    /// </summary>
    /// <param name="msg">错误消息</param>
    /// <returns>错误结果实例</returns>
    public static HwPortalAjaxResult Error(string msg)
    {
        return Error(msg, null);
    }

    /// <summary>
    /// 返回错误结果（带数据）。
    /// </summary>
    /// <param name="msg">错误消息</param>
    /// <param name="data">返回数据</param>
    /// <returns>错误结果实例</returns>
    public static HwPortalAjaxResult Error(string msg, object data)
    {
        return new HwPortalAjaxResult
        {
            Code = ErrorCode,
            Msg = msg,
            Data = data
        };
    }

    /// <summary>
    /// 返回错误结果（自定义状态码）。
    /// </summary>
    /// <param name="code">自定义状态码</param>
    /// <param name="msg">错误消息</param>
    /// <returns>错误结果实例</returns>
    public static HwPortalAjaxResult Error(int code, string msg)
    {
        return new HwPortalAjaxResult
        {
            Code = code,
            Msg = msg,
            Data = null
        };
    }

    /// <summary>
    /// 根据影响行数返回成功或失败结果。
    /// <para>
    /// 【业务场景】
    /// 在数据库操作中，增删改会返回"影响行数"：
    /// - rows > 0：表示操作成功，有数据被修改
    /// - rows = 0：表示操作失败，没有数据被修改
    /// 
    /// 这个方法把"影响行数"转换为"响应结果"，简化控制器代码：
    /// return ToAjax(await service.Insert(input));
    /// 
    /// 对比 Java 若依：
    /// 若依的 BaseController.toAjax(int rows) 做同样的事情。
    /// </para>
    /// </summary>
    /// <param name="rows">数据库影响行数</param>
    /// <returns>成功或失败结果</returns>
    public static HwPortalAjaxResult FromRows(int rows)
    {
        // 【三元运算符】
        // condition ? valueIfTrue : valueIfFalse
        // 和 Java 完全一样的语法。
        // 
        // Why：RuoYi 的 BaseController.toAjax(int rows) 只根据影响行数返回成功/失败，
        // 不会把 rows 本身塞进 data；这里必须保持同一口径，否则前端判断会漂移。
        return rows > 0 ? Success() : Error();
    }

    /// <summary>
    /// 判断是否成功。
    /// </summary>
    /// <returns>是否成功</returns>
    public bool IsSuccess()
    {
        return Code == SuccessCode;
    }

    /// <summary>
    /// 判断是否警告。
    /// </summary>
    /// <returns>是否警告</returns>
    public bool IsWarn()
    {
        return Code == WarnCode;
    }

    /// <summary>
    /// 判断是否错误。
    /// </summary>
    /// <returns>是否错误</returns>
    public bool IsError()
    {
        return Code == ErrorCode;
    }

    /// <summary>
    /// 链式设置字段值（兼容原 Java AjaxResult 的 put 方法）。
    /// <para>
    /// 【C# 语法知识点 - 链式调用】
    /// 这个方法返回 this，可以链式调用：
    ///   result.Put("code", 200).Put("msg", "成功");
    /// 
    /// 对比 Java：
    /// Java 若依的 AjaxResult 继承自 HashMap，可以：
    ///   result.put("code", 200).put("msg", "成功");
    /// 
    /// C# 这里用强类型对象实现，只对常见字段做兼容。
    /// </para>
    /// <para>
    /// 【C# 语法知识点 - StringComparison.OrdinalIgnoreCase】
    /// OrdinalIgnoreCase 表示"忽略大小写的序号比较"。
    /// 这样 "Code" 和 "code" 会被视为相同，提高容错性。
    /// 
    /// 对比 Java：
    /// Java 用 equalsIgnoreCase() 方法：
    ///   key.equalsIgnoreCase(CodeTag)
    /// </para>
    /// </summary>
    /// <param name="key">字段名</param>
    /// <param name="value">字段值</param>
    /// <returns>当前实例，支持链式调用</returns>
    public HwPortalAjaxResult Put(string key, object value)
    {
        // 【字符串比较的最佳实践】
        // string.Equals(a, b, StringComparison.OrdinalIgnoreCase)
        // 比 a.ToLower() == b.ToLower() 更高效，不会产生新字符串对象。
        if (string.Equals(key, CodeTag, StringComparison.OrdinalIgnoreCase))
        {
            // 【类型转换】
            // Convert.ToInt32 可以处理多种类型：string, long, double 等。
            // CultureInfo.InvariantCulture 表示使用"不变的格式规则"，
            // 避免不同地区的数字格式差异（如某些地区用逗号作小数点）。
            Code = Convert.ToInt32(value, CultureInfo.InvariantCulture);
            return this;
        }

        if (string.Equals(key, MsgTag, StringComparison.OrdinalIgnoreCase))
        {
            Msg = Convert.ToString(value, CultureInfo.InvariantCulture);
            return this;
        }

        if (string.Equals(key, DataTag, StringComparison.OrdinalIgnoreCase))
        {
            Data = value;
        }

        return this;
    }
}