Java OpenSDK 简介

这是什么？

Lovrabet Java OpenSDK 是一个轻量级的 Java 客户端库，用于在 Java 应用中访问 Lovrabet 云兔平台的 OpenAPI 服务。

通过这个 SDK，您可以在 Java 后端应用中轻松地：

• 📊 读取数据 - 从 Lovrabet 云兔平台获取业务数据
• ✏️ 写入数据 - 创建和更新您的业务记录
• 🔐 安全访问 - 自动处理签名认证，保障数据安全
• 🚀 快速集成 - 几行代码即可完成对接

解决什么问题？

场景 1：将 Lovrabet 数据集成到现有 Java 系统

问题：您在 Lovrabet 云兔平台上管理着客户、订单、销售漏斗等业务数据，现在需要在自己的 Java 后台系统中使用这些数据。

使用 OpenSDK：

// 在您的 Spring Boot 应用中
@Service
public class CustomerService {
    private final LovrabetSDKClient sdkClient;

    public List<Customer> getSalesLeads() {
        LovrabetRequest request = new LovrabetRequest();
        request.setAppCode("app-xxx");
        request.setModelCode("customer-dataset");

        // 获取销售线索数据
        LovrabetResult<?> result = sdkClient.getList(request);

        if (result.isSuccess()) {
            return parseCustomers(result.getData());
        }
        return Collections.emptyList();
    }
}

价值：

• ✅ 无需手动管理 HTTP 请求和签名逻辑
• ✅ 类型安全的 API 调用
• ✅ 统一的错误处理
• ✅ 开箱即用的认证机制

---

场景 2：从 Java 应用向 Lovrabet 同步数据

问题：您的 Java 系统产生了新的业务数据（如订单、工单），需要同步到 Lovrabet 云兔平台进行可视化分析和报表生成。

使用 OpenSDK：

// 在您的订单服务中
@Service
public class OrderSyncService {
    private final LovrabetSDKClient sdkClient;

    public void syncOrder(Order order) {
        LovrabetRequest request = new LovrabetRequest();
        request.setAppCode("app-xxx");
        request.setModelCode("orders-dataset");

        // 构建订单数据
        Map<String, Object> orderData = new HashMap<>();
        orderData.put("order_no", order.getOrderNo());
        orderData.put("amount", order.getAmount());
        orderData.put("customer_name", order.getCustomerName());
        orderData.put("create_date", order.getCreateDate());
        request.setParamMap(orderData);

        // 创建订单记录
        LovrabetResult<String> result = sdkClient.create(request);

        if (result.isSuccess()) {
            logger.info("订单同步成功: {}", result.getData());
        } else {
            logger.error("订单同步失败: {}", result.getResultMsg());
        }
    }
}

价值：

• ✅ 实时数据同步
• ✅ 减少手动数据导入工作
• ✅ 统一的数据源，支持跨系统分析

---

场景 3：构建微服务架构中的数据中台

问题：在微服务架构中，多个服务需要访问 Lovrabet 的统一数据，但不希望每个服务都直接对接 OpenAPI。

使用 OpenSDK：

// 构建统一的数据服务
@RestController
@RequestMapping("/api/data")
public class DataGatewayController {
    private final LovrabetSDKClient sdkClient;

    // 为内部微服务提供统一的数据访问接口
    @GetMapping("/customers")
    public ResponseEntity<List<Map<String, Object>>> getCustomers(
        @RequestParam(defaultValue = "1") int page,
        @RequestParam(defaultValue = "20") int size
    ) {
        LovrabetRequest request = new LovrabetRequest();
        request.setAppCode("app-xxx");
        request.setModelCode("customers");

        Map<String, Object> params = new HashMap<>();
        params.put("currentPage", page);
        params.put("pageSize", size);
        request.setParamMap(params);

        LovrabetResult<?> result = sdkClient.getList(request);

        if (result.isSuccess()) {
            return ResponseEntity.ok((List<Map<String, Object>>) result.getData());
        }
        return ResponseEntity.status(500).build();
    }
}

价值：

