# 从 iztro 迁移：API 对照 (/zh/docs/guide/about/iztro-parity) iztro 每个公开 API 在 x-iztro 三侧的落点，换了形状的几处及其原因，以及不提供的那些。 *适合：开发者，尤其是从 JS iztro 迁移过来的* x-iztro 是 [iztro](https://github.com/SylarLong/iztro) v2.6.1 的移植。 iztro 的每个公开 API 在 Rust、Python、Go 三侧都有等价物， 三侧能力完全一致，形式各随语言习惯。 这一页写给从 iztro 迁移过来的人：名字对不上时来这里查。 逐个 API 的用法见各语言的 API 参考。 ## 名字直接对得上的 [#名字直接对得上的] | iztro | Rust | Python | Go | | ------------------------- | ------------------------------ | -------------------------- | ----------------------------------- | | `astro.bySolar` | `by_solar` | `astro.by_solar` | `BySolar` | | `astro.byLunar` | `by_lunar` | `astro.by_lunar` | `ByLunar` | | `chart.horoscope` | `chart.horoscope` | `chart.horoscope` | `Horoscope` | | `chart.palace` | `chart.palace` | `chart.palace` | `Palace` / `PalaceByIndex` | | `chart.surroundedPalaces` | `chart.surrounded_palaces` | `chart.surrounded_palaces` | `SurroundedPalaces` | | `chart.flankingPalaces` | `chart.flanking_palaces` | `chart.flanking_palaces` | `FlankingPalaces` | | `chart.decadalList` | `chart.decadal_list` | `chart.decadal_list` | `DecadalList` | | `chart.yearlyList` | `chart.yearly_list` | `chart.yearly_list` | `YearlyList` / `YearlyListByPalace` | | `chart.monthlyList` | `chart.monthly_list` | `chart.monthly_list` | `MonthlyList` | | `palace.fliesTo` | `flies_to` | `flies_to` | `FliesTo` | | `util.fixIndex` | `utils::fix_index` | `utils.fix_index` | `FixIndex` | | `star.getMajorStar` | `star::query::get_major_stars` | `star.get_major_star` | `GetMajorStar` | | `i18n.t` | `translate_key` | `i18n.translate` | `Translate` | | `i18n.kot` | `key_of` | `i18n.key_of` | `KeyOf` | 其余同理：JS 的 camelCase 在 Rust / Python 下是 snake\_case，在 Go 下是 PascalCase。 ## 换了形状的 [#换了形状的] 这几处不是照抄，因为照抄会把 JS 的限制一起搬过来。 ### 排盘视角（天盘 / 地盘 / 人盘） [#排盘视角天盘--地盘--人盘] iztro 把 `astroType` 放在 `astro.withOptions` 的选项对象上， 是因为它的 `astro.config()` 是全局单例、装不下按盘变化的值。 x-iztro 的配置本来就随每次排盘传入，因此 `astroType` 直接收进 `Config`， 两个排盘入口都能用，不必再记一个入口： ```python from x_iztro import Astro, ChartConfig chart = Astro().by_solar("2000-8-16", 2, "female", config=ChartConfig(astro_type="earth")) ``` 从任意干支起盘对应 `rearrangeAstrolable`，三侧都是星盘方法 `rearranged(干, 支)`。 ### 没有全局配置与全局语言 [#没有全局配置与全局语言] iztro 的 `astro.config()`、`i18n.setLanguage()` 改的是模块级单例， 因此还需要 `astro.getConfig()` 把值读回来。 x-iztro 没有全局状态：配置与语言都随每次调用传入，由调用方自己持有。 所以不提供 `getConfig` 与 `setLanguage` —— 想读回来，读你自己那份就是。 ### 大限小限 [#大限小限] `astro/palace` 的 `getHoroscope(param)` 收一份 `AstrolabeParam`。 x-iztro 的 `get_decadals_and_ages` 直接收命宫索引与五行局， 不必先凑出一份出生数据，能力是 iztro 那个的超集。 ### 农历入口的闰月参数 [#农历入口的闰月参数] `byLunar(lunarDateStr, timeIndex, gender, isLeapMonth?, fixLeap?, language?)` 用两个相邻的布尔 描述闰月：写反了不报错，盘会静默错一个月，而 `fixLeap` 又只在输入是闰月时才有意义。 x-iztro 把两者合成一个三态值：Rust `LeapMonth::{NotLeap, Leap, LeapFixed}`、 Go `NotLeapMonth / LeapMonthKeep / LeapMonthFixed`；Python 保留两个布尔但改为只能按关键字传入 （`is_leap_month=`、`fix_leap=`）。绑定层的 JSON 线协议仍是 `isLeapMonth`/`fixLeap` 两个键， 与 iztro 一致。阳历入口的 `fixLeap` 单独一个布尔，没有写反的余地，保持不变。 Go 侧同理把 `gender`、`language` 做成具名字符串类型 `Gender` / `Language` （`GenderFemale`、`LanguageZhCN`），字面量仍可直接传，但别的字符串变量传错位置会在编译期被挡下。 ### 插件 [#插件] iztro 的 `loadPlugin` / `use(plugin)` 是运行期往星盘对象上挂函数 —— 这是 JS 缺少其他扩展手段的产物。三侧各按语言给出的答案实现同一能力， 都是编译期或加载期完成，不牺牲类型检查： | | 做法 | | ------ | -------------------------------------------------------------------- | | Rust | 扩展 trait | | Python | `x_iztro.plugin` 的 `load_plugin` / `load_plugins`，往 `Astrolabe` 类挂方法 | | Go | 嵌入 `*Astrolabe`（Go 不允许给外部包的类型加方法，嵌入是语言给出的答案） | 写法见[扩展星盘](/zh/docs/guide/guides/plugins)。 ### 反查译名时的消歧 [#反查译名时的消歧] `kot(value, k)` 的第二个参数在三侧是独立入口： `key_of_in`（Rust）、`key_of(text, key_filter)`（Python）、`KeyOfIn`（Go）。 取值与 iztro 逐例一致，包括 `horse`、`dragon`、`유시`（韩语的酉时）这类同形译名落到哪个标识。 iztro 的 `kot` 查不到会把入参吐回来；x-iztro 返回 `None`（Rust / Python）或空串（Go）。 迁移时如果依赖过「查不到就当作原值继续用」这个行为，这里要改。 ## 不提供的 [#不提供的] | iztro | 为什么不做 | | -------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `astro.astrolabeBySolarDate` / `astrolabeByLunarDate` | iztro v2.0.5 起废弃的别名，与 `bySolar` / `byLunar` 同参同行为 | | `star.initStars` | JS 里是返回 12 个空数组的工厂；三侧的类型系统本身就给出定长 12 的数组 | | `util.fixEarthlyBranchIndex` | 与 `earthlyBranchIndexToPalaceIndex` 同义 | | `palace.setAstrolabe` / `star.setPalace` / `star.setAstrolabe` | 建立对象间引用是内部行为，三侧在解析后自动完成 | | `astro/analyzer` 模块 | 里面 11 个函数是宫位与三方四正方法的自由函数版（`hasStars` 即 `palace.has`），能力已由对象方法覆盖 | | `calendar` 模块 | 在 iztro v2.5.8 里已是死代码——活的代码路径全部改走 `lunar-lite` 依赖，该模块也不在包的根导出里；v2.6.1 已把它从包中删除 | | `i18n` 默认导出的 i18next 实例 | 不转手第三方库实例；翻译与反查由 `translate` / `key_of` 覆盖 | | `Astrolabe.copyright` | iztro 自身的版权声明字符串 | ## 行为上要注意的几处 [#行为上要注意的几处] ### 自定义四化表与亮度表只收标识 [#自定义四化表与亮度表只收标识] `Config` 的 `mutagens` / `brightness` 两张覆盖表**只接受语言无关标识**： `"ziweiMaj"` 可以，`"紫微"` 不行 —— 收译名会让配置绑死在某种盘面语言上。 ### 覆盖表长度严格校验 [#覆盖表长度严格校验] 四化表必须给满 4 项（禄权科忌），亮度表必须给满 12 项（第一项是寅宫）， 多一项少一项都直接报 `invalid_argument`，不做补齐也不做截断。 见 [Config 详解](/zh/docs/guide/guides/config#自定义四化表与亮度表)。 ### 覆盖表不回显在输出的 config 里 [#覆盖表不回显在输出的-config-里] 星盘上回显的 `config` 只有六个开关。覆盖表是排盘的输入， 放进 DTO 会破坏与 iztro 的字段契约，所以读回来是空的 —— 要留档自己存。 ## 比 iztro 多的 [#比-iztro-多的] ### 格局判定（iztro 无对应 API） [#格局判定iztro-无对应-api] iztro 没有格局相关的 API，x-iztro 在排盘之上加了一层格局判定引擎： 64 条格局，本命盘与运限盘共用同一套规则，命中带成格宫位、口径（`variant`）、 破格标记（`broken`）与证据星。规则条目、示例盘与古籍引文取自 iztro-docs 的《格局》页 （MIT License，作者 Sylar Long），判定实现、六语言格局名与多种说法之间的取舍是 x-iztro 的工作。 三侧的入口：Rust 的 `Astrolabe::patterns` / `HoroscopeRef::patterns`、 Python 的 `Astrolabe.patterns` / `Horoscope.patterns`、 Go 的 `Astrolabe.Patterns` / `Horoscope.Patterns`， 另有语言无关的格局标识（Rust `PatternKey`、Python `PatternKey`、Go `PatternXxx` 常量）。 概念与 64 条总表见[格局](/zh/docs/guide/concepts/patterns)。 因为 iztro 没有对应实现，这部分没有金标数据，正确性由四层测试守着： 每条规则的单测、来源页 32 张示例盘的真实盘复现、tier1 那 1,560 张盘上的批量不变量检查， 以及三侧共读的输出快照。 ### 知识包（iztro 无对应 API） [#知识包iztro-无对应-api] iztro 只给事实，星耀与格局的解读文本在它的文档站上、不在库里。 x-iztro 把解读做成一份协议化的数据：知识包是「语言无关标识 → 文本与属性」的 JSON， 库里内嵌一份默认包（107 颗星、64 条格局、12 宫、4 化、49 条术语， 取自 iztro-docs 的《学习》各页，MIT License，作者 Sylar Long）， 不认同其中说法可以写覆盖包按字段合并。 三侧的入口：Rust 的 `KnowledgePack::builtin` / `merged`、 Python 的 `KnowledgePack.builtin` / `merged`、 Go 的 `BuiltinKnowledgePack` / `Merged`，合并只在 Rust 内核实现一处。 星耀的阴阳五行、斗分、化气这类**属性**也在包里而不进核心数据表—— 核心的 `StarInfo` 与 iztro 逐值一致，属性是门派说法。 见[知识包](/zh/docs/guide/guides/knowledge-pack)。 ### 反推（iztro 无对应 API） [#反推iztro-无对应-api] iztro 只有「生辰 → 盘」一个方向。x-iztro 加上了反方向：`solar_dates_by_bazi` 由八字四柱反查公历生辰——四柱按传入 `Config` 的分界口径解释， 与 `raw_dates.chinese_date` 同一套语义；`reverse_chart` 由星盘特征 （命宫身宫地支、五行局、星耀落宫、生年四化）反查候选生辰。 两者都是「剪枝枚举 + 正排终验」，结果与正向排盘零分歧。 一组四柱约每 60 年重复一次，因此天然多解，候选拿去正排即可复现目标。 三侧的入口：Rust 的 `solar_dates_by_bazi` / `reverse_chart`、 Python 的 `solar_dates_by_bazi` / `reverse_chart`、 Go 的 `SolarDatesByBazi` / `ReverseChart`（各带 Context 变体）。 见[反推](/zh/docs/guide/guides/reverse)。 ### 其余增补 [#其余增补] * **语言无关标识**：星盘每个字段在译名之外同时给出 `*key` / `*Key`， 取值是 iztro 的 i18n key。判断逻辑因此不受盘面语言影响， 不必再反查译名。详见[标识体系](/zh/docs/guide/guides/keys) * **语义化文本投影（to\_text）**：把星盘、运限、宫位或三方四正投影成自然语言文本， 喂大模型或直接给人读，见[语义化文本](/zh/docs/guide/guides/to-text) * **入口前置校验**：非法日期、越界时辰等在入口返回错误而非 panic， 且带机器可读的分类码，见[错误处理](/zh/docs/guide/guides/errors) * **自定义四化表与亮度表**：按标识整表替换内置数据， 见 [Config 详解](/zh/docs/guide/guides/config#自定义四化表与亮度表) * **`all_keys`**：一次取全部 260 个可翻译标识 ## 数值一致性 [#数值一致性] 功能对齐之外，排盘结果与 iztro **逐字段零差异**，由 716,314 例金标数据守着。 覆盖矩阵与验证方式见[准确性保证](/zh/docs/guide/about/accuracy)。