dwn.poxiao-labs.work / atpasser
Codebase rewritten to: tangled.org/atpasser.poxiao-labs.work/atpasser
fork atom
atpasser / ARCHITECTURE_OVERVIEW.md
at dantic 5.6 kB view raw view code

ATProto Data 和 Lexicon 模块架构总览#

项目概述#

本项目为 ATProto (Authenticated Transfer Protocol) 提供 Python 实现，专注于数据模型和 Lexicon 定义的处理。基于现有的 URI 模块架构模式，提供类型安全的数据验证、序列化和 Lexicon 解析功能。

整体架构设计#

1. 系统架构图#

graph TB
    subgraph "ATProto 核心模块"
        URI[URI 模块]
        Data[Data 模块]
        Lexicon[Lexicon 模块]
    end
    
    subgraph "外部依赖"
        Pydantic[Pydantic]
        CBOR[cbor2]
        CID[py-cid]
    end
    
    subgraph "数据流"
        LexiconJSON[Lexicon JSON 文件]
        RawData[原始数据]
    end
    
    LexiconJSON --> Lexicon
    Lexicon --> Data
    RawData --> Data
    Data --> Serialized[序列化数据]
    
    URI --> Data
    URI --> Lexicon
    
    Pydantic --> Data
    Pydantic --> Lexicon
    CBOR --> Data
    CID --> Data

2. 模块职责划分#

2.1 Data 模块 (src/atpasser/data)#

  • 数据序列化: JSON 和 DAG-CBOR 格式的序列化/反序列化
  • 数据验证: 类型验证、格式验证、约束验证
  • 特殊类型处理: CID 链接、Blob 引用、日期时间格式等
  • 错误处理: 详细的验证错误和序列化错误

2.2 Lexicon 模块 (src/atpasser/lexicon)#

  • 定义解析: 解析 Lexicon JSON 定义文件
  • 模型生成: 动态生成 Pydantic 模型类
  • 引用解析: 处理跨定义引用和联合类型
  • 注册管理: 模型注册表和缓存管理
  • 兼容性验证: 前向和后向兼容性检查

3. 核心功能特性#

3.1 类型安全#

  • 基于 Pydantic 的强类型系统
  • 运行时类型验证
  • 自动类型转换和规范化

3.2 格式支持#

  • JSON: 符合 ATProto JSON 编码规范
  • DAG-CBOR: 支持规范的 DAG-CBOR 编码
  • 混合格式: 支持两种格式间的转换

3.3 验证系统#

  • 语法验证 (基础数据类型)
  • 语义验证 (业务规则和约束)
  • 格式验证 (字符串格式如 datetime、uri、did 等)
  • 引用验证 (CID、blob、跨定义引用)

4. 集成架构#

4.1 与现有 URI 模块的集成#

# 示例：URI 与 Data 模块的集成
from atpasser.uri import URI, NSID
from atpasser.data import ATProtoSerializer
from atpasser.lexicon import LexiconRegistry

# 解析 URI
uri = URI("at://example.com/com.example.blog.post/123")

# 根据 NSID 获取对应的数据模型
model_class = LexiconRegistry.get_model(uri.collection.nsid)

# 使用 Data 模块处理数据
serializer = ATProtoSerializer()
data = serializer.from_json(raw_data, model_class)

4.2 数据流架构#

原始数据 → Data 模块验证 → Lexicon 模型转换 → 序列化输出
Lexicon JSON → Lexicon 模块解析 → 生成 Pydantic 模型 → 注册到注册表

5. 错误处理架构#

5.1 统一的错误体系#

class ATProtoError(Exception):
    """基础错误类"""
    pass

class DataError(ATProtoError):
    """数据相关错误"""
    pass

class LexiconError(ATProtoError):
    """Lexicon 相关错误"""
    pass

class URIError(ATProtoError):
    """URI 相关错误"""
    pass

5.2 错误诊断#

  • 字段级错误定位: 精确到具体字段的路径信息
  • 上下文信息: 包含验证时的输入数据和期望格式
  • 建议修复: 提供具体的修复建议

6. 性能优化策略#

6.1 缓存机制#

  • 模型缓存: 缓存已解析的 Lexicon 模型
  • 序列化缓存: 缓存序列化结果
  • 引用解析缓存: 缓存跨定义引用解析结果

6.2 懒加载#

  • 按需解析 Lexicon 定义
  • 延迟模型生成直到实际使用
  • 动态导入依赖模块

7. 扩展性设计#

7.1 插件系统#

  • 支持自定义类型处理器
  • 支持自定义验证规则
  • 支持自定义序列化格式

7.2 中间件支持#

  • 预处理钩子 (数据清洗、转换)
  • 后处理钩子 (日志记录、监控)
  • 验证钩子 (自定义验证逻辑)

8. 实施路线图#

阶段 1: 基础实现 (2-3 周)#

  • 实现 Data 模块基础类型和 JSON 序列化
  • 实现 Lexicon 模块基础解析器
  • 建立基本的错误处理系统

阶段 2: 完整功能 (3-4 周)#

  • 添加 CBOR 序列化支持
  • 实现完整的验证系统
  • 添加引用解析和联合类型支持

阶段 3: 优化增强 (2 周)#

  • 实现缓存和性能优化
  • 添加高级格式验证
  • 完善错误处理和诊断信息

阶段 4: 测试部署 (1-2 周)#

  • 编写完整的测试套件
  • 性能测试和优化
  • 文档编写和示例代码

9. 依赖管理#

9.1 核心依赖#

  • pydantic >=2.11.9: 数据验证和模型定义
  • cbor2 >=5.7.0: CBOR 序列化支持
  • py-cid >=0.3.0: CID 处理支持

9.2 可选依赖#

  • jsonpath-ng >=1.7.0: JSONPath 支持
  • langcodes >=3.5.0: 语言代码验证

10. 质量保证#

10.1 测试策略#

  • 单元测试: 覆盖所有核心功能
  • 集成测试: 测试模块间集成
  • 兼容性测试: 确保与规范兼容
  • 性能测试: 验证性能指标

10.2 代码质量#

  • 类型注解覆盖率达到 100%
  • 测试覆盖率超过 90%
  • 遵循 PEP 8 编码规范
  • 详细的文档和示例

总结#

本架构设计提供了一个完整、可扩展的 ATProto 数据处理解决方案，充分利用了 Python 的类型系统和现有生态，同时保持了与 ATProto 规范的完全兼容性。模块化的设计使得各个组件可以独立开发和测试，同时也便于未来的扩展和维护。