wechat_minapp/qr/
minapp_code.rs

1//! 微信小程序小程序码生成模块
2//!
3//! 该模块提供了生成微信小程序小程序码的功能，支持多种类型的小程序码和自定义参数。
4//!
5//! # 主要功能
6//!
7//! - 生成小程序页面小程序码
8//! - 支持自定义尺寸、颜色、透明度等参数
9//! - 支持不同环境版本（开发版、体验版、正式版）
10//! - 链式参数构建器模式
11//!
12//! # 快速开始
13//!
14//! ```no_run
15//! use wechat_minapp::client::WechatMinapp;
16//! use wechat_minapp::qr::{QrCodeArgs,Qr, MinappEnvVersion};
17//!
18//! #[tokio::main]
19//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
20//!     // 初始化客户端
21//!     let app_id = "your_app_id";
22//!     let secret = "your_app_secret";
23//!     let client = WechatMinapp::new(app_id, secret);
24//!     let qr = Qr::new(client);
25//!
26//!     // 构建小程序码参数
27//!     let args = QrCodeArgs::builder()
28//!         .path("pages/index/index")
29//!         .width(300)
30//!         .env_version(MinappEnvVersion::Release)
31//!         .build()?;
32//!
33//!     // 生成小程序码
34//!     let qr_code = qr.qr_code(args).await?;
35//!     
36//!     // 获取小程序码图片数据
37//!     let buffer = qr_code.buffer();
38//!     println!("生成的小程序码大小: {} bytes", buffer.len());
39//!
40//!     // 可以将 buffer 保存为文件或直接返回给前端
41//!     // std::fs::write("qrcode.png", buffer)?;
42//!     
43//!     Ok(())
44//! }
45//! ```
46//!
47//! # 参数说明
48//!
49//! - `path`: 小程序页面路径，必填，最大长度 1024 字符
50//! - `width`: 小程序码宽度，单位 px，最小 280px，最大 1280px
51//! - `auto_color`: 是否自动配置线条颜色
52//! - `line_color`: 自定义线条颜色，RGB 格式
53//! - `is_hyaline`: 是否透明背景
54//! - `env_version`: 环境版本，默认为正式版
55//!
56//! # 注意事项
57//!
58//! - 生成的小程序码永不过期，数量不限
59//! - 接口只能生成已发布的小程序的小程序码
60//! - 支持带参数路径，如 `pages/index/index?param=value`
61//! - 小程序码大小限制为 128KB，请合理设置 width 参数
62//!
63//! # 示例
64//!
65//! ## 生成带颜色的小程序码
66//!
67//! ```no_run
68//! use wechat_minapp::client::WechatMinapp;
69//! use wechat_minapp::qr::{QrCodeArgs,Qr, MinappEnvVersion};
70//!
71//! #[tokio::main]
72//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
73//!     // 初始化客户端
74//!     let app_id = "your_app_id";
75//!     let secret = "your_app_secret";
76//!     let client = WechatMinapp::new(app_id, secret);
77//!     let qr = Qr::new(client);
78//!
79//!     let args = QrCodeArgs::builder()
80//!     .path("pages/detail/detail?id=123")
81//!     .width(400)
82//!     .line_color(Rgb::new(255, 0, 0)) // 红色线条
83//!     .with_is_hyaline() // 透明背景
84//!     .env_version(MinappEnvVersion::Develop)
85//!     .build()
86//!     .unwrap();
87//!     // 生成小程序码
88//!     let qr_code = qr.qr_code(args).await?;
89//!     
90//!     // 获取小程序码图片数据
91//!     let buffer = qr_code.buffer();
92//!     Ok(())
93//! }
94//! ```
95//!
96//! ## 生成简单小程序码
97//!
98//! ```no_run
99//! use wechat_minapp::client::WechatMinapp;
100//! use wechat_minapp::qr::{QrCodeArgs,Qr, MinappEnvVersion};
101//!
102//! #[tokio::main]
103//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
104//!     // 初始化客户端
105//!     let app_id = "your_app_id";
106//!     let secret = "your_app_secret";
107//!     let client = WechatMinapp::new(app_id, secret);
108//!     let qr = Qr::new(client);
109//!
110//!     let args = QrCodeArgs::builder()
111//!     .path("pages/index/index")
112//!     .build()
113//!     .unwrap();
114//!     // 生成小程序码
115//!     let qr_code = qr.qr_code(args).await?;
116//!     
117//!     // 获取小程序码图片数据
118//!     let buffer = qr_code.buffer();
119//!     Ok(())
120//! }
121//! ```
122//!
123//! # 错误处理
124//!
125//! 小程序码生成可能遇到以下错误：
126//!
127//! - 参数验证错误（路径为空或过长）
128//! - 认证错误（access_token 无效）
129//! - 网络错误
130//! - 微信 API 返回错误
131//!
132//! 建议在生产环境中妥善处理这些错误。
133
134use super::Qr;
135use crate::{
136    Result, constants,
137    error::Error::{self, InternalServer},
138    new_type::PagePath,
139};
140use http::header::{CONTENT_TYPE, HeaderValue};
141use http::{Method, Request};
142use serde::{Deserialize, Serialize};
143use std::collections::HashMap;
144use tracing::debug;
145
146/// 二维码图片数据
147///
148/// 包含生成的二维码图片的二进制数据，通常是 PNG 格式。
149///
150/// # 示例
151///
152/// ```no_run
153/// use wechat_minapp::client::WechatMinappSDK;
154/// use wechat_minapp::qr::{QrCodeArgs,Qr, MinappEnvVersion};
155///
156/// #[tokio::main]
157/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
158///     // 初始化客户端
159///     let app_id = "your_app_id";
160///     let secret = "your_app_secret";
161///     let client = WechatMinappSDK::new(app_id, secret);
162///     let qr = Qr::new(client);
163///
164///     let args = QrCodeArgs::builder()
165///     .path("pages/index/index")
166///     .build()
167///     .unwrap();
168///     // 生成小程序码
169///     let qr_code = qr.qr_code(args).await?;
170///     
171///     // 获取小程序码图片数据
172///     let buffer = qr_code.buffer();
173///     Ok(())
174/// }
175/// ```
176#[derive(Debug, Serialize, Deserialize, Clone)]
177pub struct QrCode {
178    pub buffer: Vec<u8>,
179}
180
181impl QrCode {
182    /// 获取二维码图片的二进制数据
183    ///
184    /// 返回的字节向量通常是 PNG 格式的图片数据，可以直接写入文件或返回给 HTTP 响应。
185    ///
186    /// # 返回
187    ///
188    /// 二维码图片的二进制数据引用
189    pub fn buffer(&self) -> &Vec<u8> {
190        &self.buffer
191    }
192}
193
194/// 二维码生成参数
195///
196/// 用于配置二维码的生成选项，通过 [`QrCodeArgs::builder()`] 方法创建。
197#[derive(Debug, Deserialize)]
198pub struct QrCodeArgs {
199    path: String,
200    width: Option<i16>,
201    auto_color: Option<bool>,
202    line_color: Option<Rgb>,
203    is_hyaline: Option<bool>,
204    env_version: Option<MinappEnvVersion>,
205}
206
207/// 二维码参数构建器
208///
209/// 提供链式调用的方式构建二维码参数，确保参数的正确性。
210///
211/// # 示例
212///
213/// ```
214/// use wechat_minapp::qr::{QrCodeArgs, Rgb, MinappEnvVersion};
215///
216/// let args = QrCodeArgs::builder()
217///     .path("pages/index/index")
218///     .width(300)
219///     .with_auto_color()
220///     .line_color(Rgb::new(255, 0, 0))
221///     .with_is_hyaline()
222///     .env_version(MinappEnvVersion::Release)
223///     .build()
224///     .unwrap();
225/// ```
226#[derive(Debug, Deserialize)]
227pub struct QrCodeArgBuilder {
228    path: Option<String>,
229    width: Option<i16>,
230    auto_color: Option<bool>,
231    line_color: Option<Rgb>,
232    is_hyaline: Option<bool>,
233    env_version: Option<MinappEnvVersion>,
234}
235
236// RGB 颜色值
237///
238/// 用于自定义二维码线条颜色。
239///
240/// # 示例
241///
242/// ```
243/// use wechat_minapp::qr::Rgb;
244///
245/// let red = Rgb::new(255, 0, 0);      // 红色
246/// let green = Rgb::new(0, 255, 0);    // 绿色
247/// let blue = Rgb::new(0, 0, 255);     // 蓝色
248/// let black = Rgb::new(0, 0, 0);      // 黑色
249/// ```
250#[derive(Debug, Deserialize, Clone, Serialize)]
251pub struct Rgb {
252    r: i16,
253    g: i16,
254    b: i16,
255}
256
257impl Rgb {
258    /// 创建新的 RGB 颜色
259    ///
260    /// # 参数
261    ///
262    /// - `r`: 红色分量 (0-255)
263    /// - `g`: 绿色分量 (0-255)
264    /// - `b`: 蓝色分量 (0-255)
265    ///
266    /// # 返回
267    ///
268    /// 新的 Rgb 实例
269    pub fn new(r: i16, g: i16, b: i16) -> Self {
270        Rgb { r, g, b }
271    }
272}
273
274impl QrCodeArgs {
275    pub fn builder() -> QrCodeArgBuilder {
276        QrCodeArgBuilder::new()
277    }
278
279    pub fn path(&self) -> String {
280        self.path.clone()
281    }
282
283    pub fn width(&self) -> Option<i16> {
284        self.width
285    }
286
287    pub fn auto_color(&self) -> Option<bool> {
288        self.auto_color
289    }
290
291    pub fn line_color(&self) -> Option<Rgb> {
292        self.line_color.clone()
293    }
294
295    pub fn is_hyaline(&self) -> Option<bool> {
296        self.is_hyaline
297    }
298
299    pub fn env_version(&self) -> Option<MinappEnvVersion> {
300        self.env_version.clone()
301    }
302}
303
304impl Default for QrCodeArgBuilder {
305    fn default() -> Self {
306        Self::new()
307    }
308}
309
310/// 小程序环境版本
311///
312/// 指定二维码生成的环境版本，不同环境版本对应不同的小程序实例。
313#[derive(Debug, Clone, Serialize, Deserialize)]
314pub enum MinappEnvVersion {
315    /// 开发版，用于开发环境
316    Release,
317    /// 体验版，用于测试环境
318    Trial,
319    /// 正式版，用于生产环境
320    Develop,
321}
322
323impl From<MinappEnvVersion> for String {
324    fn from(value: MinappEnvVersion) -> Self {
325        match value {
326            MinappEnvVersion::Develop => "develop".to_string(),
327            MinappEnvVersion::Release => "release".to_string(),
328            MinappEnvVersion::Trial => "trial".to_string(),
329        }
330    }
331}
332
333impl QrCodeArgBuilder {
334    pub fn new() -> Self {
335        QrCodeArgBuilder {
336            path: None,
337            width: None,
338            auto_color: None,
339            line_color: None,
340            is_hyaline: None,
341            env_version: None,
342        }
343    }
344
345    pub fn path(mut self, path: impl Into<String>) -> Self {
346        self.path = Some(path.into());
347        self
348    }
349
350    pub fn width(mut self, width: i16) -> Self {
351        self.width = Some(width);
352        self
353    }
354
355    pub fn with_auto_color(mut self) -> Self {
356        self.auto_color = Some(true);
357        self
358    }
359
360    pub fn line_color(mut self, color: Rgb) -> Self {
361        self.line_color = Some(color);
362        self
363    }
364
365    pub fn with_is_hyaline(mut self) -> Self {
366        self.is_hyaline = Some(true);
367        self
368    }
369
370    pub fn env_version(mut self, version: MinappEnvVersion) -> Self {
371        self.env_version = Some(version);
372        self
373    }
374
375    pub fn build(self) -> Result<QrCodeArgs> {
376        let path = self.path.map_or_else(
377            || {
378                Err(Error::InvalidParameter(
379                    "小程序页面路径不能为空".to_string(),
380                ))
381            },
382            |v| {
383                let valid_path = PagePath::try_from(v)?;
384                Ok(valid_path.to_string())
385            },
386        )?;
387
388        if self.auto_color.is_some() && self.line_color.is_some() {
389            return Err(Error::InvalidParameter(
390                "auto_color 为 true 时，line_color 不能设置".to_string(),
391            ));
392        }
393
394        Ok(QrCodeArgs {
395            path,
396            width: self.width,
397            auto_color: self.auto_color,
398            line_color: self.line_color,
399            is_hyaline: self.is_hyaline,
400            env_version: self.env_version,
401        })
402    }
403}
404
405impl Qr {
406    /// 生成小程序二维码
407    ///
408    /// 调用微信小程序二维码生成接口，返回包含二维码图片数据的 [`QrCode`] 对象。
409    ///
410    /// # 参数
411    ///
412    /// - `args`: 二维码生成参数
413    ///
414    /// # 返回
415    ///
416    /// 成功返回 `Ok(QrCode)`，失败返回错误信息。
417    ///
418    /// # 示例
419    ///
420    /// ```no_run
421    /// use wechat_minapp::client::WechatMinappSDK;
422    /// use wechat_minapp::qr::{QrCodeArgs,Qr, MinappEnvVersion};
423    ///
424    /// #[tokio::main]
425    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
426    ///     // 初始化客户端
427    ///     let app_id = "your_app_id";
428    ///     let secret = "your_app_secret";
429    ///     let client = WechatMinappSDK::new(app_id, secret);
430    ///     let qr = Qr::new(client);
431    ///
432    ///     // 构建小程序码参数
433    ///     let args = QrCodeArgs::builder()
434    ///         .path("pages/index/index")
435    ///         .width(300)
436    ///         .env_version(MinappEnvVersion::Release)
437    ///         .build()?;
438    ///
439    ///     // 生成小程序码
440    ///     let qr_code = qr.qr_code(args).await?;
441    ///     
442    ///     // 获取小程序码图片数据
443    ///     let buffer = qr_code.buffer();
444    ///     println!("生成的小程序码大小: {} bytes", buffer.len());
445    ///
446    ///     // 可以将 buffer 保存为文件或直接返回给前端
447    ///     // std::fs::write("qrcode.png", buffer)?;
448    ///     
449    ///     Ok(())
450    /// }
451    /// ```
452    ///
453    /// # 错误
454    ///
455    /// - 网络错误
456    /// - 认证错误（access_token 无效）
457    /// - 微信 API 返回错误
458    /// - 参数序列化错误
459    pub async fn qr_code(&self, args: QrCodeArgs) -> Result<QrCode> {
460        debug!("get qr code args {:?}", &args);
461        let token = format!("access_token={}", self.client.token().await?);
462        let mut url = url::Url::parse(constants::QR_CODE_ENDPOINT)?;
463        url.set_query(Some(&token));
464
465        let mut body = HashMap::new();
466
467        body.insert("path", args.path);
468
469        if let Some(width) = args.width {
470            body.insert("width", width.to_string());
471        }
472
473        if let Some(auto_color) = args.auto_color {
474            body.insert("auto_color", auto_color.to_string());
475        }
476
477        if let Some(line_color) = args.line_color {
478            let value = serde_json::to_string(&line_color)?;
479            body.insert("line_color", value);
480        }
481
482        if let Some(is_hyaline) = args.is_hyaline {
483            body.insert("is_hyaline", is_hyaline.to_string());
484        }
485
486        if let Some(env_version) = args.env_version {
487            body.insert("env_version", env_version.into());
488        }
489
490        let client = &self.client.client;
491        let req_body = serde_json::to_vec(&body)?;
492        let request = Request::builder()
493            .uri(url.as_str())
494            .method(Method::POST)
495            .header("encoding", HeaderValue::from_static("null"))
496            .header(CONTENT_TYPE, HeaderValue::from_static("application/json"))
497            .header(
498                "User-Agent",
499                HeaderValue::from_static(constants::HTTP_CLIENT_USER_AGENT),
500            )
501            .body(req_body)?;
502
503        let response = client.execute(request).await?;
504
505        debug!("response: {:#?}", response);
506
507        if response.status().is_success() {
508            Ok(QrCode {
509                buffer: response.into_body(),
510            })
511        } else {
512            let (_parts, body) = response.into_parts();
513            let message = String::from_utf8_lossy(&body).to_string();
514            Err(InternalServer(message))
515        }
516    }
517}
wechat_minapp/qr/minapp_code.rs

wechat_minapp/qr/
minapp_code.rs
