schemaui：为你的应用添加交互式配置，只用 3 行代码！

TL;DR：作为 CLI 工具开发者，你不再需要手动解析 JSON/YAML 配置，也不需要写复杂的参数校验逻辑。schemaui 能将你的 JSON Schema 一键转换为交互式终端 UI，让用户优雅地编辑配置。支持预填充当前值、实时验证、自动保存，集成简单，用户体验极佳。

---

🔗 链接

• schemaui 库：https://crates.io/crates/schemaui
• schemaui GitHub：https://github.com/yuniqueunic/schemaui
• schemaui-cli：https://crates.io/crates/schemaui-cli
• CLI GitHub：https://github.com/yuniqueunic/schemaui/tree/main/schemaui-cli

---

⚡ 为什么选择 schemaui 作为库？

如果你正在开发一个 CLI 工具，需要用户配置，你通常会遇到这些痛点：

痛点 1：参数太多，clap 定义爆炸

#[derive(Clap)]
struct Args {
    #[clap(long)]
    runtime_http_host: String,
    #[clap(long)]
    runtime_http_port: u16,
    #[clap(long)]
    runtime_http_timeout: u64,
    // ... 30 个字段，难以维护
}

痛点 2：让用户手动编辑 config.json

• 他们总会：a) 破坏 JSON 语法 b) 填错类型 c) 漏掉必填字段
• 你的 issue 区全是配置问题

痛点 3：自己写配置向导

• 200 行代码，只处理了 3 个字段，还要手动同步 Schema

schemaui 的解决方案：你已经有 JSON Schema 了，直接用！

// 3 行代码，搞定所有配置逻辑
let config = SchemaUI::new(load_schema())
    .with_default_data(&current_config)  // 可选：预填充当前值
    .run()?;  // 返回 Result<Value>，用户编辑的结果

// 就这么简单：
// ✅ 自动生成表单界面
// ✅ 必填字段一目了然
// ✅ 枚举值下拉选择
// ✅ 数字范围验证
// ✅ 数组增删改
// ✅ 嵌套对象编辑

---

🚀 核心特性（以库为主）

1. 极简集成，返回干净的 Value

// run() 返回 Result<Value>，你可以自由处理
let edited_config = SchemaUI::new(my_schema).run()?;

// 直接序列化
std::fs::write("config.json", serde_json::to_string_pretty(&edited_config)?)?;

// 或者应用到你的结构体
let app_config: AppConfig = serde_json::from_value(edited_config)?;

2. 预填充当前配置（with_default_data）

// 读取当前配置
let current = load_config().unwrap_or(json!({}));

// 让用户基于当前值编辑
let new_config = SchemaUI::new(schema)
    .with_default_data(&current)  // 预填充
    .run()?;

// 用户体验：
// $ myapp --configure
// [Tab] 跳到想改的字段
// [Enter] 修改
// [Ctrl+S] 保存 → 得到完整的新配置

3. 自动保存到文件/stdout（with_output）

// 用户编辑后自动保存，你不需要手动处理
SchemaUI::new(schema)
    .with_output(OutputOptions::file("config.toml"))  // 自动保存
    .run()?;  // 还是返回 Value

// 或者多目标
.with_output(
    OutputOptions::new(DocumentFormat::Json)
        .add_destination(File("config.json"))
        .add_destination(Stdout)  // 同时输出到 stdout
)

4. JSON Schema Draft-07 支持

• ✅ patternProperties - 正则匹配属性名
• ✅ oneOf / anyOf - 变体类型选择
• ✅ enum - 枚举值下拉选择
• ✅ array - 内联列表 + 浮面编辑器
• ✅ default / required - 默认值和必填验证

5. 实时验证，错误精确到字段

# 用户输入时立即看到：
/runtime/http/port: expected integer, got string
/metadata/environment: "devx" is not one of ["dev", "staging", "prod"]

6. 键盘优先，开发者友好的快捷键

