SpringBoot 生成二维码

前言

嗨，大家好！今天我们来聊聊一个程序员日常中非常实用的小工具——二维码生成。

最近遇到一个需求，需要根据订单号生成支付二维码并提供访问链接。虽然看起来很简单，但其中涉及的一些细节可能会让人踩坑。因此，本文将使用 Spring Boot + ZXing 来完整梳理二维码生成的实现过程，并提供最佳实践。

1. 配置项目依赖

二维码生成通常需要一个工具库，这里我们选用 ZXing（Zebra Crossing），它功能强大且易于使用。

在 pom.xml 中添加以下依赖：

<dependency>
    <groupId>com.google.zxing</groupId>
    <artifactId>javase</artifactId>
    <version>3.3.0</version>
</dependency>

注意： 建议使用最新稳定版本，以避免兼容性问题。

2. 编写二维码工具类

核心功能是生成二维码图片。我们创建一个 QRCodeGenerator 工具类，该类主要分为两步：

• 编码内容：将文本信息转换为二维码数据矩阵。
• 生成图片：将数据矩阵转换为二维码图片并保存。

2.1 代码实现

import com.google.zxing.*;
import com.google.zxing.client.j2se.MatrixToImageWriter;
import com.google.zxing.common.BitMatrix;
import com.google.zxing.qrcode.QRCodeWriter;
import java.io.IOException;
import java.nio.file.FileSystems;
import java.nio.file.Path;

public class QRCodeGenerator {
    public static void generateQRCodeImage(String text, int width, int height, String filePath)
            throws WriterException, IOException {
        // 生成二维码矩阵
        QRCodeWriter qrCodeWriter = new QRCodeWriter();
        BitMatrix bitMatrix = qrCodeWriter.encode(text, BarcodeFormat.QR_CODE, width, height);
        
        // 指定输出路径
        Path path = FileSystems.getDefault().getPath(filePath);
        
        // 将二维码写入文件
        MatrixToImageWriter.writeToPath(bitMatrix, "PNG", path);
    }
}

2.2 代码解析

• QRCodeWriter：用于生成二维码数据矩阵。
• MatrixToImageWriter：用于将矩阵转换为二维码图片并保存。
• 参数解析：
  • text：二维码包含的内容，比如支付链接。
  • width & height：二维码图片的尺寸。
  • filePath：二维码图片的保存路径。

2.3 测试二维码生成

public static void main(String[] args) {
    try {
        QRCodeGenerator.generateQRCodeImage("Hello World", 300, 300, "hello_world.png");
        System.out.println("二维码生成成功！");
    } catch (Exception e) {
        System.err.println("生成二维码失败：" + e.getMessage());
    }
}

运行后，可以在项目目录下看到 hello_world.png，效果妥妥的。

3. Service 层实现

有了工具类后，我们在 Service 层 添加业务逻辑，比如根据订单号生成支付二维码。

3.1 核心逻辑

• 拼接支付链接
• 调用工具类生成二维码
• 返回二维码访问地址

3.2 代码实现

import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.*;
import javax.servlet.http.HttpServletRequest;

@RestController
@RequestMapping("/api")
public class QRCodeService {
    @Value("${file.upload.ip}")
    private String ip;
    
    @Value("${file.upload.path}")
    private String uploadPath;

    @GetMapping("/qrcode")
    public String qrcode(@RequestParam String orderNo, HttpServletRequest request) {
        try {
            // 拼接支付链接
            String address = ip + ":" + request.getLocalPort();
            String payUrl = "http://" + address + "/pay?orderNo=" + orderNo;
            
            // 生成二维码
            String filePath = uploadPath + orderNo + ".png";
            QRCodeGenerator.generateQRCodeImage(payUrl, 350, 350, filePath);
            
            // 返回二维码图片地址
            return "http://" + address + "/images-dev/" + orderNo + ".png";
        } catch (Exception e) {
            return "二维码生成失败：" + e.getMessage();
        }
    }
}

4. 参数配置

为了方便本地和线上调试，我们使用 Spring Boot 配置文件。

application.properties 配置示例：

file.upload.ip=127.0.0.1
file.upload.path=/var/uploads/

这样修改 IP 地址或上传目录时，不需要改代码，直接改配置即可，灵活又优雅。

5. 启动验证

启动 Spring Boot 项目后，在浏览器访问：

http://127.0.0.1:8080/api/qrcode?orderNo=123456

如果成功，返回的地址类似于：

http://127.0.0.1:8080/images-dev/123456.png

6. 常见问题 & 优化建议

6.1 图片路径找不到

确保 uploadPath 目录存在，否则会生成失败。可在启动时检查并创建：

File dir = new File(uploadPath);
if (!dir.exists()) {
    dir.mkdirs();
}

6.2 生成带 Logo 的二维码

可以使用 Java 图像处理库（BufferedImage） 来合并二维码和 Logo，提高美观度。

6.3 局域网访问失败

如果需要让局域网访问，可以动态获取本机 IP 地址：

InetAddress localHost = InetAddress.getLocalHost();
String ip = localHost.getHostAddress();

7. 总结

本文详细介绍了 Spring Boot 结合 ZXing 生成二维码 的完整流程，包括：

• 配置 ZXing 依赖
• 编写二维码工具类
• 实现 API 接口
• 处理参数配置
• 常见问题及优化方案

二维码生成功能虽然看似简单，但路径、配置、兼容性等问题不容忽视。希望本文对你有所帮助，Happy Coding！🚀