# 系统边界设计

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

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

## 简介

ts-native 是一个将 TypeScript 编译为本地机器码的系统，提供了完整的编译-链接-执行流水线。该系统的核心边界设计围绕以下关键接口：

- **外部函数接口（FFI）边界**：定义了 Rust 编译器与外部环境的交互接口
- **运行时库集成边界**：JavaScript 运行时函数的导出和调用约定
- **可执行文件生成边界**：从源代码到可执行文件的完整转换过程
- **插件系统边界**：动态加载和调用外部 DLL 插件的能力
- **安全边界**：内存管理和符号解析的安全控制机制

## 项目结构

系统采用模块化架构，主要包含以下核心模块：

```mermaid
graph TB
subgraph "编译器层"
A[src/lib.rs - 库入口]
B[src/main.rs - 命令行编译器]
C[src/tsn_ffi.rs - FFI 接口]
D[src/codegen.rs - 代码生成器]
E[src/coff.rs - COFF 解析器]
end
subgraph "运行时层"
F[runtime/src/lib.rs - JavaScript 运行时]
end
subgraph "加载器层"
G[loader/src/main.rs - 主加载器]
H[src/standalone_loader.rs - 独立加载器]
I[src/standalone_gen.rs - 独立生成器]
end
subgraph "工具层"
J[src/bin/native_linker_main.rs - 原生链接器]
K[Cargo.toml - 项目配置]
end
A --> F
B --> C
C --> F
G --> F
H --> F
I --> H
J --> E
```

