aria

🎯 与主流框架对比

一句话：aria 把响应式引擎从 UI 框架里拆出来，做成纯 C++20 头文件库。你选什么 UI 工具包都行，ViewModel 一份代码跑六个平台。

✨ 核心特性

• 📦 仅头文件核心 —— Property<T> / Computed<T> / Effect / Command<> / ObservableList<T> / Validator<T> 共享同一个响应式依赖图引擎。Computed 自动跟踪依赖，reactive::batch / reactive::untracked 精确控制通知范围。
• 🔌 类型擦除 ABI 层 —— aria-abi / aria-runtime / aria-binding 在主版本号内 ABI 稳定；模板层仅源码兼容。
• ⚡ C++20 协程 —— Task<T>、执行器、co_await schedule_on(pool)，异步代码写起来像同步代码。
• 🖥 适配器抽象 (IViewAdapter) —— Qt6 / AppKit / UIKit / JNI / HTTP / WASM，任何 UI 工具包都能用同一套业务逻辑驱动。

🏗 架构（10 个模块）

┌────────────────────────────────────────────────────────────────────────┐
│                         应用层 (Application)                            │
└────────────────────────────────┬───────────────────────────────────────┘
              ┌──────────────────┼──────────────────┐
              ▼                  ▼                  ▼
   ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
   │ Qt6 适配器    │    │ JNI 适配器    │    │ HTTP 适配器   │     (可选模块；
   │ (Win/Mac/Lin)│    │  (Android)   │    │ REST/SSE Web │      按需启用)
   │ AppKit/UIKit │    │              │    │ WASM 计划中   │
   └──────┬───────┘    └──────┬───────┘    └──────┬───────┘
          └───────────────────┴───────────────────┘
                              ▼
              ┌─────────────────────────────────┐
              │    aria-binding  (SHARED)       │
              │  BindingEngine + IViewAdapter   │
              └────────────────┬────────────────┘
                               │
        ┌──────────────────────┴───────────────────────┐
        ▼                                              ▼
┌───────────────────┐                       ┌────────────────────┐
│ aria-runtime      │                       │  aria-async        │
│ (SHARED .dylib)   │                       │   (仅头文件)        │
│ EventBus          │                       │ Task<T>            │
│ Container         │                       │ Scheduler          │
│ Dispatcher        │                       │ Executor           │
│ Logger            │                       │ schedule_on        │
└───────┬───────────┘                       └─────────┬──────────┘
        └──────────────────┬─────────────────────────┘
                           ▼
              ┌─────────────────────────────┐
              │ aria-core  (仅头文件)        │
              │ Property / Computed / Cmd   │
              │ ObservableList / Validator  │
              │ Subscription                │
              └────────────┬──────────────┘
                             ▼
              ┌─────────────────────────────┐
              │  aria-abi  (STATIC .a)      │
              │ 类型擦除 Signal/Slot         │
              │ ABI 稳定，无模板              │
              └─────────────────────────────┘

📋 环境要求

• CMake >= 3.20
• 完整支持 C++20 的编译器：
  • GCC >= 12（Windows 下可走 MSYS2 UCRT64 工具链）
  • Clang >= 15（macOS/iOS 上 AppleClang 15+ 即可）
  • MSVC v143 / Visual Studio 2022（Windows，详见下文）
• (可选) Qt6 >= 6.4（用于 Qt6 适配器和 GUI 示例）

Windows 同时支持 MSYS2 UCRT64（GCC）和 MSVC / Visual Studio 2022 两条工具链。 团队栈里有哪个就用哪个 —— 同一棵源码树都能编出完整框架 + 测试 + 适配器，不需要分支或 fork。

🚀 快速开始

git clone https://github.com/dqsjqian/aria.git
cd aria
cmake -B build/flavors/release -DCMAKE_BUILD_TYPE=Release
cmake --build build/flavors/release -j
ctest --test-dir build/flavors/release --output-on-failure

build/ 是构建树的容器，不要直接配置进它。统一布局见 scripts/build.sh 顶部。

🔧 一键构建脚本

# macOS / Linux
scripts/build.sh             # Release
scripts/build.sh tests       # Release + 跑测试
scripts/build.sh asan        # Debug + AddressSanitizer + UBSan
scripts/build.sh tsan        # Debug + ThreadSanitizer

# Windows —— MSYS2 UCRT64（GCC + Ninja）
scripts\build.ps1            # Release
scripts\build.ps1 tests
scripts\build.ps1 asan

# Windows —— MSVC / Visual Studio 2022
scripts\build-msvc.ps1       # Release（使用 build/flavors/msvc/ 目录）
scripts\build-msvc.ps1 tests
scripts\build-msvc.ps1 debug

🛠 Windows 工具链

# 1. 安装 Visual Studio 2022 Build Tools（或完整 IDE），勾选
#    "Desktop development with C++" + "C++ CMake tools"。
# 2. （可选）安装 Qt 6 的 msvc2022_64 组件。
# 3. 任意 PowerShell 窗口里：
scripts\build-msvc.ps1 tests

