Kiponos Java SDK 5.0 What’s New — Developer Guide

查看原文 / View Original 编辑 / Edit

Kiponos Java SDK 5.0 What’s New — Developer Guide

Kiponos Java SDK 5.0 What’s New — Developer Guide. This is the technical companion to the 5.0 milestone announcement: what changed, how modes behave, how to read config with the Folder API, and how to upgrade cleanly. Kiponos Java SDK 5.0 新特性 — 开发者指南。这是 5.0 里程碑公告的技术配套文档：涵盖了变更内容、模式行为、如何使用 Folder API 读取配置以及如何平滑升级。

Version 5.0.0.260710 版本 5.0.0.260710

  • Maven group: io.kiponos
  • Artifacts: sdk-boot-3 (recommended), sdk-boot-2 (legacy)
  • Released: 2026-07-12 (Maven Central)
  • Maven 组： io.kiponos
  • 制品： sdk-boot-3（推荐），sdk-boot-2（旧版）
  • 发布日期： 2026-07-12 (Maven Central)

1. Summary for busy engineers

1. 忙碌工程师摘要

5.0 productizes client reliability using a classic state pattern behind a stable facade: 5.0 版本通过稳定的外观模式（Facade）背后的经典状态模式，实现了客户端可靠性的产品化：

ModeConfig readsMutations / hooksNotes
ReadyConnected to hubLive in-memory treeFull Production happy path
OfflineDisconnected but LKG availableLast Known Good (read-only)No-op / ignored
SafeFail-closedEmpty / null-safeNo-op
模式配置读取变更/钩子备注
Ready连接至中心实时内存树完整的生产环境正常路径
Offline断开连接但 LKG 可用最后已知良好状态 (只读)无操作/忽略
Safe故障关闭空/空安全无操作

Public entry remains: Kiponos kiponos = Kiponos.createForCurrentTeam(); 公共入口保持不变：Kiponos kiponos = Kiponos.createForCurrentTeam();

You do not receive mode instances as the API surface. Modes switch internally. Query with: 你不会直接接收模式实例作为 API 接口。模式在内部切换。请使用以下方法查询： kiponos.getCurrentMode(); kiponos.isReadyMode(); kiponos.isOfflineMode(); kiponos.isSafeMode();

2. Install

2. 安装

Gradle — Boot 3

repositories { mavenCentral() }
dependencies { implementation 'io.kiponos:sdk-boot-3:5.0.0.260710' }

Gradle — Boot 2

implementation 'io.kiponos:sdk-boot-2:5.0.0.260710'

Runtime inputs

InputMechanism
Identityenv KIPONOS_ID
Accessenv KIPONOS_ACCESS
Profile / tree sliceJVM -Dkiponos="['App']['1.0.0']['dev']['base']"

运行时输入

输入机制
身份环境变量 KIPONOS_ID
访问权限环境变量 KIPONOS_ACCESS
配置文件/树切片JVM 参数 -Dkiponos="['App']['1.0.0']['dev']['base']"

Tokens and profile come from the Kiponos Connect screen for your team. sdk-common is not a separate app dependency for consumers — boot jars include shared classes (fat-jar pattern). 令牌和配置文件来自你团队的 Kiponos Connect 界面。sdk-common 不是消费者的独立应用依赖——boot jar 包包含了共享类（Fat-jar 模式）。

3. Architecture (state pattern)

3. 架构（状态模式）

Application code
│
▼ Kiponos / KiponosBase ◄── stable facade (one reference for app lifetime)
│
▼ volatile SdkState
├── ReadyMode*    → live WebSocket + full Folder ops
├── OfflineMode*  → LKG reads only
└── SafeMode*     → fail-closed + safe diagnostic dump

Design rule: never return Ready/Offline/Safe objects to callers. Returning a mode freezes the application on that mode forever. Boot modules stay thin adapters (ReadyModeBoot3, connection controllers) over sdk-common cores. 设计原则：永远不要将 Ready/Offline/Safe 对象返回给调用者。返回模式会将应用程序永久锁定在该模式下。Boot 模块保持为 sdk-common 核心之上的轻量级适配器（ReadyModeBoot3，连接控制器）。

4. Folder API (the surface you code against)

4. Folder API（你编码所使用的接口）

Root: KiponosFolder root = kiponos.getRootFolder(); 根目录： KiponosFolder root = kiponos.getRootFolder();

Navigation: KiponosFolder server = root.path("server", "http"); // or stepwise: KiponosFolder s = root.folder("server").folder("http"); 导航： KiponosFolder server = root.path("server", "http"); // 或分步： KiponosFolder s = root.folder("server").folder("http");

Useful members (conceptual contract): path(String... folders), folder(String folderName), folderOrCreate(String folderName), createFolder / renameFolder / deleteFolder / hasFolder, getFolderName / getFolders, get(String key), get(String key, String def), getInt(String key), set(String key, String value), hasKey(String keyName) 常用成员（概念契约）： path(String... folders), folder(String folderName), folderOrCreate(String folderName), createFolder / renameFolder / deleteFolder / hasFolder, getFolderName / getFolders, get(String key), get(String key, String def), getInt(String key), set(String key, String value), hasKey(String keyName)

Recommended reads:

// Prefer typed getters on the SDK surface
int port = kiponos.getRootFolder()
    .path("server", "http")
    .getInt("port");

