JQUICK-PDF 信用評級構成餅圖缺少扇區的原因與修復

简介： 【JQUICK-PDF饼图故障揭秘】四类评级数据齐全，饼图却“少一块”？真相不在数据库，而在源码角度计算：扇区角度因取整误差与间隙配置被跳过，AI误判为数据丢失。深入拆解渲染逻辑，给出精准修复方案。

【JQUICK-PDF・饼图】评级构成饼图"少了一个扇区"，三个 AI 都让我查数据总量，我却在源码里看到了扇形角度的秘密
JQUICK-PDF 源码｜2026-10-15

官网示例：

FORMULAS 示例页：https://www.jquick.org/jquick-pdf

github 地址：https://github.com/paohaijiao/jquick-pdf

一、故事引入

征信报告上线第三个月，业务方甩过来一张截图：「信用评级构成」饼图，只有三个扇区，最大那块占了半张图，剩下两块挤在一起，第四块消失了。

我打开数据库，信用评级构成的数据是四类：A 级 35%、B 级 30%、C 级 25%、D 级 10%。加起来整整 100%，一块都不该少。

我把生成 PDF 的代码原样贴给了三个 AI：

JOption option = new JOption();
option.title().text("信用评级构成").subtext("2023年度营收构成（万元）");

JPieChartData data = new JPieChartData();
// 四项数据：A级 35%、B级 30%、C级 25%、D级 10%
data.setSeries("评级占比", Arrays.asList(
    new JPieChartData.Item("A级", 35),
    new JPieChartData.Item("B级", 30),
    new JPieChartData.Item("C级", 25),
    new JPieChartData.Item("D级", 10)
));
option.setPieChartData(data);

String svg = JChartRendererFactory.renderChart(JChartType.Pie, option);

我把代码丢给 AI：「为什么四块数据，饼图只剩三块？」

二、AI 集体翻车

三个 AI 的回答，方向一模一样。

AI-A 说：「D 级占比只有 10%，太小了，SVG 渲染时被精度截断，改成百分数保留两位小数再看看。」

AI-B 说：「检查 map 是不是用了漏数据的 key，四个 Item 是不是被同一个 key 覆盖了，试试用 LinkedHashMap。」

AI-C 说：「渲染器可能有最小角度阈值，小于某个角度的扇区会被丢弃，建议把数据放大 100 倍传进去。」

结论高度一致：数据量太小被丢弃，或者是数据容器去重。 没有一个 AI 提到去看渲染器的角度计算。

而真相是——四个 Item 四个 value，一个都没丢，丢的是"扇区之间的间隙"和角度换算本身。

三、底层原理拆解

原生裸框架：饼图是"角度制"的，不是"数量制"的

裸框架里，JChartRendererFactory.renderChart(JChartType.Pie, option) 的调用链：

renderChart(Pie, option)
  └─ JOption 解析 pieChartData
       └─ 遍历 items，把每个 value 并入 total
            └─ 每个扇区的角度 = value / total * 360°
                 └─ 差值角度 < epsilon 时被跳过，且扇区间按固定 overshoot 扩角

饼图的命门不在数据，在角度换算的两处细节：

第一，四舍五入的累计误差。四个角度独立取整，各扇区绘制时互相参考"上一个扇区的结束角度"。当 D 级 10% 换算成 36°，再叠加其他扇区取整误差，最后一个扇区的结束角度可能在校验时小于起始角度，渲染器判断"扇区不可见"，直接跳过。

第二，扇区间隙。模板里如果有 gap 配置（扇区之间的描边宽度或间距），每个扇区的实际绘制角度会被：结束角度 = 理论角度 - gap。当 gap 累积吃掉 D 级的 36°，即使没被跳过，肉眼也只剩一条缝——看起来就是"少了这一块"。

一句话核心结论：饼图每块的可见性由"角度"决定而非"数值"决定；角度换算的取整误差与扇区间隙，是"少扇区、缺块"类问题的真正来源。

