做开源3年,我不再追求「PDF代码写得快」,只追求「模板维护成本低」

🔶 上一篇我聊了放弃手动算坐标半年踩的坑，后台有朋友问："那你现在做PDF工具，是不是把'写得快'做到极致就行了？"我想了想，发现这恰恰是我这三年走过的弯路——早期我确实在追求写得快，直到被一个改版需求打醒，才明白维护成本才是真问题。

今天这篇就聊聊，我是怎么从"追求写代码速度"转向"压低模板维护成本"的，以及JQuick-PDF在这个转向里具体做了哪些取舍。

问题还原

🟨 先还原那个打醒我的需求。

客户突然说："所有对账单的表头，从单行改成两行——第一行是'客户名称'，第二行是'合同编号'。"

放在以前用坐标写的代码里，这个需求意味着什么？表头从一行变两行，表头自身高度变了，下面表格的起始Y坐标要往下挪；表格行数不变的话，表格底部位置不变，但中间内容区高度变了；如果内容区之前算过分页，那分页阈值也要重新算。

我打开当时那份代码，三百多行，光表头相关的坐标就散落在十几处。改到一半发现，有个Y坐标是写死的"720"，但其实它应该是"上一个元素底部+间距"。我根本不知道这个720是哪来的——是当初拍脑袋写的，还是某次调试留下来的。

那天晚上我改到十一点，第二天早上客户又说："哦对了，这个两行表头只适用于A客户，B客户还是单行。"我当场崩溃。

隐性成本放大

🟨 那次之后我开始统计：过去一年，我花在"写新PDF"上的时间，和花在"改旧PDF"上的时间，到底是几比几？

答案是1:7。

写新报表其实很快，半天就能出一份。但改旧报表是个无底洞：客户换logo、财务加一列、法务改条款、运营要双语版本、合规要求加页码……每份报表在它两三年的生命周期里，平均要被改二十次以上。

每次改都要重新理解上次那个人写的坐标逻辑。如果这份代码是AI生成的，那更惨——连"上次那个人"都不存在，全是没有上下文的魔法数字。

这时候我才意识到：写代码的速度是一次性的，维护成本是持续复利的。你第一次写报表省的那两小时，会在未来二十次改版里，每次都连本带利地讨回来。

核心冲突思辨

🔸 那"写得快"和"维护便宜"到底是什么关系？

我以前以为它们是正相关的——写得越快，维护也越省事。后来发现根本不是。甚至在PDF这个领域，它们常常是负相关的。

为什么？因为最快的写法往往是最耦合的：直接在业务方法里new文档、画坐标、塞数据。写的时候行云流水，但排版逻辑和业务逻辑缠成一团，以后想单独改排版都改不动。

反而那些"看起来写得慢"的写法——把模板抽出来、把样式集中管理、把数据和视图分开——第一次写要多花半小时，但之后每次改版都省几小时。

这就是为什么我不再把"写得快"当目标。写得快解决的是今天的事，维护便宜解决的是未来三年的事。

工程两难分析

想通这一点之后，我做JQuick-PDF的设计目标就变了。

早期版本我做了很多"快捷语法"——一行代码画个表格、一行代码加个水印。听起来很香，但用久了发现，这些快捷语法其实是把"耦合"封装得更隐蔽了。你一行画出来的表格，样式散在那一行的参数里，以后想全局改表头颜色，还是要一个个找。

后来我把方向调成：让模板的每一处样式都有明确的归属，能被集中管理。具体做了几件事：

• 样式单独抽成CSS文件，不混在模板结构里
• 表格的表头、行、单元格用类选择器统一控制
• 页眉页脚、水印作为页面级配置，不写进内容模板
• 字体、边距这些全局项放在配置里，一份配置套所有模板

这样改表头颜色？改CSS里一个类。改全局字体？改配置里一行。不用翻任何业务代码。

方案效果演示

回到那个"两行表头"的需求。用模板写出来是这样的：

<tableclass="stmt">  <theadclass="two-row-header">    <tr><thcolspan="2">客户信息</th></tr>    <tr><th>客户名称</th><th>合同编号</th></tr>  </thead>  <tbody>    <trth:each="r : ${rows}">      <td>${r.name}</td>      <td>${r.contractNo}</td>    </tr>  </tbody></table>

A客户用two-row-header这个类，B客户不加这个类就是单行表头。表格往下排多少、分页怎么处理，引擎自己算。我不需要调任何Y坐标。