String region = kiponos.getRootFolder()
    .path("deploy")
    .get("region", "eu-west-1");

推荐读取方式：

// 优先在 SDK 表面使用类型化获取器
int port = kiponos.getRootFolder()
    .path("server", "http")
    .getInt("port");

String region = kiponos.getRootFolder()
    .path("deploy")
    .get("region", "eu-west-1");

Avoid Integer.parseInt(folder.get("port")) for normal integer keys — use getInt. 对于普通的整数键，请避免使用 Integer.parseInt(folder.get("port")) —— 请使用 getInt。

Writes (Ready mode): kiponos.getRootFolder().path("feature-flags").set("checkout-v2", "true"); In Offline/safe modes, mutations are intentionally no-ops (do not assume silent remote write). 写入（Ready 模式）： kiponos.getRootFolder().path("feature-flags").set("checkout-v2", "true"); 在 Offline/Safe 模式下，变更操作被有意设计为无操作（不要假设会进行静默远程写入）。

5. Last Known Good (LKG) Intent

5. 最后已知良好状态 (LKG) 意图

When the hub is unreachable, apps should continue with a known good snapshot, not hang and not invent random defaults. 当中心不可达时，应用应继续使用已知的良好快照，而不是挂起或虚构随机的默认值。

Behavior sketch (5.0):

EventBehavior
Live tree healthyReady serves live data; LKG can be refreshed from good state
Disconnect / unreachablePrefer Offline with LKG reads
No trustworthy backupSafe fail-closed
Safe diagnostic dumpWrites safe-dump-* style artifacts — never overwrites LKG

行为概览 (5.0)：

事件行为
实时树健康Ready 提供实时数据；LKG 可从良好状态刷新
断开连接/不可达优先使用 Offline 并读取 LKG
无可信备份Safe 故障关闭
安全诊断转储写入 safe-dump-* 风格的制品 — 绝不覆盖 LKG

LKG resolution conceptually prefers: live memory → backup → on-disk LKG file under the SDK dump location. LKG 解析在概念上优先顺序为：实时内存 → 备份 → SDK 转储位置下的磁盘 LKG 文件。

App guidance:

  • Treat Offline as read-only truth of last good.
  • Do not assume writes succeed without Ready.
  • Use mode queries if UI or probes must show “degraded but serving LKG”. 应用指南：
  • 将 Offline 视为最后良好状态的只读真理。
  • 不要假设在非 Ready 状态下写入会成功。
  • 如果 UI 或探针必须显示“降级但正在提供 LKG 服务”，请使用模式查询。

6. Lifecycle

6. 生命周期

Kiponos kiponos = Kiponos.createForCurrentTeam();
try {
    // work
} finally {
    kiponos.disconnect();
}

Notes: Always disconnect on orderly shutdown. Intentional disconnect can remain in Offline rather than surprising flip back to Ready (verify against your mode transition policy). Reconnect recovery continues to improve. 注意： 在有序关闭时务必调用 disconnect。主动断开连接可以保持在 Offline 状态，而不是意外地跳回 Ready（请根据你的模式转换策略进行验证）。重连恢复功能在持续改进中。

7. Upgrade from 4.4.x

7. 从 4.4.x 升级

StepAction
1Change dependency version to 5.0.0.260710
2Rebuild / run tests against staging hub
3Replace parseInt(get(...)) with getInt where applicable
4Re-test disconnect / reconnect paths (unit + one live smoke)
5Optional: surface getCurrentMode() in health/admin endpoints
6Confirm no code assumed “throw and hang” as the only offline strategy
步骤操作
1将依赖版本更改为 5.0.0.260710
2针对预发布中心重新构建/运行测试
3在适用处将 parseInt(get(...)) 替换为 getInt
4重新测试断开/重连路径（单元测试 + 一次实时冒烟测试）
5可选：在健康/管理端点中暴露 getCurrentMode()
6确认没有代码将“抛出异常并挂起”作为唯一的离线策略

Breaking risk: low for pure read apps. Behavioral change is improved offline safety; re-validate anything that depended on exceptions during disconnect. 破坏性风险：对于纯读取应用较低。行为变化在于提高了离线安全性；请重新验证任何依赖于断开连接期间抛出异常的逻辑。

8. Example: Spring-friendly service skeleton

8. 示例：Spring 友好的服务骨架

import io.kiponos.sdk.Kiponos;
import io.kiponos.sdk.configs.KiponosFolder;
import org.springframework.stereotype.Component;
import javax.annotation.PreDestroy;

@Component
public class CheckoutLimits {
    private final Kiponos kiponos;
    private final KiponosFolder limits;

    public CheckoutLimits() {
        this.kiponos = Kiponos.createForCurrentTeam();
        this.limits = kiponos.getRootFolder().path("checkout", "limits");
    }

    public int maxCartItems() { return limits.getInt("max-cart-items"); }
    public String currency() { return limits.get("currency", "USD"); }

    @PreDestroy
    public void shutdown() { kiponos.disconnect(); }
}

Dashboard changes to checkout/limits/* propagate live while Ready; Offline continues serving LKG values. 对 checkout/limits/* 的仪表板更改在 Ready 状态下实时传播；Offline 状态下继续提供 LKG 值。

← 返回新闻列表 / Back to news list