# 贡献指南

<cite>
**本文档引用的文件**
- [README.md](file://README.md)
- [Cargo.toml](file://Cargo.toml)
- [src/main.rs](file://src/main.rs)
- [src/lib.rs](file://src/lib.rs)
- [src/cli.rs](file://src/cli.rs)
- [src/config.rs](file://src/config.rs)
- [src/discovery.rs](file://src/discovery.rs)
- [src/state.rs](file://src/state.rs)
- [src/error.rs](file://src/error.rs)
- [deploy_to_local.sh](file://deploy_to_local.sh)
- [upload.sh](file://upload.sh)
- [docs/micro-app-development.md](file://docs/micro-app-development.md)
- [docs/ssl-configuration.md](file://docs/ssl-configuration.md)
- [docs/micro-app-volumes-refactor-plan.md](file://docs/micro-app-volumes-refactor-plan.md)
</cite>

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

## 简介

micro_proxy 是一个用于管理微应用的工具，支持 Docker 镜像构建、容器管理、Nginx 反向代理配置等功能。该项目采用 Rust 语言开发，提供了完整的微服务开发和部署解决方案。

## 项目结构

项目采用模块化设计，主要包含以下核心模块：

```mermaid
graph TB
subgraph "核心模块"
CLI[CLI 模块]
Config[配置管理]
Discovery[应用发现]
State[状态管理]
Builder[镜像构建]
Compose[Docker Compose]
Nginx[Nginx 配置]
Container[容器管理]
Network[网络管理]
Script[脚本执行]
Volumes[卷配置]
end
subgraph "工具模块"
Dockerfile[Dockerfile 解析]
Error[错误处理]
end
CLI --> Config
CLI --> Discovery
CLI --> State
CLI --> Builder
CLI --> Compose
CLI --> Nginx
CLI --> Container
CLI --> Network
CLI --> Script
CLI --> Volumes
Config --> Error
Discovery --> Error
State --> Error
Builder --> Error
Compose --> Error
Nginx --> Error
Container --> Error
Network --> Error
Script --> Error
Volumes --> Error
```

**图表来源**
- [src/lib.rs:6-26](file://src/lib.rs#L6-L26)
- [src/main.rs:1-25](file://src/main.rs#L1-L25)

**章节来源**
- [src/lib.rs:1-26](file://src/lib.rs#L1-L26)
- [src/main.rs:1-25](file://src/main.rs#L1-L25)

## 核心组件

### 命令行接口 (CLI)
CLI 模块负责处理用户输入和提供命令行交互界面。支持多种子命令和参数配置。

### 配置管理系统
负责读取和解析配置文件，包括主配置文件和应用配置文件。

### 应用发现模块
扫描指定目录，自动发现包含 micro-app.yml 和 Dockerfile 的微应用。

### 状态管理模块
跟踪微应用的状态，支持基于目录 hash 的增量构建判断。

**章节来源**
- [src/cli.rs:21-116](file://src/cli.rs#L21-L116)
- [src/config.rs:125-367](file://src/config.rs#L125-L367)
- [src/discovery.rs:235-352](file://src/discovery.rs#L235-L352)
- [src/state.rs:30-186](file://src/state.rs#L30-L186)

## 架构概览

micro_proxy 采用分层架构设计，各模块职责清晰，耦合度低：

```mermaid
sequenceDiagram
participant User as 用户
participant CLI as CLI 接口
participant Discovery as 应用发现
participant Config as 配置管理
participant State as 状态管理
participant Builder as 镜像构建
participant Compose as Docker Compose
participant Nginx as Nginx 配置
participant Docker as Docker 引擎
User->>CLI : 执行命令
CLI->>Config : 加载配置
CLI->>Discovery : 扫描微应用
Discovery-->>CLI : 返回应用列表
CLI->>State : 检查构建状态
State-->>CLI : 返回状态信息
CLI->>Builder : 构建镜像
Builder->>Docker : 执行构建
Docker-->>Builder : 构建结果
CLI->>Compose : 生成配置
CLI->>Nginx : 生成配置
CLI->>Docker : 启动容器
Docker-->>CLI : 启动结果
CLI-->>User : 返回执行结果
```

**图表来源**
- [src/cli.rs:296-463](file://src/cli.rs#L296-L463)
- [src/discovery.rs:235-352](file://src/discovery.rs#L235-L352)
- [src/state.rs:162-177](file://src/state.rs#L162-L177)

## 详细组件分析

### CLI 模块详细分析

CLI 模块实现了完整的命令行接口，支持以下命令：

```mermaid
classDiagram
class Cli {
+PathBuf config
+bool verbose
+Commands command
+run(args) Result
}
class Commands {
<<enumeration>>
Start
Stop
Clean
Status
Network
}
class Start {
+bool force_rebuild
}
class Clean {
+bool force
+bool network
}
class Network {
+PathBuf output
}
Cli --> Commands
Commands <|-- Start
Commands <|-- Clean
Commands <|-- Network
```

**图表来源**
- [src/cli.rs:22-69](file://src/cli.rs#L22-L69)

#### 命令执行流程

```mermaid
flowchart TD
Start([命令执行开始]) --> ParseArgs["解析命令行参数"]
ParseArgs --> LoadConfig["加载配置文件"]
LoadConfig --> ExecuteCommand["执行具体命令"]
ExecuteCommand --> StartCmd{"Start 命令?"}
ExecuteCommand --> StopCmd{"Stop 命令?"}
ExecuteCommand --> CleanCmd{"Clean 命令?"}
ExecuteCommand --> StatusCmd{"Status 命令?"}
ExecuteCommand --> NetworkCmd{"Network 命令?"}
StartCmd --> |是| ExecuteStart["执行启动流程"]
StopCmd --> |是| ExecuteStop["执行停止流程"]
CleanCmd --> |是| ExecuteClean["执行清理流程"]
StatusCmd --> |是| ExecuteStatus["执行状态查询"]
NetworkCmd --> |是| ExecuteNetwork["执行网络查询"]
ExecuteStart --> DiscoverApps["发现微应用"]
ExecuteStart --> BuildImages["构建镜像"]
ExecuteStart --> GenerateConfigs["生成配置文件"]
ExecuteStart --> StartContainers["启动容器"]
DiscoverApps --> BuildImages
BuildImages --> GenerateConfigs
GenerateConfigs --> StartContainers
StartContainers --> End([执行完成])
ExecuteStop --> End
ExecuteClean --> End
ExecuteStatus --> End
ExecuteNetwork --> End
```

**图表来源**
- [src/cli.rs:78-116](file://src/cli.rs#L78-L116)
- [src/cli.rs:296-463](file://src/cli.rs#L296-L463)

**章节来源**
- [src/cli.rs:1-669](file://src/cli.rs#L1-L669)

### 配置管理模块分析

配置管理模块负责处理各种配置文件的读取、解析和验证：

```mermaid
classDiagram
class ProxyConfig {
+Vec~String~ scan_dirs
+String apps_config_path
+String nginx_config_path
+String compose_config_path
+String state_file_path
+String network_list_path
+String network_name
+u16 nginx_host_port
+String web_root
+String cert_dir
+Option~String~ domain
+from_file(path) Result~Self~
+load_apps() Result~Vec~AppConfig~~
+save_apps(apps) Result
+validate(apps, discovered) Result
}
class AppConfig {
+String name
+Vec~String~ routes
+String container_name
+u16 container_port
+AppType app_type
+Option~String~ description
+Option~String~ nginx_extra_config
+Option~String~ path
+Vec~String~ docker_volumes
+Option~String~ run_as_user
}
class AppType {
<<enumeration>>
Static
Api
Internal
}
ProxyConfig --> AppConfig
AppConfig --> AppType
```

**图表来源**
- [src/config.rs:125-367](file://src/config.rs#L125-L367)

**章节来源**
- [src/config.rs:1-842](file://src/config.rs#L1-L842)

### 应用发现模块分析

应用发现模块实现了智能的微应用扫描和验证功能：

```mermaid
flowchart TD
ScanDirs["扫描目录列表"] --> IterateDirs["遍历每个目录"]
IterateDirs --> CheckEntry["检查目录项"]
CheckEntry --> IsDirectory{"是否为目录?"}
IsDirectory --> |否| NextEntry["下一个目录项"]
IsDirectory --> |是| CheckMicroAppYml["检查 micro-app.yml"]
CheckMicroAppYml --> HasMicroAppYml{"存在 micro-app.yml?"}
HasMicroAppYml --> |否| NextEntry
HasMicroAppYml --> |是| GenerateName["生成唯一名称"]
GenerateName --> ValidateName{"名称唯一性验证"}
ValidateName --> |重复| SkipDir["跳过目录"]
ValidateName --> |通过| LoadMicroApp["加载微应用信息"]
LoadMicroApp --> ValidateMicroApp["验证微应用"]
ValidateMicroApp --> Valid{"验证通过?"}
Valid --> |否| SkipDir
Valid --> |是| AddToList["添加到应用列表"]
AddToList --> NextEntry
NextEntry --> MoreEntries{"还有更多条目?"}
MoreEntries --> |是| CheckEntry
MoreEntries --> |否| CompleteScan["扫描完成"]
```

**图表来源**
- [src/discovery.rs:235-352](file://src/discovery.rs#L235-L352)

**章节来源**
- [src/discovery.rs:1-721](file://src/discovery.rs#L1-L721)

### 状态管理模块分析

状态管理模块提供了基于目录 hash 的增量构建能力：

```mermaid
classDiagram
class StateManager {
+PathBuf state_file_path
+HashMap~String,AppState~ states
+new(state_file_path) StateManager
+load() Result
+save() Result
+get_state(app_name) Option~&AppState~
+update_state(app_name, hash, image_exists) void
+remove_state(app_name) void
+needs_rebuild(app_name, current_hash) bool
+get_all_states() Iterator~&AppState~
}
class AppState {
+String app_name
+String hash
+DateTime~Utc~ last_built
+bool image_exists
}
StateManager --> AppState
```

**图表来源**
- [src/state.rs:30-186](file://src/state.rs#L30-L186)

**章节来源**
- [src/state.rs:1-311](file://src/state.rs#L1-L311)

## 依赖分析

项目采用现代化的 Rust 生态系统，主要依赖包括：

```mermaid
graph TB
subgraph "核心依赖"
Serde[Serde 1.0]
Clap[Clap 4.5]
anyhow[anyhow 1.0]
thiserror[thiserror 1.0]
log[log 0.4]
chrono[chrono 0.4]
end
subgraph "文件系统"
walkdir[walkdir 2.5]
fs_extra[fs_extra 1.3]
pathdiff[pathdiff 0.2]
end
subgraph "加密和正则"
sha2[sha2 0.10]
regex[regex 1.11]
end
subgraph "异步运行时"
tokio[tokio 1.0]
end
subgraph "配置管理"
dumbo_config[dumbo_config 0.1]
dumbo_log[dumbo_log 0.3]
end
subgraph "开发依赖"
tempfile[tempfile 3.13]
end
Serde --> Clap
Serde --> dumbo_config
log --> dumbo_log
walkdir --> sha2
tokio --> Serde
```

**图表来源**
- [Cargo.toml:13-55](file://Cargo.toml#L13-L55)

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

## 性能考虑

### 构建优化策略
- 使用目录 hash 进行增量构建，避免不必要的镜像重建
- 支持强制重建模式，通过 `--force-rebuild` 参数启用
- 智能的 Docker Compose 配置生成，减少重复工作

### 内存管理
- 使用 `walkdir` 进行高效的目录遍历
- 采用 `HashMap` 进行状态缓存，提供 O(1) 查找性能
- 合理的内存分配策略，避免大对象的频繁创建

### 并发处理
- 利用 Rust 的并发模型，避免数据竞争
- 使用 `tokio` 异步运行时提升 I/O 性能

## 故障排除指南

### 常见问题诊断

#### 配置文件问题
- 检查 YAML 格式是否正确
- 验证必需字段是否完整
- 确认路径配置的正确性

#### Docker 相关问题
- 确认 Docker 服务正常运行
- 检查网络权限和端口占用
- 验证镜像构建上下文路径

#### 权限问题
- 确认用户对配置文件有读取权限
- 检查 Docker socket 权限
- 验证卷挂载目录的访问权限

**章节来源**
- [src/error.rs:1-50](file://src/error.rs#L1-L50)

## 结论

micro_proxy 提供了一个完整、可靠的微服务管理解决方案。其模块化设计、完善的错误处理机制和丰富的功能特性使其成为微服务开发和部署的理想选择。

## 附录

### 开发环境搭建

#### 系统要求
- Rust 1.60+ (推荐使用 rustup 管理)
- Docker Engine 20.10+
- Docker Compose 2.0+

#### 安装步骤
1. 克隆项目仓库
2. 安装 Rust 工具链
3. 安装 Docker 和 Docker Compose
4. 运行 `cargo build` 进行编译

#### 开发工具推荐
- IDE: VS Code + Rust 插件
- 调试器: LLDB 或 GDB
- 代码格式化: rustfmt
- 代码检查: clippy

### 代码规范

#### 命名约定
- 模块名：snake_case
- 结构体名：PascalCase
- 方法名：snake_case
- 常量名：SCREAMING_SNAKE_CASE

#### 错误处理
- 使用 `anyhow` 进行错误传播
- 使用 `thiserror` 定义自定义错误类型
- 提供有意义的错误消息

#### 文档注释
- 为公共 API 添加完整的文档注释
- 使用标准的 Rust 文档格式
- 包含使用示例和注意事项

### 测试指南

#### 单元测试
- 为每个模块编写单元测试
- 使用 `#[cfg(test)]` 标记测试代码
- 测试边界条件和异常情况

#### 集成测试
- 测试完整的命令执行流程
- 验证配置文件的正确性
- 测试 Docker 集成功能

### 提交规范

#### Git 提交消息
```
<type>(<scope>): <subject>

<body>

<footer>
```

#### 提交类型
- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建过程或辅助工具变动

### 版本发布

#### 发布流程
1. 更新版本号 (Cargo.toml)
2. 生成变更日志
3. 运行完整测试套件
4. 构建发布版本
5. 上传到 crates.io

#### 版本策略
- 遵循语义化版本控制
- 重大变更使用主版本号
- 功能更新使用次版本号
- 修复使用修订版本号

### 社区贡献

#### 交流渠道
- GitHub Issues: 问题报告和功能请求
- GitHub Discussions: 一般讨论和技术交流
- 邮件: zongying_cao@163.com

#### 行为准则
- 尊重他人的贡献
- 提供建设性的反馈
- 保持开放和包容的态度

### 许可证

项目采用 MIT 许可证，允许自由使用、修改和分发，但需保留原始版权声明和许可声明。