一个月前，我们发布了简书非官方 SDK JKit 的第一个 Beta 版本，标志着 JKit 已包含了原 JRT 中的绝大部分功能，并进入公开测试阶段。
我们已在同步研发的 JFetcher v4 开发版本中使用 JKit Beta 实现了数据采集工作流，并观察到了性能和开发者体验的显著提升。
在 JKit 不断扩展应用范围的同时，我们也对 Alpha 版本中一些不恰当的设计进行了调整，其中包含较多的破坏性变更。这些变更旨在优化开发者体验，对各数据源 API 中设计不合理的部分进行适当抽象，并利用 Msgspec 提供的数据校验能力，保障 SDK 获取数据的正确性。
对此，我们向受到 Beta 版本迭代中破坏性变更影响的开发者表示歉意。目前，我们已在全部项目上规范化 Commit Message 与 Release Log 中关于此类变更的标注，具体说明如下：
- Commit Message 中包含
!的提交涉及破坏性变更，如feat!: xxx - Release Log 中包含
[Breaking]的条目涉及破坏性变更
同时，我们提醒各位开发者，JKit 遵循 semver（语义化版本）规范，在 Alpha 和 Beta 阶段的版本升级均有可能包含破坏性变更，请在升级项目依赖时加以留意。
您可在此处查看 JKit v3.0.0b1 - v3.0.0b3 的 GitHub 版本发布：
- v3.0.0b1：https://github.com/FHU-yezi/JKit/releases/tag/v3.0.0b1/
- v3.0.0b2：https://github.com/FHU-yezi/JKit/releases/tag/v3.0.0b2/
- v3.0.0b3：https://github.com/FHU-yezi/JKit/releases/tag/v3.0.0b3/
功能变动
[Breaking] 模块结构与数据对象命名调整
在 JKit v3.0.0b2 中，我们对各模块结构和 DataObject 的命名进行了调整。
以 user 模块为例，该模块包含一个 ResourceObject，即对简书用户的抽象。
该变更后，DataObject 将分为两类，使用不同命名规则进行区分。
第一类后缀为 Data，由 ResourceObject 上的属性和方法直接获取得到，如 User.info 属性的类型为 InfoData，包含用户信息。
第二类前缀为 _，后缀为 Field，用于存储嵌套数据，如 InfoData.membership_info 属性的类型为 _MembershipInfoField，包含用户会员信息。
第一类 DataObject 公开，可在其它代码中导入，第二类则仅供 JKit 内部使用。
两类 DataObject 的字段重命名、删除、层级调整等不兼容改动均被视为破坏性变更。
此变更旨在降低开发者对 ResourceObject 属性、方法与 DataObject 对应关系的理解难度，并允许开发者导入第一类 DataObject 用于类型标注。
使用示例：
import asyncio
from jkit.user import InfoData, User
async def get_user_info(user: User) -> InfoData:
return await user.info
async def main() -> None:
user = User.from_slug("ea36c8d8aa30")
user_info = await get_user_info(user)
print(user_info)
asyncio.run(main())
上述代码中，InfoData 被用于 get_user_info 函数的类型标注。
如您在代码中使用了 DataObject 进行类型标注，升级到 JKit Beta 后需同步进行调整。
[Breaking] 模块与 ResourceObject 命名调整
在 JKit v3.0.0b2 和 v3.0.0b3 版本中，我们对部分模块与 ResourceObject 的命名进行了调整。
模块命名调整如下：
| 原名称 | 现名称 |
|---|---|
constraint |
constraints |
credential |
credentials |
private.assets |
private.assets_wallet |
ranking.assets |
ranking.user_assets |
ResourceObject 命名调整如下：
| 原名称 | 现名称 |
|---|---|
ranking.assets.AssetsRanking |
ranking.user_assets.UserAssetsRanking |
private.assets.Assets |
private.assets_wallet.AssetsWallet |
如您在代码中使用了上述模块和 ResourceObject，升级到 JKit Beta 后需同步进行调整。
[Breaking] 配置项重构
在 JKit v3.0.0b2 中，我们对配置项进行了调整。
该变更后，配置项拓扑关系如下：
-
datasources：数据源配置-
jianshu/jpep/beijiaoyi：各数据源配置项-
endpoint：接口端点，可调整以作为 API 变更的临时解决方案，或用于实现透明代理 -
headers：自定义 HTTP Headers -
http_version：HTTP/1 与 HTTP/2 切换，默认值为已根据各数据源进行调整 -
timeout：请求超时，默认为 5 秒 -
proxy：代理配置，请参考 HTTPX 代理配置文档
-
-
-
resource_check：资源检查配置-
auto_check：自动执行资源检查， 默认开启 -
force_check_on_safe_data：强制对从安全来源构建的资源对象进行资源检查，默认关闭
-
-
data_validation：数据校验配置-
enabled：数据校验开关，默认开启
-
升级到 JKit Beta 版本后，您需同步对修改 JKit 配置项的代码进行调整。
[Breaking] 异常类调整
在 JKit v3.0.0b2 和 v3.0.0b3 中，我们对现有的异常类进行了调整。
该变更后，异常类拓扑关系如下：
-
JKitError：JKit 全部异常的基类-
InvalidIdentifierError：标识符无效 -
RatelimitError：触发流控，目前仅对简书数据源有效 -
ValidationError：数据校验失败 -
APIUnsupportedError：API 不支持此操作 -
ResourceUnavailableError：资源不可用 -
AssetsActionError：资产操作异常的基类-
BalanceNotEnoughError：余额不足 -
WeeklyConvertLimitExceededError：超出每周钻贝互转限制
-
-
同时，我们对部分操作引发的异常进行了调整：
| 场景 | 原异常 | 现异常 |
|---|---|---|
初始化 ResourceObject 时传入的标识符无效 |
ValueError |
InvalidIdentifierError |
使用 identifier_convert 模块进行标识符转换时传入的标识符无效 |
ValueError |
InvalidIdentifierError |
| 触发简书流控（HTTP 502） | 未知异常 | RatelimitError |
| 尝试获取未来的排行榜数据 | ValueError |
ResourceUnavailableError |
如您在代码中针对上述异常进行了捕获，升级到 JKit Beta 版本后需同步进行调整。
[Breaking] 用户资产信息获取方式调整
在使用 JKit 时，我们发现绝大多数获取用户资产数据的场景中，均需要同时获取简书钻、简书贝、总资产三种数据，而使用 Alpha 版本实现此需求需要访问多个属性。
因此，我们在 JKit v3.0.0b2 版本中将资产信息接口合并为单一的 user.User.assets_info，并返回 (简书钻, 简书贝, 总资产) 三元组，在 v3.0.0b3 版本中将此属性改为返回 AssetsInfoData 对象，从而降低理解难度，并充分利用现有的数据校验机制。
由于减少了 API 访问次数，此变更会在一定程度上提升获取用户资产数据的性能。
同时，我们通过优化资产数据算法，降低了简书贝数据的计算误差。
使用示例：
import asyncio
from jkit.user import User
async def main() -> None:
user = User.from_slug("ea36c8d8aa30")
assets_info = await user.assets_info
print(
f"简书钻：{assets_info.fp_amount}",
f"简书贝：{assets_info.ftn_amount}",
f"总资产：{assets_info.assets_amount}",
)
asyncio.run(main())
支持获取贝交易平台简书贝市场订单数据
2025 年 1 月 14 日，贝交易平台 公测上线，JKit v3.0.0b3 现已加入对该平台简书贝市场订单数据的支持。
该数据源需使用贝交易平台 Bearer Token 进行鉴权，您可使用浏览器登录贝交易平台，在开发者工具（DevTools）- 控制台（Console）选项卡中输入以下代码获取：
JSON.parse(window.localStorage.app_user_token).token
该凭证为 JSON Web Token（JWT） 格式，可自行解码查看。
使用示例：
import asyncio
from jkit.beijiaoyi.ftn_macket import FtnMacket
from jkit.credentials import BeijiaoyiCredential
BEARER_TOKEN = "<YOUR_BEARER_TOKEN>"
async def main() -> None:
credential = BeijiaoyiCredential.from_bearer_token(BEARER_TOKEN)
async for item in FtnMacket(credential=credential).iter_orders(type="BUY"):
print(item)
asyncio.run(main())
[Breaking] 枚举项调整
JKit v3.0.0b2 版本中，使用 typing.Literal 替换了原 enum.Enum 枚举项，且全部枚举项已改为遵循常量命名规则，即使用全大写字母、下划线分隔。
该变动后，开发者可选择性地从各模块导入以 Type 为后缀的 Literal 枚举项，用于类型标注。
升级到 JKit Beta 后，您需对相关代码进行调整。
JKit 的开发者体验依赖于完善的类型检查，如您的项目尚未使用类型标注与类型检查工具，建议您尽快进行迁移。
[Breaking] 支持 Python 版本调整
自 JKit v3.0.0b1 起，JKit 支持的最低 Python 版本调整为 Python 3.9。使用 pip 在低版本 Python 环境中安装 JKit 将出现错误，我们将不再对 Python 3.8 及以下版本进行兼容和错误修复。
同时，我们加入了对 Python 3.13 的支持。
Python 3.8 已于 2024 年 10 月 7 日结束支持（EOL），为了您项目的安全运行，如您正在使用 Python 3.8，建议您尽快进行迁移。
网络请求加入 User-Agent 标头
自 JKit v3.0.0b2 起，由 JKit 发起的网络请求将默认携带 User-Agent HTTP Header，其中包含当前使用的 JKit 版本信息，如 JKit/3.0.0b3。
如您是简书生态服务提供者，可通过解析此标头分析您服务的流量来源，并对不当请求进行识别和限制。如您遇到带有 JKit 标识的恶意请求，请与我们联系以获取协助。
您可通过修改 config.datasources.<datasource_name>.headers 配置项关闭此功能。
该变更不需要您进行代码修改。
作为简书生态的重要参与者，我们建议您以合理的方式使用 JKit，避免对其他生态参与者造成影响。
基础类重构
在 JKit v3.0.0b1 - v3.0.0b3 中，我们对基础类进行了重构，以降低其逻辑复杂度，将资源对象检查等逻辑移至相关 Mixin 类，降低维护成本。
该变更不需要您进行代码修改。
网络请求、数据编码重构
在 Jkit v3.0.0b2 和 v3.0.0b3 版本中，我们重写了网络请求模块，降低了其内部逻辑的复杂度，并使用 Msgspec 进行 JSON 数据的编码，从而提升数据编码性能。
该变更不需要您进行代码修改。
错误修复
在 JKit v3.0.0b1 - v3.0.0b3 中，我们修复的错误如下：
- 修复标识符检测与转换对部分旧版本 Slug 误判为无效标识符的问题
- 修复部分情况下将网络异常误判成资源不存在的问题
- 修复资源对象检查逻辑异常导致额外网络请求的问题
- 修复在特定情况下用户资产数据中简书贝数值为负的问题
- 修复无法正常实例化
Notebook对象的问题 - 修复接口参数传递异常导致分页、筛选条件无法正确应用的问题
- 修复
ValidationError继承关系错误的问题
总结
本阶段的版本更新中，我们显著提升了 JKit 的开发者体验，但因此引入了较多破坏性变更，需要您加以留意并进行适配和调整。
JKit 现已支持获取贝交易平台简书贝市场订单数据。
同时，我们对部分内部模块进行了重构，从而改善其可维护性和可靠性。
在接下来的开发中，我们将：
- 扩展私有资产数据获取范围
- 扩展贝交易平台数据源的获取范围
- 为 JKit 加入完整的文档
JKit 仍处于 Beta 测试阶段，可能随时进行破坏性变更，请您留意 GitHub 版本发布与更新日志。
感谢您使用 JKit。
创造可能性。
