loveyu-kit 0.2.0

面向 Axum 项目的可组合 API 工具库
Documentation
//! 文本和 Markdown 消息。

use serde::Serialize;

use crate::messaging::MessagingError;

use super::{ensure_max_bytes, require_non_empty};

const MAX_TEXT_BYTES: usize = 2_048;
const MAX_MARKDOWN_BYTES: usize = 4_096;

/// 文本消息体。
#[derive(Clone, Default, Serialize)]
pub struct WeComTextContent {
    content: String,
    #[serde(skip_serializing_if = "Vec::is_empty")]
    mentioned_list: Vec<String>,
    #[serde(skip_serializing_if = "Vec::is_empty")]
    mentioned_mobile_list: Vec<String>,
}

impl WeComTextContent {
    /// 创建文本消息体。
    #[must_use]
    pub fn new(content: impl Into<String>) -> Self {
        Self {
            content: content.into(),
            mentioned_list: Vec::new(),
            mentioned_mobile_list: Vec::new(),
        }
    }

    /// 追加需要 @ 的企业微信用户 ID。
    #[must_use]
    pub fn mention_user(mut self, user_id: impl Into<String>) -> Self {
        push_non_empty_unique(&mut self.mentioned_list, user_id.into());
        self
    }

    /// 追加多个需要 @ 的企业微信用户 ID。
    #[must_use]
    pub fn mention_users<I, S>(mut self, user_ids: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        for user_id in user_ids {
            push_non_empty_unique(&mut self.mentioned_list, user_id.into());
        }
        self
    }

    /// 追加需要 @ 的手机号。
    #[must_use]
    pub fn mention_mobile(mut self, mobile: impl Into<String>) -> Self {
        push_non_empty_unique(&mut self.mentioned_mobile_list, mobile.into());
        self
    }

    /// @ 群内所有人。
    #[must_use]
    pub fn mention_all(mut self) -> Self {
        push_non_empty_unique(&mut self.mentioned_list, "@all".to_owned());
        self
    }

    /// 返回消息内容。
    #[must_use]
    pub fn content(&self) -> &str {
        &self.content
    }

    pub(crate) fn validate(&self) -> Result<(), MessagingError> {
        require_non_empty("文本消息内容", &self.content)?;
        ensure_max_bytes("文本消息内容", &self.content, MAX_TEXT_BYTES)
    }
}

/// Markdown 消息体。
#[derive(Clone, Default, Serialize)]
pub struct WeComMarkdownContent {
    content: String,
}

impl WeComMarkdownContent {
    /// 创建 Markdown 消息体。
    #[must_use]
    pub fn new(content: impl Into<String>) -> Self {
        Self {
            content: content.into(),
        }
    }

    /// 返回消息内容。
    #[must_use]
    pub fn content(&self) -> &str {
        &self.content
    }

    pub(crate) fn validate(&self) -> Result<(), MessagingError> {
        require_non_empty("Markdown 消息内容", &self.content)?;
        ensure_max_bytes("Markdown 消息内容", &self.content, MAX_MARKDOWN_BYTES)
    }
}

/// Markdown V2 消息体。
///
/// V2 协议支持更完整的 Markdown 语法,但是否可用仍取决于企业微信客户端版本。
#[derive(Clone, Default, Serialize)]
pub struct WeComMarkdownV2Content {
    content: String,
}

impl WeComMarkdownV2Content {
    /// 创建 Markdown V2 消息体。
    #[must_use]
    pub fn new(content: impl Into<String>) -> Self {
        Self {
            content: content.into(),
        }
    }

    /// 返回消息内容。
    #[must_use]
    pub fn content(&self) -> &str {
        &self.content
    }

    pub(crate) fn validate(&self) -> Result<(), MessagingError> {
        require_non_empty("Markdown V2 消息内容", &self.content)?;
        // 官方协议对 Markdown 类消息按 UTF-8 字节数限制,在网络请求前提前失败。
        ensure_max_bytes("Markdown V2 消息内容", &self.content, MAX_MARKDOWN_BYTES)
    }
}

fn push_non_empty_unique(values: &mut Vec<String>, value: String) {
    let trimmed = value.trim();
    if !trimmed.is_empty() && !values.iter().any(|existing| existing == trimmed) {
        if trimmed.len() == value.len() {
            values.push(value);
        } else {
            values.push(trimmed.to_owned());
        }
    }
}