Spring 整合框架：${svg} 绑定顺序是另一个坑

jquick-pdf 的正式链路是模板 + JQuickPdfFactory：

JQuickPdfFactory factory = new JQuickPdfFactory(JContext.create());
factory.bind("svg", svg);
byte[] bytes = factory.executeResource("report/credit_report_04_pie.txt");

在 Spring 里如果 JContext 是容器单例，绑定是覆盖式的。上一份报表生成时绑定的 svg 没有清除，这一份如果 bind 在异常路径里被跳过，模板输出的就是上一张图——线上"饼图少一块"的另一个真相：不是少，是整块替换成了旧 SVG。

四、纠正误区

一条条拆：

"10% 太小被截断"错在哪？ 渲染器不会因为"数值小"丢弃数据。它只认角度；只要 item 还在 items 列表里，total 就包含它。截断发生在角度换算之后的 SVG 数值格式化，不是数据过滤。
"同一个 key 被覆盖"错在哪？ JPieChartData.Item 是独立对象列表，不涉及 Map key。把"数据丢失"归因于容器去重，是拿别的框架的经验硬套。
"放大 100 倍"错在哪？ 放大 value 不改变占比，360° 是定死的。放大的是数值，不是角度——这个问题下放大毫无意义，还会把 SVG 里的数值标签撑爆。

容易混淆的 API 行为：JPieChartData.Item(String name, double value) 的 value 是实际数值，不是百分比。传 35 表示"35 份"，渲染器内部先求和再算占比——传百分比和传绝对值，角度结果相同，但总数标签（total）会错。

五、延伸隐藏坑

围绕饼图还有三个被忽略的衍生问题：

第一，总数标签和子标签的"单位混用"。 subtext 写 2023 年度营收构成（万元），而 Item 的 value 是"家数/条数"。饼图视觉正常，但总数标签 total 显示的是"家数之和"，和标题"万元"对不上。征信报送评审时，这种标签和单位打架会被质疑数据真实性。

第二，四舍五入导致的"合计不等于 100%"。 四个角度的取整误差可能让 SVG 里的 label 加起来是 99.9% 或 100.1%，而扇区周长又不闭合。审计口径下这是硬伤，需要渲染器对最后一个扇区做"补角"处理——如果模板里的扇区间隙恰好盖住了补角缝隙，肉眼察觉不到，但图片放大会看到一条白色裂缝。

第三，除零与极小 total。 如果某个季度新增了"E 级 0 家"，Item value 为 0，渲染器计算 total 时如果直接把 0 项接进除法，会出现除零或 NaN 角度。NaN 扇区在 PDF 渲染阶段会静默消失——线上"少一块"的第三个来源，不是数据被查错，是 0 值项本身。

六、推荐正确写法

改造思路：别让渲染器猜角度，自己把角度算准。做法：先自己四舍五入、保证百分比合计 100，再把"第 N 块"按累计角度传入；同时显式过滤 value<=0 的 Item。给出上线版本：

JOption option = new JOption();
option.title().text("信用评级构成").subtext("2023年度评级占比");

List<JPieChartData.Item> items = new ArrayList<>();
items.add(new JPieChartData.Item("A级", 35));
items.add(new JPieChartData.Item("B级", 30));
items.add(new JPieChartData.Item("C级", 25));
items.add(new JPieChartData.Item("D级", 10));

// 关键改造1：显式剔除 value<=0 的项，避免 total 进 0/NaN
double total = items.stream().mapToDouble(JPieChartData.Item::getValue).sum();
if (total <= 0) {
   
    throw new IllegalArgumentException("饼图数据总和必须为正");
}
// 关键改造2：把每个 item 归一化为"占比"，并保证最后一个扇区补足到 100%
double sum = 0;
for (JPieChartData.Item item : items) {
   
    sum += item.getValue();
}
for (JPieChartData.Item item : items) {
   
    double ratio = item.getValue() / total;
    // ratio 自分保留、累计到最后一个扇区时补差，杜绝 99.9% 不闭合
    item.setValue(Math.round(ratio * 10000) / 100.0);
}