**图表来源**
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [runtime/src/lib.rs:1-800](file://runtime/src/lib.rs#L1-L800)
- [loader/src/main.rs:1-1260](file://loader/src/main.rs#L1-L1260)

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

## 核心组件

### FFI 接口系统

ts-native 的 FFI 接口设计遵循严格的 ABI 约定，确保与外部环境的稳定交互：

```mermaid
classDiagram
class TsnCompileResult {
+uint8* code_ptr
+uint32 code_len
+uint8* data_ptr
+uint32 data_len
+uint8* rdata_ptr
+uint32 rdata_len
+TsnSymbol* symbols
+uint32 symbol_count
+TsnRelocation* relocations
+uint32 reloc_count
+char* error_msg
+uint32 error_line
+uint32 error_col
+char* error_context
+void* _context
}
class TsnSymbol {
+uint8 section
+uint32 offset
+uint8[64] name
}
class TsnRelocation {
+uint8 section
+uint32 offset
+uint8 type_
+uint8 _padding
+uint8[64] target_name
}
class CompileContext {
+Vec~u8~ code
+Vec~u8~ data
+Vec~u8~ rdata
+Vec~TsnSymbol~ symbols
+Vec~TsnRelocation~ relocations
+CString error_msg
+CString error_context
}
TsnCompileResult --> TsnSymbol : "包含"
TsnCompileResult --> TsnRelocation : "包含"
TsnCompileResult --> CompileContext : "拥有"
```

**图表来源**
- [src/tsn_ffi.rs:11-44](file://src/tsn_ffi.rs#L11-L44)
- [src/tsn_ffi.rs:48-56](file://src/tsn_ffi.rs#L48-L56)

### 运行时库架构

JavaScript 运行时采用 NaN-tagging 技术实现高效的数据类型表示：

```mermaid
classDiagram
class JsRuntime {
+float64 js_string_from_static(char*)
+float64 js_strict_equals(float64, float64)
+float64 js_print(float64)
+float64 js_add(float64, float64)
+float64 js_sub(float64, float64)
+float64 js_array_new(float64)
+float64 js_object_new()
+float64 js_fs_read_file_sync(float64)
}
class JsValue {
+get_tag(float64) uint64
+is_number(float64) bool
+store_string(String) float64
+get_string(float64) Option~String~
}
class JsArray {
+Vec~float64~ elements
+usize length
}
class JsObject {
+HashMap~uint64, float64~ properties
}
JsRuntime --> JsValue : "使用"
JsRuntime --> JsArray : "管理"
JsRuntime --> JsObject : "管理"
```

**图表来源**
- [runtime/src/lib.rs:138-192](file://runtime/src/lib.rs#L138-L192)
- [runtime/src/lib.rs:65-103](file://runtime/src/lib.rs#L65-L103)
- [runtime/src/lib.rs:108-133](file://runtime/src/lib.rs#L108-L133)

**章节来源**
- [src/tsn_ffi.rs:1-341](file://src/tsn_ffi.rs#L1-L341)
- [runtime/src/lib.rs:1-800](file://runtime/src/lib.rs#L1-L800)

## 架构概览

系统采用分层架构，各层之间通过明确定义的接口进行交互：

```mermaid
graph TB
subgraph "用户界面层"
CLI[命令行界面]
GUI[图形界面]
end
subgraph "编译接口层"
FFI[FFI 接口]
API[编译 API]
end
subgraph "编译执行层"
COMPILER[编译器]
CODEGEN[代码生成器]
LINKER[链接器]
end
subgraph "运行时层"
RUNTIME[JavaScript 运行时]
PLUGINS[插件系统]
end
subgraph "操作系统层"
KERNEL[Windows 内核]
MEMORY[内存管理]
FILESYS[文件系统]
end
CLI --> FFI
GUI --> API
FFI --> COMPILER
API --> COMPILER
COMPILER --> CODEGEN
CODEGEN --> LINKER
LINKER --> RUNTIME
RUNTIME --> PLUGINS
RUNTIME --> KERNEL
PLUGINS --> KERNEL
KERNEL --> MEMORY
KERNEL --> FILESYS
```

**图表来源**
- [src/main.rs:7-78](file://src/main.rs#L7-L78)
- [loader/src/main.rs:42-127](file://loader/src/main.rs#L42-L127)

## 详细组件分析

### 编译器边界设计

编译器系统提供了两种主要的编译模式：

#### 模式一：命令行编译模式

```mermaid
sequenceDiagram
participant User as 用户
participant CLI as 命令行编译器
participant Parser as 解析器
participant CodeGen as 代码生成器
participant FS as 文件系统
User->>CLI : ts-native <input.ts> [-o output.obj]
CLI->>FS : 读取源文件
FS-->>CLI : 源代码内容
CLI->>Parser : 解析 TypeScript
Parser-->>CLI : HIR 结构
CLI->>CodeGen : 生成 COFF
CodeGen-->>CLI : 二进制数据
CLI->>FS : 写入 .obj 文件
FS-->>CLI : 确认写入
CLI-->>User : 显示编译结果
```

**图表来源**
- [src/main.rs:7-78](file://src/main.rs#L7-L78)
- [src/tsn_ffi.rs:162-169](file://src/tsn_ffi.rs#L162-L169)

#### 模式二：DLL 编译模式

```mermaid
sequenceDiagram
participant Loader as 加载器
participant DLL as ts-native DLL
participant Parser as 解析器
participant CodeGen as 代码生成器
participant Runtime as 运行时
Loader->>DLL : tsn_compile(source)
DLL->>Parser : 解析 TypeScript
Parser-->>DLL : HIR 结构
DLL->>CodeGen : 生成原生数据
CodeGen-->>DLL : 原始数据
DLL-->>Loader : TsnCompileResult
Loader->>Runtime : 加载运行时 DLL
Loader->>Runtime : 应用重定位
Loader->>Runtime : 调用入口函数
Runtime-->>Loader : 执行结果
```

**图表来源**
- [loader/src/main.rs:387-502](file://loader/src/main.rs#L387-L502)
- [src/tsn_ffi.rs:172-292](file://src/tsn_ffi.rs#L172-L292)

**章节来源**
- [src/main.rs:1-79](file://src/main.rs#L1-L79)
- [loader/src/main.rs:1-1260](file://loader/src/main.rs#L1-L1260)

### 插件系统边界

插件系统提供了动态加载和符号解析能力：

```mermaid
classDiagram
class PluginManager {
+HashMap~String, HMODULE~ loaded
+HashMap~String, FARPROC~ symbol_cache
+load_plugin(Path) Result
+resolve_symbol(String) Option~FARPROC~
}
class TsnCompiler {
+HMODULE dll
+extern "C" compile_fn
+extern "C" free_fn
+extern "C" compile_coff_fn
+extern "C" free_coff_fn
+compile(String, String) Result~CompiledModule~
+compile_coff(String) Result~Vec~u8~~
}
class CompiledModule {
+Vec~u8~ code
+Vec~u8~ data
+Vec~u8~ rdata
+Vec~TsnSymbolEntry~ symbols
+Vec~TsnRelocationEntry~ relocations
}
PluginManager --> TsnCompiler : "管理"
TsnCompiler --> CompiledModule : "创建"
```

**图表来源**
- [loader/src/main.rs:272-333](file://loader/src/main.rs#L272-L333)
- [loader/src/main.rs:337-508](file://loader/src/main.rs#L337-L508)

### 内存管理边界

系统实现了严格的内存分配和清理机制：

```mermaid
flowchart TD
Start([开始执行]) --> AllocCode["分配可执行内存<br/>VirtualAlloc(code_size)"]
AllocCode --> CopyCode["复制代码到可执行内存"]
CopyCode --> AllocData["分配数据内存<br/>VirtualAlloc(total_data_size)"]
AllocData --> CopyData["复制数据到数据内存"]
CopyData --> ApplyReloc["应用重定位"]
ApplyReloc --> CallEntry["调用入口函数"]
CallEntry --> Cleanup["清理内存<br/>VirtualFree()"]
Cleanup --> End([执行完成])
ApplyReloc --> CheckSymbol{"符号解析成功？"}
CheckSymbol --> |否| HandleError["记录错误并继续"]
CheckSymbol --> |是| Continue["继续执行"]
HandleError --> Continue
```

**图表来源**
- [loader/src/main.rs:568-743](file://loader/src/main.rs#L568-L743)

**章节来源**
- [loader/src/main.rs:1-1260](file://loader/src/main.rs#L1-L1260)

### 安全边界设计

系统在多个层面实施了安全控制：

#### 内存安全
- 使用 RAII 模式管理内存分配
- 明确的内存释放责任链
- 指针有效性检查和边界验证

#### 符号安全
- 外部符号解析的白名单机制
- 符号名称长度限制（64字节）
- 重定位类型的严格验证

#### 访问控制
- DLL 加载的权限检查
- 文件系统访问的路径验证
- 进程间通信的安全边界

**章节来源**
- [src/tsn_ffi.rs:85-106](file://src/tsn_ffi.rs#L85-L106)
- [loader/src/main.rs:285-306](file://loader/src/main.rs#L285-L306)

## 依赖关系分析

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

```mermaid
graph TB
subgraph "核心依赖"
CRANELIFT[cranelift-0.93.2]
SWC[swc-5.x]
OBJECT[object-0.29]
end
subgraph "运行时依赖"
LOG[log-0.4]
ENV_LOGGER[env_logger-0.11]
SERDE[serde-1.0.197]
end
subgraph "系统依赖"
KERNEL32[kernel32.dll]
NTDLL[ntdll.dll]
SHELL32[shell32.dll]
end
CRANELIFT --> CODEGEN[cranelift-codegen]
SWC --> PARSER[swc_ecma_parser]
OBJECT --> COFF_PARSER[COFF 解析]
LOG --> ENV_LOGGER
SERDE --> SWC
KERNEL32 --> LOADER[加载器]
NTDLL --> LOADER
SHELL32 --> NATIVE_LINKER[原生链接器]
```

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

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

## 性能考量

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

### 编译性能
- **并行编译**：多模块项目支持并行编译
- **增量编译**：依赖图优化减少重复编译
- **内存池**：运行时对象的内存池管理

### 执行性能
- **JIT 编译**：Cranelift JIT 编译器优化
- **NaN-tagging**：高效的值类型识别
- **内联缓存**：热点函数的内联优化

### 内存管理
- **零拷贝操作**：大量使用切片避免不必要的复制
- **智能指针**：自动内存管理减少泄漏风险
- **分页内存**：Windows 分页内存模型优化

## 故障排除指南

### 常见问题诊断

#### 编译错误
- **源码解析失败**：检查 TypeScript 语法和依赖
- **符号未定义**：确认模块导入和导出声明
- **重定位失败**：验证外部符号的可用性

#### 运行时错误
- **DLL 加载失败**：检查运行时 DLL 的路径和权限
- **内存分配失败**：监控系统内存使用情况
- **符号解析错误**：验证符号名称和类型匹配

#### 性能问题
- **编译时间过长**：启用增量编译和并行构建
- **运行时性能低**：分析热点函数和内存使用模式
- **内存泄漏**：检查资源释放和生命周期管理

**章节来源**
- [src/tsn_ffi.rs:294-325](file://src/tsn_ffi.rs#L294-L325)
- [loader/src/main.rs:161-222](file://loader/src/main.rs#L161-L222)

## 结论

ts-native 系统的边界设计体现了现代编译器系统的最佳实践：

### 设计优势
- **清晰的接口分离**：各层职责明确，接口稳定
- **强大的扩展性**：插件系统和模块化设计
- **高性能执行**：JIT 编译和优化的运行时
- **严格的安全控制**：多层次的安全边界设计

### 关键特性
- **跨平台兼容**：基于标准 ABI 的可移植性
- **开发友好**：完善的错误报告和调试支持
- **生产就绪**：经过充分测试的稳定实现
- **持续演进**：模块化架构支持未来扩展

该系统为 TypeScript 到本地代码的转换提供了完整、高效且安全的解决方案，适合各种规模的应用场景。