• ✅ 统一数据访问层
• ✅ 集中管理认证凭证
• ✅ 降低系统耦合度
• ✅ 支持访问控制和审计

---

适用场景

场景	是否适用	说明
✅ Spring Boot 后端应用	推荐	与 Spring 生态完美集成
✅ 定时任务/数据同步	推荐	使用 OpenSDK 构建可靠的数据同步服务
✅ 微服务数据中台	推荐	构建统一的数据访问层
✅ 传统 Java Web 应用	适用	Servlet、Struts、JSP 等均可使用
⚠️ 前端直接调用	不推荐	前端请使用 Node.js SDK 或浏览器端 SDK
⚠️ Android 应用	不推荐	请使用专门的移动端 SDK

---

核心优势

1. 简单易用

// 只需 3 步即可完成数据查询
LovrabetSDKClient client = new LovrabetSDKClient(accessKey, baseUrl);
LovrabetRequest request = new LovrabetRequest();
request.setAppCode("app-xxx");
LovrabetResult<?> result = client.getDatasetCodeList(request);

2. 安全可靠

• ✅ 自动签名 - SDK 自动处理 HMAC-SHA256 签名，无需手动计算
• ✅ 密钥保护 - AccessKey 只在服务端使用，不会暴露给前端
• ✅ HTTPS 传输 - 所有请求通过 HTTPS 加密传输

3. 完整的错误处理

LovrabetResult<?> result = client.getOne(request);

if (result.isSuccess()) {
    // 成功：处理业务数据
    Object data = result.getData();
} else {
    // 失败：获取错误码和错误信息
    String errorCode = result.getResultCode();
    String errorMsg = result.getResultMsg();
    logger.error("查询失败 [{}]: {}", errorCode, errorMsg);
}

4. 生产级质量

• ✅ 线程安全，支持高并发
• ✅ 统一的响应格式
• ✅ 详细的错误信息
• ✅ 支持重试和超时控制

---

快速开始

1. 引入依赖

<dependency>
    <groupId>com.lovrabet.runtime</groupId>
    <artifactId>lovrabet-runtime-opensdk</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

2. 获取访问凭证

1. 登录 Lovrabet 云兔平台
2. 进入应用管理，获取 应用编码（AppCode）
3. 开通 OpenAPI 功能，生成 访问密钥（AccessKey）

3. 编写第一个程序

import com.lovrabet.runtime.opensdk.client.LovrabetSDKClient;
import com.lovrabet.runtime.opensdk.model.LovrabetRequest;
import com.lovrabet.runtime.opensdk.model.LovrabetResult;

public class HelloLovrabet {
    public static void main(String[] args) {
        // 1. 创建客户端
        String accessKey = "ak-your-access-key";
        String baseUrl = "https://runtime.lovrabet.com/openapi";
        LovrabetSDKClient client = new LovrabetSDKClient(accessKey, baseUrl);

        // 2. 构建请求
        LovrabetRequest request = new LovrabetRequest();
        request.setAppCode("app-xxx");

        // 3. 调用 API
        LovrabetResult<?> result = client.getDatasetCodeList(request);

        // 4. 处理结果
        if (result.isSuccess()) {
            System.out.println("数据集列表: " + result.getData());
        } else {
            System.err.println("失败: " + result.getResultMsg());
        }
    }
}

4. 学习路径

按照以下顺序学习，循序渐进掌握 SDK 使用：

1. 📖 快速开始 - 5 分钟完成第一个 CRUD 程序
2. 📚 核心概念 - 深入理解 SDK 工作原理
3. 📋 API 参考 - 查阅完整的接口文档
4. 💡 业务示例 - 学习 5 个真实场景的实现
5. 🚀 最佳实践 - 掌握生产环境优化技巧
6. ❓ 常见问题 - 解决使用中的疑问

---

技术支持

如果遇到问题，请通过以下方式获取帮助：

• 📧 客服邮箱：service@lovrabet.com
• 🌐 官方网站：https://lovrabet.com
• 📚 文档中心：https://open.lovrabet.com

---

文档版本: 1.0.0 最后更新: 2025-10-12 适用于: lovrabet-runtime-opensdk 1.0.0+