# 组件交互关系

<cite>
**本文档引用的文件**
- [src/lib.rs](file://src/lib.rs)
- [src/main.rs](file://src/main.rs)
- [src/project.rs](file://src/project.rs)
- [src/project_compiler.rs](file://src/project_compiler.rs)
- [src/dep_graph.rs](file://src/dep_graph.rs)
- [src/codegen.rs](file://src/codegen.rs)
- [src/swc_transform.rs](file://src/swc_transform.rs)
- [src/standalone_gen.rs](file://src/standalone_gen.rs)
- [src/standalone_loader.rs](file://src/standalone_loader.rs)
- [src/coff.rs](file://src/coff.rs)
- [src/tsn_ffi.rs](file://src/tsn_ffi.rs)
- [src/native_linker.rs](file://src/native_linker.rs)
- [loader/src/main.rs](file://loader/src/main.rs)
- [runtime/src/lib.rs](file://runtime/src/lib.rs)
- [Cargo.toml](file://Cargo.toml)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介

ts-native 是一个 TypeScript 到原生代码的编译器系统，提供了完整的组件交互关系和模块化架构。该系统通过多个专门的模块协同工作，实现了从 TypeScript 源码到可执行文件的完整编译链路。

系统的核心设计理念是模块解耦和接口抽象，通过清晰的组件边界和标准化的消息传递协议，实现了高度的可扩展性和维护性。

## 项目结构

项目采用模块化的组织方式，主要分为以下几个核心模块：

```mermaid
graph TB
subgraph "核心编译器模块"
A[src/lib.rs] --> B[src/main.rs]
A --> C[src/project.rs]
A --> D[src/dep_graph.rs]
A --> E[src/codegen.rs]
A --> F[src/swc_transform.rs]
end
subgraph "运行时模块"
G[src/tsn_ffi.rs] --> H[runtime/src/lib.rs]
I[src/standalone_gen.rs] --> J[src/standalone_loader.rs]
end
subgraph "工具模块"
K[src/coff.rs] --> L[src/native_linker.rs]
M[loader/src/main.rs] --> N[Cargo.toml]
end
B --> G
C --> D
D --> E
E --> I
H --> M
```

**图表来源**
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [src/main.rs:1-79](file://src/main.rs#L1-L79)
- [src/project.rs:1-461](file://src/project.rs#L1-L461)

**章节来源**
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [Cargo.toml:1-57](file://Cargo.toml#L1-L57)

## 核心组件

### 项目发现模块 (Project Module)
负责扫描目录结构、识别入口文件和模块文件，构建项目结构信息。

### 依赖图构建器 (Dependency Graph Builder)
解析模块间的导入导出关系，构建有向无环图(DAG)，支持拓扑排序和闭包计算。

### 编译协调器 (Compilation Coordinator)
协调多模块项目的编译流程，管理编译阶段和资源分配。

### 代码生成器 (Code Generator)
将 TypeScript 抽象语法树转换为原生机器码，支持多种输出格式。

**章节来源**
- [src/project.rs:1-461](file://src/project.rs#L1-L461)
- [src/dep_graph.rs:1-257](file://src/dep_graph.rs#L1-L257)
- [src/project_compiler.rs:1-728](file://src/project_compiler.rs#L1-L728)
- [src/codegen.rs:1-800](file://src/codegen.rs#L1-L800)

## 架构概览

系统采用分层架构设计，各层之间通过清晰的接口进行通信：

```mermaid
graph TB
subgraph "用户接口层"
CLI[命令行界面]
Loader[tsn-loader]
end
subgraph "编译协调层"
PC[ProjectCompiler]
DG[DependencyGraph]
PM[ProjectManager]
end
subgraph "编译执行层"
ST[SWC Transformer]
CG[CodeGen]
FF[FFI Interface]
end
subgraph "运行时层"
RT[Runtime Library]
SL[Standalone Loader]
end
CLI --> PC
Loader --> SL
PC --> DG
PC --> PM
PM --> ST
ST --> CG
CG --> FF
FF --> RT
SL --> RT
```

**图表来源**
- [src/project_compiler.rs:190-246](file://src/project_compiler.rs#L190-L246)
- [src/tsn_ffi.rs:58-106](file://src/tsn_ffi.rs#L58-L106)
- [loader/src/main.rs:42-127](file://loader/src/main.rs#L42-L127)

## 详细组件分析

### 项目发现模块分析

项目发现模块负责扫描文件系统并识别 TypeScript 模块：

```mermaid
classDiagram
class Project {
+Path root
+ProjectConfig config
+HashMap~PathBuf,SourceFile~ files
+Vec~PathBuf~ entries
+Vec~PathBuf~ modules
+from_dir(root) Project
+load_content(path) String
+resolve_import(from, path) PathBuf
}
class ProjectConfig {
+Vec~String~ entries
+String src_dir
+String out_dir
}
class SourceFile {
+PathBuf path
+String module_name
+bool is_entry
+Option~String~ content
}
Project --> ProjectConfig : "使用"
Project --> SourceFile : "管理"
```

**图表来源**
- [src/project.rs:44-153](file://src/project.rs#L44-L153)

**章节来源**
- [src/project.rs:58-153](file://src/project.rs#L58-L153)

### 依赖图构建器分析

依赖图构建器解析模块间的导入导出关系：

```mermaid
classDiagram
class DepGraph {
+HashMap~PathBuf,ModuleNode~ nodes
+HashMap~PathBuf,Vec~PathBuf~~ entry_closures
+Vec~PathBuf~ compile_order
+from_project(project) DepGraph
+get_compile_order() Vec~PathBuf~
+get_entry_modules(entry) Vec~PathBuf~
}
class ModuleNode {
+PathBuf path
+String module_name
+HashSet~String~ exports
+HashMap~PathBuf,Vec~String~~ imports
+Vec~PathBuf~ deps
+Vec~PathBuf~ reverse_deps
+usize level
+bool is_entry
}
DepGraph --> ModuleNode : "包含"
```

**图表来源**
- [src/dep_graph.rs:32-132](file://src/dep_graph.rs#L32-L132)

**章节来源**
- [src/dep_graph.rs:43-132](file://src/dep_graph.rs#L43-L132)

### 编译协调器分析

编译协调器管理整个编译流程：

```mermaid
sequenceDiagram
participant CLI as "命令行接口"
participant PC as "ProjectCompiler"
participant DG as "DependencyGraph"
participant CG as "CodeGen"
participant SL as "StandaloneLoader"
CLI->>PC : compile_project()
PC->>DG : from_project()
DG-->>PC : DepGraph
PC->>PC : get_compile_order()
loop 按拓扑顺序编译
PC->>CG : compile_module(path)
CG->>CG : parse()
CG->>CG : compile_coff()
CG-->>PC : COFF bytes
end
PC->>SL : build_standalone_executable()
SL->>SL : parse_coff_to_module_data()
SL->>SL : serialize_to_tsnobj()
SL-->>PC : .exe 文件
```

**图表来源**
- [src/project_compiler.rs:248-332](file://src/project_compiler.rs#L248-L332)
- [src/project_compiler.rs:384-567](file://src/project_compiler.rs#L384-L567)

**章节来源**
- [src/project_compiler.rs:205-332](file://src/project_compiler.rs#L205-L332)

### 代码生成器分析

代码生成器负责将 TypeScript 转换为原生代码：

```mermaid
flowchart TD
Start([开始编译]) --> Parse["解析 TypeScript 源码"]
Parse --> Collect["收集函数签名和字符串常量"]
Collect --> Define["定义函数和数据"]
Define --> Compile["编译函数体"]
Compile --> Finish["生成 COFF 对象"]
Finish --> End([完成])
subgraph "编译阶段"
Parse
Collect
Define
Compile
end
```

**图表来源**
- [src/codegen.rs:520-604](file://src/codegen.rs#L520-L604)

**章节来源**
- [src/codegen.rs:451-604](file://src/codegen.rs#L451-L604)

### 消息传递协议

系统采用标准化的消息传递协议：

| 协议类型 | 数据结构 | 用途 | 生命周期 |
|---------|----------|------|----------|
| TsnCompileResult | 包含代码、数据、重定位信息 | 编译结果传输 | 请求-响应 |
| ModuleData | 节区、符号、重定位表 | 独立可执行文件数据 | 持久化 |
| TsnSymbol | 符号名称、节区、偏移 | 符号解析 | 临时 |
| TsnRelocation | 重定位类型、目标符号 | 地址重定位 | 临时 |

**章节来源**
- [src/tsn_ffi.rs:27-44](file://src/tsn_ffi.rs#L27-L44)
- [src/standalone_gen.rs:11-34](file://src/standalone_gen.rs#L11-L34)

## 依赖分析

系统依赖关系呈现清晰的层次结构：

```mermaid
graph TB
subgraph "核心依赖"
SWC[SWC Parser 5.x]
Cranelift[Cranelift 0.93.2]
Object[object crate 0.29]
end
subgraph "编译器依赖"
SWC --> ST[SWC Transform]
Cranelift --> CG[CodeGen]
Object --> SG[Standalone Gen]
end
subgraph "运行时依赖"
CG --> FF[FFI Interface]
FF --> RT[Runtime Library]
RT --> LO[Loader]
end
```

**图表来源**
- [Cargo.toml:22-47](file://Cargo.toml#L22-L47)

**章节来源**
- [Cargo.toml:22-47](file://Cargo.toml#L22-L47)

### 组件耦合度分析

系统通过以下机制降低耦合度：

1. **接口抽象**: 所有模块通过标准化接口进行通信
2. **数据契约**: 明确的数据结构和协议规范
3. **功能分离**: 每个模块专注于单一职责
4. **异步处理**: 编译过程中的并行化处理

## 性能考虑

### 编译性能优化

系统采用了多项性能优化策略：

1. **并行编译**: 多模块项目支持并行编译
2. **内存管理**: 智能的内存分配和回收机制
3. **缓存策略**: 模块符号表和依赖关系缓存
4. **增量编译**: 支持部分文件的增量编译

### 内存使用监控

系统提供实时内存使用监控：

| 监控指标 | 实现方式 | 阈值管理 |
|---------|----------|----------|
| 进程内存 | 平台特定 API | Windows: GetProcessMemoryInfo |
| 编译阶段 | 时间戳记录 | 自动统计 |
| 对象文件大小 | 字节计数 | 格式化显示 |

**章节来源**
- [src/project_compiler.rs:54-121](file://src/project_compiler.rs#L54-L121)

## 故障排除指南

### 常见问题及解决方案

| 问题类型 | 症状 | 原因 | 解决方案 |
|---------|------|------|----------|
| 循环依赖 | 编译失败 | 依赖图检测 | 检查模块导入关系 |
| 符号未定义 | 运行时崩溃 | 外部符号解析失败 | 确认运行时库完整性 |
| 内存不足 | 编译中断 | 内存分配失败 | 增加系统内存或优化代码 |
| 链接错误 | PE 文件生成失败 | 重定位处理错误 | 检查节区对齐和符号表 |

### 错误传播机制

系统采用分层错误处理机制：

```mermaid
flowchart TD
Error[底层错误] --> Propagate[错误传播]
Propagate --> Transform[错误转换]
Transform --> Wrap[包装为上层错误]
Wrap --> Report[错误报告]
Report --> Recovery[恢复机制]
Recovery --> End[完成]
```

**章节来源**
- [src/project_compiler.rs:275-278](file://src/project_compiler.rs#L275-L278)
- [src/dep_graph.rs:205-207](file://src/dep_graph.rs#L205-L207)

## 结论

ts-native 系统通过精心设计的模块化架构，实现了 TypeScript 到原生代码的高效转换。系统的主要优势包括：

1. **模块解耦**: 各组件职责明确，接口清晰
2. **扩展性强**: 支持插件机制和自定义扩展
3. **性能优异**: 多项优化技术确保编译效率
4. **可靠性高**: 完善的错误处理和恢复机制

该架构为 TypeScript 原生编译领域提供了一个优秀的参考实现，具有良好的可维护性和可扩展性。