Lib.rs

Crud Api

此 crate 提供了一个框架，用于生成从 CLI 操作您的 HTTP API 的可执行文件。

使用此库的应用可以替换您需要访问您最喜欢的 API 时的 curl 查询。

功能

API

• 数据以 JSON 编码。它不支持 XML、grpc 等。
• 输出可以格式化为 json、yaml、toml、csv 或 tsv
• 输出流到 stdout 或文件中

教程

让我们为 jsonplaceholder API 创建一个 CLI。对于急于看到结果的人，这个示例的完整代码可以在 examples/jsonplaceholder_api.rs 中找到

首先将这些依赖项添加到 Cargo.toml

[dependencies]
log = "0.4"
pretty_env_logger = "0.5"
clap = "4.3"
crud-api = {version = "0.1", path="../crud/crud-api", default-features=false, features=["toml","json","yaml"]}
crud-auth = {version = "0.1", path="../crud/crud-auth"}
crud-auth-bearer = {version = "0.1", path="../crud/crud-auth-bearer"}
hyper = { version = "0.14", features = ["client","http1"] }
hyper-tls = "0.5"
miette = { version = "5.9", features = ["fancy"] }
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
# To force static openssl
openssl = { version = "0.10", features = ["vendored"] }

现在，创建一个最小的运行器结构和 main 函数。在 JSONPlaceHolder 上使用 ApiRun 继承所有 CLI。

use crud_api::ApiRun;
use crud_auth::CrudAuth;
use crud_auth_no_auth::Auth;
use miette::{IntoDiagnostic, Result};

#[derive(ApiRun)]
struct JSONPlaceHolder;

#[tokio::main]
async fn main() -> Result<()> {
  JSONPlaceHolder::run().await
}

crud_api_endpoint::ApiRun 接受一些参数。它们在 crud_api_endoint 包中进行了文档说明。让我们使用一个 base_url 来自定义我们的 CLI，该 base_url 用于 API、文档和设置中的 name。 qualifier 和 organisation 用于计算设置位置，而 env_prefix 是环境变量的前缀

#[derive(ApiRun)]
#[api(infos(
  base_url = "http://jsonplaceholder.typicode.com",
  name = "jsonplaceholder",
  qualifier = "com",
  organisation = "typicode",
  env_prefix = "JSONPLACEHOLDER"
))]
struct JSONPlaceHolder;

在创建第一个端点之前，我们需要描述其输出结构。

use serde::{Deserialize, Serialize};
#[derive(Debug, Default, Deserialize, Serialize)]
struct Post {
  id: u32,
  #[serde(rename = "userId")]
  user_id: u32,
  title: String,
  body: String,
}

现在，我们可以声明端点。最小参数包括

• route，目标 API 路由。
• cli_route，作为 CLI 参数转换的路由。每个斜杠分隔一个子命令。其他参数可以在 crud_api_endpoint::Api 和 crud_api_endpoint::Enpoint 结构的文档中找到。

use crud_api::Api;
#[derive(Api, Debug, Default, Deserialize, Serialize)]
#[api(
  endpoint(
    route = "/posts",
    cli_route = "/post",
    multiple_results,
  ))]
struct Post {
  id: u32,
  #[serde(rename = "userId")]
  user_id: u32,
  title: String,
  body: String,
}

我们可以创建更复杂的端点。让我们创建一个编辑路由。

• route 参数接收一个帖子的 id 参数。这个参数应该在 cli_route 中存在。
• HTTP 方法通过 method 参数设置。
• 可以通过 cli_help 和 cli_long_help 参数提供一些帮助信息。
• 负载由使用 payload_struct 声明的结构体描述。可以通过 query_struct 参数添加查询参数。

在此步骤中，负载结构是 PostCreate（创建和更新都使用相同的结构）。PostCreate 继承自 ApiInput。所有 PostCreate 字段参数的描述在 crud_api_endpoint::ApiInputConfig 结构体中。

use crud_api::{Api, ApiInput};
#[derive(Api, Debug, Default, Deserialize, Serialize)]
#[api(
  endpoint(
    route = "/posts",
    cli_route = "/post",
    multiple_results,
  ),
  endpoint(
    route = "/posts/{id}",
    method = "PUT",
    payload_struct = "PostCreate",
    cli_route = "/post/{id}/replace",
    cli_help = "Update a Posts (replace the whole post)"
  )
)]
struct Post {
  id: u32,
  #[serde(rename = "userId")]
  user_id: u32,
  title: String,
  body: String,
}

#[derive(Debug, ApiInput, Default, Serialize, Deserialize)]
#[allow(dead_code, non_snake_case)]
struct PostCreate {
  #[api(long = "user-id")]
  userId: u32,
  #[api(no_short, help = "Title of the post")]
  title: String,
  #[api(no_short)]
  body: String,
}

输出自定义

表格

结果数组使用 crud-tidy-viewer crate 格式化。可用的表格列选项有

• table_skip：在表格中不显示此字段。
• table_format：在表格中格式化此字段。
  • 日期格式化器：date(format = "%Y-%m-%d %H:%M:%S")

漂亮的结构

crate crud-pretty-struct 可以格式化单个（json）结构。