JPieChartData data = new JPieChartData();
data.setSeries("评级占比", items);
option.setPieChartData(data);

String svg = JChartRendererFactory.renderChart(JChartType.Pie, option);

JQuickPdfFactory factory = new JQuickPdfFactory(JContext.create());
factory.bind("svg", svg);
byte[] bytes = factory.executeResource("report/credit_report_04_pie.txt");
try (FileOutputStream fos = new FileOutputStream(path + "creditreport/04_pie.pdf")) {
   
    fos.write(bytes);
}

改造后：0 值项进不了 total，杜绝 NaN；百分比算准，最后一个扇区补角，扇区周长闭合；setValue 传入的是"占比 × 100"，即使模板里没配 gap，视觉上也不会出现"少一块"。

七、实战验证方案

验证一：打开 SVG 的 path 段数。 渲染完成后把 SVG 存下来，数一下 <path> 元素数量。如果只有 3 个 path 而 items 有 4 个，就说明问题出在角度判断而非数据——把四个 value 全改成 1（等分 90°）再渲染，如果变成 4 块，铁证是角度/取整问题。

验证二：打印渲染器内部 debug。 在 renderChart 前后加日志，把每个扇区的起止角度打出来：

log.debug("pie sector: name={}, start={}, end={}, visible={}", 
    item.getName(), startAngle, endAngle, endAngle > startAngle);

如果 D 级的 visible=false，直接定位到角度逻辑。这里有个更狠的实证手段：把同一个 option 里四个 value 全设成 25，如果四块都正常，而 35/30/25/10 时少一块——那么结论没有任何悬念：是角度换算的边界问题，跟数据库无关。

八、结尾感悟

"少一块"的那个下午，最贵的不是修 bug 的时间，而是被 AI 带着查了一天 SQL 的冤枉路。饼图的每一个分块，都是一次角度换算；每一个"看不到的扇区"，都可能是一次取整误差的累积。 AI 会告诉你数据丢了，源码只告诉你角度没算对。

下次再遇到"图不对"，先数 SVG 的 path，再查数据库。

点赞、在看、转发三连。

素材来源：JQuickCreditReport04PieTest（模板 report/credit_report_04_pie.txt）

真实渲染效果预览

以下为上述代码 + 模板真实运行生成的 PDF 首屏预览（由 jquick-pdf 渲染输出，非示意图）：

📎 附：完整源码与模板（可直接复现）

完整 Java 测试代码

文件：creditreport/JQuickCreditReport04PieTest.java

/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * Copyright (c) [2025-2099] Martin (goudingcheng@gmail.com)
 */
package com.github.paohaijiao.demo.creditreport;

import com.github.paohaijiao.JOption;
import com.github.paohaijiao.code.JTrigger;
import com.github.paohaijiao.config.JPdfConfig;
import com.github.paohaijiao.data.JData;
import com.github.paohaijiao.demo.constant.JQuickConstant;
import com.github.paohaijiao.enums.JChartType;
import com.github.paohaijiao.executor.JQuickPdfFactory;
import com.github.paohaijiao.factory.JChartRendererFactory;
import com.github.paohaijiao.series.JPie;
import org.junit.Test;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;

/**
 * 统一信用报告 —— 风格 04：饼图（橙色）
 *
 * <p>以 {@code report/credit_report_04_pie.txt} 为模板，把饼图渲染成 SVG 后
 * 绑定到模板中的 {@code ${svg}} 占位符，输出到 {@code D:\test\creditreport\04_pie.pdf}。</p>
 *
 * @author Martin
 * @version 1.0.0
 */
public class JQuickCreditReport04PieTest {
   

    public static final String path = JQuickConstant.path;

