mihomo：崩坏：星穹铁道的 Python 类型安全 API 封装库

图：崩坏：星穹铁道游戏角色图标（来源：StarRailRes 仓库）

---

一、它是什么：当你需要一个"不会崩溃"的星穹铁道数据查询工具

你是一个《崩坏：星穹铁道》的玩家，也是一名 Python 开发者。你想用代码查询某个玩家的角色练度、遗器配置、光锥搭配——但翻遍官方文档，发现所有数据都以原始 JSON 格式返回，没有类型定义，没有代码补全，字段名全是 c8、p1、s2 这样的缩写。你要么去读几十页的 API 文档，要么对着返回数据一个个猜字段含义。

mihomo 解决的就是这个问题。它是一个纯 Python 的第三方库，底层封装了社区维护的 Mihomo API（api.mihomo.me），通过 Pydantic 模型将星穹铁道的原始游戏数据解析为结构化的 Python 对象。你只需传入一个 UID，就能拿到完整类型注解的玩家信息——角色列表、光锥（武器）、遗器（圣遗物）、战斗属性，全部有 IDE 自动补全。

from mihomo import Language, MihomoAPI
from mihomo.models import StarrailInfoParsed

client = MihomoAPI(language=Language.EN)

async def main():
    data: StarrailInfoParsed = await client.fetch_user(800333171)
    print(f"玩家: {data.player.name}")
    print(f"等级: {data.player.level}")
    for char in data.characters:
        print(f"  {char.name} | 星级: {char.rarity} | 等级: {char.level}")

代码的补全提示如图所示，每一个字段都有清晰的类型标注。

---

二、项目背景：社区驱动的游戏数据聚合

mihomo 并非米哈游官方出品，而是一个由独立开发者 KT-Yeh 创建并维护的开源项目（GitHub org: MetaCubeX，该组织还托管了知名的 mihomo 代理内核项目，两者同名但不同项目）。它的诞生背景很清晰：星穹铁道的游戏数据分散在多个来源，没有一个统一的、易用的编程接口。

该库于 2021 年 5 月上线，依赖极其精简——仅 aiohttp（异步 HTTP 客户端）和 Pydantic v1（数据验证），运行在 Python 3.10+ 环境。项目采用 MIT 许可证，完全开源。截至分析时，该仓库已积累超过 3.4 万 star，是同类星穹铁道 Python 工具中 star 数量最高的项目之一。

---

三、核心功能：V1/V2 双版本兼容的数据模型

3.1 异步 API 客户端

MihomoAPI 类是整个库的入口。它支持 14 种语言（简/繁体中文、英语、日语、韩语、德语、法语、西班牙语、印尼语、葡萄牙语、俄语、泰语、越南语），内部使用 aiohttp 异步客户端发起 HTTP 请求，响应状态码映射到三类自定义异常：HttpRequestError（网络错误）、InvalidParams（参数错误）和 UserNotFound（玩家不存在）。

from mihomo import Language

client = MihomoAPI(language=Language.CHS)  # 简体中文

# V2（当前推荐版本）
data_v2 = await client.fetch_user(800333171)

# V1（兼容旧版，数据结构略有不同）
data_v1 = await client.fetch_user_v1(800333171)

3.2 Pydantic 数据模型体系

整个项目的核心价值在于其精心设计的 Pydantic 模型层。数据模型按功能分为以下模块：

模型模块	说明
base.py	根模型 StarrailInfoParsed，包含 player 和 characters
player.py	玩家基本信息：UID、昵称、等级、签名、世界等级
character.py	角色数据：等级、星级、元素、行迹（Trace）、武器、光锥、遗器
combat.py	战斗属性：元素（虚无、毁灭、同谐等）、命途、属性加成
equipment.py	装备模型：光锥（LightCone）和遗器（Relic）及其副词条
stat.py	属性数值：主词条、副词条、遗器套装效果

所有模型继承自 pydantic.BaseModel，天然支持 JSON 序列化、字段验证、类型转换和 IDE 自动补全。当 API 返回数据格式发生变化时，Pydantic 会在解析阶段抛出明确的验证错误，而不是让程序在访问 data['characters'][0]['light_cone']['sub_affixes'][2]['prop']['value'] 时悄悄拿到 None。

3.3 工具函数

tools.py 提供了三个实用工具函数：

• remove_empty_dict()：递归删除响应中的空字典，避免数据结构过于冗余
• replace_icon_name_with_url()：将图标路径（如 /icon/avatar/1201.png）自动替换为完整的 CDN URL（指向 StarRailRes 仓库），用于直接渲染角色立绘和装备图标
• replace_trailblazer_name()：修复开拓者（主角）在不同命途下名字不一致的问题

---

四、技术架构：轻量级封装的核心逻辑

架构类型

mihomo 属于**薄包装层（Thin Wrapper）**架构。项目不涉及复杂的业务逻辑，也没有机器学习组件，其核心职责只有两件事：

