跳到主要内容

集成开发常见问题

本文档回答集成开发中的常见问题，帮助您快速解决遇到的问题。

❓ 常见问题​

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

A: 集成开发采用微前端架构，您的代码独立维护，不会与主系统代码混在一起。

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

推荐做法：

  • ✅ 使用集成开发，保持代码独立性
  • ✅ 通过 lovrabet menu sync 一键集成到主系统
  • ✅ 享受微前端架构的所有优势

Q2: MCP 是否必须配置？​

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

配置 MCP 的优势：

  • ✅ AI 完全理解你的数据结构
  • ✅ 生成的代码准确度接近 100%
  • ✅ 节省 50-80% 的开发时间
  • ✅ 复杂查询和数据关联自动处理

不配置 MCP：

  • 仍然可以使用 SDK 手动编写代码
  • 需要自己查文档、理解 API
  • 开发效率较低

对比示例：

不使用 MCP：
- 查文档 → 手写代码 → 调试错误 → 修改 → 再调试 → 完成
- 耗时：1-2 小时

使用 MCP：
- 告诉 AI 需求 → AI 生成代码 → 完成
- 耗时：5-10 分钟

Q3: MCP 支持哪些 AI 工具？​

A: 目前支持所有基于 MCP 协议的工具：

  • ✅ Claude Desktop - Anthropic 官方桌面应用
  • ✅ Cursor - AI 代码编辑器
  • ✅ 其他 MCP 兼容工具 - 持续增加中

配置方式：

每个工具的配置方式类似，都是在配置文件中添加 MCP Server：

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

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

A: 是的。lovrabet menu sync 完成后：

  1. 菜单会立即出现在主系统中
  2. 点击菜单会加载你的扩展应用页面
  3. 用户感知不到这是独立开发的子应用

前提条件：

  • ✅ 扩展应用已正确构建和部署
  • ✅ 主应用配置了正确的子应用访问地址

如果菜单没有出现：

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

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

A: SDK 提供了调试模式：

const client = createClient({
  appCode: "your-app-code",
  accessKey: process.env.ACCESS_KEY,
  options: {
    debug: true, // 开启调试模式
  },
});

开启后会在控制台输出：

  • 完整的 HTTP 请求信息（URL、Headers、Body）
  • 请求和响应的详细内容

调试步骤：

  1. 开启 debug 模式
  2. 查看控制台的请求详情
  3. 检查认证信息是否正确
  4. 检查 API 参数是否符合要求
  5. 查看响应错误信息

常见错误：

错误原因解决方案
401 Unauthorized认证失败检查 AccessKey 或 Token
403 Forbidden权限不足检查数据集访问权限
404 Not Found资源不存在检查 datasetCode 是否正确
400 Bad Request参数错误检查请求参数
500 Internal Server服务器错误联系技术支持
Network Error网络问题或 CORS 错误检查网络连接和 CORS 配置
CORS Error跨域配置问题检查服务端 CORS 配置
Timeout请求超时检查网络或增加超时时间
Token ExpiredToken 已过期重新生成 Token 或使用 Cookie

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

Q6: 一个应用可以创建多个扩展项目吗？​

A: 可以！这是微前端架构的优势。

场景示例：

  • 团队 A 开发「销售分析」扩展，独立仓库
  • 团队 B 开发「客服服务」扩展，独立仓库
  • 团队 C 开发「财务报表」扩展，独立仓库

所有扩展通过 lovrabet menu sync 同步后，在主系统中无缝集成，就像一个完整的应用。

优势：

  • ✅ 团队独立开发，互不干扰
  • ✅ 可以使用不同的技术栈（React、Vue 等）
  • ✅ 独立部署和更新
  • ✅ 降低代码冲突风险
  • ✅ 便于团队协作和管理

注意事项：

  • 确保不同扩展的菜单名称不重复
  • 建议统一 SDK 和 CLI 版本
  • 可以共享公共组件库（可选）

Q7: 扩展应用的性能会受影响吗？​

A: 不会。微前端架构的性能优势：

性能优势：

  • ✅ 按需加载：只有访问时才加载扩展应用代码
  • ✅ 独立缓存：扩展应用独立缓存，更新不影响主系统
  • ✅ 并行加载：多个扩展应用可以并行加载
  • ✅ 构建优化：CLI 内置了性能优化配置

性能最佳实践：

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

// 2. 合理使用代码分割
import("./heavy-lib").then((module) => {
  // 只在需要时加载
});