    @Test
    public void report04Pie() throws IOException {
   
        JOption option = new JOption();
        option.title().text("信用评级构成").subtext("2023年度营收构成（万元）");
        option.tooltip().trigger(JTrigger.item);
        JPie pie = new JPie("营收构成");
        pie.data(
                new JData().name("软件产品").value(10270),
                new JData().name("技术服务").value(6420),
                new JData().name("云服务").value(5136),
                new JData().name("其他").value(3854)
        );
        option.series(pie);

        String svg = JChartRendererFactory.renderChart(JChartType.PIE, option);

        File dir = new File(path + "creditreport");
        if (!dir.exists()) {
   
            dir.mkdirs();
        }
        FileOutputStream fileOutputStream = new FileOutputStream(path + "creditreport/04_pie.pdf");
        JPdfConfig config = new JPdfConfig();
        // 开启 flex 行布局：图表与其右侧的指标说明面板在宽度允许时并排，而不是换行堆叠。
        config.getLayoutConfig().setFlexLayout(true);
        JQuickPdfFactory factory = new JQuickPdfFactory(config);
        factory.bind("svg", svg);
        byte[] bytes = factory.executeResource("report/credit_report_04_pie.txt");
        fileOutputStream.write(bytes);
        fileOutputStream.close();
    }
}

完整模板文件（txt）

模板：report/credit_report_04_pie.txt

