safety-eval-service-frontend/.cursor/skills/specs/19-底座平台API调用规范/13-注意事项与最佳实践/SKILL.md

name	description
jjb-base-api-best-practices	定义 JJB 底座 baseAPI 注意事项与最佳实践。在调用 baseAPI 时确保环境判断、错误处理时查阅。

底座平台API调用规范

注意事项和最佳实践

必须遵守

1. 环境判断：所有 baseAPI 调用前必须判断 typeof window.__IN_BASE__ !== 'undefined'，确保应用运行在底座中
2. 错误处理：对于异步 API（如 getClientInfo、getTenantInfo、getUserInfo），必须提供 onFail 回调处理错误情况
3. 参数验证：调用 API 前验证必要参数是否存在，避免运行时错误

最佳实践

1. 封装工具函数：将 baseAPI 调用封装成工具函数，统一处理环境判断和错误处理
2. 类型定义：为 baseAPI 的返回数据定义 TypeScript 类型，提升代码可维护性
3. 异步处理：对于返回 Promise 的 API（如 getMenuInfoByPath），使用 async/await 或 .then().catch() 处理异步逻辑
4. 事件监听：对于需要监听事件的 API（如表单引擎），在组件挂载时添加监听，在组件卸载时移除监听

常见错误

1. 未判断环境：直接调用 baseAPI 而不判断是否在底座中，导致运行时错误
2. 缺少错误处理：调用异步 API 时未提供 onFail 回调，导致错误无法捕获
3. 参数错误：传递错误的参数类型或格式，导致 API 调用失败
4. 事件监听泄漏：添加了事件监听但未在组件卸载时移除，导致内存泄漏