最佳实践
开发规范与避坑指南
这篇文档汇总了在 Lovrabet 平台上做集成开发时，经过验证的一些好的做法。
前置阅读如果你还不了解 Lovrabet 的工具体系，建议先阅读 开发者工具全景。
AI 驱动的开发规范（推荐）
**为什么提示词模板能被 AI 准确执行？**这个模板写的"API 客户端使用单例模式"——没有后端的话，你连接口都没有，更别提 API 客户端。得先搭后端、写接口、处理认证、处理错误，写完接口再写请求封装。"列表查询加分页"——后端分页接口还没写，你得先让后端同学加，前后端对齐参数名又搞了半天。"错误处理用 try-catch"——每个后端同学的错误格式都不一样：这个返回 \{ code: 500, msg: \&\#34;xxx\&\#34; \}，那个返回 \{ success: false, error: \&\#34;xxx\&\#34; \}，catch 到了也不知道怎么给用户提示。模板写的是最佳实践，但没有后端接口，每一条都是在空中盖楼。有了 rabetbase：CLI 的 api pull 已经生成了标准路径的 SDK client（src/api/client\.ts），filter 的参数和返回值有 TypeScript 类型，异常类型在 SDK 中定义。Skill 确保了 AI 独享这些真实信息——模板里的每一条规范，都有真实的类型和方法可以依托。不是概念正确的空话，是有基础设施支撑的 SOP。在 Claude Code 中使用 rabetbase CLI 开发时，以下提示词模板可以确保 AI 遵循最佳实践：
用 rabetbase CLI 帮我实现一个 {'{功能描述}'}。要求：
AI 会按照这些规范生成代码。下方是各项规范的详细说明，供你理解和后续维护。
应用场景参考
在开始讲具体实践之前，先看几个典型的集成开发场景，帮你找到和自己需求最接近的模式。
小程序生态扩展
基于企业数据构建微信小程序、支付宝小程序：
import { createClient } from "@lovrabet/sdk";
const client = createClient({
appCode: "your-enterprise-app",
token: wx.getStorageSync("userToken"),
});
const customerData = await client.models.customers.filter({
region: "华东",
level: "VIP",
});
工作流自动化
构建复杂的审批流程、数据处理管道：
const approvalWorkflow = {
trigger: await client.models.orders.filter({ status: "pending" }),
conditions: [
{ field: "amount", operator: ">", value: 10000 },
{ field: "customer.level", operator: "=", value: "VIP" },
],
actions: ["sendNotification", "createApprovalTask", "updateOrderStatus"],
};
多系统集成中台
连接 Lovrabet 与企业现有系统（ERP、CRM、OA）：
const dataHub = {
lovrabet: await lovrabetClient.models.products.filter(),
erp: await erpConnector.getInventory(),
crm: await crmConnector.getCustomers(),
synchronize: () => {
// 复杂的数据同步和转换逻辑
},
};
客户端管理
前端：单例模式复用
创建一次客户端实例，全局复用。不要在每个组件里都 createClient。
// src/api/client.ts — 推荐：单例模式
import { createClient } from "@lovrabet/sdk";
export const client = createClient({
appCode: "your-app-code",
});
// 在组件中使用
import { client } from "@/api/client";
// 不推荐：每次渲染都创建新实例
function MyComponent() {
const client = createClient({ appCode: "..." });
}
后端：Spring Bean 单例
@Configuration
public class LovrabetConfig {
@Bean
public LovrabetSDKClient lovrabetSDKClient() {
return new LovrabetSDKClient(accessKey, baseUrl);
}
}
安全性
AccessKey 管理
AccessKey 是访问数据的凭证，务必妥善保管。
# 通过环境变量传入，不要写死在代码里
export LOVRABET_ACCESS_KEY="ak-your-access-key"
// 浏览器端绝对不要硬编码 AccessKey
// 前端应该使用 Cookie 或 Token 认证
const client = createClient({
appCode: "your-app-code",
// 自动使用 Cookie 认证
});
敏感数据脱敏
// 前端：脱敏手机号
const maskPhone = (phone: string) => {
return phone.replace(/(\d{3})\d{4}(\d{4})/, "$1****$2");
};
// 138****8000
// 后端：日志脱敏
String maskedPhone = phone.replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2");
log.info("客户电话: {}", maskedPhone);
性能优化
分页与防抖
接口调用时注意控制数据量，搜索场景加上防抖：
// 使用分页，不要一次拉全量
const { data } = await client.models.customers.filter({
currentPage: 1,
pageSize: 20,
});
// 搜索加防抖，避免每次按键都发请求
import { debounce } from "lodash-es";
const handleSearch = debounce(async (keyword) => {
await client.models.customers.filter({ searchKeyword: keyword });
}, 300);
代码分割
页面多的时候，用懒加载减少首屏包体积：
import { lazy } from "react";
const CustomerAnalysis = lazy(() => import("./pages/CustomerAnalysis"));
后端缓存
频繁读取的数据可以加一层缓存：
private final Cache<String, Object> cache = Caffeine.newBuilder()
.maximumSize(1000)
.expireAfterWrite(5, TimeUnit.MINUTES)
.build();
错误处理
前端统一处理
try {
const result = await client.models.customers.filter(params);
if (result.success) {
setData(result.data);
} else {
message.error(result.message);
}
} catch (error) {
console.error("API 调用失败:", error);
message.error("网络错误，请稍后重试");
}
后端重试机制
对于网络不稳定的场景，加上指数退避重试：
public <T> LovrabetResult<T> executeWithRetry(
Supplier<LovrabetResult<T>> operation, int maxRetries) {
for (int attempt = 0; attempt <= maxRetries; attempt++) {
try {
LovrabetResult<T> result = operation.get();
if (result.isSuccess()) return result;
Thread.sleep((long) Math.pow(2, attempt) * 1000);
} catch (Exception e) {
if (attempt == maxRetries) throw new RuntimeException("重试失败", e);
}
}
return null;
}
日志规范
后端服务建议使用结构化日志，方便后续排查问题：
@Slf4j
public class DataService {
public void createData(Map<String, Object> data) {
long startTime = System.currentTimeMillis();
log.info("开始操作 - operation={}, dataSize={}", "create", data.size());
LovrabetResult<String> result = sdkClient.create(request);
long duration = System.currentTimeMillis() - startTime;
if (result.isSuccess()) {
log.info("操作成功 - id={}, duration={}ms", result.getData(), duration);
} else {
log.error("操作失败 - code={}, duration={}ms", result.getResultCode(), duration);
}
}
}
测试策略
前端单元测试
import { render, screen, waitFor } from "@testing-library/react";
test("should load customers", async () => {
render(<CustomerList />);
await waitFor(() => {
expect(screen.getByText("张三")).toBeInTheDocument();
});
});
后端集成测试
@SpringBootTest
public class DataServiceIntegrationTest {
@Autowired
private DataService dataService;
@Test
public void testGetCustomers() {
List<Map<String, Object>> customers = dataService.getCustomers(1, 10);
assertNotNull(customers);
assertTrue(customers.size() > 0);
}
}
部署建议
前端部署
rabetbase run build
# 产物在 dist/ 目录，部署到 CDN
Nginx 配置参考：
server {
listen 80;
root /var/www/your-app/dist;
location / {
try_files $uri $uri/ /index.html;
}
location ~* \.(js|css|png|jpg|svg)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
}
后端 Docker 部署
FROM openjdk:11-jre-slim
WORKDIR /app
COPY target/myapp.jar app.jar
ENV LOVRABET_ACCESS_KEY=""
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
健康检查
@GetMapping("/health/lovrabet")
public Map<String, Object> checkHealth() {
Map<String, Object> health = new HashMap<>();
try {
long start = System.currentTimeMillis();
LovrabetResult<?> result = sdkClient.getDatasetCodeList(request);
health.put("status", result.isSuccess() ? "UP" : "DOWN");
health.put("responseTime", (System.currentTimeMillis() - start) + "ms");
} catch (Exception e) {
health.put("status", "DOWN");
health.put("error", e.getMessage());
}
return health;
}
小结
实践领域 | 核心要点 |
客户端管理 | 前后端都使用单例模式 |
安全性 | 永远不要在前端硬编码 AccessKey |
性能优化 | 分页、缓存、代码分割 |
错误处理 | 统一处理 + 重试机制 |
日志管理 | 结构化日志、敏感信息脱敏 |
测试策略 | 单元测试 + 集成测试 |
部署 | 健康检查、容器化 |