using System;
using NewLife;
namespace NewLife.XCoder.Tools.Mqtt;
/// <summary>MQTT 主题与参数校验</summary>
/// <remarks>
/// MQTT 通配符规则容易踩坑:<c>+</c> 只能独占一层,<c>#</c> 只能出现在最后一层且必须是整层。
/// 发布时不允出现通配符。这里把规则集中成可单测的纯函数,界面直接用返回的错误文案提示用户。
/// </remarks>
public static class MqttTopicValidator
{
/// <summary>主题最大长度(MQTT 规范限制为 65535 字节)</summary>
public const Int32 MaxLength = 65535;
/// <summary>校验主题</summary>
/// <param name="topic">主题</param>
/// <param name="forSubscribe">是否订阅场景(允许通配符)</param>
/// <returns>错误说明;通过返回 null</returns>
public static String? Validate(String? topic, Boolean forSubscribe)
{
if (topic.IsNullOrEmpty()) return "主题不能为空";
if (topic!.Length > MaxLength) return $"主题过长({topic.Length},上限 {MaxLength})";
var levels = topic.Split('/');
for (var i = 0; i < levels.Length; i++)
{
var level = levels[i];
if (level.Contains('#'))
{
if (!forSubscribe) return "发布主题不能包含通配符 #";
if (level != "#") return "# 必须独占最后一层";
if (i != levels.Length - 1) return "# 只能出现在最后一层";
}
if (level.Contains('+'))
{
if (!forSubscribe) return "发布主题不能包含通配符 +";
if (level != "+") return "+ 必须独占一层";
}
}
return null;
}
/// <summary>校验 QoS,越界时夹到 0~2</summary>
/// <param name="qos">QoS</param>
/// <returns>合法值</returns>
public static Int32 NormalizeQos(Int32 qos) => qos < 0 ? 0 : qos > 2 ? 2 : qos;
/// <summary>客户端标识缺失时生成一个</summary>
/// <param name="clientId">用户输入的客户端标识</param>
/// <returns>可直接使用的客户端标识</returns>
public static String EnsureClientId(String? clientId)
{
if (clientId.IsNullOrWhiteSpace()) return "xcoder-" + Guid.NewGuid().ToString("N")[..8];
var text = clientId!.Trim();
// MQTT 3.1.1 建议 1~23 字节;超长直接截断避免服务端拒绝
return text.Length > 23 ? text[..23] : text;
}
/// <summary>把主题拆成层级,便于界面显示主题树</summary>
/// <param name="topic">主题</param>
/// <returns>层级数组,空主题返回空数组</returns>
public static String[] SplitLevels(String? topic)
{
if (topic.IsNullOrEmpty()) return [];
return topic!.Split('/');
}
}
|