核心概念

在 maimai.py 中，我们使用了一种较为规范的方式定义了方法和接口的调用方式。

与 RESTful 规范类似，如果您能理解我们的规范，便可以直接使用符合直觉的方式进行开发，而不必过多阅读文档和API。

缓存

maimai.py 中的所有方法和接口都支持缓存机制，默认情况下会缓存 24 小时。

# ✅ 全局创建一个 MaimaiClient 实例, 避免缓存失效
maimai = MaimaiClient()
async def quick_start():
    songs: MaimaiSongs = await maimai.songs() # 填充缓存
    songs: MaimaiSongs = await maimai.songs() # 命中缓存

asyncio.run(quick_start())

DANGER

务必在全局只创建一个 MaimaiClient 实例，避免缓存失效。

异步

在 maimai.py 中，所有方法和接口都需要通过 MaimaiClient 进行异步的调用，类似下面的形式。

from maimai_py.maimai import MaimaiClient, MaimaiSongs

client: MaimaiClient = MaimaiClient()
songs: MaimaiSongs = await client.songs()

针对密集IO类应用，异步可以提供较大的开发优势，在不影响可读性的情况下避免阻塞，maimai.py仅支持异步。

我们尚未有提供同步调度的开发计划，如果您有使用上的困难，请联系我们，我们将尽可能为您提供帮助。

TIP

我们强烈推荐您在整个应用程序中共用 MaimaiClient 实例，因为缓存机制是基于 MaimaiClient 实例的。

如果您在不同的地方创建了多个 MaimaiClient 实例，会导致缓存失效，造成性能损失。

封装对象

上文提到过的 MaimaiSongs 是一个封装对象，与直接返回 list[Song] 相比，封装对象为您提供了一些方便的方法。

例如，您可以直接调用 songs.by_title() 等方法直接进行筛选，如果需要，您也可以通过 songs.get_all 进行遍历。

我们针对大多数数据都进行了封装（MaimaiSongs, MaimaiScores, MaimaiPlates），读者可以自行查看预置的方法。

由于封装对象的灵活性，我们设计了基于封装对象的缓存机制，从而避免多次请求谱面信息等数据。关于缓存机制与缓存刷新等内容，请查阅 缓存策略 章节。

数据源

在 maimai.py 中，我们引入了数据源的概念，进而支持了以通用的方式从多个位置获取或者上传数据。

INFO

截止目前，我们已经支持水鱼、落雪、微信服务号、舞萌机台等数据源，支持向水鱼和落雪提交数据。

您可以在调用方法时用 provider 参数，来指示从何处获取数据，例如：

from maimai_py.maimai import MaimaiClient

client = MaimaiClient()
lxns = LXNSProvider(developer_token="your_lxns_developer_token")
divingfish = DivingFishProvider()

# 使用落雪作为数据源
player_lxns = await maimai.players(PlayerIdentifier(friend_code=664994421382429), provider=lxns)
# 使用水鱼作为数据源
player_diving = await maimai.players(PlayerIdentifier(username="turou"), provider=divingfish)

玩家标识

在获取或上传玩家信息时，往往需要标识玩家的身份，我们使用 PlayerIdentifier 实例来作为标识符。

PlayerIdentifier 是一个通用的概念，您需要根据使用场景传入合适的值，例如：

• 落雪没有 username 这个概念，所以在使用落雪作为数据源时，传入 username 会抛出异常。
• 上传分数到水鱼时使用用户名和密码：PlayerIdentitifer(username="Username", credentials="Password")。
• 上传分数到水鱼时使用Import-Token：PlayerIdentitifer(credentials="Import-Token")。
• 使用机台作为数据源时，credentials 就是玩家加密后的userId，您可以保存并复用。

阅读对应 Provider 的文档可以了解更多关于如何使用 PlayerIdentifier 的信息。

曲目ID

在本查分器中，同一首曲目的标准、DX 谱面、宴会谱面的 曲目ID 一致，不存在大于 10000 的 曲目ID（如有，均会对 10000 / 100000 取余处理）。

例如，Oshama Scramble! 的标准、DX、宴会谱面的 曲目ID 均为 363。

下一步

至此，您已经了解了 maimai.py 的全部核心概念。

• 您已经具备了基于 maimai.py 开发舞萌相关项目的能力，可以开始旅程了。
• 如果想要更进一步详细了解我们的功能，可以继续阅读文档。
• 对于有经验的开发者，也可以直接阅读API文档。