Scryfall SDK 技术指南：高效访问万智牌API的JavaScript工具库

概述

Scryfall SDK是一个专为万智牌(MTG)开发者设计的JavaScript工具库，它提供了对Scryfall API的完整封装。Scryfall是当前最全面的万智牌数据库，包含所有卡牌、系列、规则和符号信息。本指南将详细介绍如何使用这个SDK来获取和处理万智牌相关数据。

基础配置

设置用户代理

Scryfall API要求所有非浏览器应用必须设置用户代理标识：

import Scry = require("scryfall-sdk");
Scry.setAgent("MyMTGApp", "1.0.0");

这个标识帮助Scryfall团队跟踪API使用情况，并在出现问题时能联系到你。

卡牌数据操作

基本卡牌查询方法

Scryfall SDK提供了多种方式来获取单张卡牌信息：

1. 通过Scryfall ID查询：

const card = await Scry.Cards.byId("9ea8179a-d3c9-4cdc-a5b5-68cc73279050");

2. 通过名称查询（支持模糊匹配）：

// 精确匹配
const exactCard = await Scry.Cards.byName("Lightning Bolt");

// 模糊匹配（允许拼写错误）
const fuzzyCard = await Scry.Cards.byName("Ligtning Bolt", true);

3. 通过系列和编号查询：

const card = await Scry.Cards.bySet("mrd", "150");

高级查询功能

1. 搜索功能：

// 查找所有生物牌
Scry.Cards.search("type:creature")
  .on("data", card => console.log(card.name))
  .on("end", () => console.log("搜索完成"));

2. 随机卡牌：

// 随机一张牌
const randomCard = await Scry.Cards.random();

// 随机一张鹏洛客牌
const randomWalker = await Scry.Cards.random("type:planeswalker");

3. 名称自动完成：

const suggestions = await Scry.Cards.autoCompleteName("bloodsc");
// 返回：["Bloodscent", "Blood Scrivener", ...]

批量卡牌查询

使用collection方法可以批量获取多张卡牌信息：

const cards = await Scry.Cards.collection(
  Scry.CardIdentifier.byName("Lightning Bolt"),
  Scry.CardIdentifier.bySet("mrd", "150"),
  // 更多卡牌标识...
).waitForAll();

SDK会自动处理Scryfall的75张卡牌限制，将大请求拆分为多个API调用。

卡牌对象扩展功能

获取卡牌对象后，可以进一步获取相关信息：

1. 获取所属系列：

const set = await card.getSet();

2. 获取所有印刷版本：

const prints = await card.getPrints();

3. 获取规则解释：

const rulings = await card.getRulings();

4. 合法性检查：

// 检查在薪传赛制是否合法
const isLegacyLegal = card.isLegal("legacy");

// 检查在标准赛制是否被禁
const isStandardBanned = card.isIllegal("standard");

符号转换功能

Scryfall SDK提供了强大的符号转换功能，可以将卡牌文本中的符号（如{U}、{B/W}）转换为其他格式：

// 设置为Discord表情格式
Scry.Cards.setSymbologyTransformer(":mana$1$2:");

// 获取转换后的卡牌文本
const formattedText = card.getText();
// 示例输出：":mana3::manaG:: Put a +1/+1 counter..."

系列数据操作

系列查询方法

1. 通过系列代码查询：

const set = await Scry.Sets.byCode("mrd");

2. 通过名称查询：

const set = await Scry.Sets.byName("Mirrodin");

3. 获取所有系列：

const allSets = await Scry.Sets.all();

系列对象功能

获取系列对象后，可以查询该系列的所有卡牌：

const cards = await set.getCards();

其他实用功能

规则查询

可以直接查询卡牌的规则解释，无需先获取卡牌对象：

const rulings = await Scry.Rulings.bySet("dgm", 22);

符号系统

1. 获取所有符号：

const symbols = await Scry.Symbology.all();

2. 解析法术力费用：

const manaCost = await Scry.Symbology.parseMana("{1}{W}{U}");

分类目录

Scryfall提供了多种分类目录查询：

// 获取所有生物类型
const creatureTypes = await Scry.Catalog.creatureTypes();

// 获取所有关键词异能
const keywordAbilities = await Scry.Catalog.keywordAbilities();

性能优化技巧

1. 设置超时：

Scry.setTimeout(5000); // 5秒超时

2. 重试机制：

Scry.setRetry(3, 1000); // 最多重试3次，每次间隔1秒

3. 自定义模糊搜索算法：

Scry.setFuzzySearch(myCustomSearchAlgorithm);

总结

Scryfall SDK为万智牌开发者提供了强大而灵活的工具集，从简单的卡牌查询到复杂的批量处理，都能轻松应对。通过合理使用其提供的各种功能，你可以构建出功能丰富的万智牌相关应用。无论是卡牌数据库、套牌构建工具，还是规则查询应用，这个SDK都能成为你的得力助手。