二维码承载信息量大、成本低且易集成到系统开发,所以,在订单核销、电子凭证、产品溯源、工单系统、物料标签等业务场景里,我们经常需要生成二维码。
很多开发者第一反应就是:自建二维码生成能力。
但“自建”也分为两种思路,一种是基于开源库从零封装,另一种是在自己业务层封装转发,对接成熟API。
下面我们就把两种方案讲清楚,同时聊聊各自适合什么场景。
方案1:底层自建
适用于内网私有化系统、内部小工具、流量很小、不需要美化样式的场景。
原理很简单,调用成熟的二维码编码开源库,实现二维码内容编码、画布渲染,常用的有ZXing(Java)、qrcode(Node.js)、segno(Python)等。
简单放一段Python FastAPI示例:
from fastapi import FastAPI, Response
import segno
from io import BytesIO
app = FastAPI()
@app.get("/qr")
async def create_qr(text: str, width: int = 300):
qrcode = segno.make(text)
buffer = BytesIO()
qrcode.save(buffer, kind="png", scale=width//25)
buffer.seek(0)
return Response(content=buffer.read(), media_type="image/png")
if __name__ == "__main__":
import uvicorn
uvicorn.run("main:app", host="0.0.0.0", port=8000)
优点
不依赖第三方,可以部署在内部环境,数据不出内网;
基础生成逻辑自主可控,没有次数限制。
缺点
样式成本高:想要自定义颜色、控制边距、调节Logo大小等都要单独写代码;
测试繁琐:中文编码、矢量SVG输出、不同设备兼容都要反复测试;
维护成本高:识别异常、图片渲染bug,都需要开发人员排查。
方案2:业务自建封装层
很多人想要自建系统并不是方案一所说的真的“自建”,而是:拥有统一的业务出口、统一管理调用,在自己项目里封装二维码能力,不零散到处调用接口。
这种情况下,可以选择接入二维码生成API,在自己后端写一层转发封装,对外依旧是自己业务的接口,这也是兼顾可控性和效率的自建思路。
这里拿探数API的二维码生成接口举例:
请求参数
| 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|
| key | 是 | string | 个人中心查看 |
| text | 是 | string | 二维码内容 |
| bg_color | 否 | string | 背景色代码,例如:ffffff |
| fg_color | 否 | string | 前景色代码,例如:000000 |
| logo | 否 | string | logo图片URL地址或base64编码的图片内容,urlencode |
| width | 否 | string | 尺寸大小(像素),例如:300 |
| margins | 否 | string | 边距大小(像素),例如:10 |
| logo_width | 否 | string | logo宽度(像素),例如:60 |
Python调用示例
import requests
url = "https://api.tanshuapi.com/api/qrcode/v1/index"#接口地址
params = {
"key": "你的key",
"text": "[https://www.example.com](https://www.example.com)",
"width": "300",
"bg_color": "ffffff",
"fg_color": "000000",
"margins": "10"
}
resp = requests.get(url=url, params=params)
with open("qrcode.png", "wb") as f:
f.write(resp.content)
方案优势
业务层完全自建,统一收口,后续如果需要切换底层服务,只改这一处代码,前端不用改动;
原生支持Logo合成、颜色自定义,不用额外引入图片处理库,避开大量图片合成坑;
GET请求调试方便,参数简洁,集成速度快。
如果你的目的不是研究二维码编码原理,而是快速在业务系统落地二维码生成能力,可以选择这个方案。
两种方案对比表格
| 方案 | 可控性 | 工作量 | 适用场景 |
|---|---|---|---|
| 底层自建 | 极高 | 高 | 内网部署、严格数据隔离、低流量内部系统 |
| 接入API(以探数为例) | 高 | 低 | 公网业务、订单核销、电子凭证、需要 Logo 美化 |
最佳实践与避坑总结
- 学习原理、内部工具开发:优先用开源库自建,吃透编码逻辑;
- 正式生产项目、对外给客户使用、需要带Logo美化:自建业务转发层,接入第三方API;
- 传入Logo参数时注意:url形式或者base64形式都需要做urlencode,避免参数解析异常;
- 按需设置边距,预留空白区域,提升扫码识别成功率。