Scryfall SDK

这是一个为神奇的 Scryfall 搜索引擎 提供的轻量级 SDK（http api-binding），Scryfall 是一款强大的用于寻找《万智牌》卡片、系列等的搜索工具。

此 SDK 主要用于学习和练习 Rust 技能。

要求

• 最低 Rust 版本: 1.61

用法

将依赖项添加到 Cargo.toml

[dependencies]
scryfall_sdk_rust = "0.1"

SDK 通过 reqwest crate 提供了两个 HTTP 客户端

• 异步客户端（默认）通过 Scryfall 结构体
• 阻塞客户端通过 ScryfallBlocking 结构体

注意 要使用阻塞客户端，您必须在 Cargo.toml 中启用 blocking 可选功能。

[dependencies]
scryfall_sdk_rust = {version = "0.1", features = ["blocking"] }

示例

为了使用 SDK，您必须使用其中一个客户端实例，并通过实现资源之一使用它来发出请求。

例如

通过 Scryfall id 获取单个卡片（异步）

use std::error::Error;
use scryfall_sdk_rust::{CardResource, Scryfall};

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let scryfall = Scryfall::default();

    let card = scryfall.request(
        &CardResource::ById("f295b713-1d6a-43fd-910d-fb35414bf58a")
    ).await?;

    Ok(println!("{:?}", card))
}

卡片搜索

Scryfall 提供了一种非常强大的 搜索语法，您可以使用它来搜索卡片。 注意 目前 SDK 仅提供在查询参数中使用行 q 字符串的用法。未来的版本将提供支持单独搜索关键字的 Rust 流畅 API。

查找攻击力为 3 的红色生物（异步）

use std::error::Error;
use scryfall_sdk_rust::{CardPageResource, Scryfall};
use scryfall_sdk_rust::resources::cards::SearchQueryParams;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let scryfall = Scryfall::default();

    let search = CardPageResource::Search(
        SearchQueryParams::with_q("c%3Ared+pow%3D3")
    );

    let cards = scryfall.request(&search).await?;

    Ok(println!("{:?}", cards))
}

错误响应处理

在前面的非常基本的示例中，任何类型的错误，无论是 API 的错误响应还是客户端错误，都会传播到 Result 返回的 main 函数。这是通过特殊的 ? Rust 操作符实现的，该操作符将错误传播到函数的调用者。

在实际情况下，您可能需要在某个时候处理这些错误，至少是API返回的错误响应（例如404）。客户端的request函数返回一个Result<M, ErrorBody>，该结果应包含预期的对象（例如Card）的模型，在成功的情况下，或者在出错的情况下包含一个ErrorBody。有关错误响应有效负载（ErrorBody）的更多信息，请参阅Scryfall文档。

以下是一个可能的错误处理示例：

use std::error::Error;
use scryfall_sdk_rust::{CardResource, Scryfall};

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let scryfall = Scryfall::default();

    let card = scryfall.request(
        &CardResource::ById("f295b713-1d6a-43fd-910d-fb35414bf58a")
    ).await; // <1>

    println!("{:?}", card
        .map_err(|e| format!("Error {}: {}", e.status, e.details)
    )); // <2>

    let error = scryfall.request(
        &CardResource::ById("invalid")
    ).await; // <3>

    Ok(println!("{:?}", error
        .map_err(|e| format!("Error {}: {}", e.status, e.details))
    )) // <4>
}

对于客户端错误，例如当Scryfall API服务器无法解析或由于某种原因无法解码json响应时，将返回一个特殊的ErrorBody。这将具有code = CLIENT_ERR和status = 599，其中details包含原始错误原因。

实现资源列表

以下资源目前已被实现：

• CardResource -> https://scryfall.com/docs/api/cards（单个）
• CardPageResource -> https://scryfall.com/docs/api/cards（页面/搜索）
• CardCatalogResource -> https://scryfall.com/docs/api/cards/autocomplete
• CardCollectionResource -> https://scryfall.com/docs/api/cards/collection
• BulkDataListResource -> https://scryfall.com/docs/api/bulk-data（列表）
• BulkDataResource -> https://scryfall.com/docs/api/bulk-data（单个）
• CatalogResource -> https://scryfall.com/docs/api/catalogs
• CardSymbolsResource -> https://scryfall.com/docs/api/card-symbols/all
• ManaCostResource -> https://scryfall.com/docs/api/card-symbols/parse-mana
• CardSetListResource -> https://scryfall.com/docs/api/sets（列表）
• CardSetResource -> https://scryfall.com/docs/api/sets（单个）
• RulingListResource -> https://scryfall.com/docs/api/rulings