# 1. 从 https://www.msys2.org 安装 MSYS2
# 2. 打开 "MSYS2 UCRT64" 终端：
pacman -Syu
pacman -S --needed mingw-w64-ucrt-x86_64-toolchain \
                   mingw-w64-ucrt-x86_64-cmake \
                   mingw-w64-ucrt-x86_64-ninja git
# 3. （可选）把 C:\msys64\ucrt64\bin 加入 PATH
# 4. 从任意终端执行：
scripts\build.ps1 tests

📦 在自己的项目中使用

方式 A —— 先安装，再用 find_package（生产环境推荐）：

cmake -S . -B build/flavors/release -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build build/flavors/release -j && sudo cmake --install build/flavors/release

find_package(aria 1.0 REQUIRED)
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE aria::aria)
# 也可以按需选择模块：aria::core / ::async / ::runtime / ::binding

方式 B —— 直接嵌入（不安装）：

add_subdirectory(third_party/aria EXCLUDE_FROM_ALL)
target_link_libraries(my_app PRIVATE aria::core aria::async)

即拷即用的模板在 templates/quickstart/。

💻 示例项目

aria 提供覆盖每一个受支持 UI 工具包的可运行示例，外加几个无界面、专门压核心的控制台示例。

UI 展示示例：

无界面 / 控制台示例（ARIA_BUILD_EXAMPLES=ON）：

# 示例 1（Qt）
cmake -S . -B build/flavors/qt-demo -DARIA_BUILD_QT6=ON
cmake --build build/flavors/qt-demo -j
./build/flavors/qt-demo/bin/ex_qt_showcase

# 示例 4（web）—— 需要 HTTP 适配器
cmake -S . -B build/flavors/web-demo -DARIA_BUILD_HTTP=ON
cmake --build build/flavors/web-demo --target example_4_web_mvvm

⚙️ 构建选项

👋 Hello, world

#include "aria/aria.hpp"
using namespace aria;

Property<int> count{0};

// 不再需要显式依赖列表 —— Computed 首次求值时，
// 内部读到的每一个 Property::get() 都会被自动追踪为依赖。
Computed<std::string> label([&]{
    return "count = " + std::to_string(count.get());
});

Command<> increment([&]{ count = count.get() + 1; });

auto sub = label.bind([](const std::string& s) { std::cout << s << '\n'; });

increment();   // → "count = 1"
increment();   // → "count = 2"

⚡ 异步编程（C++20 协程）

#include "aria/async/task.hpp"
#include "aria/async/executor.hpp"
using namespace aria::async;

Task<std::string> fetch_user(int id) {
    co_await schedule_on(network_pool);     // 跳到工作线程
    auto raw = http::get("/users/" + std::to_string(id));
    co_await schedule_on(main_dispatcher);   // 切回 UI 线程
    co_return parse(raw);
}

🌍 跨平台映射

🧪 测试状态

$ ctest --test-dir build --output-on-failure
    Start 1: abi_tests           ✅ Passed
    Start 2: core_tests          ✅ Passed
    Start 3: fuzz_tests          ✅ Passed
    Start 4: async_tests         ✅ Passed
    Start 5: runtime_tests       ✅ Passed
    Start 6: binding_tests       ✅ Passed
    Start 7: qt6_tests           ✅ Passed   (ARIA_BUILD_QT6=ON)
    Start 8: appkit_conformance  ✅ Passed   (Apple 平台)
    Start 9: appkit_table_source ✅ Passed   (Apple 平台)

100% tests passed, 0 tests failed

75+ 个测试用例覆盖 docs/reference/lifecycle.md、docs/reference/error-model.md 中所有生命周期 / 重入 / 异常安全契约。

📊 性能基准（Apple M 系列, -O3 -DNDEBUG）

📋 框架本体契约

所有非平庸行为都钉在带编号的契约文档里，每条契约有稳定 ID（如 L-13 / E-22 / LD-7）。

🗺 路线图

Aria 已开源（MIT License），源码托管在 GitHub。待办与已延后清单的唯一信息源在 docs/ROADMAP.md；当前能力快照见 CHANGELOG.md。

🤝 贡献指南

欢迎贡献！涉及架构改动的请先开 Issue 讨论。

• 代码风格由 .clang-format 和 .clang-tidy 统一管控
• 所有变更必须通过 ctest --output-on-failure
• 新功能需要在对应 modules/*/tests/ 套件中补充测试

🙏 致谢

• doctest —— 轻量级测试框架
• nlohmann_json —— JSON for Modern C++
• cpp-httplib —— HTTP/HTTPS server
• OpenSSL —— TLS 1.2/1.3（3.5 LTS）
• CPM.cmake —— CMake 依赖管理

📄 License

MIT © 2026 aria contributors