parser-html-json

项目背景与战略目标

在后端数据采集（爬虫）、日志分析、第三方接口适配及内容管理系统中，经常需要处理大量的非结构化或半结构化 HTML 数据，并将其转换为结构化的 JSON 格式以便下游业务处理。现有的 HTML 解析方案多基于 DOM 树构建，内存开销大且遍历速度慢；而正则匹配方案则脆弱且难以处理嵌套复杂的标签。特别是在高并发场景下，低效的解析逻辑极易成为系统吞吐量的瓶颈，且动态语言的弱类型特性容易导致解析错误在运行时才暴露。

本项目旨在利用仓颉编程语言（Cangjie Language）1.0.0+重构 parser-html-json，打造一款零拷贝、流式处理、强类型安全的后端数据解析中间件。

• 极致解析性能：利用仓颉的静态编译优化和手动内存管理潜力，实现基于事件驱动（SAX 风格）或轻量级 DOM 的流式解析，避免全量构建 DOM 树的内存峰值，解析速度提升 5-10 倍。

• 内存安全与可控：依托仓颉所有权机制，精确控制解析过程中的字符串切片与临时对象生命周期，杜绝内存泄漏，适合长运行时的微服务。

• 灵活的 JSON 映射策略：提供声明式的规则引擎，允许用户通过配置或 DSL 定义 HTML 节点到 JSON 字段的映射关系，支持 XPath 类似的选择器语法。

• 强类型错误处理：利用代数数据类型（ADT）显式表达解析成功、部分成功或特定格式错误，杜绝隐式的 null 或异常崩溃，提升系统稳定性。

核心功能需求与技术规格

功能模块分解

非功能性需求规范

• 性能指标：单线程解析吞吐量 > 100MB/s，P99 延迟 < 5ms（针对典型网页片段），内存峰值控制在输入大小的 3 倍以内。

• 安全要求：严格防止 ReDoS（正则表达式拒绝服务）攻击，限制递归深度防止栈溢出；支持白名单过滤危险标签（如 <script>）。

• 可靠性：能够处理截断的 HTML 流、编码混乱（自动检测 UTF-8/GBK）及非标准标签，保证服务不挂起。

• 可维护性：解析规则与核心引擎解耦，支持热加载解析配置，代码具备完善的文档注释。

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

// 定义解析配置
struct ParseConfig {
    extractRules: Map<String, Selector> // 字段名 -> 选择器
    keepWhitespace: Bool
    decodeEntities: Bool
    maxDepth: Int32
}

// 定义选择器 (简化版 CSS/XPath)
enum Selector {
    case Tag(String)          // e.g., "div"
    case Class(String)        // e.g., ".content"
    case Id(String)           // e.g., "#main"
    case Path(String)         // e.g., "div > p.title"
    case Regex(String)        // 文本正则提取
}

// 定义解析结果
enum ParseResult<T> {
    case Success(T)
    case PartialSuccess(T, List<ParseWarning>)
    case Failure(ParseError)
}

// 定义错误类型
enum ParseError {
    case InvalidHtml(String)
    case SelectorMismatch(String)
    case EncodingError(String)
    case DepthExceeded
}

// 核心解析器接口
interface HtmlToJsonParser {
    // 从字符串解析
    func parse(input: String, config: ParseConfig): ParseResult<JsonNode>
    
    // 从字节流解析 (流式处理)
    func parseStream(input: InputStream, config: ParseConfig): ParseResult<JsonNode>
    
    // 批量解析 (并发优化)
    func parseBatch(inputs: List<String>, config: ParseConfig): List<ParseResult<JsonNode>>
    
    // 提取特定字段 (快捷方法)
    func extractField(input: String, selector: Selector): Result<String, ParseError>
}

// 工厂类
object ParserFactory {
    static func createStrict(): HtmlToJsonParser
    static func createLenient(): HtmlToJsonParser // 容忍更多错误
}

项目交付物与实施路线图

阶段性交付物清单

• 第一阶段：核心词法分析器 + 基础 DOM 构建 + 简单选择器实现 + 单元测试 (覆盖率≥95%)。

• 第二阶段：JSON 映射引擎 + 流式解析支持 + 容错机制 + 性能基准测试。

• 第三阶段：高级选择器（XPath 子集）+ 并发批量处理 + 模糊测试 + cjpm 发布包 + 最佳实践文档。

项目实施路线图

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

仓颉语言专项质量规范

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

• 类型安全：充分利用泛型定义解析结果，利用模式匹配 exhaustive check 确保所有错误分支被处理。

• 错误处理：所有解析异常必须通过 Result 类型返回，严禁抛出未捕获的运行时异常。

测试与验证标准

• 单元测试：核心模块行覆盖率≥95%，重点覆盖嵌套标签、自闭合标签、属性缺失、编码错误等边界情况。

• 兼容性测试：使用真实互联网网页数据集（包含大量不规范 HTML）进行回归测试，确保解析成功率。

• 性能基准：建立与 Jsoup (Java), Cheerio (Node.js), BeautifulSoup (Python) 的性能对比基准。

文档与可维护性

• API 文档：代码须包含规范的文档注释，详细说明选择器语法及配置项含义。

• 架构决策记录：记录解析算法选型（如 SAX vs DOM）及内存管理策略的依据。

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

持续集成质量门禁

#!/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 real-world-html-validation

# 6. 性能基准测试 (对比基线)
cjpm bench --threshold 5%

技术栈与开发环境

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

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

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

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

• 环境要求：仓颉 1.0.0+ 标准工具链，CI 环境需预置大规模 HTML 测试数据集。

交付件

验收标准

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

过程质量要求