开发者总结Atlassian Forge文档未提及的五个坑

我们今年为 Jira 和 Confluence 发布了八个 Forge 应用。大部分工作都如文档所述顺利进行。但下面这五件事并非如此，每一件都耗费了我们数小时。它们在开发过程中都不会显现，这正是其危险之处。

大多数 Forge resolver 都包在一个辅助函数里，该函数捕获错误并以友好消息的形式返回给 UI。这是很好的做法，直到一个新用户打开你的应用，而应用以 asUser() 调用 Jira。Forge 需要该用户的同意，因此调用抛出 NEEDS_AUTHENTICATION_ERR。如果你的辅助函数捕获了它，用户只会看到一条错误消息，却没有任何方式授予访问权限。 你自己永远看不到这个问题：你在第一次运行应用时就已授予了访问权限。而每一位客户都会遇到。 修复方法：将该错误重新抛出，以便 Forge 能显示自己的“允许访问”按钮。 const handle = (fn) => async (req) => { try { return { ok: true, data: await fn(req) }; } catch (e) { if (e?.name === 'NEEDS_AUTHENTICATION_ERR') throw e; // let Forge ask for consent console.error(e); return { ok: false, error: e.message }; }; 然后在提交前，用第二个浏览器配置文件或同事的账号进行测试。 UI Kit（render: native）可能会在两次状态更新之间渲染你的组件。像这样的代码看起来是安全的： setData(await invoke('getData')); setSettings(await invoke('getSettings')); // ... return <Text>{settings.mode}</Text>; 但会出现一次渲染，此时 data 已设置，而 settings 仍为 null。settings.mode 抛出错误，整个页面消失。forge 日志中没有任何内容，因为崩溃发生在浏览器中。 修复方法：在屏幕所需的所有数据到达之前不渲染任何内容，并将每个屏幕包裹在错误边界中，这样 bug 会显示一条消息，而不是空白页面。 if (!data || !settings) return <Spinner />; 3. 一个 manifest 变更会隐藏你的自定义字段，以及该类型的所有字段 我们在 jira:customFieldType 的 contextConfig 中添加了一个 resolver。forge lint 通过，部署成功。Jira 静默判定该模块无效，并隐藏了字段类型以及由它创建的所有现有字段。任何地方都没有错误：这些字段只是从问题和设置中消失了。 移除嵌套的 resolver 并再次部署后，一切恢复。 修复方法：在对自定义字段类型做任何 manifest 变更后，打开该类型的一个现有字段，检查它是否仍然存在。两个相关的意外：字段的上下文配置无法可靠地到达编辑视图（请在 Forge 存储中保留自己的副本），并且自定义字段类型仅在公司管理的项目中有效。 使用 read:board-scope:jira-software 列出 Jira Software 看板返回了 401。缺失的部分是 read:project:jira，看板端点也需要它，而错误从未提及。通过 Agile API 获取 sprint 问题需要更细粒度的作用域；JQL 搜索更简单： await api.asApp().requestJira(route/rest/api/3/search/jql, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jql: sprint = ${sprintId}, fields: ['status'] }), }); 请记住，添加作用域是一次主版本升级：每个现有安装都必须批准升级。在公开发布之前确定好你的作用域。 额外提示：如果某个屏幕只显示不透露任何内容的聚合数据（计数、进度、总计），asApp() 可以完全避免同意屏幕。 我们所有的链接都加载正常，但应用仍在几分钟内被拒绝。原因是列表中“支持工单系统”字段为空：自动检查将空的支持链接视为无效链接。第二个耗费了我们一天时间的问题：通过 API 输入的定价仍会显示“定价尚未设置”，直到你打开定价页面并点击一次保存。 修复方法：填写每个链接字段（支持、文档、条款），检查每个链接返回 HTTP 200，并在提交前在 UI 中保存定价。 有时在 forge deploy 之后页面立即空白，浏览器控制台出现 404，日志中没有 resolver 调用。那是 Forge 仍在提供新 bundle，而不是你的代码的问题。再次部署或等待几分钟，然后再开始调试。