一個月前，我們發(fā)布了簡書非官方 SDK JKit 的第一個 Beta 版本，標(biāo)志著 JKit 已包含了原 JRT 中的絕大部分功能，并進入公開測試階段。
我們已在同步研發(fā)的 JFetcher v4 開發(fā)版本中使用 JKit Beta 實現(xiàn)了數(shù)據(jù)采集工作流，并觀察到了性能和開發(fā)者體驗的顯著提升。
在 JKit 不斷擴展應(yīng)用范圍的同時，我們也對 Alpha 版本中一些不恰當(dāng)?shù)脑O(shè)計進行了調(diào)整，其中包含較多的破壞性變更。這些變更旨在優(yōu)化開發(fā)者體驗，對各數(shù)據(jù)源 API 中設(shè)計不合理的部分進行適當(dāng)抽象，并利用 Msgspec 提供的數(shù)據(jù)校驗?zāi)芰ΓＵ?SDK 獲取數(shù)據(jù)的正確性。
對此，我們向受到 Beta 版本迭代中破壞性變更影響的開發(fā)者表示歉意。目前，我們已在全部項目上規(guī)范化 Commit Message 與 Release Log 中關(guān)于此類變更的標(biāo)注，具體說明如下：
- Commit Message 中包含
!的提交涉及破壞性變更，如feat!: xxx - Release Log 中包含
[Breaking]的條目涉及破壞性變更
同時，我們提醒各位開發(fā)者，JKit 遵循 semver（語義化版本）規(guī)范，在 Alpha 和 Beta 階段的版本升級均有可能包含破壞性變更，請在升級項目依賴時加以留意。
您可在此處查看 JKit v3.0.0b1 - v3.0.0b3 的 GitHub 版本發(fā)布：
- 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] 模塊結(jié)構(gòu)與數(shù)據(jù)對象命名調(diào)整
在 JKit v3.0.0b2 中，我們對各模塊結(jié)構(gòu)和 DataObject 的命名進行了調(diào)整。
以 user 模塊為例，該模塊包含一個 ResourceObject，即對簡書用戶的抽象。
該變更后，DataObject 將分為兩類，使用不同命名規(guī)則進行區(qū)分。
第一類后綴為 Data，由 ResourceObject 上的屬性和方法直接獲取得到，如 User.info 屬性的類型為 InfoData，包含用戶信息。
第二類前綴為 _，后綴為 Field，用于存儲嵌套數(shù)據(jù)，如 InfoData.membership_info 屬性的類型為 _MembershipInfoField，包含用戶會員信息。
第一類 DataObject 公開，可在其它代碼中導(dǎo)入，第二類則僅供 JKit 內(nèi)部使用。
兩類 DataObject 的字段重命名、刪除、層級調(diào)整等不兼容改動均被視為破壞性變更。
此變更旨在降低開發(fā)者對 ResourceObject 屬性、方法與 DataObject 對應(yīng)關(guān)系的理解難度，并允許開發(fā)者導(dǎo)入第一類 DataObject 用于類型標(biāo)注。
使用示例：
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 函數(shù)的類型標(biāo)注。
如您在代碼中使用了 DataObject 進行類型標(biāo)注，升級到 JKit Beta 后需同步進行調(diào)整。
[Breaking] 模塊與 ResourceObject 命名調(diào)整
在 JKit v3.0.0b2 和 v3.0.0b3 版本中，我們對部分模塊與 ResourceObject 的命名進行了調(diào)整。
模塊命名調(diào)整如下：
| 原名稱 | 現(xiàn)名稱 |
|---|---|
constraint |
constraints |
credential |
credentials |
private.assets |
private.assets_wallet |
ranking.assets |
ranking.user_assets |
ResourceObject 命名調(diào)整如下：
| 原名稱 | 現(xiàn)名稱 |
|---|---|
ranking.assets.AssetsRanking |
ranking.user_assets.UserAssetsRanking |
private.assets.Assets |
private.assets_wallet.AssetsWallet |
如您在代碼中使用了上述模塊和 ResourceObject，升級到 JKit Beta 后需同步進行調(diào)整。
[Breaking] 配置項重構(gòu)
在 JKit v3.0.0b2 中，我們對配置項進行了調(diào)整。
該變更后，配置項拓?fù)潢P(guān)系如下：
-
datasources：數(shù)據(jù)源配置-
jianshu/jpep/beijiaoyi：各數(shù)據(jù)源配置項-
endpoint：接口端點，可調(diào)整以作為 API 變更的臨時解決方案，或用于實現(xiàn)透明代理 -
headers：自定義 HTTP Headers -
http_version：HTTP/1 與 HTTP/2 切換，默認(rèn)值為已根據(jù)各數(shù)據(jù)源進行調(diào)整 -
timeout：請求超時，默認(rèn)為 5 秒 -
proxy：代理配置，請參考 HTTPX 代理配置文檔
-
-
-
resource_check：資源檢查配置-
auto_check：自動執(zhí)行資源檢查， 默認(rèn)開啟 -
force_check_on_safe_data：強制對從安全來源構(gòu)建的資源對象進行資源檢查，默認(rèn)關(guān)閉
-
-
data_validation：數(shù)據(jù)校驗配置-
enabled：數(shù)據(jù)校驗開關(guān)，默認(rèn)開啟
-
升級到 JKit Beta 版本后，您需同步對修改 JKit 配置項的代碼進行調(diào)整。
[Breaking] 異常類調(diào)整
在 JKit v3.0.0b2 和 v3.0.0b3 中，我們對現(xiàn)有的異常類進行了調(diào)整。
該變更后，異常類拓?fù)潢P(guān)系如下：
-
JKitError：JKit 全部異常的基類-
InvalidIdentifierError：標(biāo)識符無效 -
RatelimitError：觸發(fā)流控，目前僅對簡書數(shù)據(jù)源有效 -
ValidationError：數(shù)據(jù)校驗失敗 -
APIUnsupportedError：API 不支持此操作 -
ResourceUnavailableError：資源不可用 -
AssetsActionError：資產(chǎn)操作異常的基類-
BalanceNotEnoughError：余額不足 -
WeeklyConvertLimitExceededError：超出每周鉆貝互轉(zhuǎn)限制
-
-
同時，我們對部分操作引發(fā)的異常進行了調(diào)整：
| 場景 | 原異常 | 現(xiàn)異常 |
|---|---|---|
初始化 ResourceObject 時傳入的標(biāo)識符無效 |
ValueError |
InvalidIdentifierError |
使用 identifier_convert 模塊進行標(biāo)識符轉(zhuǎn)換時傳入的標(biāo)識符無效 |
ValueError |
InvalidIdentifierError |
| 觸發(fā)簡書流控（HTTP 502） | 未知異常 | RatelimitError |
| 嘗試獲取未來的排行榜數(shù)據(jù) | ValueError |
ResourceUnavailableError |
如您在代碼中針對上述異常進行了捕獲，升級到 JKit Beta 版本后需同步進行調(diào)整。
[Breaking] 用戶資產(chǎn)信息獲取方式調(diào)整
在使用 JKit 時，我們發(fā)現(xiàn)絕大多數(shù)獲取用戶資產(chǎn)數(shù)據(jù)的場景中，均需要同時獲取簡書鉆、簡書貝、總資產(chǎn)三種數(shù)據(jù)，而使用 Alpha 版本實現(xiàn)此需求需要訪問多個屬性。
因此，我們在 JKit v3.0.0b2 版本中將資產(chǎn)信息接口合并為單一的 user.User.assets_info，并返回 (簡書鉆, 簡書貝, 總資產(chǎn)) 三元組，在 v3.0.0b3 版本中將此屬性改為返回 AssetsInfoData 對象，從而降低理解難度，并充分利用現(xiàn)有的數(shù)據(jù)校驗機制。
由于減少了 API 訪問次數(shù)，此變更會在一定程度上提升獲取用戶資產(chǎn)數(shù)據(jù)的性能。
同時，我們通過優(yōu)化資產(chǎn)數(shù)據(jù)算法，降低了簡書貝數(shù)據(jù)的計算誤差。
使用示例：
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"總資產(chǎn)：{assets_info.assets_amount}",
)
asyncio.run(main())
支持獲取貝交易平臺簡書貝市場訂單數(shù)據(jù)
2025 年 1 月 14 日，貝交易平臺 公測上線，JKit v3.0.0b3 現(xiàn)已加入對該平臺簡書貝市場訂單數(shù)據(jù)的支持。
該數(shù)據(jù)源需使用貝交易平臺 Bearer Token 進行鑒權(quán)，您可使用瀏覽器登錄貝交易平臺，在開發(fā)者工具（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] 枚舉項調(diào)整
JKit v3.0.0b2 版本中，使用 typing.Literal 替換了原 enum.Enum 枚舉項，且全部枚舉項已改為遵循常量命名規(guī)則，即使用全大寫字母、下劃線分隔。
該變動后，開發(fā)者可選擇性地從各模塊導(dǎo)入以 Type 為后綴的 Literal 枚舉項，用于類型標(biāo)注。
升級到 JKit Beta 后，您需對相關(guān)代碼進行調(diào)整。
JKit 的開發(fā)者體驗依賴于完善的類型檢查，如您的項目尚未使用類型標(biāo)注與類型檢查工具，建議您盡快進行遷移。
[Breaking] 支持 Python 版本調(diào)整
自 JKit v3.0.0b1 起，JKit 支持的最低 Python 版本調(diào)整為 Python 3.9。使用 pip 在低版本 Python 環(huán)境中安裝 JKit 將出現(xiàn)錯誤，我們將不再對 Python 3.8 及以下版本進行兼容和錯誤修復(fù)。
同時，我們加入了對 Python 3.13 的支持。
Python 3.8 已于 2024 年 10 月 7 日結(jié)束支持（EOL），為了您項目的安全運行，如您正在使用 Python 3.8，建議您盡快進行遷移。
網(wǎng)絡(luò)請求加入 User-Agent 標(biāo)頭
自 JKit v3.0.0b2 起，由 JKit 發(fā)起的網(wǎng)絡(luò)請求將默認(rèn)攜帶 User-Agent HTTP Header，其中包含當(dāng)前使用的 JKit 版本信息，如 JKit/3.0.0b3。
如您是簡書生態(tài)服務(wù)提供者，可通過解析此標(biāo)頭分析您服務(wù)的流量來源，并對不當(dāng)請求進行識別和限制。如您遇到帶有 JKit 標(biāo)識的惡意請求，請與我們聯(lián)系以獲取協(xié)助。
您可通過修改 config.datasources.<datasource_name>.headers 配置項關(guān)閉此功能。
該變更不需要您進行代碼修改。
作為簡書生態(tài)的重要參與者，我們建議您以合理的方式使用 JKit，避免對其他生態(tài)參與者造成影響。
基礎(chǔ)類重構(gòu)
在 JKit v3.0.0b1 - v3.0.0b3 中，我們對基礎(chǔ)類進行了重構(gòu)，以降低其邏輯復(fù)雜度，將資源對象檢查等邏輯移至相關(guān) Mixin 類，降低維護成本。
該變更不需要您進行代碼修改。
網(wǎng)絡(luò)請求、數(shù)據(jù)編碼重構(gòu)
在 Jkit v3.0.0b2 和 v3.0.0b3 版本中，我們重寫了網(wǎng)絡(luò)請求模塊，降低了其內(nèi)部邏輯的復(fù)雜度，并使用 Msgspec 進行 JSON 數(shù)據(jù)的編碼，從而提升數(shù)據(jù)編碼性能。
該變更不需要您進行代碼修改。
錯誤修復(fù)
在 JKit v3.0.0b1 - v3.0.0b3 中，我們修復(fù)的錯誤如下：
- 修復(fù)標(biāo)識符檢測與轉(zhuǎn)換對部分舊版本 Slug 誤判為無效標(biāo)識符的問題
- 修復(fù)部分情況下將網(wǎng)絡(luò)異常誤判成資源不存在的問題
- 修復(fù)資源對象檢查邏輯異常導(dǎo)致額外網(wǎng)絡(luò)請求的問題
- 修復(fù)在特定情況下用戶資產(chǎn)數(shù)據(jù)中簡書貝數(shù)值為負(fù)的問題
- 修復(fù)無法正常實例化
Notebook對象的問題 - 修復(fù)接口參數(shù)傳遞異常導(dǎo)致分頁、篩選條件無法正確應(yīng)用的問題
- 修復(fù)
ValidationError繼承關(guān)系錯誤的問題
總結(jié)
本階段的版本更新中，我們顯著提升了 JKit 的開發(fā)者體驗，但因此引入了較多破壞性變更，需要您加以留意并進行適配和調(diào)整。
JKit 現(xiàn)已支持獲取貝交易平臺簡書貝市場訂單數(shù)據(jù)。
同時，我們對部分內(nèi)部模塊進行了重構(gòu)，從而改善其可維護性和可靠性。
在接下來的開發(fā)中，我們將：
- 擴展私有資產(chǎn)數(shù)據(jù)獲取范圍
- 擴展貝交易平臺數(shù)據(jù)源的獲取范圍
- 為 JKit 加入完整的文檔
JKit 仍處于 Beta 測試階段，可能隨時進行破壞性變更，請您留意 GitHub 版本發(fā)布與更新日志。
感謝您使用 JKit。
創(chuàng)造可能性。
