跳到主要内容

常见问题解答

这里汇总了集成开发中经常被问到的问题。如果你遇到的问题不在这里，可以在文末找到技术支持渠道。

集成开发和直接修改主系统有什么区别？​

集成开发采用微前端架构，你的代码在独立仓库里，和主系统完全隔离。

对比项集成开发（微前端）直接修改主系统
代码隔离独立仓库，清晰边界混在主系统代码中
维护成本低，只维护自己的代码高，主系统更新时容易冲突
团队协作不同团队独立开发容易相互影响
部署灵活独立构建、独立部署必须整体重新部署
版本管理独立版本控制耦合在主系统版本中

推荐使用集成开发，通过 lovrabet menu sync 一键集成到主系统。

MCP 是否必须配置？​

不是必须的，但强烈推荐。

配置 MCP 后，AI 能完全理解你的数据结构，生成的代码准确度接近 100%，开发时间可以节省一半以上。不配置的话，你仍然可以使用 SDK 手动编写代码，只是需要自己查文档、理解 API，效率会低一些。

简单说就是：不配能用，配了事半功倍。

MCP 支持哪些 AI 工具？​

目前支持所有基于 MCP 协议的工具，包括 Claude Desktop、Cursor 等。配置方式都差不多，在配置文件中添加 MCP Server 即可：

{
  "mcpServers": {
    "lovrabet-dataset": {
      "command": "npx",
      "args": ["-y", "@lovrabet/dataset-mcp-server"],
      "env": {
        "DEFAULT_APP_CODE": "your-app-code"
      }
    }
  }
}

菜单同步后，主系统会立即看到新页面吗？​

是的。lovrabet menu sync 完成后，菜单会立即出现在主系统中，用户点击后加载你的子应用页面。对用户来说，感知不到这是独立开发的子应用。

如果菜单没有出现，检查以下几点：

  1. lovrabet menu sync 是否执行成功
  2. 子应用是否已部署到服务器
  3. 主应用的子应用配置是否正确
  4. 刷新一下主系统页面

如何调试 SDK 调用失败的问题？​

SDK 提供了调试模式，开启后会在控制台输出完整的请求和响应信息：

const client = createClient({
  appCode: "your-app-code",
  accessKey: process.env.ACCESS_KEY,
  options: {
    debug: true,
  },
});

常见错误及解决方法：

错误原因解决方案
401 Unauthorized认证失败检查 AccessKey 或 Token
403 Forbidden权限不足检查数据集访问权限
404 Not Found资源不存在检查 datasetCode 是否正确
400 Bad Request参数错误检查请求参数格式
Network Error网络或 CORS 问题检查网络连接和 CORS 配置
Token ExpiredToken 已过期重新生成 Token 或使用 Cookie

更多调试技巧：SDK 故障排查

一个应用可以创建多个子应用吗？​

可以，这正是微前端架构的优势。

比如团队 A 开发"销售分析"扩展，团队 B 开发"客服服务"扩展，团队 C 开发"财务报表"扩展——各自独立仓库、独立部署，最终都通过 lovrabet menu sync 同步到主系统，在用户看来就像一个完整的应用。

注意事项：

  • 确保不同子应用的菜单名称不重复
  • 建议统一 SDK 和 CLI 版本
  • 可以共享公共组件库

子应用的性能会受影响吗？​

不会。微前端架构下，子应用是按需加载的——只有用户访问时才加载对应的代码。加上独立缓存和 CLI 内置的构建优化，性能表现不用担心。

日常开发中注意这几点就好：

// 路由懒加载
const CustomerAnalysis = lazy(() => import("./pages/CustomerAnalysis"));

// 按需引入，不要整包引入
import debounce from "lodash-es/debounce"; // 好
// import _ from "lodash";  // 不好

// 数据分页，不要一次拉全量
const result = await client.models.customers.filter({
  currentPage: 1,
  pageSize: 20,
});

MCP 会泄露数据吗？​

不会。MCP Server 在你的本地运行，只读取数据集的元数据（表结构、字段定义），不会读取实际的业务数据。AI 工具通过 MCP 理解的是"你有哪些表、每张表有什么字段"，而不是"张三的手机号是多少"。

MCP 传递的信息大致长这样：

{
  tableName: "customers",
  fields: [
    { name: "id", type: "string", isPrimaryKey: true },
    { name: "customer_name", type: "string" },
    { name: "phone", type: "string" },
    { name: "company", type: "string" }
  ]
}

如何在本地开发时预览效果？​

本地开发时，你的子应用独立运行：

lovrabet start
# 子应用运行在 http://localhost:3000
# 数据通过 SDK 从真实系统获取

如果需要看集成到主系统后的完整效果，有两种方式：

  1. 方案一：把本地地址配置到测试环境的子应用入口
  2. 方案二：构建后部署到测试服务器，再同步菜单

日常开发建议用本地模式快速迭代，定期部署到测试环境验证集成效果。

子应用能访问主系统的所有数据吗？​

子应用通过 SDK 访问数据，权限由认证方式决定：

  • Cookie 认证：继承当前登录用户的权限
  • AccessKey 认证：继承 AccessKey 配置的权限

数据集和字段级别的权限都受平台权限系统限制。

安全建议：

  • 服务端使用 AccessKey，浏览器端使用 Token 或 Cookie
  • 遵循最小权限原则
  • 不要在前端代码中硬编码 AccessKey

注意事项​

安全性​

  • 永远不要在前端代码中硬编码 AccessKey
  • 用环境变量管理敏感信息
  • 生产环境使用 Token 或 Cookie 认证
  • 数据传输走 HTTPS
  • 定期更新 SDK 和 CLI 版本

版本兼容性​

  • 确保 SDK、CLI、MCP Server 版本兼容
  • 关注工具链的更新日志
  • 测试环境先验证再部署生产

推荐的版本管理方式：

{
  "dependencies": {
    "@lovrabet/sdk": "^1.1.18",
    "@lovrabet/cli": "^1.1.15"
  },
  "devDependencies": {
    "@lovrabet/dataset-mcp-server": "^1.0.8"
  }
}

菜单命名​

  • 使用 Title 注释提供清晰的中文名称
  • 避免特殊字符
  • 确保菜单名称在应用内唯一
  • 名称简洁明了，不超过 10 个字

好的例子：客户分析、销售漏斗、数据报表

不好的例子：page1、基于机器学习算法的客户行为分析与预测系统

相关资源​

文档​

工具包​

示例项目​

技术支持​