1. 一张打不出来的小票:问题不在打印机,在功能库这层封装
某食堂窗口换了一台热敏打印机,收银端网页能正常出票,Java 打单程序打出来却全是问号。换了驱动、重启打印机、甚至换了一台机器,问题照旧。真正的原因不在设备,而在那段直接写在业务类里的打印代码:它缺一个功能库,ESC/POS 指令、GBK 编码、走纸和切纸全散在订单逻辑里,既没法单独测试,也没法换一种输出方式。把这一层抽出来,做成只负责按顺序写对字节的功能库,乱码、丢行、切纸不对才有地方查。这篇写给已经能打出小票、但代码还停留在能跑就行的人:下面从六条指令讲起,落到一个可注入 OutputStream 的工具类,再把踩过的坑一条条摊开。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 功能库的底座:ESC/POS 六条指令与 OutputStream 注入
2.1 先认清对象:ESC/POS 是一串十六进制字节,不是打印 API
很多打印代码写歪,是因为一开始把打印机当成了某个「打印接口」。它没有 printOrder() 这样的方法,应用能做的只有一件事:把字节按顺序写进输出流,打印机自己解释这些字节。ESC/POS 指令通常以 1B(ESC)或 1D(GS)开头,后面跟一个命令字节和若干参数字节。比如 1B 40 是初始化,1B 61 01 是居中,1D 56 01 是部分切纸。
这件事决定了功能库的职责边界。业务层只应该告诉库「窗口名是什么、订单号是什么、明细有哪些、合计多少」,库负责把这些数据变成正确顺序、正确编码、正确缓冲的字节。打印机不会回一句「收到」,也没有请求-应答,写完就认为你发完了。所以顺序错一步、编码错一字节,纸上就会以乱码、错位、半截票的形式反馈出来,排查时像面对一个黑匣子。
还有一个容易被忽略的点:中文不是「文本」,在打印机眼里是字节。热敏打印机大多按 GBK 解码,Java 里如果随手用默认编码或 UTF-8,英文数字可能正常,中文直接变成问号。功能库要做的第一件事,就是把编码锁死在一个地方,而不是让每个业务方法各自 getBytes()。
2.2 六条指令的最小集:一张小票够用
食堂取餐小票不需要复杂排版,实际用到的指令只有六条。下面这张表建议直接落到常量类里,后面所有方法都只引用这些常量,不再手写十六进制:
| 功能 | 指令字节 | 参数说明 | 封装常量 |
|---|---|---|---|
| 初始化打印机 | 1B 40 |
清空缓冲区,复位 | INIT |
| 设置对齐方式 | 1B 61 n |
n=0 左对齐,1 居中,2 右对齐 | ALIGN_LEFT / ALIGN_CENTER |
| 设置字体倍宽倍高 | 1D 21 n |
高位表示倍宽,低位表示倍高 | FONT_NORMAL / FONT_DOUBLE |
| 打印并换行 | 0A |
每次写一行后追加 | LF |
| 走纸 n 行 | 1B 64 n |
出一段空白,便于撕票 | FEED_3_LINES |
| 切纸 | 1D 56 01 |
部分切纸,半切不切断 | CUT_PAPER |
逐条看它们的作用范围,能避免很多「设置了一次以为只影响一行」的误会。1B 40 放在每次打印的最前面,清掉上一单可能残留的字体、对齐和缓冲;1B 61 n 是状态指令,设置后影响后续所有行,直到下一次设置;1D 21 n 也一样,0x11 按高位倍宽、低位倍高理解,就是倍宽加倍高,0x00 是正常字体,标题打完必须复位,否则明细会跟着变大。0A 是行边界,每写一条文本就补一个,不要指望打印机自动换行。1B 64 03 是在切纸前走三行空白,给切刀留位置。1D 56 01 是部分切纸,半切不切断,撕票时留毛边是正常现象,不是故障。
这六条指令拼起来,就是一张小票的完整生命周期:初始化、居中放大打标题、复位、左对齐打明细、走纸、切纸。功能库不需要一上来就支持图片、条码、二维码,那些是后面按机型手册再加的;先把这六条写对,食堂窗口的出票问题就解决大半。
2.3 构造函数为什么收 OutputStream,而不是收 Socket
最直接的写法是在打印方法里 new Socket(ip, port),拿输出流就写。这样写能跑,但会把设备连接和指令拼装绑死:测试必须连真机,换一台打印机要改方法内部,想先在本地看字节只能靠调试器。更麻烦的是,业务类里会散落 getBytes("GBK")、write(0x1B)、flush(),改一个格式要翻好几个文件。
功能库的构造器只收一个 OutputStream,把传输层留给调用方。真机联调时传 Socket 输出流,本地测试时传 FileOutputStream,甚至传 ByteArrayOutputStream 在内存里比对字节。指令类不关心字节最终去了哪里,只关心写得对不对。常量类和构造器可以整理成这样:
java复制public final class EscPosCmd {
public static final byte[] INIT = {0x1B, 0x40};
public static final byte[] ALIGN_LEFT = {0x1B, 0x61, 0x00};
public static final byte[] ALIGN_CENTER = {0x1B, 0x61, 0x01};
public static final byte[] FONT_NORMAL = {0x1D, 0x21, 0x00};
public static final byte[] FONT_DOUBLE = {0x1D, 0x21, 0x11}; // 倍宽倍高
public static final byte[] CUT_PAPER = {0x1D, 0x56, 0x01};
public static final byte[] FEED_3_LINES = {0x1B, 0x64, 0x03};
public static final byte LF = 0x0A;
}
public class EscPosPrinter {
private final OutputStream out;
public EscPosPrinter(OutputStream out) {
this.out = out;
}
}
这段代码的逻辑说明只有一句:常量类负责「字节是什么」,打印类负责「什么时候写」,构造器负责「写到哪里」。参数上,out 是唯一依赖,调用方必须保证它在打印期间可用;库本身不打开流,也不关闭流,流的生命周期交给调用方。byte[] 常量是只读的,write 不会修改数组内容,多个打印任务共用同一组常量没有问题;但同一个输出流不要被多个线程同时写,打印任务最好串行化,否则字节顺序会乱。
2.4 常量类的摆放与复用边界
常量类独立成一个文件,不要塞进业务类,也不要在每个打印方法里重新 new byte[]。前者会导致业务类越来越重,后者会让指令定义散落,改一个切纸字节要全局搜索。用 byte[] 而不是字符串拼十六进制,是因为字符串很容易多一个空格、大小写不一致,再转回字节时又引入一次编码转换,出错点反而变多。
功能库的边界也要提前划清:它只负责写字节,不负责重试、不负责弹窗、不负责判断打印机是否在线。连接失败是调用方的事,打印失败是调用方决定重打还是提示的事。库如果吞掉 IOException,上层就失去了「这单到底出没出票」的判断依据。我一般让 printOrderTicket 直接 throws IOException,调用方拿到异常后记录订单号,整单重打,而不是从中间续打。
3. 功能库落地:一张取餐小票从初始化到切纸的调用链
3.1 调用顺序:初始化、标题、复位、明细、合计、走纸、切纸
把六条指令串成一个方法,顺序比代码技巧更重要。下面这段是食堂取餐小票的核心方法,输出流从构造器传入,方法只关心业务数据和指令顺序:
java复制public void printOrderTicket(String orderNo, String windowName,
List<OrderItem> items, String totalAmount) throws IOException {
out.write(INIT);
// 标题倍宽倍高居中
out.write(ALIGN_CENTER);
out.write(FONT_DOUBLE);
writeGbkLine(windowName + " 取餐单");
out.write(FONT_NORMAL);
writeGbkLine("订单号:" + orderNo);
writeGbkLine("--------------------------------");
// 明细左对齐
out.write(ALIGN_LEFT);
for (OrderItem item : items) {
writeGbkLine(item.getDishName() + " x" + item.getQuantity()
+ " ¥" + item.getPrice());
}
writeGbkLine("--------------------------------");
writeGbkLine("合计:¥" + totalAmount);
writeGbkLine("");
out.write(FEED_3_LINES);
out.write(CUT_PAPER);
out.flush();
}
private void writeGbkLine(String text) throws IOException {
// 热敏打印机大多按 GBK 解码,不能用 UTF-8
out.write(text.getBytes("GBK"));
out.write(LF);
}
逻辑说明分四段看。第一段 INIT 必须在最前,清掉上一单可能残留的放大字体和对齐方式;第二段 ALIGN_CENTER 加 FONT_DOUBLE 只作用于标题,标题写完立刻 FONT_NORMAL 复位,否则后面的订单号和明细都会变成倍宽倍高;第三段 ALIGN_LEFT 切回左对齐,循环写明细,每条明细后面由 writeGbkLine 自动补 LF;第四段是收尾,先写一条空行,再走纸三行,最后部分切纸,flush 放在切纸之后,确保缓冲区里的字节都推出去。
参数上,windowName 会进标题,长度要控制,倍宽倍高下同样字数占的纸宽更大;orderNo 只做展示,不要在这个方法里做业务校验;items 依赖 getDishName()、getQuantity()、getPrice() 三个取值方法;totalAmount 用字符串传入,金额格式化留在调用方,库内不再做一次计算,避免引入浮点误差。
3.2 参数怎么传:把格式化责任留在业务层
| 参数 | 类型 | 作用 | 注意点 |
|---|---|---|---|
orderNo |
String |
订单号展示 | 只负责打印,不在这里查库或校验状态 |
windowName |
String |
窗口名进标题 | 太长会换行,倍宽倍高下更明显 |
items |
List<OrderItem> |
菜品明细 | 依赖三个取值方法,空列表要提前拦 |
totalAmount |
String |
合计金额 | 调用方格式化好再传,库内不计算 |
明细列表不建议无限长。一张小票超过十几行,打印时间、走纸长度和切纸位置都会变得难控制,常见做法是在业务层限制单票明细行数,超出就分页或另打汇总单。空列表也要在调用前拦住,不然会打出一张只有标题和合计的票,现场看起来像漏打了。
3.3 先用 FileOutputStream 跑通,再换 Socket 输出流
功能库最大的好处是能先在本地把字节跑一遍。下面这段冒烟测试不连打印机,只把整张票写进文件,跑完用十六进制查看器核对字节:
java复制public class TicketSmokeTest {
public static void main(String[] args) throws IOException {
try (OutputStream out = new FileOutputStream("ticket.bin")) {
EscPosPrinter printer = new EscPosPrinter(out);
List<OrderItem> items = Arrays.asList(
new OrderItem("宫保鸡丁", 1, "18.00"),
new OrderItem("米饭", 2, "2.00"));
printer.printOrderTicket("20240501-001", "3号窗口", items, "22.00");
}
}
}
这段代码的逻辑是:用 FileOutputStream 替代 Socket 输出流,try-with-resources 负责关闭文件,EscPosPrinter 完全不知道输出目的地变了。参数上,OrderItem 按项目里的实际构造方式创建,这里只示意名称、数量、价格三个字段;ticket.bin 是本地文件名,跑完可以用十六进制查看器打开,先看开头是不是 1B 40,再看标题后有没有 1D 21 00,最后看结尾是不是 1D 56 01。字节不对,真机一定不对;字节对了真机还不对,再去查打印机设置和连接。
3.4 writeGbkLine 与 flush:编码和缓冲的两个关键点
writeGbkLine 虽小,却是功能库最该锁死的地方。它做两件事:把文本按 GBK 转成字节,再补一个 LF。getBytes("GBK") 会抛 UnsupportedEncodingException,它是 IOException 的子类,所以方法签名写 throws IOException 就能覆盖。每条文本写完立即追加 LF,是为了让打印机在异常或断电时知道行边界,不至于把两行粘在一起。
flush 只放在切纸之后,不要每写一行就刷一次。如果输出流外面包了 BufferedOutputStream,flush 的作用是把缓冲里的字节推出去;如果直接是 Socket 输出流,flush 至少能保证 Java 侧没有攒着没发的数据。库不关闭流,调用方用 try-with-resources 或 finally 关闭,这样连接失败和打印失败能分开处理。
4. 功能库避坑:中文乱码、半切不切断与丢行的排查
打印这层的问题有个共同点:现象都在纸上,原因都在字节里。下面五条是实际踩过的,按「现象 → 原因 → 解决」写,方便对着小票直接定位。
4.1 中文全是问号:编码没有固定成 GBK
现象:英文、数字、分隔线都正常,中文变成一排 ???? 或方块,换一台打印机依旧。
原因:writeGbkLine 里用了 text.getBytes() 默认编码,或者随手写了 UTF-8。热敏打印机按 GBK 解码,字节对不上就显示问号。这个问题很玄学的地方在于:开发机默认编码可能是 UTF-8,本地文件看着正常,一到真机就翻车。
解决:在功能库里强制 text.getBytes("GBK"),所有文本只走这一个方法,不允许业务代码自己转字节。再用 FileOutputStream 打一段中文,十六进制查看器里确认是 GBK 双字节,而不是 UTF-8 的三字节。如果字节对了真机还是乱码,去查打印机自身的字符集或代码页设置。
4.2 小票打到一半停住,重启后从中间开始:攒字节加没有逐行 LF
现象:明细打到一半打印机停了,重启后接着打,前面缺行或者两行粘在一起,现场只能重打。
原因:把整张票拼成一个大字符串一次写,异常或断电时缓冲区只出去一部分;或者文本之间没有 LF,打印机分不清行边界。材料里的做法是每条文本写完立即追加 LF,这个习惯就是针对这个问题的。
解决:坚持逐行 write 加 LF,切纸前再 flush;调用方捕获 IOException 后按订单号整单重打,不要尝试从中间续打。续打看似省纸,实际会让一张票的行序错乱,后面对账更麻烦。
4.3 切纸只切一半,票撕不下来:1D 56 01 是部分切纸
现象:纸被切出一道虚线但没有断,撕下来毛边,严重时票被扯变形。
原因:1D 56 01 是部分切纸,半切不切断,不是故障;再叠加走纸行数不够,切刀位置压在小票内容上,撕票体验更差。
解决:先确认机型支持的切纸模式,按手册决定用部分切还是全切;走纸三行不够就加大 1B 64 n 的 n,让切刀落在空白区。不要在不清楚机型能力时乱换切纸字节,换错模式可能直接不切。
4.4 标题之后明细也变大:FONT_DOUBLE 没有复位
现象:窗口名是倍宽倍高,订单号、明细、合计也跟着变大,一张票打不下,换行乱七八糟。
原因:1D 21 11 是状态指令,设置后影响后续所有行,代码里只写了放大,没有写 1D 21 00 复位。
解决:标题打完立即 out.write(FONT_NORMAL),把「放大-复位」成对写在一个方法里,避免中间插入其他逻辑时漏掉。更稳的做法是把标题封装成 printTitle(),内部固定先放大后复位,业务层不直接碰字体指令。
4.5 单测跑不了:构造器直接收了 Socket
现象:打印类一跑就要连真机,CI 上直接抛连接异常;想改格式只能在窗口反复试,改一次打一张废票。
原因:构造器或静态方法里直接建连接,传输层和指令层绑死,测试没有入口。
解决:构造器只收 OutputStream,测试传 FileOutputStream 或 ByteArrayOutputStream,真机再换 Socket 输出流。这样格式改动可以先在文件里比对字节,确认无误再上真机,废票数量会明显下降。
5. 功能库的验证与复用:文件流回放与真机联调顺序
5.1 先比字节,再上真机
每次改完指令顺序或编码,先跑一遍文件流测试,用十六进制查看器按下面这张表核对。字节不对,真机一定不对;字节对了,真机的问题才可能是连接、打印机设置或硬件。
| 核对点 | 期望字节 | 说明 |
|---|---|---|
| 文件开头 | 1B 40 |
初始化必须在最前 |
| 标题之后 | 1D 21 00 |
字体复位,防止明细变大 |
| 明细之前 | 1B 61 00 |
左对齐,避免继承居中 |
| 切纸之前 | 1B 64 03 |
走纸三行,给切刀留位置 |
| 文件结尾 | `1D |
