mirror of
https://github.com/exchanges-lab/tradesync.git
synced 2026-08-05 05:06:07 +08:00
0xcathiefish
116 lines
4.4 KiB
Markdown
116 lines
4.4 KiB
Markdown
# nosync
|
||
|
||
一款高效、解耦的异步消息处理与任务编排框架。
|
||
|
||
## 1. 项目简介
|
||
`nosync` 是一个高性能的 Rust 异步消息处理和组件协作框架，专为解决多模块间松耦合通信、结构化日志追踪以及鲁棒的错误恢复机制而设计。它主要面向需要高并发、低延迟以及强模块化设计的服务端开发人员，为构建复杂微服务或本地计算引擎提供核心底座。
|
||
|
||
## 2. 核心功能
|
||
* **模块化封装架构**：遵循面向对象设计原则，将组件封装为高内聚的 `pub struct` 并持有独立状态，杜绝全局可变状态与裸函数。
|
||
* **异步事件处理**：全面支持基于 `tokio` 运行时的多任务处理，提升高负载场景下的吞吐量。
|
||
* **结构化日志监控**：集成 `tracing` 系统，提供细粒度的业务追踪与故障还原能力。
|
||
* **强类型错误管理**：利用 `thiserror` 定义清晰的组件级错误，拒绝吞掉异常，确保系统的健壮性。
|
||
* **多环境适配能力**：天然支持通过 `.env` 文件和环境变量在运行时动态配置系统属性。
|
||
|
||
## 3. 架构与模块
|
||
本项目的目录结构与模块划分如下：
|
||
|
||
```
|
||
nosync/
|
||
├── src/
|
||
│ ├── lib.rs # 库入口，统一导出公共接口与类型
|
||
│ ├── structs.rs # 存放跨模块共享的纯数据结构
|
||
│ ├── module_a.rs # 业务模块 A (消息接收与底层处理)
|
||
│ └── module_b.rs # 业务模块 B (工作流编排与核心控制)
|
||
├── examples/ # 使用示例
|
||
│ └── demo.rs # 核心运行演示
|
||
├── tests/ # 集成测试
|
||
│ ├── module_a_test.rs
|
||
│ └── module_b_test.rs
|
||
├── references/ # Git 子模块与外部参考仓库目录
|
||
├── .env # 实际运行环境变量配置文件 (本地开发，不提交)
|
||
├── .env.example # 环境变量配置模板
|
||
├── Cargo.toml # Cargo 配置文件
|
||
└── CHANGELOG.md # 变更日志
|
||
```
|
||
|
||
* **ModuleA** (`ModuleA`)：负责消息接收、数据有效性校验与核心的异步解析处理。
|
||
* **ModuleB** (`ModuleB`)：负责编排 `ModuleA` 的执行流，充当协调器（Orchestrator）角色。
|
||
* **Structs** (`structs`)：定义了消息体 `SharedMessage` 等公共数据契约。
|
||
|
||
## 4. 环境要求
|
||
* **Rust**: `1.85.0` 或更高版本（支持最新 edition 2024）
|
||
* **OS**: Linux, macOS, Windows
|
||
* **运行时**: `tokio` (Full features)
|
||
|
||
## 5. 安装与启动
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/cathiefish/nosync.git
|
||
cd nosync
|
||
|
||
# 复制并配置环境变量
|
||
cp .env.example .env
|
||
# 可以根据需要修改 .env 中的内容
|
||
|
||
# 构建项目
|
||
cargo build --release
|
||
|
||
# 运行默认二进制应用
|
||
cargo run
|
||
|
||
# 运行使用示例
|
||
cargo run --example demo
|
||
```
|
||
|
||
## 6. 使用示例
|
||
最小可运行示例位于 [examples/demo.rs](file:///home/cathiefish/App/nosync/examples/demo.rs)：
|
||
```rust
|
||
use anyhow::Result;
|
||
use nosync::{ModuleA, ModuleB};
|
||
use tracing_subscriber::{EnvFilter, FmtSubscriber};
|
||
|
||
#[tokio::main]
|
||
async fn main() -> Result<()> {
|
||
let subscriber = FmtSubscriber::builder()
|
||
.with_env_filter(EnvFilter::new("info"))
|
||
.finish();
|
||
tracing::subscriber::set_global_default(subscriber)?;
|
||
|
||
// 初始化核心组件
|
||
let processor = ModuleA::new("example-processor".to_string())?;
|
||
let orchestrator = ModuleB::new(processor)?;
|
||
|
||
// 运行工作流
|
||
orchestrator.run().await?;
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
## 7. 环境变量说明
|
||
| 环境变量名 | 用途 | 是否必填 | 默认值 / 示例值 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `APP_NAME` | 应用程序或当前节点的名称标识，用于日志和初始化 | 否 | `nosync-default` |
|
||
| `RUST_LOG` | 设定日志输出级别 (e.g. error, warn, info, debug, trace) | 否 | `info` |
|
||
|
||
## 8. 测试与开发
|
||
### 开发分支约定
|
||
* `dev`：主开发分支，新功能与修复首发合并至此。
|
||
* `main`：生产稳定分支，当且仅当测试、Clippy 与格式化全部通过后才合并。
|
||
|
||
### 本地验证命令
|
||
在提交代码前，**必须**运行以下命令进行本地验证：
|
||
```bash
|
||
# 自动格式化代码
|
||
cargo fmt --all
|
||
|
||
# 运行代码规范检查（不能有 warnings）
|
||
cargo clippy --all-targets --all-features -- -D warnings
|
||
|
||
# 执行单元测试与集成测试
|
||
cargo test
|
||
```
|
||
|
||
## 9. 变更日志指引
|
||
关于项目的历史演进和每个版本的详细改动，请参阅 [CHANGELOG.md](file:///home/cathiefish/App/nosync/CHANGELOG.md)。
|