快捷键	功能	说明
Ctrl+E	Edit	打开编辑器
Ctrl+S	Save	保存 + 验证
Ctrl+N	New	新建数组项
Ctrl+D	Delete	删除
Tab	Next	字段间切换

设计哲学：保留首字母，10 秒上手。

---

🛠️ 实际应用场景

场景 1：微服务开发 - 快速调参测试

// 开发时频繁改配置？
// 老方法：vi config.json → 改 → 重启 → 报错 → 循环

// 新方法：./myservice --configure
#[clap(long)]
configure: bool,

if args.configure {
    let schema = include_str!("../config/schema.json");
    let current = load_config().unwrap_or(json!({}));

    let new_config = schemaui::SchemaUI::new(
        serde_json::from_str(schema)?
    )
    .with_default_data(&current)  // 从当前配置开始
    .with_title("Service Configuration")
    .run()?;  // 用户交互式编辑

    // 保存
    save_config(&new_config)?;
    println!("✅ Configuration updated, restarting...");

    // 重启服务
    restart_service();
}

// 开发者体验：
// $ ./myservice --configure
// [Tab] 跳到 runtime.http.port
// [Backspace] 删除 8080
// [Enter] 输入 8081
// [Ctrl+S] → 自动保存 + 重启
// （整个过程 5 秒，不用离开终端）

场景 2：CLI 工具 - 用户配置向导

// 新用户第一次使用
#[clap(long)]
setup: bool,

if args.setup {
    println!("欢迎使用 MyTool! 让我们创建配置文件...");

    let config = schemaui::SchemaUI::new(
        include_str!("config-schema.json")
    )
    .with_title("MyTool Initial Setup")
    .run()?;  // 引导式填写表单

    // 保存
    std::fs::write(
        "config.json",
        serde_json::to_string_pretty(&config)?
    )?;

    println!("✅ 配置已保存! 运行 `mytool start` 开始");
}

// 用户体验：
// ./mytool --setup
// → 看到清晰的表单
// → 实时验证，不会填错
// → 5 分钟后就能正常使用工具
//
// 对比手动编辑：
// → 复制 example.json
// → 阅读 20 分钟文档
// → 填错 3 个字段
// → 提交 issue
// → 等待回复

场景 3：测试配置矩阵

// 需要测试不同参数组合？
#[test]
fn test_performance_with_various_configs() {
    let base_config = json!({
        "host": "127.0.0.1",
        "port": 8080
    });

    let scenarios = [
        ("low-timeout", json!({"timeout": 100})),
        ("medium-timeout", json!({"timeout": 500})),
        ("high-timeout", json!({"timeout": 1000})),
    ];

    for (name, overrides) in scenarios {
        // 让用户交互式调整参数
        let test_config = schemaui::SchemaUI::new(SCHEMA)
            .with_default_data(&merge(&base_config, &overrides))
            .with_title(format!("Test Scenario: {}", name))
            .run()?;  // 可以微调参数

        // 运行测试
        let result = run_benchmark(&test_config);
        save_result(name, result);
    }
}

// 价值: 快速测试边界条件，不用手动改 20 个 config 文件

场景 4：集成到复杂 CLI 应用

// 嵌套在复杂的 CLI 中，提供配置子命令
enum Command {
    Start,
    Stop,
    Configure {
        #[clap(long)]
        schema: Option<PathBuf>,
    },
}

match args.command {
    Command::Configure { schema } => {
        let schema_value = load_schema(schema)?;
        let current = load_config().ok();

        let edited = schemaui::SchemaUI::new(schema_value)
            .with_default_data(current.as_ref())  // 如果有当前配置
            .with_output(OutputOptions::file("config.toml"))  // 自动保存
            .with_title("Application Configuration")
            .run()?;  // 返回编辑后的值

        // 还可以做后置处理
        validate_and_apply(&edited)?;
    }
    // ... 其他命令
}

---

📦 安装与使用

方式 1：作为库集成（强烈推荐）

[dependencies]
schemaui = "0.2.0"
serde_json = "1"