// 3. 避免引入过大的第三方库
// ❌ 不推荐：引入整个 lodash
import _ from "lodash";
// ✅ 推荐：只引入需要的函数
import debounce from "lodash-es/debounce";

// 4. 优化图片和资源
// 使用适当的图片格式和大小
// 使用 CDN 加载静态资源

// 5. 分页加载数据
const result = await client.models.customers.filter({
  currentPage: 1,
  pageSize: 20, // 控制每页数量
});

性能监控：

# 分析包体积
lovrabet build
npx source-map-explorer dist/*.js

# 使用 Lighthouse 检测性能
npx lighthouse http://localhost:3000

Q8: MCP 会泄露数据吗？​

A: 不会。MCP Server 的工作原理：

安全机制：

  1. MCP Server 在你的本地运行
  2. 只读取数据集的元数据（表结构、字段定义）
  3. 不会读取实际的业务数据
  4. AI 工具通过 MCP 理解结构，但不访问数据

安全保障：

  • ✅ 数据不离开你的环境
  • ✅ 只提供结构信息给 AI
  • ✅ 符合数据安全规范
  • ✅ 不会上传到云端

MCP 传递的信息示例：

// MCP 传递给 AI 的信息（仅结构）
{
  tableName: "customers",
  fields: [
    { name: "id", type: "string", isPrimaryKey: true },
    { name: "customer_name", type: "string" },
    { name: "phone", type: "string" },
    { name: "company", type: "string" }
  ]
}

// ❌ MCP 不会传递实际数据
// 不会传递：{ id: "001", customer_name: "张三", ... }

Q9: 如何在本地开发时看到完整的主系统？​

A: 本地开发时，您主要关注自己的扩展功能：

本地开发模式：

lovrabet start
# 扩展应用独立运行在 http://localhost:3000
# 可以调试业务逻辑，数据通过 SDK 从真实系统获取

完整预览集成效果：

  1. 方案一：将本地服务器地址配置到测试环境

    // 测试环境主应用配置
    microApps: [
      {
        name: "my-extension",
        url: "http://localhost:3000", // 指向本地开发服务器
      },
    ];

  2. 方案二：构建后部署到测试环境

    lovrabet build
    # 部署到测试服务器
    lovrabet menu sync --env test

推荐做法：

  • ✅ 日常开发使用本地模式，快速迭代
  • ✅ 定期部署到测试环境，验证集成效果
  • ✅ 上线前在生产环境充分测试

Q10: 扩展应用能访问主系统的所有数据吗？​

A: 扩展应用通过 SDK 访问数据，权限由以下因素决定：

权限控制机制：

  1. 认证方式：

    • 使用 Cookie 认证时，继承当前用户的权限
    • 使用 AccessKey 认证时，继承 AccessKey 的权限

  2. 数据集权限：

    • 只能访问已配置的数据集
    • 受平台权限系统限制

  3. 字段权限：

    • 遵循数据集的字段权限设置
    • 敏感字段可能被隐藏或脱敏

安全建议：

  • ✅ 服务端使用 AccessKey（不要泄露）
  • ✅ 浏览器使用 Token 或 Cookie
  • ✅ 遵循最小权限原则
  • ❌ 不要在客户端存储敏感数据
  • ❌ 永远不要在前端代码中硬编码 AccessKey

⚠️ 注意事项​

1. 安全性​

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

2. 版本兼容性​

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

推荐的版本管理：

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

3. 菜单命名​

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

好的菜单命名：

✅ 客户分析
✅ 销售漏斗
✅ 数据报表

不好的菜单命名：

❌ page1
❌ 基于机器学习算法的客户行为分析与预测系统（太长）
❌ analysis_page（使用下划线）

4. 数据安全​

  • 不要在客户端存储敏感数据
  • 使用 HTTPS 传输数据
  • 遵循 Lovrabet 平台的安全规范
  • 定期审查代码安全问题
  • 使用环境变量管理配置

5. 代码质量​

  • 使用 TypeScript 获得类型安全
  • 编写单元测试
  • 遵循代码规范（ESLint、Prettier）
  • 代码审查（Code Review）
  • 持续集成（CI/CD）

📚 相关资源​

核心文档​

工具包​

示例项目​

技术支持​

🤝 还有其他问题？​

如果您的问题没有在这里找到答案：

  1. 📖 查看详细的 SDK 文档
  2. 📖 查看详细的 CLI 文档
  3. 💬 在开发者社区提问
  4. 📧 发送邮件到 support@lovrabet.com
  5. 🐛 在 GitHub 提交 Issue

我们会持续更新本文档，添加更多常见问题和解决方案。