Codebase rewritten to:
tangled.org/atpasser.poxiao-labs.work/atpasser
dwn.poxiao-labs.work
1# ATProto Data 和 Lexicon 模块架构总览
2
3## 项目概述
4
5本项目为 ATProto (Authenticated Transfer Protocol) 提供 Python 实现，专注于数据模型和 Lexicon 定义的处理。基于现有的 URI 模块架构模式，提供类型安全的数据验证、序列化和 Lexicon 解析功能。
6
7## 整体架构设计
8
9### 1. 系统架构图
10
11```mermaid
12graph TB
13 subgraph "ATProto 核心模块"
14 URI[URI 模块]
15 Data[Data 模块]
16 Lexicon[Lexicon 模块]
17 end
18
19 subgraph "外部依赖"
20 Pydantic[Pydantic]
21 CBOR[cbor2]
22 CID[py-cid]
23 end
24
25 subgraph "数据流"
26 LexiconJSON[Lexicon JSON 文件]
27 RawData[原始数据]
28 end
29
30 LexiconJSON --> Lexicon
31 Lexicon --> Data
32 RawData --> Data
33 Data --> Serialized[序列化数据]
34
35 URI --> Data
36 URI --> Lexicon
37
38 Pydantic --> Data
39 Pydantic --> Lexicon
40 CBOR --> Data
41 CID --> Data
42```
43
44### 2. 模块职责划分
45
46#### 2.1 Data 模块 (`src/atpasser/data`)
47- **数据序列化**: JSON 和 DAG-CBOR 格式的序列化/反序列化
48- **数据验证**: 类型验证、格式验证、约束验证
49- **特殊类型处理**: CID 链接、Blob 引用、日期时间格式等
50- **错误处理**: 详细的验证错误和序列化错误
51
52#### 2.2 Lexicon 模块 (`src/atpasser/lexicon`)
53- **定义解析**: 解析 Lexicon JSON 定义文件
54- **模型生成**: 动态生成 Pydantic 模型类
55- **引用解析**: 处理跨定义引用和联合类型
56- **注册管理**: 模型注册表和缓存管理
57- **兼容性验证**: 前向和后向兼容性检查
58
59### 3. 核心功能特性
60
61#### 3.1 类型安全
62- 基于 Pydantic 的强类型系统
63- 运行时类型验证
64- 自动类型转换和规范化
65
66#### 3.2 格式支持
67- **JSON**: 符合 ATProto JSON 编码规范
68- **DAG-CBOR**: 支持规范的 DAG-CBOR 编码
69- **混合格式**: 支持两种格式间的转换
70
71#### 3.3 验证系统
72- 语法验证 (基础数据类型)
73- 语义验证 (业务规则和约束)
74- 格式验证 (字符串格式如 datetime、uri、did 等)
75- 引用验证 (CID、blob、跨定义引用)
76
77### 4. 集成架构
78
79#### 4.1 与现有 URI 模块的集成
80
81```python
82# 示例：URI 与 Data 模块的集成
83from atpasser.uri import URI, NSID
84from atpasser.data import ATProtoSerializer
85from atpasser.lexicon import LexiconRegistry
86
87# 解析 URI
88uri = URI("at://example.com/com.example.blog.post/123")
89
90# 根据 NSID 获取对应的数据模型
91model_class = LexiconRegistry.get_model(uri.collection.nsid)
92
93# 使用 Data 模块处理数据
94serializer = ATProtoSerializer()
95data = serializer.from_json(raw_data, model_class)
96```
97
98#### 4.2 数据流架构
99
100```
101原始数据 → Data 模块验证 → Lexicon 模型转换 → 序列化输出
102Lexicon JSON → Lexicon 模块解析 → 生成 Pydantic 模型 → 注册到注册表
103```
104
105### 5. 错误处理架构
106
107#### 5.1 统一的错误体系
108
109```python
110class ATProtoError(Exception):
111 """基础错误类"""
112 pass
113
114class DataError(ATProtoError):
115 """数据相关错误"""
116 pass
117
118class LexiconError(ATProtoError):
119 """Lexicon 相关错误"""
120 pass
121
122class URIError(ATProtoError):
123 """URI 相关错误"""
124 pass
125```
126
127#### 5.2 错误诊断
128- **字段级错误定位**: 精确到具体字段的路径信息
129- **上下文信息**: 包含验证时的输入数据和期望格式
130- **建议修复**: 提供具体的修复建议
131
132### 6. 性能优化策略
133
134#### 6.1 缓存机制
135- **模型缓存**: 缓存已解析的 Lexicon 模型
136- **序列化缓存**: 缓存序列化结果
137- **引用解析缓存**: 缓存跨定义引用解析结果
138
139#### 6.2 懒加载
140- 按需解析 Lexicon 定义
141- 延迟模型生成直到实际使用
142- 动态导入依赖模块
143
144### 7. 扩展性设计
145
146#### 7.1 插件系统
147- 支持自定义类型处理器
148- 支持自定义验证规则
149- 支持自定义序列化格式
150
151#### 7.2 中间件支持
152- 预处理钩子 (数据清洗、转换)
153- 后处理钩子 (日志记录、监控)
154- 验证钩子 (自定义验证逻辑)
155
156### 8. 实施路线图
157
158#### 阶段 1: 基础实现 (2-3 周)
159- 实现 Data 模块基础类型和 JSON 序列化
160- 实现 Lexicon 模块基础解析器
161- 建立基本的错误处理系统
162
163#### 阶段 2: 完整功能 (3-4 周)
164- 添加 CBOR 序列化支持
165- 实现完整的验证系统
166- 添加引用解析和联合类型支持
167
168#### 阶段 3: 优化增强 (2 周)
169- 实现缓存和性能优化
170- 添加高级格式验证
171- 完善错误处理和诊断信息
172
173#### 阶段 4: 测试部署 (1-2 周)
174- 编写完整的测试套件
175- 性能测试和优化
176- 文档编写和示例代码
177
178### 9. 依赖管理
179
180#### 9.1 核心依赖
181- `pydantic >=2.11.9`: 数据验证和模型定义
182- `cbor2 >=5.7.0`: CBOR 序列化支持
183- `py-cid >=0.3.0`: CID 处理支持
184
185#### 9.2 可选依赖
186- `jsonpath-ng >=1.7.0`: JSONPath 支持
187- `langcodes >=3.5.0`: 语言代码验证
188
189### 10. 质量保证
190
191#### 10.1 测试策略
192- **单元测试**: 覆盖所有核心功能
193- **集成测试**: 测试模块间集成
194- **兼容性测试**: 确保与规范兼容
195- **性能测试**: 验证性能指标
196
197#### 10.2 代码质量
198- 类型注解覆盖率达到 100%
199- 测试覆盖率超过 90%
200- 遵循 PEP 8 编码规范
201- 详细的文档和示例
202
203## 总结
204
205本架构设计提供了一个完整、可扩展的 ATProto 数据处理解决方案，充分利用了 Python 的类型系统和现有生态，同时保持了与 ATProto 规范的完全兼容性。模块化的设计使得各个组件可以独立开发和测试，同时也便于未来的扩展和维护。