458 lines
13 KiB
Go
458 lines
13 KiB
Go
// Package utils 提供通用工具函数
|
||
//
|
||
// 二维码生成功能模块
|
||
//
|
||
// 本模块提供了完整的二维码生成功能，支持：
|
||
// - 基础二维码生成（保存为PNG文件）
|
||
// - 生成字节数组（可用于HTTP响应、数据库存储等）
|
||
// - Base64编码输出（便于存储和传输）
|
||
// - Data URL格式（可直接用于HTML <img>标签）
|
||
// - 自定义配置（尺寸、颜色、纠错级别）
|
||
// - 带Logo的二维码
|
||
// - 批量生成二维码
|
||
package utils
|
||
|
||
import (
|
||
"bytes"
|
||
"encoding/base64"
|
||
"fmt"
|
||
"image"
|
||
"image/color"
|
||
"image/png"
|
||
"os"
|
||
|
||
"github.com/skip2/go-qrcode"
|
||
)
|
||
|
||
// QRCodeErrorLevel 二维码纠错级别
|
||
//
|
||
// 纠错级别决定了二维码能容忍多少损坏：
|
||
// - 级别越高，容错能力越强，但二维码会更复杂
|
||
// - 添加Logo时建议使用高级纠错
|
||
// - 一般场景使用中级纠错即可
|
||
type QRCodeErrorLevel int
|
||
|
||
const (
|
||
// QRCodeErrorLevelLow 低级纠错（约7%容错）
|
||
// 适用场景：环境良好、追求小尺寸、内容较少
|
||
QRCodeErrorLevelLow QRCodeErrorLevel = iota
|
||
|
||
// QRCodeErrorLevelMedium 中级纠错（约15%容错）
|
||
// 适用场景：通用场景（默认推荐）
|
||
QRCodeErrorLevelMedium
|
||
|
||
// QRCodeErrorLevelQuartile 较高级纠错（约25%容错）
|
||
// 适用场景：需要较高容错能力
|
||
QRCodeErrorLevelQuartile
|
||
|
||
// QRCodeErrorLevelHigh 高级纠错（约30%容错）
|
||
// 适用场景：添加Logo、容易损坏的环境、长期使用
|
||
QRCodeErrorLevelHigh
|
||
)
|
||
|
||
const (
|
||
// DefaultQRCodeSize 默认二维码尺寸（像素）
|
||
DefaultQRCodeSize = 256
|
||
// MinQRCodeSize 最小二维码尺寸
|
||
MinQRCodeSize = 21
|
||
// MaxQRCodeSize 最大二维码尺寸
|
||
MaxQRCodeSize = 8192
|
||
)
|
||
|
||
// QRCodeConfig 二维码配置结构
|
||
//
|
||
// 用于自定义二维码的外观和质量参数
|
||
//
|
||
// 示例：
|
||
//
|
||
// config := &QRCodeConfig{
|
||
// Size: 512, // 尺寸512x512像素
|
||
// ErrorLevel: QRCodeErrorLevelHigh, // 高级纠错
|
||
// ForegroundColor: color.RGBA{255, 0, 0, 255}, // 红色二维码
|
||
// BackgroundColor: color.White, // 白色背景
|
||
// }
|
||
type QRCodeConfig struct {
|
||
Size int // 尺寸（像素），范围：21-8192
|
||
ErrorLevel QRCodeErrorLevel // 纠错级别，影响容错能力和复杂度
|
||
ForegroundColor color.Color // 前景色（二维码颜色），建议使用深色
|
||
BackgroundColor color.Color // 背景色，建议使用浅色以保证对比度
|
||
}
|
||
|
||
// DefaultQRCodeConfig 返回默认配置
|
||
//
|
||
// 默认配置适用于大多数场景：
|
||
// - 尺寸：256x256像素（适合手机扫描）
|
||
// - 纠错级别：中级（15%容错）
|
||
// - 颜色：黑白配色（最佳识别率）
|
||
//
|
||
// 返回值：
|
||
//
|
||
// *QRCodeConfig: 默认配置对象
|
||
func DefaultQRCodeConfig() *QRCodeConfig {
|
||
return &QRCodeConfig{
|
||
Size: DefaultQRCodeSize,
|
||
ErrorLevel: QRCodeErrorLevelMedium,
|
||
ForegroundColor: color.Black,
|
||
BackgroundColor: color.White,
|
||
}
|
||
}
|
||
|
||
// convertErrorLevel 转换纠错级别为底层库的纠错级别
|
||
//
|
||
// 将自定义的纠错级别枚举转换为 go-qrcode 库所需的格式
|
||
//
|
||
// 参数：
|
||
//
|
||
// level: 自定义纠错级别
|
||
//
|
||
// 返回值：
|
||
//
|
||
// qrcode.RecoveryLevel: go-qrcode库的纠错级别
|
||
func convertErrorLevel(level QRCodeErrorLevel) qrcode.RecoveryLevel {
|
||
switch level {
|
||
case QRCodeErrorLevelLow:
|
||
return qrcode.Low
|
||
case QRCodeErrorLevelMedium:
|
||
return qrcode.Medium
|
||
case QRCodeErrorLevelQuartile:
|
||
return qrcode.High
|
||
case QRCodeErrorLevelHigh:
|
||
return qrcode.Highest
|
||
default:
|
||
return qrcode.Medium
|
||
}
|
||
}
|
||
|
||
// GenerateQRCode 生成二维码并保存为PNG文件
|
||
//
|
||
// 这是最简单的二维码生成方法，适合快速生成标准黑白二维码。
|
||
// 使用中级纠错，黑白配色，PNG格式输出。
|
||
//
|
||
// 参数：
|
||
//
|
||
// content: 二维码内容（支持URL、文本、vCard、WiFi等格式）
|
||
// filename: 保存的文件路径（.png文件）
|
||
// size: 二维码尺寸（可选，单位：像素）
|
||
// - 不传参数：使用默认256x256
|
||
// - 传一个参数：使用指定尺寸
|
||
// - 有效范围：21-8192像素
|
||
//
|
||
// 返回值：
|
||
//
|
||
// error: 错误信息，成功时返回nil
|
||
//
|
||
// 注意事项：
|
||
// - 内容越长，二维码越复杂，建议尺寸>=256
|
||
// - 文件权限为0644
|
||
// - 会覆盖已存在的同名文件
|
||
func GenerateQRCode(content, filename string, size ...int) error {
|
||
qrSize := DefaultQRCodeSize
|
||
if len(size) > 0 {
|
||
qrSize = size[0]
|
||
if qrSize < MinQRCodeSize || qrSize > MaxQRCodeSize {
|
||
return fmt.Errorf("二维码尺寸必须在 %d 到 %d 之间", MinQRCodeSize, MaxQRCodeSize)
|
||
}
|
||
}
|
||
|
||
err := qrcode.WriteFile(content, qrcode.Medium, qrSize, filename)
|
||
if err != nil {
|
||
return fmt.Errorf("生成二维码失败: %w", err)
|
||
}
|
||
|
||
return nil
|
||
}
|
||
|
||
// GenerateQRCodeBytes 生成二维码字节数组（PNG格式）
|
||
//
|
||
// 生成二维码的字节数组而不保存到文件，适合：
|
||
// - HTTP响应直接返回图片
|
||
// - 存储到数据库
|
||
// - 通过网络传输
|
||
// - 进一步处理（如添加到PDF）
|
||
//
|
||
// 参数：
|
||
//
|
||
// content: 二维码内容
|
||
// size: 二维码尺寸（可选，默认256）
|
||
//
|
||
// 返回值：
|
||
//
|
||
// []byte: PNG格式的图片字节数组
|
||
// error: 错误信息
|
||
func GenerateQRCodeBytes(content string, size ...int) ([]byte, error) {
|
||
qrSize := DefaultQRCodeSize
|
||
if len(size) > 0 {
|
||
qrSize = size[0]
|
||
if qrSize < MinQRCodeSize || qrSize > MaxQRCodeSize {
|
||
return nil, fmt.Errorf("二维码尺寸必须在 %d 到 %d 之间", MinQRCodeSize, MaxQRCodeSize)
|
||
}
|
||
}
|
||
|
||
bytes, err := qrcode.Encode(content, qrcode.Medium, qrSize)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("生成二维码失败: %w", err)
|
||
}
|
||
|
||
return bytes, nil
|
||
}
|
||
|
||
// GenerateQRCodeBase64 生成Base64编码的二维码字符串
|
||
//
|
||
// 将二维码图片编码为Base64字符串，便于：
|
||
// - 存储到数据库的文本字段
|
||
// - 通过JSON/XML传输
|
||
// - 避免二进制数据处理问题
|
||
//
|
||
// 参数：
|
||
//
|
||
// content: 二维码内容
|
||
// size: 二维码尺寸（可选，默认256）
|
||
//
|
||
// 返回值：
|
||
//
|
||
// string: Base64编码的字符串（不包含data:image/png;base64,前缀）
|
||
// error: 错误信息
|
||
func GenerateQRCodeBase64(content string, size ...int) (string, error) {
|
||
qrBytes, err := GenerateQRCodeBytes(content, size...)
|
||
if err != nil {
|
||
return "", err
|
||
}
|
||
|
||
base64Str := base64.StdEncoding.EncodeToString(qrBytes)
|
||
return base64Str, nil
|
||
}
|
||
|
||
// GenerateQRCodeWithConfig 使用自定义配置生成二维码
|
||
//
|
||
// 提供完全自定义的二维码生成能力，可以控制：
|
||
// - 尺寸大小
|
||
// - 纠错级别
|
||
// - 前景色和背景色
|
||
//
|
||
// 参数：
|
||
//
|
||
// content: 二维码内容
|
||
// config: 二维码配置对象（nil时使用默认配置）
|
||
//
|
||
// 返回值：
|
||
//
|
||
// []byte: PNG格式的字节数组
|
||
// error: 错误信息
|
||
//
|
||
// 注意事项：
|
||
// - 确保前景色和背景色有足够对比度
|
||
// - 浅色前景配深色背景可能影响扫描
|
||
func GenerateQRCodeWithConfig(content string, config *QRCodeConfig) ([]byte, error) {
|
||
if config == nil {
|
||
config = DefaultQRCodeConfig()
|
||
}
|
||
|
||
// 验证尺寸
|
||
if config.Size < MinQRCodeSize || config.Size > MaxQRCodeSize {
|
||
return nil, fmt.Errorf("二维码尺寸必须在 %d 到 %d 之间", MinQRCodeSize, MaxQRCodeSize)
|
||
}
|
||
|
||
// 创建二维码对象
|
||
qr, err := qrcode.New(content, convertErrorLevel(config.ErrorLevel))
|
||
if err != nil {
|
||
return nil, fmt.Errorf("创建二维码失败: %w", err)
|
||
}
|
||
|
||
// 设置颜色
|
||
qr.ForegroundColor = config.ForegroundColor
|
||
qr.BackgroundColor = config.BackgroundColor
|
||
|
||
// 生成PNG
|
||
pngBytes, err := qr.PNG(config.Size)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("生成PNG失败: %w", err)
|
||
}
|
||
|
||
return pngBytes, nil
|
||
}
|
||
|
||
// GenerateQRCodeWithLogo 生成带Logo的二维码
|
||
//
|
||
// 在二维码中心嵌入Logo图片，Logo会占据二维码约1/5的区域。
|
||
// 使用高级纠错以确保Logo不影响二维码的可读性。
|
||
//
|
||
// 参数：
|
||
//
|
||
// content: 二维码内容
|
||
// logoPath: Logo图片文件路径（支持PNG、JPEG等格式）
|
||
// size: 二维码尺寸（可选，默认256，建议>=512以保证清晰度）
|
||
//
|
||
// 返回值：
|
||
//
|
||
// []byte: PNG格式的字节数组
|
||
// error: 错误信息
|
||
//
|
||
// 注意事项：
|
||
// - Logo会自动缩放到二维码的1/5大小
|
||
// - 建议Logo使用正方形图片
|
||
// - 使用高级纠错级别（~30%容错）
|
||
// - Logo会覆盖二维码中心区域
|
||
// - 建议二维码尺寸>=512以保证Logo清晰
|
||
// - Logo文件必须存在且可读取
|
||
func GenerateQRCodeWithLogo(content, logoPath string, size ...int) ([]byte, error) {
|
||
qrSize := DefaultQRCodeSize
|
||
if len(size) > 0 {
|
||
qrSize = size[0]
|
||
if qrSize < MinQRCodeSize || qrSize > MaxQRCodeSize {
|
||
return nil, fmt.Errorf("二维码尺寸必须在 %d 到 %d 之间", MinQRCodeSize, MaxQRCodeSize)
|
||
}
|
||
}
|
||
|
||
// 生成基础二维码
|
||
qr, err := qrcode.New(content, qrcode.High)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("创建二维码失败: %w", err)
|
||
}
|
||
|
||
// 生成二维码图像
|
||
qrImage := qr.Image(qrSize)
|
||
|
||
// 读取Logo图片
|
||
logoFile, err := os.Open(logoPath)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("打开Logo文件失败: %w", err)
|
||
}
|
||
defer logoFile.Close()
|
||
|
||
logoImage, _, err := image.Decode(logoFile)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("解码Logo图片失败: %w", err)
|
||
}
|
||
|
||
// 计算Logo位置和大小（Logo占二维码的1/5）
|
||
logoSize := qrSize / 5
|
||
logoX := (qrSize - logoSize) / 2
|
||
logoY := (qrSize - logoSize) / 2
|
||
|
||
// 创建最终图像
|
||
finalImage := image.NewRGBA(qrImage.Bounds())
|
||
|
||
// 绘制二维码
|
||
for y := 0; y < qrSize; y++ {
|
||
for x := 0; x < qrSize; x++ {
|
||
finalImage.Set(x, y, qrImage.At(x, y))
|
||
}
|
||
}
|
||
|
||
// 绘制Logo
|
||
logoOriginalBounds := logoImage.Bounds()
|
||
for y := 0; y < logoSize; y++ {
|
||
for x := 0; x < logoSize; x++ {
|
||
// 计算原始Logo的对应像素
|
||
origX := x * logoOriginalBounds.Dx() / logoSize
|
||
origY := y * logoOriginalBounds.Dy() / logoSize
|
||
finalImage.Set(logoX+x, logoY+y, logoImage.At(origX, origY))
|
||
}
|
||
}
|
||
|
||
// 转换为PNG字节
|
||
var buf bytes.Buffer
|
||
if err := png.Encode(&buf, finalImage); err != nil {
|
||
return nil, fmt.Errorf("编码PNG失败: %w", err)
|
||
}
|
||
|
||
return buf.Bytes(), nil
|
||
}
|
||
|
||
// SaveQRCodeBytes 保存二维码字节数组到文件
|
||
//
|
||
// 将二维码字节数组保存为PNG文件，常与 GenerateQRCodeBytes 或
|
||
// GenerateQRCodeWithConfig 配合使用。
|
||
//
|
||
// 参数：
|
||
//
|
||
// data: PNG格式的二维码字节数组
|
||
// filename: 保存的文件路径
|
||
//
|
||
// 返回值：
|
||
//
|
||
// error: 错误信息
|
||
//
|
||
// 注意事项：
|
||
// - 文件权限为0644
|
||
// - 会覆盖已存在的文件
|
||
// - 确保目录已存在
|
||
func SaveQRCodeBytes(data []byte, filename string) error {
|
||
if err := os.WriteFile(filename, data, 0644); err != nil {
|
||
return fmt.Errorf("保存文件失败: %w", err)
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// GenerateQRCodeDataURL 生成Data URL格式的二维码
|
||
//
|
||
// 生成可以直接用于HTML <img>标签的Data URL格式字符串。
|
||
// Data URL包含了完整的图片数据，无需额外的图片文件。
|
||
//
|
||
// 参数：
|
||
//
|
||
// content: 二维码内容
|
||
// size: 二维码尺寸（可选，默认256）
|
||
//
|
||
// 返回值：
|
||
//
|
||
// string: Data URL格式字符串（包含data:image/png;base64,前缀）
|
||
// error: 错误信息
|
||
//
|
||
// 注意事项：
|
||
// - Data URL字符串较长，不适合存储到数据库
|
||
// - 适合临时显示、前端渲染等场景
|
||
// - 某些老旧浏览器可能不支持
|
||
func GenerateQRCodeDataURL(content string, size ...int) (string, error) {
|
||
qrBytes, err := GenerateQRCodeBytes(content, size...)
|
||
if err != nil {
|
||
return "", err
|
||
}
|
||
|
||
base64Str := base64.StdEncoding.EncodeToString(qrBytes)
|
||
dataURL := fmt.Sprintf("data:image/png;base64,%s", base64Str)
|
||
return dataURL, nil
|
||
}
|
||
|
||
// BatchGenerateQRCode 批量生成二维码文件
|
||
//
|
||
// 一次性生成多个二维码文件，适合：
|
||
// - 批量生成产品二维码
|
||
// - 生成多个用户的会员卡
|
||
// - 批量生成门票、优惠券等
|
||
//
|
||
// 参数：
|
||
//
|
||
// items: map[内容]文件名，例如：map["产品A":"qr_a.png", "产品B":"qr_b.png"]
|
||
// size: 二维码尺寸（可选，默认256，所有二维码使用相同尺寸）
|
||
//
|
||
// 返回值：
|
||
//
|
||
// []string: 失败的文件名列表（成功时为nil）
|
||
// error: 错误信息（部分失败时返回错误，但成功的文件已生成）
|
||
//
|
||
// 注意事项：
|
||
// - 即使部分失败，成功的二维码仍会生成
|
||
// - 建议检查返回的failed列表以确定哪些失败了
|
||
// - 大批量生成时注意磁盘空间
|
||
func BatchGenerateQRCode(items map[string]string, size ...int) ([]string, error) {
|
||
var failed []string
|
||
qrSize := DefaultQRCodeSize
|
||
if len(size) > 0 {
|
||
qrSize = size[0]
|
||
}
|
||
|
||
for content, filename := range items {
|
||
err := GenerateQRCode(content, filename, qrSize)
|
||
if err != nil {
|
||
failed = append(failed, filename)
|
||
}
|
||
}
|
||
|
||
if len(failed) > 0 {
|
||
return failed, fmt.Errorf("有 %d 个二维码生成失败", len(failed))
|
||
}
|
||
|
||
return nil, nil
|
||
}
|