JFreeChart

项目背景与战略目标

JFreeChart 是 Java 生态中历史最悠久、功能最全面的开源 2D 图表库，支持生成折线图、柱状图、饼图、散点图、甘特图等 20+ 种专业图表，并可直接导出为 PNG、JPEG、PDF、SVG 等格式。它广泛应用于企业级报表系统、监控大屏后端渲染及自动化数据分析场景。然而，传统 JFreeChart 强依赖 Java 2D (Graphics2D) 和 AWT/Swing 组件，导致在无图形界面（Headless）的服务器环境中配置复杂、字体渲染易乱码、内存占用高且并发性能受限。

本项目旨在利用仓颉编程语言（Cangjie Language）重构 JFreeChart 的核心渲染引擎与数据模型，剥离对 AWT/Swing 的重依赖，构建一款原生、轻量、高并发的服务端图表库。

• 去 GUI 化重构：彻底移除对 AWT/Swing 的依赖，基于仓颉原生图形原语实现矢量绘制，完美适配 Linux 无头服务器环境，解决中文乱码与字体缺失痛点。

• 性能跃升：利用仓颉值类型优化图表对象内存布局，通过轻量级线程实现万级并发下的图表批量生成，消除 GC 停顿。

• 多格式输出：原生支持高分辨率位图（PNG/JPEG）及矢量图（SVG/PDF）导出，渲染质量超越 Java 2D 默认实现。

• 动态交互支持：虽然主打服务端渲染，但保留数据结构的可序列化能力，便于前端交互式图表库（如 ECharts）的数据对接。

核心功能需求与技术规格

功能模块分解

非功能性需求规范

• 性能指标：单张复杂图表（含 1000+ 数据点）生成耗时 < 10ms，内存占用比 Java 实现降低 50%，支持 5k+ QPS 并发导出。

• 安全要求：杜绝图像解析中的缓冲区溢出风险；限制单次渲染的最大内存与 CPU 消耗，防止 DoS 攻击。

• 可靠性：在数据异常（如空数据、极大值）下能降级渲染或抛出明确错误，不崩溃。

• 可维护性：绘图引擎与具体图表类型解耦，易于扩展新的图表种类（如热力图、雷达图）。

核心接口设计示例 (伪代码)

// 定义数据集接口
interface Dataset {
    func getRowCount(): Int32
    func getColumnCount(): Int32
    func getValue(row: Int32, col: Int32): Double?
}

// 定义图表配置
struct ChartConfig {
    title: String
    width: Int32
    height: Int32
    theme: ChartTheme
    fontFamily: String // 支持指定中文字体
}

// 定义绘图上下文
class DrawingContext {
    func drawLine(x1: Double, y1: Double, x2: Double, y2: Double, style: StrokeStyle): Unit
    func drawRect(x: Double, y: Double, w: Double, h: Double, fill: FillStyle): Unit
    func drawPath(path: Path, style: StrokeStyle): Unit
    func drawText(text: String, x: Double, y: Double, font: Font): Unit
}

// 核心图表工厂
object ChartFactory {
    func createBarChart(dataset: CategoryDataset, config: ChartConfig): Chart
    func createLineChart(dataset: XYDataset, config: ChartConfig): Chart
    func createPieChart(dataset: PieDataset, config: ChartConfig): Chart
}

// 图表导出接口
class Chart {
    func renderToBufferedImage(format: ImageFormat): ByteArray
    func renderToSvg(): String
    func renderToPdf(): ByteArray
}

项目交付物与实施路线图

阶段性交付物清单

• 第一阶段：基础数据模型 + 矢量绘图引擎核心 + 柱状图/折线图渲染 + PNG 导出 + 单元测试。

• 第二阶段：饼图/散点图等更多图表类型 + SVG/PDF 导出 + 中文字体适配 + 性能优化。

• 第三阶段：高级特性（组合图、动态更新）+ 压力测试报告 + 生产级部署指南 + cjpm 发布包。

项目实施路线图

技术实现规范与质量认证体系

仓颉语言专项质量规范

• 编码规范：100% 符合仓颉语言官方编码规范，通过 cjfmt 自动格式化校验。

• 类型安全：充分利用泛型处理不同类型的数据集，减少运行时转换。

• 错误处理：显式声明异常类型，所有渲染错误必须转换为业务友好的错误码。

测试与验证标准

• 单元测试：核心模块行覆盖率≥95%，重点覆盖边界数据、空数据及极端值。

• 视觉回归测试：建立基准图片库，自动对比仓颉版与 Java 版 JFreeChart 的渲染输出，确保像素级一致（或更优）。

• 兼容性测试：生成的 SVG/PDF 文件需在主流阅读器（Chrome, Adobe Reader）中完美展示。

文档与可维护性

• API 文档：代码须包含规范的文档注释，详细说明图表配置项及导出参数。

• 架构决策记录（ADR）：记录关于绘图引擎选型及字体处理策略的技术依据。

• 贡献指南：明确仓颉项目构建、调试、提交全流程规范。

持续集成质量门禁

#!/bin/bash
# PR 自动化流水线脚本

# 1. 格式检查
cjpm fmt --check

# 2. 构建检查
cjpm build
cjpm build --release

# 3. 静态 lint 检查
cjpm lint --deny-warnings

# 4. 全量测试与覆盖率
cjpm test --all-features --coverage

# 5. 视觉回归测试 (对比基准图)
cjpm test --suite visual-regression

# 6. 性能基准测试
cjpm bench

技术栈与开发环境

• 核心语言：仓颉编程语言（Cangjie Language）1.0.0 及以上版本（强制）。

• 构建与包管理：CJPM (Cangjie Package Manager)。

• 测试框架：仓颉原生测试框架。

• 质量工具：cjfmt, cjpm lint, cjpm bench。

• 环境要求：仓颉 1.0.0+ 标准工具链，CI 环境需安装基础字体库用于测试。

交付件

验收标准

1.功能

1. 三方库必须有明确的功能；

2. 如果参考对标库移值开发，功能与参考三方库保持一致。

2.资料

1. Readme：包含简介，软件架构，目录结构，下载安装（编译构建），接口说明，使用示例，约束限制，开源协议，参与贡献等内容；

2. Changelog，三方库版本需包含基本的修改说明。

3.标准遵从性（可选），三方库实现需满足对应协议或行业标准，举例

1. appquth：支持对OAuth 的PKCE扩展；

2. icu4j：支持unicode标准库，通用字符集ISO/IEC 10646。

4.性能目标

1. 性能敏感三方库接口运行性能持平对标三方库

5.开源协议遵从，必须包含License文件

1. 放置合适的开源License协议，建议Apache License Version 2.0；

2. 引用或参考开源三方库，需遵从开源协议。

6.网络安全要求

1. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求