dd-plist

项目背景与战略目标

dd-plist 项目旨在为仓颉语言生态构建一个原生、全格式的 Apple Property List (Plist) 解析与序列化库。Plist 是 macOS 和 iOS 系统的核心配置文件格式，广泛应用于应用元数据（Info.plist）、用户偏好设置、系统配置及移动设备管理（MDM）场景。在跨平台后端服务中（如 iOS 应用分发平台、自动化测试农场、移动设备集群管理），经常需要在非 Apple 设备上解析或生成 Plist 文件。现有的 Java 实现（如 dd-plist）虽然功能完备，但在处理大规模二进制 Plist 或高并发解析任务时，存在内存占用高、GC 压力大等问题。本项目将利用仓颉编程语言（Cangjie Language）1.0.0+ 的内存安全特性，彻底消除二进制解析中的缓冲区溢出风险；借助轻量级线程模型，实现万级并发下的低延迟配置读取；利用强类型系统确保 Plist 数据结构（字典、数组、基本类型）的严格映射。目标是打造一款兼容 Apple 官方标准、支持 XML/ASCII/Binary 三种格式、性能卓越且易于集成的后端配置解析组件。

核心功能需求与技术规格

功能模块分解

非功能性需求规范

• 性能指标：单条 Plist 解析延迟 < 1ms (10KB 文件)，高吞吐场景下（>10k QPS）内存占用比 Java 实现降低 50%。

• 安全要求：依托仓颉编译期内存检查，杜绝缓冲区溢出；严格限制递归深度与对象数量，防止恶意构造的 Plist 导致 DoS 攻击（如 Billion Laughs 攻击变种）。

• 可靠性：完善的异常捕获机制，确保在畸形 Plist 输入下服务不崩溃，资源自动回收。

• 可维护性：模块化设计，协议解析与业务逻辑解耦，符合仓颉编码规范。

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

// 定义 Plist 根节点类型
enum PlistValue {
    case Dictionary(Map<String, PlistValue>)
    case Array(List<PlistValue>)
    case String(String)
    case Number(Double)
    case Bool(Bool)
    case Date(Int64) // Unix timestamp
    case Data(ByteArray)
    case Uid(Int64)
}

// 定义 Plist 格式枚举
enum PlistFormat {
    case XML
    case ASCII
    case Binary
}

// 定义解析错误类型
enum PlistError {
    case UnsupportedFormat(String)
    case ParseError(String)
    case TypeConversionFailed(String)
    case CircularReferenceDetected
}

// Plist 编解码器核心接口
interface PlistCodec {
    // 解析 Plist 字节流，自动探测格式
    func parse(data: ByteArray) throws<PlistError> Result<PlistValue, PlistError>

    // 解析 Plist 字符串 (仅 XML/ASCII)
    func parseString(content: String, format: PlistFormat) throws<PlistError> Result<PlistValue, PlistError>

    // 序列化为指定格式的字节流
    func serialize(value: PlistValue, format: PlistFormat) throws<PlistError> Result<ByteArray, PlistError>
    
    // 序列化为格式化字符串 (XML/ASCII)
    func serializeToString(value: PlistValue, format: PlistFormat, prettyPrint: Bool) throws<PlistError> Result<String, PlistError>
}

项目交付物与实施路线图

阶段性交付物清单

• 第一阶段：XML/ASCII 解析与序列化 + 基础二进制解析 + 单元测试 (覆盖率≥95%)。

• 第二阶段：完整二进制 Plist 支持 (UID, 复杂引用) + 性能优化 (零拷贝) + 集成测试 (兼容性验证)。

• 第三阶段：与仓颉文件 IO 框架集成示例 + 压力测试报告 + 生产级部署指南 + cjpm 发布包。

项目实施路线图

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

仓颉语言专项质量规范

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

• 类型安全：充分利用泛型与模式匹配处理动态类型映射，减少强制类型转换；所有权设计需确保二进制缓冲区的安全访问。

• 错误处理：显式声明异常类型（throws），杜绝不可控的运行时崩溃，所有解析错误必须转换为业务友好的错误码。

测试与验证标准

• 单元测试：核心模块行覆盖率≥95%（通过 cjpm test --coverage 验证），重点覆盖边界条件、循环引用及非法输入。

• 兼容性测试：使用真实的 iOS/macOS Plist 文件（Info.plist, .mobileconfig 等）进行双向兼容性验证，确保与 Apple plutil 工具互操作。

• 安全扫描：通过仓颉语言内置静态分析工具扫描，确保无内存安全隐患，并通过模糊测试 (Fuzzing) 验证协议健壮性。

文档与可维护性

• API 文档：代码须包含规范的文档注释（Doc Comments），详细说明类型映射规则及格式差异。

• 架构决策记录（ADR）：记录关于二进制 Plist 引用追踪算法选型的技术依据。

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

持续集成质量门禁

#!/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. 兼容性测试 (对比 Apple plutil 输出)
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 使用官方/社区认证 Docker 镜像，支持 Linux/x86_64 及 Linux/ARM64 架构。

交付件

验收标准

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

过程质量要求