1. HTTP 请求封装：通过 aiohttp 异步请求 Mihomo API，处理认证、参数构造和错误响应
2. 数据模型映射：用 Pydantic 将 JSON 响应解析为带类型的 Python 对象

这种架构的优势在于极低的依赖开销和极高的维护效率——整个项目的源代码行数不超过 2000 行，但覆盖了星穹铁道游戏中几乎所有实体类型。

依赖分析

aiohttp == 3.*     # 异步 HTTP 客户端（API 请求）
pydantic == 1.*    # 数据验证与序列化（模型层）
Python >= 3.10      # 运行环境

值得注意的是，项目明确拒绝引入 requests（同步库），而是选择了 aiohttp 的异步方案。这意味着如果你在异步框架（如 FastAPI）中使用 mihomo，请求是真正的并发非阻塞的；如果在同步脚本中使用，需要用 asyncio.run() 包装。

代码质量评估

• 类型安全：全库使用类型注解，Pydantic 模型提供运行时验证，代码可以在 mypy/pyright 下达到零错误
• 文档质量：README 结构清晰，包含完整的多语言用法示例和 API 变更说明（V1→V2 迁移指南），DeepWiki 上有详细的模型文档
• 测试覆盖：仓库包含 GitHub Actions CI/CD 流程（Delete.yml、build.yml），但未公开测试代码覆盖率数据
• 错误处理：自定义异常体系覆盖了主要错误场景，HTTP 状态码到应用异常的映射逻辑清晰

---

五、上手体验：5 行代码获取玩家数据

安装

pip install -U git+https://github.com/KT-Yeh/mihomo.git

注意：当前最新版本为 v1.1.7，仅发布在 GitHub（未上传 PyPI），需通过 Git URL 安装。

基础用法

import asyncio
from mihomo import Language, MihomoAPI

async def main():
    client = MihomoAPI(language=Language.CHS)
    
    # 抓取玩家数据
    uid = 800333171
    info = await client.fetch_user(uid)
    
    # 玩家信息
    print(f"UID: {info.player.uid}")
    print(f"昵称: {info.player.name}")
    print(f"等级: {info.player.level}")
    print(f"签名: {info.player.signature}")
    
    # 角色列表
    for char in info.characters:
        print(f"  角色: {char.name} | 星级: {char.rarity} | 等级: {char.level}")
        print(f"    元素: {char.element} | 行途: {char.path}")
        if char.light_cone:
            print(f"    光锥: {char.light_cone.name} (+{char.light_cone.superimposition})")
        for relic in (char.relics or []):
            print(f"    遗器: {relic.name} Lv.{relic.level}")

图标 URL 获取

# 自动替换为 CDN URL
info = await client.fetch_user(uid, replace_icon_name_with_url=True)
# 或者手动构造
icon_url = client.get_icon_url(char.icon)  # 返回完整 URL

---

六、争议与局限：这不是万能工具

局限性

1. 依赖外部 API，不保证可用性

mihomo 本身代码质量不错，但它强依赖 api.mihomo.me 这个第三方服务。该 API 并非米哈游官方接口，没有 SLA 保障，数据更新可能存在延迟。如果 Mihomo API 服务不稳定或下线，整个库将无法工作——这是使用第三方游戏 API 的固有风险。

2. 数据深度有限

mihomo 只能查询公开可见的玩家数据（如角色列表和练度），无法访问玩家的私密设置、抽卡记录、任务进度等未公开信息。它的定位是"玩家数据展示工具"，而非"游戏辅助工具"。

3. V1 向 V2 的迁移成本

对于已在生产环境中使用 V1 接口的项目，需要逐个字段地迁移数据模型。V1 和 V2 的数据结构有较大差异，没有自动迁移工具，依赖开发者手动对照。

4. 仅支持 Python

非 Python 语言的开发者需要寻找对应语言的 SDK（如 JavaScript/TypeScript 的 starrail.js，或 C# 的 MihomoSharp），或者自行封装 HTTP 请求。

---

七、行业意义与生态定位

mihomo 在星穹铁道开发者生态中扮演了一个"数据标准化层"的角色。它将杂乱的原始 JSON 转换为人类可读的结构化对象，大幅降低了游戏数据二次开发的门槛。

从数据可以看出，这个仅有约 4500 个 fork 的项目（对比 34000+ star）获得了极高的社区认可——star/fork 比约为 7.6:1，说明大多数使用者是在个人项目或学习场景中引用它，而非 fork 后做大规模二次开发。

该项目属于典型的小而美开源工具：定位清晰、依赖极简、维护活跃（最后更新距今不到 3 天）、文档完善。它不需要复杂的部署流程，不需要 GPU 资源，也不需要 Docker——只需要一个 Python 环境，就能将它集成到任何数据看板、个人博客或自动化脚本中。

对于想要开发星穹铁道相关内容（如角色强度排行、遗器推荐系统、配装模拟器）的开发者来说，mihomo 是目前最省力的起点。