use schemaui::{SchemaUI, OutputOptions, OutputDestination};

// 基础用法
let config = SchemaUI::new(schema).run()?;

// 预填充 + 自动保存
let config = SchemaUI::new(schema)
    .with_default_data(&current)
    .with_output(OutputOptions::file("config.json"))
    .run()?;

// 处理返回值
save_config(&config)?;

方式 2：CLI 工具（快速体验）

cargo install schemaui-cli
# 安装后命令为 `schemaui`

# 快速试用
schemaui --schema examples/config-schema.json

---

🎯 对比其他方案

方案	集成成本	用户体验	验证	维护成本	灵活性
schemaui	3 行	⭐⭐⭐⭐⭐ 交互式	✅ 实时自动	低 (Schema=UI)	高 (返回 Value)
clap 嵌套 struct	50+ 行	⭐⭐ 命令行	❌ 手动	高	低
手动编辑 JSON	无需	⭐ 易错	⚠️ 事后	极高 (issue 多)	中
自写对话 UI	200+ 行	⭐⭐⭐ 一般	⚠️ 手动	极高	中
Web UI 生成器	中等	⭐⭐⭐⭐ 好	✅	中等	高 (需浏览器)

schemaui 的核心优势：

• Schema 就是 UI：修改 schema 自动更新界面，零重复工作
• 适合 CLI：终端内完成，不依赖浏览器
• 键盘优先：开发者最爱，效率高
• 灵活：run() 返回 Value，你可以自由处理
• 简单：几行代码搞定，专注业务逻辑

---

📊 当前状态：基本可用，积极开发中！

已稳定（生产使用）

• ✅ 核心库 0.2.0 发布，API 稳定
• ✅ JSON Schema Draft-07 支持
• ✅ CLI 工具可用，功能完整
• ✅ 实时验证和错误显示
• ✅ 键盘导航和语义化快捷键
• ✅ 多格式 I/O (JSON/YAML/TOML)

正在开发（Roadmap）

• 🔨 Web UI 生成：同一 Schema 生成 Web 表单（需要前端贡献者！）
• 🔨 编译时代码生成：从 Schema 生成 Rust 结构体（proc-macro）
• 🔨 交互式 CLI 参数：命令行参数也能交互式填写
• 🔨 自定义验证器：支持更多格式验证
• 🔨 主题系统：自定义颜色和样式

需要社区帮助

schemaui 核心功能已在个人项目中验证，但要服务更广泛的用户，需要你的参与：

欢迎贡献：

1. 测试反馈：在你的项目中试用，提 Bug、提需求
2. Web UI：懂 React/Vue/Svelte？一起来做 Web 前端生成！
3. proc-macro：有宏编程经验？编译时代码生成是个大 feature！
4. 文档和示例：更多使用场景的示例代码
5. 平台测试：Windows/Linux/macOS 不同终端的兼容性
6. 性能优化：超大规模 Schema 的解析性能

开发理念：KISS 原则

• 每个模块 <600 行代码（硬上限 800）
• 优先使用成熟 crate，不自造轮子
• API 简洁胜于过度设计

---

🌟 如何参与？

试试看（1 分钟）

cargo install schemaui-cli
schemaui --schema your-schema.json

集成到你的项目（1 分钟）

cargo add schemaui

// 加到你的 CLI
let base_config = json!({
    "host": "127.0.0.1",
    "port": 8080
});
let config = schemaui::SchemaUI::new(base_config)
    .run()?;

反馈和贡献

• 有 Bug? https://github.com/yuniqueunic/schemaui/issues
• 想要新功能? 提 Issue 或 PR
• 会用但不熟 Rust? 分享你的使用场景，我们帮你集成
• Star 支持：https://github.com/yuniqueunic/schemaui ⭐

你的参与能让 schemaui 变得更好！

---

觉得有用？Star 一下帮它获得更多曝光！
有建议或问题？评论区见！

Licensed under Apache 2.0 / MIT - 自由使用、修改、分发！