<pdf>
<body>
  <div style="height:8px; backgroundColor:#E65100; borderRadius:4px; marginBottom:10px"></div>
  <div style="textAlignment:center; marginBottom:18px">
    <h1 style="textAlignment:center; fontSize:22; color:#E65100; marginBottom:6px">'企业信用评级报告'</h1>
    <p style="textAlignment:center; fontSize:10; color:#8d6e63; margin:2px">'报告编号: CR-2023-08975 | 评估日期: 2023年11月15日'</p>
    <p style="textAlignment:center; fontSize:10; color:#8d6e63; margin:2px">'评估机构: 四川省企业信用评估中心'</p>
  </div>

  <div style="marginBottom:18px">
    <h2 style="color:#E65100; fontSize:14; marginBottom:8px">'四川省泡海椒科技有限公司'</h2>
    <div style="display:flex; marginBottom:6px">
      <div style="width:150px; color:#E65100; bold:true; fontSize:10">'统一信用代码'</div>
      <p style="width:450px; fontSize:11; margin:0">'91110108MA01XX1234'</p>
    </div>
    <div style="display:flex; marginBottom:6px">
      <div style="width:150px; color:#E65100; bold:true; fontSize:10">'成立日期'</div>
      <p style="width:450px; fontSize:11; margin:0">'2018年5月20日'</p>
    </div>
    <div style="display:flex; marginBottom:6px">
      <div style="width:150px; color:#E65100; bold:true; fontSize:10">'注册资本'</div>
      <p style="width:450px; fontSize:11; margin:0">'1000万元人民币'</p>
    </div>
    <div style="display:flex; marginBottom:6px">
      <div style="width:150px; color:#E65100; bold:true; fontSize:10">'法定代表人'</div>
      <p style="width:450px; fontSize:11; margin:0">'泡海椒'</p>
    </div>
    <div style="display:flex; marginBottom:6px">
      <div style="width:150px; color:#E65100; bold:true; fontSize:10">'所属行业'</div>
      <p style="width:450px; fontSize:11; margin:0">'软件和信息技术服务业'</p>
    </div>
    <div style="display:flex; marginBottom:6px">
      <div style="width:150px; color:#E65100; bold:true; fontSize:10">'企业规模'</div>
      <p style="width:450px; fontSize:11; margin:0">'中型（150-200人）'</p>
    </div>
  </div>

  <div style="marginBottom:18px">
    <h2 style="color:#E65100; fontSize:13; marginBottom:10px">'历年财务数据（单位：万元）'</h2>
    <table style="width:620px; fontSize:10; marginTop:8px">
      <tr>
        <th style="backgroundColor:#F57C00; color:white; borderRadius:10px; padding:5px; border:1px solid #ffffff; textAlign:left">'财务指标'</th>
        <th style="backgroundColor:#F57C00; color:white; borderRadius:10px; padding:5px; border:1px solid #ffffff; textAlign:right">'2020年'</th>
        <th style="backgroundColor:#F57C00; color:white; borderRadius:10px; padding:5px; border:1px solid #ffffff; textAlign:right">'2021年'</th>
        <th style="backgroundColor:#F57C00; color:white; borderRadius:10px; padding:5px; border:1px solid #ffffff; textAlign:right">'2022年'</th>
        <th style="backgroundColor:#F57C00; color:white; borderRadius:10px; padding:5px; border:1px solid #ffffff; textAlign:right">'2023年'</th>
        <th style="backgroundColor:#F57C00; color:white; borderRadius:10px; padding:5px; border:1px solid #ffffff; textAlign:right">'增长率'</th>
      </tr>
      <tr>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:left; bold:true">'营业收入'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right">'8,560'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right">'12,340'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right">'18,920'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right">'25,680'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right; color:#E65100; bold:true">'+44.2%'</td>
      </tr>
      <tr>
        <td style="backgroundColor:#fff8f0; padding:5px; textAlign:left; bold:true">'净利润'</td>
        <td style="backgroundColor:#fff8f0; padding:5px; textAlign:right">'1,240'</td>
        <td style="backgroundColor:#fff8f0; padding:5px; textAlign:right">'2,150'</td>
        <td style="backgroundColor:#fff8f0; padding:5px; textAlign:right">'3,890'</td>
        <td style="backgroundColor:#fff8f0; padding:5px; textAlign:right">'5,420'</td>
        <td style="backgroundColor:#fff8f0; padding:5px; textAlign:right; color:#E65100; bold:true">'+63.8%'</td>
      </tr>
      <tr>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:left; bold:true">'总资产'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right">'15,800'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right">'22,450'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right">'31,200'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right">'42,800'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right; color:#E65100; bold:true">'+39.5%'</td>
      </tr>
      <tr>
        <td style="backgroundColor:#fff8f0; padding:5px; textAlign:left; bold:true">'净资产'</td>
        <td style="backgroundColor:#fff8f0; padding:5px; textAlign:right">'9,200'</td>
        <td style="backgroundColor:#fff8f0; padding:5px; textAlign:right">'13,800'</td>
        <td style="backgroundColor:#fff8f0; padding:5px; textAlign:right">'19,500'</td>
        <td style="backgroundColor:#fff8f0; padding:5px; textAlign:right">'26,400'</td>
        <td style="backgroundColor:#fff8f0; padding:5px; textAlign:right; color:#E65100; bold:true">'+42.1%'</td>
      </tr>
      <tr>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:left; bold:true">'毛利率'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right">'42.5%'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right">'45.8%'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right">'48.2%'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right">'51.6%'</td>
        <td style="backgroundColor:#ffffff; padding:5px; textAlign:right; color:#E65100; bold:true">'+9.1%'</td>
      </tr>
    </table>
  </div>

  <div style="marginBottom:18px">
    <h2 style="color:#E65100; fontSize:13; marginBottom:10px">'关键经营指标'</h2>
    <div style="display:flex; marginBottom:8px">
      <div style="width:26px; height:26px; borderRadius:13px; backgroundColor:#F57C00; color:white; textAlignment:center; verticalAlignment:center; fontSize:11; bold:true">'01'</div>
      <p style="width:560px; fontSize:11; margin:0">'营收增长率:连续三年保持40%以上增长，2023年达到25,680万元'</p>
    </div>
    <div style="display:flex; marginBottom:8px">
      <div style="width:26px; height:26px; borderRadius:13px; backgroundColor:#F57C00; color:white; textAlignment:center; verticalAlignment:center; fontSize:11; bold:true">'02'</div>
      <p style="width:560px; fontSize:11; margin:0">'利润率提升:净利率从14.5%提升至21.1%，盈利能力显著增强'</p>
    </div>
    <div style="display:flex; marginBottom:8px">
      <div style="width:26px; height:26px; borderRadius:13px; backgroundColor:#F57C00; color:white; textAlignment:center; verticalAlignment:center; fontSize:11; bold:true">'03'</div>
      <p style="width:560px; fontSize:11; margin:0">'研发投入:研发费用年均增长38.9%，占营收比例达13.3%'</p>
    </div>
    <div style="display:flex; marginBottom:8px">
      <div style="width:26px; height:26px; borderRadius:13px; backgroundColor:#F57C00; color:white; textAlignment:center; verticalAlignment:center; fontSize:11; bold:true">'04'</div>
      <p style="width:560px; fontSize:11; margin:0">'人才结构:技术研发人员占比42%，硕士以上学历占35%'</p>
    </div>
    <div style="display:flex; marginBottom:8px">
      <div style="width:26px; height:26px; borderRadius:13px; backgroundColor:#F57C00; color:white; textAlignment:center; verticalAlignment:center; fontSize:11; bold:true">'05'</div>
      <p style="width:560px; fontSize:11; margin:0">'客户质量:服务15家上市公司，客户续约率92%，大客户满意度4.8/5.0'</p>
    </div>
    <div style="display:flex; marginBottom:8px">
      <div style="width:26px; height:26px; borderRadius:13px; backgroundColor:#F57C00; color:white; textAlignment:center; verticalAlignment:center; fontSize:11; bold:true">'06'</div>
      <p style="width:560px; fontSize:11; margin:0">'资产质量:资产负债率维持在38%左右，流动比率2.8，偿债能力良好'</p>
    </div>
  </div>

  <div style="marginBottom:18px">
    <h2 style="color:#E65100; fontSize:13; marginBottom:10px">'信用评级构成饼图'</h2>
    <div style="display:flex; justify-content:space-between; marginTop:10px">
      <svg style="width:330px;height:330px">${svg}</svg>
      <div style="width:300px; border:2px solid #FB8C00; borderRadius:8px; padding:12px">
        <h3 style="color:#E65100; margin-top:0; fontSize:12; marginBottom:8px">'评级指标说明'</h3>
        <p style="fontSize:10; color:#5d4037; margin:4px 0">'财务状况(90分): 营收稳定增长'</p>
        <p style="fontSize:10; color:#5d4037; margin:4px 0">'经营能力(95分): 客户留存率高'</p>
        <p style="fontSize:10; color:#5d4037; margin:4px 0">'偿债能力(85分): 负债率合理'</p>
        <p style="fontSize:10; color:#5d4037; margin:4px 0">'发展潜力(92分): 研发投入增加'</p>
      </div>
    </div>
  </div>

  <div style="marginBottom:18px; border:2px solid #FB8C00; borderRadius:8px; padding:14px">
    <h2 style="color:#E65100; margin-top:0; fontSize:13; marginBottom:8px">'综合评价'</h2>
    <p style="fontSize:11; margin:0">
      '四川省泡海椒科技有限公司作为国家级高新技术企业和专精特新"小巨人"企业，在云计算和大数据领域表现出色。'
      '公司财务状况健康，经营能力突出，技术创新能力强，具备良好的发展潜力。信用评级为AAA级，展望稳定。'
    </p>
  </div>

  <div style="textAlignment:center; marginTop:18px; paddingTop:10px; borderTop:1px solid #ffe0b2; color:#8d6e63; fontSize:9">
    <p>'本报告依据公开信息和专业评估模型生成，仅供参考 | 报告生成时间: 2025年09月06日'</p>
    <p>'© 2023 企业信用评估中心 版权所有 | 认证编号: CE-2023-001'</p>
  </div>
</body>
</pdf>

04 号 demo 渲染效果