之前要改十几处的需求，现在就是加一个CSS类、写两行XML。改完跑一遍，分页自动正确——因为根本没有手动写过分页坐标。

这就是维护成本下降的体感：不是第一次变快，是第二十次改版变快。

多方案横向评估

把"PDF模板怎么写才维护便宜"这件事，几条路对比一下：

• 业务方法里直接画坐标：第一次最快，之后每次改版都像拆炸弹。适合一次性脚本。
• 封装工具类+坐标：减少重复，但样式和位置还是散在调用处，全局改样式依然要到处找。
• HTML转PDF类方案：样式集中了，但浏览器模型和PDF分页模型的差异会在复杂表格上咬人。
• JQuick-PDF这种专用模板引擎：样式集中、分页内建、字体和图表不用自己管。代价是它只支持CSS子集，表达能力不如浏览器。

我必须承认，前三条路各有各的好用场景。工具类封装在项目极小时很实在；HTML转PDF在简单单据上很香。JQuick-PDF不是要取代它们，而是在"模板数量会涨、改版会频繁、需要跨文件统一管理"这个区间里，提供一个更划算的选项。

边界与取舍

🟧 这里要说清楚，追求"维护成本低"是有代价的，JQuick-PDF不适合这些场景。

• 如果你只有两三份PDF，写完再也不改，那模板化的收益为零，直接AI生成或手搓坐标都更省事。
• 如果你的版式需要精确到像素的自由画布排布（比如宣传册、复杂海报），模板的流式模型表达不了，还是得回到坐标绘制。
• 如果你的核心需求是复杂交互式表单、数字签名、PDF/A深度合规，JQuick-PDF不是干这个的，找专门的库。
• 它的CSS支持是子集，不要指望照搬一个现成网页的样式表就能完美出PDF。
• 它不提供可视化拖拽设计器，模板是写出来的，不是拖出来的。

选它的前提：你的模板会持续改、会变多、要跨多份保持一致。没有这个前提，别硬上。

底层设计思考

🟧 为什么维护成本低这件事，在PDF领域特别难做到？

因为PDF本质上是个"绘制指令序列"——每个字画在哪、每条线画在哪，都是写死的。要在这种底层模型上长出"可维护"的上层，就得做一件很费力的事：把"绘制指令"重新编译成"结构声明"。

JQuick-PDF内部做的事，就是在模板和PDFBox的底层绘制之间，加了一层布局引擎。你写的是结构（page、section、table、text），引擎在布局阶段把这些结构算成具体坐标，再调PDFBox画出来。样式在这层被集中应用，分页在这层被统一处理。

字体也是专门处理过的。CJK字体嵌入不用你手动注册字体文件，引擎在生成时自动做子集嵌入——这是早期版本我踩过坑才加上的，不然跨平台中文乱码会把维护成本又拉回去。

项目地址在 GitHub：https://github.com/paohaijiao/jquick-pdf，Maven坐标 io.github.paohaijiao。你可以把它当作一个"把坐标地狱挡在外面"的薄层，而不是一个要你深入学习的大框架。

总结与开放讨论

🟠 做开源三年，我最大的转变是：不再跟别人比"谁写PDF代码更快"，而是比"谁的模板三年后还好改"。

简单复盘：

• 写新报表只占PDF工作量的两成，改旧报表占八成
• 最快的写法往往最耦合，维护成本会复利式增长
• 维护便宜的关键是样式集中管理、数据视图分离、分页字体内建
• 模板化收益有门槛，两三份一次性报表别硬上

留个开放问题：你们团队现在改一份半年前的PDF报表，要花多久？改的时候敢不敢动那段代码？那个时长，就是你技术债的刻度。

下一篇我想接着这个话题聊：既然维护成本这么重要，那为什么我还是不建议全程交给AI生成代码？模板和AI到底该怎么分工？

如果这篇让你重新算了一笔"改版账"，欢迎关注。后续继续聊PDF工程化里那些被忽略的长期成本。

如果这篇教程对你有帮助，欢迎给项目点一个Star⭐，也欢迎关注微信公众号「JQuick 声明式编程」，后续会持续更新模板语法、表单元素与实战案例。你的关注和 Star，是项目持续迭代的最大动力。

GitHub：https://github.com/paohaijiao

官网：http://www.jquick.org

微信公众号：微信搜一搜 JQuick声明式编程

扫码关注更方便 👇

![微信公众号：JQuick声明式编程]