Jsoup Parser

项目背景与战略目标

Jsoup 是 Java 生态中事实标准的 HTML 解析库，以其对“真实世界”混乱 HTML 的极强容错能力、类似 jQuery 的 CSS 选择器 API 以及内置的 XSS 清洗机制而闻名。它广泛应用于后端数据采集、SEO 分析、内容管理系统（CMS）及安全防护场景。然而，在面对海量网页的高并发抓取与解析任务时，Java 版本的 Jsoup 受限于 JVM 启动开销、GC 停顿及对象头内存占用，难以在资源受限的边缘计算节点或超高吞吐量的微服务中发挥极致性能。

本项目旨在利用仓颉编程语言（Cangjie Language）重构 Jsoup 的核心解析引擎与 DOM 模型，构建一款原生、极速、内存安全的 HTML 处理库。

• 极致性能：利用仓颉的轻量级线程（协程）模型实现万级并发下的非阻塞 IO 抓取与解析；通过值类型（Value Types）优化 DOM 树节点的内存布局，大幅降低内存占用。

• 内存安全：彻底消除原生代码调用中的缓冲区溢出风险，确保在处理恶意构造的 HTML 文档时服务不崩溃、不泄漏。

• 标准兼容：完整实现 WHATWG HTML5 解析算法，确保解析结果与现代浏览器（Chrome/Firefox）的 DOM 树高度一致。

• 安全增强：原生集成 XSS 过滤白名单机制，为后端应用提供开箱即用的输入清洗能力。

核心功能需求与技术规格

功能模块分解

非功能性需求规范

• 性能指标：单页解析耗时 < 2ms（中等复杂度），内存占用比 Java 实现降低 60%，支持 10k+ 并发解析任务。

• 安全要求：解析器需具备抗拒绝服务（ReDoS）能力，防止恶意正则或嵌套标签导致 CPU 飙升；清洗模块需覆盖所有已知 XSS 向量。

• 可靠性：在网络中断、编码错误或 HTML 结构严重损坏时，能降级处理或抛出明确错误，不崩溃。

• 可维护性：解析逻辑与 DOM 模型解耦，代码符合仓颉编码规范，易于扩展自定义标签处理。

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

// 定义文档对象
class Document {
    func title(): String
    func body(): Element
    func select(cssQuery: String): List<Element>
    func html(): String
}

// 定义元素节点
class Element {
    func id(): String
    func className(): String
    func text(): String
    func attr(key: String): String?
    func children(): List<Element>
    func parent(): Element?
}

// 核心解析入口
object Jsoup {
    // 从字符串解析
    func parse(html: String, charset: String = "UTF-8"): Result<Document, ParseError>
    
    // 从 URL 抓取并解析 (异步)
    func connect(url: String): ConnectionBuilder
    
    // 清洗 HTML (防 XSS)
    func clean(dirtyHtml: String, whitelist: Whitelist): Result<String, CleanError>
}

// 链式连接构建器
class ConnectionBuilder {
    func timeout(ms: Int32): Self
    func userAgent(ua: String): Self
    func cookie(name: String, value: String): Self
    func get(): Promise<Document>
}

// 预定义白名单
enum Whitelist {
    case None
    case Basic
    case BasicWithImages
    case Relaxed
    case Custom(rules: Map<String, Set<String>>)
}

项目交付物与实施路线图

阶段性交付物清单

• 第一阶段：HTML5 令牌化器 + 树构建器 + 基础 DOM 模型 + 单元测试 (覆盖率≥95%)。

• 第二阶段：CSS 选择器引擎 + 网络抓取模块 + XSS 清洗功能 + 性能基准测试。

• 第三阶段：高级特性（表单处理、元数据提取）+ 压力测试报告 + 生产级部署指南 + cjpm 发布包。

项目实施路线图

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

仓颉语言专项质量规范

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

• 类型安全：充分利用泛型与模式匹配处理 HTML 动态结构，减少运行时类型检查。

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

测试与验证标准

• 单元测试：核心模块行覆盖率≥95%，重点覆盖边界条件、非法标签及嵌套异常。

• 兼容性测试：使用 jsoup 官方测试套件（含大量真实网页样本）进行回归测试，确保解析结果一致。

• 安全扫描：通过仓颉静态分析工具扫描，并通过模糊测试（Fuzzing）验证解析器健壮性。

文档与可维护性

• 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. 兼容性测试 (对比 Java Jsoup 输出)
cjpm test --suite compatibility

# 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. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求