mdurl

项目背景与战略目标

在 Markdown 解析引擎、静态站点生成器（SSG）、富文本编辑器后端服务及内容管理系统（CMS）中，URL 的处理具有特殊性：它不仅需要符合 RFC 标准，还需兼容 Markdown 语法中的特殊字符（如括号、星号、下划线），并处理自动链接识别、转义字符还原等复杂逻辑。现有的通用 URL 解析库往往无法完美适配 Markdown 的宽松语法，导致链接截断、误判或渲染错误；而专为 Markdown 设计的库（如 mdurl for JS）多基于动态语言，存在正则回溯风险（ReDoS）、内存分配频繁及类型不安全等问题。

本项目旨在利用仓颉编程语言（Cangjie Language）1.0.0+重构 mdurl，打造一款专为 Markdown 场景优化、零正则依赖、强类型安全的后端 URL 处理基础库。

• Markdown 语义适配：内置针对 Markdown 语法的特殊解析规则（如平衡括号检测、自动链接边界识别），确保在复杂文本环境中精准提取 URL，避免渲染断裂。

• 极致解析性能：利用仓颉的状态机模式替代正则表达式，彻底消除 ReDoS 风险，实现线性时间复杂度 O(n) 的解析速度，性能较动态语言提升 20-50 倍。

• 内存安全与零分配：依托仓颉所有权机制和 Slice 视图技术，在解析过程中避免子字符串拷贝，直接引用原始缓冲区，大幅降低 GC 压力，适合高并发文档处理服务。

• 智能编码与解码：提供符合 Markdown 规范的 URL 编码/解码策略，智能保留安全字符，自动处理百分号编码，防止双重编码或解码错误。

• 强类型错误处理：利用代数数据类型（ADT）显式表达解析状态（成功、部分匹配、非法字符），杜绝隐式的 null 或异常崩溃，提升解析器的鲁棒性。

核心功能需求与技术规格

功能模块分解

非功能性需求规范

• 性能指标：单线程解析吞吐量 > 50M OPS，P99 延迟 < 10ns，内存峰值控制在输入大小的 1.1 倍以内（零拷贝模式下更低）。

• 安全要求：严禁使用正则表达式以防止 ReDoS；严格校验协议白名单，防止 XSS 和 SSRF 攻击；限制递归深度防止栈溢出。

• 可靠性：能够处理损坏的 Markdown 语法、不平衡的括号、混合编码及超长字符串，保证服务不挂起；支持线程安全的多线程并发调用。

• 可维护性：解析逻辑与 Markdown 方言解耦，支持插拔式规则配置，代码具备完善的文档注释。

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

// 定义解析后的 URL 结构 (使用 Slice 避免拷贝)
struct MdUrl {
    original: String // 原始字符串引用
    scheme: Option<String>
    host: Option<String>
    path: String
    query: Option<String>
    fragment: Option<String>
    isAutoLink: Bool // 是否为自动识别的链接
    
    // 转换为完整字符串
    func toString(): String
    
    // 获取标准化后的 URL
    func normalize(): MdUrl
}

// 定义解析结果
enum ParseResult<T> {
    case Success(T)
    case Failure(ParseError)
    case PartialMatch(T) // Markdown 中常见的部分匹配情况
}

// 定义错误类型
enum ParseError {
    case UnbalancedBrackets
    case InvalidScheme
    case MalformedUrl
    case SecurityViolation(String)
    case DeepNestingDetected
}

// 定义解析配置
struct MdParseConfig {
    allowBalancedBrackets: Bool // 是否允许 URL 中包含平衡的括号
    allowedSchemes: List<String> // 协议白名单
    detectAutoLinks: Bool // 是否启用自动链接识别
    strictSecurity: Bool // 严格安全模式
}

// 核心解析接口
interface MdUrlEngine {
    // 解析 Markdown 中的 URL
    func parse(input: String, config: MdParseConfig): ParseResult<MdUrl>
    
    // 在文本中查找所有 URL (自动链接模式)
    func findAllLinks(text: String, config: MdParseConfig): List<ParseResult<MdUrl>>
    
    // URL 编码 (Markdown 专用)
    func encode(input: String, keepSafeChars: Bool): String
    
    // URL 解码
    func decode(input: String): Result<String, DecodeError>
    
    // 验证安全性
    func validateSecurity(url: MdUrl): Result<Unit, SecurityError>
}

// 工厂类
object MdUrlFactory {
    static func createStandard(): MdUrlEngine
    static func createStrict(): MdUrlEngine
    static func createWithConfig(config: MdParseConfig): MdUrlEngine
}

项目交付物与实施路线图

阶段性交付物清单

• 第一阶段：核心解析引擎（状态机实现）+ 基础编解码 + 单元测试 (覆盖率≥95%)。

• 第二阶段：自动链接识别 + 安全过滤模块 + 零拷贝优化 + 性能基准测试。

• 第三阶段：完整 Markdown 方言支持 + 模糊测试 + cjpm 发布包 + 最佳实践文档（含 CMS/SSG 场景案例）。

项目实施路线图

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

仓颉语言专项质量规范

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

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

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

测试与验证标准

• 单元测试：核心模块行覆盖率≥95%，重点覆盖嵌套括号、转义字符、自动链接边界、非法协议及混合编码输入。

• 兼容性测试：使用 CommonMark 官方测试集及 GFM (GitHub Flavored Markdown) 测试集进行回归测试，确保解析行为一致。

• 性能基准：建立与 mdurl (JS), commonmark.py 的性能对比基准，确保在同等功能下性能最优且无 ReDoS 风险。

文档与可维护性

• API 文档：代码须包含规范的文档注释，详细说明 Markdown 特殊规则及安全配置选项。

• 架构决策记录：记录解析算法选型（状态机 vs 正则）及内存管理策略的依据。

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

持续集成质量门禁

#!/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. 兼容性测试 (CommonMark 标准数据集)
cjpm test --suite commonmark-validation

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

技术栈与开发环境

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

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

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

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

• 环境要求：仓颉 1.0.0+ 标准工具链，CI 环境需预置 CommonMark 及 GFM 标准测试数据集。

交付件

验收标准

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

过程质量要求